# Datamitsu

> Your toolchain deserves a home.

This file contains all documentation content in a single document following the llmstxt.org standard.

## About datamitsu


## Your toolchain deserves a home

Stop setting up the same tools in every repository. Linters, formatters, git hooks and the runtimes they need go into one `datamitsu.config.js` you carry from project to project.

**Define them once. Inherit them everywhere.**

Not a boilerplate, not scattered across projects, not reinvented from scratch every time. datamitsu gives your toolchain one home — versioned, composable, and always one command away.

## Why it exists

> Dozens of repositories, all on different stacks — a Typst document with scripts, a frontend, a backend, a CLI, a slide deck. Every new project meant weeks of setting up the same tools, and every setup came out slightly different. Updating twenty repositories was hell, so they went years without updating their linters — until eslint started getting in the way of the product.
>
> — Alexander Svinarev, author of datamitsu

## What is datamitsu?

datamitsu is a **platform for building reproducible, security-first development tool distributions.**

It's NOT just another task runner or runtime manager.

It's a **foundation** for creating standardized tool configurations that teams can distribute as packages (npm, rubygem, pypi, etc).

Think of it as **"lefthook for linting/tooling ecosystems"**:

- Core binary provides secure tool delivery (SHA-256 verification)
- Wrappers provide opinionated configs for different ecosystems
- Teams install one package, get everything configured

## The Two-Level Architecture

datamitsu operates on a two-level architecture that separates the platform from the content:

### Level 1: The Core (datamitsu)

The `datamitsu` binary provides the platform capabilities:

- Binary management with SHA-256 verification
- Programmable JavaScript configuration (goja runtime)
- Declarative + imperative configuration approach
- Config chaining with inheritance
- Tool operations (fix/lint/check)
- Safe managed-config reconciliation
- File patching (gitignore/dockerignore/package.json)

**What the core does NOT contain:**

- Concrete tool versions
- Linter configurations
- Opinionated defaults

### Level 2: Wrappers (npm/gem/pypi packages)

Wrapper packages provide the actual tool configurations:

- Full tool suite (eslint/prettier/golangci-lint/etc)
- Configured defaults for all tools
- VS Code recommendations
- Exportable config functions
- Project type detection
- Migration-free updates (via patching)

### Distribution Model

```
datamitsu core (Go binary)
  ↓
  Provides: binary mgmt, config engine, managed-config reconciliation

Wrappers (language-specific packages)
  ↓
  Provide: tool versions, configs, project templates

Projects (end users)
  ↓
  Install: npm install @company/dev-standards
  Run: datamitsu config reconcile && datamitsu lint
```

This architecture enables teams to:

1. **Build once, distribute everywhere** — Create your company's tool standards as a package
2. **Version independently** — Update configs without waiting for tool releases
3. **Distribute via familiar channels** — Use npm, gem, pypi, or any package manager
4. **Enforce security policies** — Mandatory hash verification for all binaries

## Who is datamitsu for?

### Primary: Config Package Creators

**Who they are:**

- Platform engineers at companies
- Open source maintainers
- DevOps teams establishing standards

**What they need:**

- Create company-wide tool standards
- Distribute via familiar package managers
- Enforce security policies (hash verification)
- Version configs independently from tools

**Value proposition:**

"Build once, distribute everywhere. One package brings all tools and configs to every project."

### Secondary: Development Teams

**Who they are:**

- Teams tired of copy-paste configs
- Projects with multiple contributors
- Companies wanting standardization

**What they need:**

- One dependency = all tools configured
- No manual setup per project
- Docker-optimized CI/CD
- Migration-free updates

**Value proposition:**

"Install one dependency, get everything configured. Zero manual setup in new projects."

### Tertiary: Open Source Maintainers

**Who they are:**

- Project template creators
- Framework maintainers
- Tool distribution authors

**What they need:**

- Distribute project templates with tools
- Ensure contributors use correct versions
- Provide both CLI and programmatic access

**Value proposition:**

"Ship your project template with tools included. Contributors get the right setup automatically."

## What makes datamitsu unique?

### 1. Mandatory Security Verification

Every binary downloaded from the internet must have a SHA-256 hash specified. No exceptions. No bypassing. Hash verification happens before extraction, preventing malicious binaries and ensuring reproducibility.

### 2. Config Chaining and Inheritance

Layer configurations from base → company → team → project:

```javascript
// Project-specific override in datamitsu.config.ts
function getConfig(prev) {
  return {
    ...prev,
    version: "1.0.0",
    apps: {
      ...prev.apps,
      // Remove a tool for this project
      "some-linter": undefined,
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

Configs receive the previous layer as input, enabling composition without duplication.

### 3. Docker CI/CD Optimization

Pre-cache all tools in a Docker layer for fast, reproducible builds:

```dockerfile
FROM node:20-alpine

# Install datamitsu + config wrapper
RUN npm install -g @company/datamitsu-config

# Download ALL tools to global store
RUN datamitsu init --all

# Save this layer
# Only changed tools re-download on updates
```

This dramatically speeds up CI builds by avoiding tool downloads on every run.

### 4. Migration-Free Updates

Update your config package, optionally preview the reconciliation, then run it;
your customizations survive:

```bash
# Update config wrapper
npm update @company/datamitsu-config

# Preview without writing or fixing
datamitsu config reconcile --dry-run

# Reconcile files, then run fix (preserves customizations!)
datamitsu config reconcile
```

The patching mechanism merges new defaults with your project-specific changes.

### 5. Multi-Runtime Support

Manage tools from different ecosystems in one place:

- **Binary apps** — Download native binaries with hash verification
- **UV apps** — Python tools via managed UV runtime (e.g., yamllint)
- **Node apps** — npm packages via managed Node.js + pnpm (e.g., eslint, prettier)
- **JVM apps** — Java applications via managed JDK runtime (e.g., openapi-generator-cli)
- **Go apps** — Go tools built from source via managed Go SDK (e.g., govulncheck)
- **Shell apps** — Wrap arbitrary system commands

All managed with the same config API, all with hash verification. Any app kind
can set custom environment variables (with `${STORE}`/`${APP_DIR}` expansion)
via the shared `env` field.

## Where does datamitsu fit?

datamitsu is **NOT**:

- A task runner (use moon/nx/turborepo for that)
- A runtime manager (use mise/asdf/volta for that)
- A package manager (use npm/pnpm/cargo for that)
- A build system (use moon/bazel/gradle for that)

datamitsu **IS**:

- A **platform** for building config distributions
- A **foundation** for team standards
- A **delivery mechanism** for verified tools
- A **configuration system** with inheritance

For detailed comparisons with similar tools, see the [Comparison Guide](./reference/comparison.md).

## Use Cases

### Company-Wide Standards

**Scenario:** Enterprise wants all projects to use the same linters and formatters.

**With datamitsu:**

```bash
# Create @company/dev-standards package once
# Then in every project:
npm install @company/dev-standards
datamitsu config reconcile  # Creates all configs automatically
```

**Result:**

- One source of truth for all configs
- Update package → all projects can update
- Enforce via package.json dependency

### Docker-Based CI/CD

**Scenario:** GitLab CI pipeline needs linting tools.

**With datamitsu:**

```dockerfile
# Base image - run once
RUN datamitsu init --all
# Layer cached with all tools

# Project build - runs every time
RUN datamitsu check
# Only new/changed tools download
```

**Result:**

- Fast CI builds (tools pre-cached in layer)
- Reproducible (hash-verified binaries)
- Incremental updates (only changed tools re-download)

### Open Source Project Template

**Scenario:** Framework wants contributors to have consistent setup.

**With datamitsu:**

```json
{
  "dependencies": {
    "@framework/dev-tools": "^1.0.0"
  }
}
```

Run `npm install && npx datamitsu config reconcile` → Everything configured automatically.

**Result:**

- Contributors get identical setup
- No "how to configure" docs needed
- Updates propagate via package version bump

## Learn More

- [Architecture Deep Dive](./guides/architecture/index.md) — Understand the internal execution model, task planning, parallelization, and caching strategies
- [Comparison Guide](./reference/comparison.md) — How datamitsu compares to mise, moon, and other tools
- [Creating Wrappers](./contributing/creating-wrappers.md) — Build your own config distribution package
- [Using Wrappers](./guides/using-wrappers.md) — Consume wrapper packages in your projects
- [Core Concepts](./getting-started/core-concepts.md) — Understand how datamitsu works

---

## Brand Guidelines


**Your toolchain deserves a home.**

Others run tools. **datamitsu defines what those tools are.**

datamitsu is the only tool that packages and distributes complete, configured toolchains. Not a task runner. Not a version manager. **Toolchain distribution as code.**

We exist so you set your tools up once, and every repository inherits them.

## Brand Personality

### Voice Attributes

**Confident, not arrogant**

- ✅ "datamitsu is a platform for building config distributions. Think lefthook, but for your entire tooling ecosystem."
- ✅ "datamitsu is for teams distributing standardized configs, not individual developers switching tool versions."
- ❌ "datamitsu is the ultimate all-in-one development tool that will revolutionize your workflow."

**Technical, not jargon-y**

- ✅ "Every binary is verified with SHA-256 hashes before extraction to prevent malicious code."
- ❌ "Enterprise-grade military-level security powered by blockchain-enabled cryptographic algorithms."

**Security-focused, not paranoid**

- ✅ "Hash verification ensures binaries match what the maintainer published."
- ❌ "Without datamitsu, hackers will definitely compromise your entire infrastructure!"

## Writing Guidelines

### Do

- **Use "Others X. datamitsu Y." framing** — "Others run tools. datamitsu defines what those tools are."
- **Lead with "Different problems" / "Different layers"** — Make distinctions clear
- **Use analogies from the ecosystem** — "Think lefthook, but for your entire tooling ecosystem"
- **Be specific about technical details** — SHA-256, not just "secure"
- **Acknowledge competitors honestly** — mise/moon solve different problems, explain how
- **Write short declarative sentences** — "Not a feature. The entire point."

### Don't

- **Use marketing buzzwords** — "Revolutionary," "game-changing," "paradigm shift"
- **Use vague security claims** — No "military-grade" or "blockchain-enabled"
- **Bash competitors** — Explain differences, never attack
- **Apologize for scope** — "datamitsu is for X, not Y" (confident, not "sorry, but...")

### Headings pass the literal-translation test

Translate a heading word for word into another language. If the sense survives, the heading says
something. If it collapses into nonsense or into a phrase that means nothing in particular, the
heading was leaning on an English idiom rather than on an idea — rewrite it.

| Heading                                                | Literally                                            | Verdict                                                       |
| ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------- |
| ❌ "Make tuning worthwhile."                           | "Make adjustment worth the cost."                    | An idiom carries the whole meaning; nothing concrete survives |
| ✅ "One evening of tuning. Every repository benefits." | "One evening of adjustment. Every repository gains." | Two plain facts, and the relation between them is the point   |
| ❌ "Upgrade deliberately."                             | "Upgrade with intent."                               | True of anything; says nothing about who decides or when      |
| ✅ "Upgrade on your terms."                            | "Upgrade when and how you decide."                   | Names the actor and the choice                                |

The test is not about being translated in practice — the site is English only. It is a check that a
heading carries an idea instead of a turn of phrase.

## Example Voice

✅ **Good:** "datamitsu is a platform for building config distributions. Think lefthook, but for your entire tooling ecosystem."

**Why:** Specific analogy, clear boundaries, confident.

❌ **Bad:** "datamitsu is a revolutionary AI-powered cloud-native DevOps solution that will transform your development workflow."

**Why:** Buzzwords, vague, overpromises.

## Language Policy

**English only. No exceptions.**

All documentation, code comments, commit messages, issues, and communications must be written in English. This policy ensures accessibility for the global developer community.

## Visual Identity

### Name Meaning

The name "datamitsu" is built on a double meaning in Japanese:

- **光 (mitsu)** — "light" → illuminating complexity, making the unclear clear
- **蜜 (mitsu)** — "honey" → smooth, polished, efficient (like a beehive)

The logo features a bee — the creature that produces honey through collective, structured work.

### Core Visual Metaphor: Light Breaking Through Complexity

**Honey + Light + Bee = datamitsu's visual identity**

- **Honey/Amber tones** — Warmth, polish, the smooth result of structured work
- **Deep blue backdrop** — The complexity being illuminated
- **Light rays** — Clarity cutting through the mess
- **Hexagons (honeycomb)** — Structure, efficiency, bee reference

### Color System

Built around the honey/light metaphor:

- **Primary: Amber/honey gold (#FFA500 family)** — The core brand color. Represents light, honey, and illumination
- **Secondary: Deep blue (#1E3A8A family)** — The backdrop. Complexity that light shines through
- **Visual pattern:** Amber light breaking through blue complexity

Not "blue for trust, gold for warmth." **Light illuminating complexity.**

### Iconography

Visual elements tied to honey/light/bee:

- **Honeycomb/hexagons** — Structure, efficiency, collective work (bee reference)
- **Light rays/beams** — Illumination, clarity breaking through
- **Layered hexagons** — Config inheritance as stacked honeycomb cells

Avoid generic dev tool icons (lock, shield, package, stack). Use the metaphor.

## Competitive Positioning Language

When discussing similar tools, use this framework:

### Template

> [Competitor] does [their use case]. **datamitsu solves a different problem.**
>
> **Different problems:**
>
> - [Competitor]: [their use case in 5-10 words]
> - datamitsu: [our use case in 5-10 words]
>
> **Use both:** [complementary example in one sentence]

### Example (mise)

> mise manages tool versions per developer. **datamitsu solves a different problem.**
>
> **Different problems:**
>
> - mise: Per-directory runtime flexibility for individuals
> - datamitsu: Team-wide toolchain standardization via packages
>
> **Use both:** mise manages Node version, datamitsu delivers ESLint with your company config.

### Example (moon)

> moon orchestrates monorepo builds with dependency graphs and caching. **datamitsu operates at a different layer.**
>
> **Different layers:**
>
> - moon: When/how tasks run (build orchestration)
> - datamitsu: What tools exist (toolchain delivery)
>
> **Use both:** datamitsu delivers the linters, moon runs them in optimal order.

## Documentation Style

### Code Examples

- **Always test examples** — Every code snippet must work
- **Use real-world scenarios** — Not "foo" and "bar"
- **Include expected output** — Show what users should see

### Formatting

- **Headings:** Sentence case ("How to configure tools")
- **Links:** Descriptive text, not "click here"
- **Admonitions:** `:::caution` for warnings, `:::danger` for destructive actions

## Core Messaging

**Tagline:** "Your toolchain deserves a home."

**One-line intro:** "datamitsu is a platform for building reproducible, security-first development tool distributions."

## Messaging by Audience

### For Platform Engineers

"Define the toolchain once. Distribute everywhere. Not scattered across 50 repos."

**Emphasize:** Toolchain distribution via npm/gem/pypi. Security policies (mandatory SHA-256). Version control as packages.

### For Development Teams

"Your company's toolchain in one package. No copy-paste configs. No manual setup."

**Emphasize:** Migration-free updates via patching. Override capabilities when needed. Docker-optimized CI.

### For Open Source Maintainers

"Ship the template with tools inside. Not a README telling people what to install."

**Emphasize:** Contributors get identical setup automatically. Version consistency enforced via package dependency.

---

## Creating Wrapper Packages


This guide explains how to build wrapper packages — the second level of datamitsu's architecture — to distribute standardized tool configurations to your team, company, or the open source community.

## What are Wrapper Packages?

Wrapper packages are language-specific packages (npm, gem, pypi, etc.) that bundle:

- Concrete tool versions and configurations
- Opinionated defaults for linters, formatters, and other tools
- Managed project files (configs, ignore files, etc.)
- Custom configuration logic in JavaScript/TypeScript

Think of wrappers as "datamitsu config distributions" — similar to how lefthook has npm/gem/pypi wrappers around its Go core.

## Two-Level Architecture

Understanding the architecture is crucial to building effective wrappers. To see how datamitsu executes tools internally, see [Architecture: Parallel Execution](../guides/architecture/execution.md).

### Level 1: The Core (datamitsu binary)

The `datamitsu` binary provides platform capabilities:

- Binary management with SHA-256 verification
- Programmable JavaScript configuration engine (goja)
- Config chaining with inheritance
- Tool operations (fix/lint/check)
- Safe managed-config reconciliation
- File patching engine

**The core does NOT provide:**

- Concrete tool versions
- Linter configurations
- Opinionated defaults

### Level 2: Wrappers (your package)

Your wrapper package provides:

- Full tool suite definitions (golangci-lint, eslint, prettier, etc.)
- Configured defaults for all tools
- Managed config files and generation rules
- Project type detection logic
- Custom config functions

## Distribution Model

```
datamitsu core (Go binary)
  ↓
  Installed globally or as dev dependency

Your wrapper package (@company/datamitsu-config)
  ↓
  Distributed via npm/gem/pypi
  Contains: tool versions, configs, managed config definitions

End-user projects
  ↓
  Install: npm install @company/dev-standards
  Config loads: datamitsu.config.ts (optional overrides)
  Run: datamitsu config reconcile && datamitsu lint
```

## Creating Your First Wrapper

### Step 1: Choose a Distribution Channel

Decide how you'll distribute your wrapper:

- **npm** — For JavaScript/TypeScript ecosystems (recommended for web projects)
- **gem** — For Ruby ecosystems
- **pypi** — For Python ecosystems
- **Multiple** — Publish the same config to multiple package managers

Example using npm:

```bash
mkdir my-datamitsu-config
cd my-datamitsu-config
npm init -y
```

### Step 2: Create the Configuration File

Create `config/datamitsu.config.js` (or `.ts`). Set `version` explicitly, or
populate it using your own build process. Datamitsu does not prescribe how
wrapper authors maintain this label.

```javascript
/**
 * @param {config.Config} prev
 * @returns {config.Config}
 */
function getConfig(prev) {
  return {
    ...prev,
    version: "1.0.0",
    apps: {
      ...prev.apps,
      // Define your tools here
      "golangci-lint": {
        binary: {
          binaries: {
            linux: {
              amd64: {
                glibc: {
                  url: "https://github.com/golangci/golangci-lint/releases/download/v1.55.0/golangci-lint-1.55.0-linux-amd64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "golangci-lint-1.55.0-linux-amd64/golangci-lint",
                },
              },
            },
            darwin: {
              amd64: {
                unknown: {
                  url: "https://github.com/golangci/golangci-lint/releases/download/v1.55.0/golangci-lint-1.55.0-darwin-amd64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "golangci-lint-1.55.0-darwin-amd64/golangci-lint",
                },
              },
              arm64: {
                unknown: {
                  url: "https://github.com/golangci/golangci-lint/releases/download/v1.55.0/golangci-lint-1.55.0-darwin-arm64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "golangci-lint-1.55.0-darwin-arm64/golangci-lint",
                },
              },
            },
          },
        },
      },
    },
    tools: {
      ...prev.tools,
      "golangci-lint": {
        name: "golangci-lint",
        operations: {
          lint: {
            app: "golangci-lint",
            args: ["run"],
            scope: "per-project",
          },
        },
        projectTypes: ["golang-package"],
      },
    },

    managedConfigs: {
      ...prev.managedConfigs,
      // Add managed config files
      ".golangci.yml": {
        content: () => `
linters:
  enable:
    - gofmt
    - govet
    - staticcheck
`,
      },
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### Step 3: Use the `--before-config` Flag

The `--before-config` flag tells datamitsu to load your wrapper config before auto-discovering `datamitsu.config.js` at the git root.

This enables the layering:

```
embedded default config (datamitsu core)
  ↓
--before-config (your wrapper) ← loaded first
  ↓
auto-discovered config (user's datamitsu.config.js) ← can override wrapper
  ↓
--config (explicit overrides)
```

### Step 4: Create a Binary Wrapper

Create `bin/datamitsu` (executable shell script):

```bash
#!/bin/sh
# Find the datamitsu binary
DATAMITSU_BIN=$(which datamitsu)

if [ -z "$DATAMITSU_BIN" ]; then
  echo "Error: datamitsu binary not found in PATH"
  exit 1
fi

# Get the directory of this script
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_DIR="$(dirname "$SCRIPT_DIR")/config"

# Execute datamitsu with our config loaded before user config
exec "$DATAMITSU_BIN" --before-config "$CONFIG_DIR/datamitsu.config.js" "$@"
```

Make it executable:

```bash
chmod +x bin/datamitsu
```

### Step 5: Configure package.json

```json
{
  "name": "@company/datamitsu-config",
  "version": "1.0.0",
  "description": "Company-wide datamitsu tool configurations",
  "bin": {
    "datamitsu": "./bin/datamitsu"
  },
  "files": ["bin/", "config/datamitsu.config.js"],
  "peerDependencies": {
    "datamitsu": "^0.1.0"
  },
  "keywords": ["datamitsu", "linting", "configuration", "tools"]
}
```

### Step 6: Publish Your Package

```bash
# Test locally first
npm link
cd ../test-project
npm link @company/datamitsu-config

# When ready, publish
npm publish
```

## Config Chaining and Inheritance

One of datamitsu's most powerful features is config chaining. Each config layer receives the previous layer as input.

### Extending a Base Config

```javascript
function getConfig(prev) {
  return {
    ...prev,
    apps: {
      ...prev.apps,
      // Add new tools
      prettier: {/* ... */},

      // Override existing tool
      "golangci-lint": {
        ...prev.apps["golangci-lint"],
        operations: {
          lint: {
            args: ["run", "--timeout=5m"], // Override args
          },
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

### Removing Tools

```javascript
function getConfig(prev) {
  const { unwantedTool, ...remainingApps } = prev.apps;

  return {
    ...prev,
    apps: remainingApps,
  };
}
globalThis.getConfig = getConfig;
```

### Conditional Configuration

Use JavaScript logic for dynamic configuration:

```javascript
function getConfig(prev) {
  const config = {
    ...prev,
    apps: { ...prev.apps },
  };

  // Add tools based on environment
  if (process.env.CI === "true") {
    config.apps["some-ci-tool"] = {/* ... */};
  }

  // Adjust settings based on OS
  if (process.platform === "darwin") {
    config.apps["golangci-lint"].operations.lint.args.push("--max-issues-per-linter=100");
  }

  return config;
}
globalThis.getConfig = getConfig;
```

## Remote Configs

Wrapper packages can reference remote configuration files for additional layering:

```javascript
/**
 * @returns {{ url: string; hash: string }[]}
 */
function getRemoteConfigs() {
  return [
    {
      url: "https://config.company.com/datamitsu/base.ts",
      hash: "sha256:abc123...", // canonical SHA-256 digest (mandatory)
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;

function getConfig(prev) {
  // prev includes the remote config merged in
  return {
    ...prev,
    // Your overrides here
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

Remote configs are resolved depth-first before your config is evaluated.

## Agent Prompts

datamitsu publishes two Markdown guides for AI agents through `sharedStorage`. The binary that evaluates the configuration produces both, so they always describe the version that loads it. The default configuration writes neither of them anywhere: your configuration decides where each one goes.

| Key                              | Written for                                                                                                                           | Where it belongs                                               |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `datamitsu-agent-prompt`         | Agents working in a repository that **uses** a datamitsu configuration                                                                | The agent instructions your wrapper ships to its consumers     |
| `datamitsu-config-author-prompt` | Agents working in a repository that **writes** one: a wrapper, or a project configuration that defines its own apps, tools or configs | The authoring repository only — never shipped to its consumers |

### Shipping the Consumer Prompt

Write the prompt into a project file through a managed config:

```javascript
function getConfig(input) {
  const agentPrompt = input.sharedStorage["datamitsu-agent-prompt"];

  return {
    ...input,
    managedConfigs: {
      ...input.managedConfigs,
      "AGENTS.md": {
        content: () => agentPrompt,
        scope: "git-root",
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

### Extending It with Custom Instructions

Create a bundle that combines the base prompt with company-specific guidance:

```javascript
function getConfig(input) {
  const basePrompt = input.sharedStorage["datamitsu-agent-prompt"];

  const customInstructions = `

## Company-Specific Guidelines

- Follow our coding standards at https://company.com/standards
- Always use our custom linter configurations
- Prefix commit messages with ticket numbers (e.g., "JIRA-123: Fix bug")
- Use TypeScript for all new JavaScript code
`;

  return {
    ...input,
    bundles: {
      ...input.bundles,
      "company-agents": {
        version: "1.0.0",
        files: {
          "AGENTS.md": basePrompt + customInstructions,
        },
        links: {
          "company-agents": "AGENTS.md",
        },
      },
    },
    managedConfigs: {
      ...input.managedConfigs,
      "AGENTS.md": {
        linkTarget: ".datamitsu/company-agents",
        scope: "git-root",
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

When datamitsu updates the prompt, `datamitsu init` rebuilds the bundle, so every project picks up the change without anyone syncing text by hand.

### Adding the Configuration-Author Guide

The configuration-author guide tells an agent how to write a layer correctly for this version of datamitsu: the JavaScript runtime, mandatory hashes and lock files, the `devtools pull-*` workflow, validation rules, and a list of recent changes a configuration should review. Because `datamitsu init` refreshes it on every upgrade, an agent working on your wrapper learns about new features from the binary itself.

Add it where the configuration is written. For a wrapper, that is the `datamitsu.config.*` at the wrapper repository's own git root — not the configuration the wrapper publishes, which would ship the guide to every consumer. Merge the bundle into that file's `getConfig`; the file keeps its own `getMinVersion()`, which every configuration must export:

```javascript
function getConfig(input) {
  return {
    ...input,
    bundles: {
      ...input.bundles,
      "config-author-guide": {
        files: {
          "datamitsu-config-author.md":
            input.sharedStorage?.["datamitsu-config-author-prompt"] ?? "",
        },
        links: {
          "ai/agents/datamitsu-config-author.md": "datamitsu-config-author.md",
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

After `datamitsu init`, point the repository's own agent instructions at it once:

```markdown
Before changing the datamitsu configuration, read [.datamitsu/ai/agents/datamitsu-config-author.md](.datamitsu/ai/agents/datamitsu-config-author.md).
```

A project whose own `datamitsu.config.*` defines apps, tools or managed configs can adopt it the same way.

## Testing Your Wrapper

### Local Testing

```bash
# In your wrapper directory
npm link

# In a test project
npm link @company/datamitsu-config

# Test commands
datamitsu init
datamitsu check
```

### CI Testing

Create a test project in your wrapper repo:

```
my-datamitsu-config/
├── config/
│   └── datamitsu.config.js
├── bin/
│   └── datamitsu
├── test-project/
│   ├── package.json (depends on your wrapper)
│   └── sample-files/
└── package.json
```

In CI:

```yaml
test:
  script:
    - npm install
    - cd test-project
    - datamitsu init
    - datamitsu check
```

## Versioning Strategy

### Semantic Versioning

Follow semver for your wrapper:

- **Major** — Breaking changes to config structure, removed tools
- **Minor** — New tools, new features, non-breaking changes
- **Patch** — Bug fixes, hash updates, documentation

### Example Changelog

```markdown
## 2.0.0 (Breaking)

- Removed deprecated `tslint` (use `eslint` instead)
- Changed `.prettierrc` format to use ES modules

## 1.5.0

- Added `hadolint` for Dockerfile linting
- Added `shellcheck` for shell script linting
- Updated `golangci-lint` to v1.55.0

## 1.4.1

- Updated `eslint` hash for security patch
- Fixed `prettier` args on Windows
```

## Publishing to Multiple Package Managers

You can publish the same config to npm, gem, and pypi simultaneously:

### npm (JavaScript)

```json
{
  "name": "@company/datamitsu-config",
  "bin": {
    "datamitsu": "./bin/datamitsu"
  }
}
```

### gem (Ruby)

```ruby
# datamitsu-config.gemspec
Gem::Specification.new do |spec|
  spec.name          = "datamitsu-config"
  spec.version       = "1.0.0"
  spec.executables   = ["datamitsu"]
end
```

### pypi (Python)

```python
# setup.py
setup(
    name="datamitsu-config",
    version="1.0.0",
    scripts=["bin/datamitsu"],
)
```

The config file and bin wrapper remain the same across all three.

## Real-World Example: shibanet0/datamitsu-config

The author maintains `shibanet0/datamitsu-config` as a reference wrapper:

- **npm package** — Distributed via npm for JavaScript projects
- **Full tool suite** — golangci-lint, prettier, eslint, shellcheck, hadolint, etc.
- **Project detection** — Detects Go, TypeScript, Rust, Dockerfile, etc.
- **Managed configs** — Symlinks for ESLint, Prettier configs
- **Remote configs** — Layers multiple config sources

[View source on GitHub](https://github.com/shibanet0/datamitsu-config)

## Best Practices

### Security

- **Always specify SHA-256 hashes** for all binaries (mandatory)
- **Pin exact versions** — Don't use "latest" or version ranges
- **Verify hashes** — Use `datamitsu devtools pull-releases --verify-extraction` during development
- **Keep hashes updated** — Monitor security advisories for tool updates

### Maintainability

- **Document your tools** — Explain why each tool is included
- **Keep configs organized** — Separate concerns (linting, formatting, git hooks)
- **Test on all platforms** — Ensure Linux, macOS, Windows support
- **Provide examples** — Show users how to override your defaults
- **Automate version updates** — For version update workflows, see [Maintaining Wrapper Packages](../how-to/maintain-wrapper.md)

### User Experience

- **Minimize required setup** — Pre-configure as much as possible
- **Support customization** — Users should be able to override any setting
- **Migration guides** — Document breaking changes clearly
- **Clear error messages** — Help users fix common issues

## Next Steps

- Read [Using Wrappers](../guides/using-wrappers.md) to understand the user experience
- See [Configuration API Reference](../reference/configuration-api.md) for complete config options
- Check out [Examples](../examples/multiple-versions.md) for advanced patterns
- Join discussions on [GitHub](https://github.com/datamitsu/datamitsu/discussions)

Building wrapper packages is how datamitsu achieves its mission: configuration standardization across teams and projects. Your wrapper becomes the single source of truth for how your team builds software.

---

## Contributing to datamitsu


Thank you for your interest in contributing to datamitsu! This project is in alpha stage and welcomes contributions from the community.

:::info[Alpha Stage]
datamitsu is in active development. The configuration API is not yet stabilized and may change between versions. Breaking changes are acceptable when they improve correctness, safety, or simplify architecture.
:::

## Ways to Contribute

### Code Contributions

Contribute to the core datamitsu platform:

- **Bug fixes** — Help identify and fix issues
- **Feature implementations** — Work on planned features from GitHub issues
- **Performance improvements** — Optimize binary downloads, cache handling, etc.
- **Platform support** — Add support for new OS/architecture combinations

**Getting started:**

1. Fork the repository on GitHub
2. Clone your fork: `git clone https://github.com/yourusername/datamitsu`
3. Create a feature branch: `git checkout -b feat/your-feature`
4. Make your changes and test them
5. Submit a pull request with a clear description

### Documentation Contributions

Improve the documentation:

- **Fix typos and errors** — Even small fixes help
- **Add examples** — Share how you use datamitsu
- **Write guides** — Help others solve common problems
- **Improve clarity** — Make complex topics easier to understand

All documentation lives in `website/docs/` and uses Docusaurus. See [Brand Guidelines](./brand-guidelines.md) for voice and style guidance.

### Wrapper Package Creation

Build and share wrapper packages for specific ecosystems:

- **Company standards** — Create internal tool configurations
- **Framework integrations** — Provide ready-to-use configs for frameworks
- **Language ecosystems** — Build opinionated defaults for Go, Rust, TypeScript, etc.

See [Creating Wrappers](./creating-wrappers.md) for a complete guide.

### Community Support

Help other users:

- **Answer questions** — On GitHub Discussions or issues
- **Share use cases** — Blog about how you use datamitsu
- **Report bugs** — Help us identify and fix problems
- **Provide feedback** — Share your experience and suggestions

## Development Setup

### Prerequisites

- Go 1.21 or later
- Node.js 20 or later (for website development)
- pnpm (for website dependencies)

### Building from Source

```bash
# Clone the repository
git clone https://github.com/datamitsu/datamitsu
cd datamitsu

# Build the binary
go build

# Run tests
go test ./...
```

### Working on Documentation

```bash
# Navigate to website directory
cd website

# Install dependencies
pnpm install

# Start development server
pnpm start

# Build for production
pnpm build
```

The documentation site will be available at `http://localhost:3000`.

#### Re-harvesting the embedded documentation

These same pages ship inside the binary, so that `datamitsu llms` can hand an AI
agent documentation that matches its exact version without network access. The
snapshot lives in `internal/llmsdocs/embed/` and is committed to git, which is
what keeps a plain `go build` free of any website toolchain.

After changing anything under `website/docs`, regenerate it:

```bash
task gen:llms-docs
git add internal/llmsdocs/embed
```

That rebuilds the site, harvests the cleaned Markdown that
`docusaurus-plugin-llms` emits, and rewrites the snapshot. CI re-runs the same
harvest on every pull request and fails if the result differs from what you
committed, so a stale snapshot cannot merge.

Two rules matter when touching the snapshot:

- **Never edit `internal/llmsdocs/embed/` by hand.** It is generated. The page
  bytes are hashed into `manifest.json`, and the tests verify that hash.
- **Never reformat it.** The pages are stored exactly as the plugin emitted
  them; `.datamitsuignore` excludes the directory from every tool for this
  reason.

## Contribution Guidelines

### Code Style

- **English-only** — All code, comments, and documentation must be in English
- **Minimal comments** — Code should be self-documenting; add comments only when necessary
- **Follow Go conventions** — Use `gofmt`, follow standard Go idioms
- **Security-first** — All binaries must have SHA-256 hashes; no exceptions

See CLAUDE.md for detailed code commenting guidelines.

### Documentation Style

- **English-only** — No exceptions
- **Clear and concise** — Avoid jargon; explain technical concepts clearly
- **Use examples** — Show, don't just tell
- **Maintain voice** — See [Brand Guidelines](./brand-guidelines.md)

### Commit Messages

Write clear, descriptive commit messages:

```
fix: address hash verification bug in binmanager

Add additional validation for empty hash strings before
downloading binaries. Prevents panic when config has
missing hash field.

Fixes #123
```

### Pull Request Process

1. **Ensure tests pass** — Run `go test ./...` before submitting
2. **Update documentation** — Document new features or API changes
3. **Keep PRs focused** — One feature or fix per PR
4. **Write clear descriptions** — Explain what and why, not just how
5. **Respond to feedback** — Be open to suggestions and changes

## Documentation Requirements

**All user-facing changes require documentation updates in the same PR.**

This includes:

- **User-facing features** → Update `website/docs/` with examples and guides
- **CLI commands** → Update `website/docs/reference/cli-commands.md`
- **Configuration options** → Update `website/docs/reference/configuration-api.md`
- **New examples** → Add to `website/docs/examples/`
- **Breaking changes** → Document migration path in docs and create blog post in `website/blog/`

Documentation is not optional — it is a required deliverable for every user-facing change.

## Project Resources

- **Repository:** [github.com/datamitsu/datamitsu](https://github.com/datamitsu/datamitsu)
- **Issues:** [GitHub Issues](https://github.com/datamitsu/datamitsu/issues)
- **Discussions:** [GitHub Discussions](https://github.com/datamitsu/datamitsu/discussions)
- **Documentation:** [datamitsu.com](https://datamitsu.com)

## Code of Conduct

Be respectful, constructive, and professional in all interactions. We aim to create a welcoming environment for contributors of all backgrounds and experience levels.

## Questions?

If you have questions about contributing:

- Open a [GitHub Discussion](https://github.com/datamitsu/datamitsu/discussions)
- Check existing [GitHub Issues](https://github.com/datamitsu/datamitsu/issues)
- Read the [documentation](https://datamitsu.com)

We appreciate your contributions!

---

## List your configuration


The [showcase](/showcase) lists configurations other people can inherit. Adding yours is one entry
in [`website/src/data/showcases.json`](https://github.com/datamitsu/datamitsu/edit/main/website/src/data/showcases.json)
and a pull request.

## What an entry needs

```json
{
  "added": "2026-09-21",
  "author": { "github": "your-handle", "name": "Your Name" },
  "consume": [{ "kind": "npm", "package": "@you/datamitsu-config" }],
  "description": "One sentence: what kinds of repositories this config is built for.",
  "id": "you-datamitsu-config",
  "links": { "repository": "https://github.com/you/datamitsu-config" },
  "name": "@you/datamitsu-config",
  "tags": ["go", "typescript"]
}
```

| Field         | Required | Notes                                                                        |
| ------------- | -------- | ---------------------------------------------------------------------------- |
| `id`          | yes      | Lowercase, unique, stable — it keys the derived data                         |
| `name`        | yes      | The listing title, usually the package name                                  |
| `author`      | yes      | Name and GitHub handle                                                       |
| `description` | yes      | One sentence, up to 200 characters                                           |
| `tags`        | yes      | From the schema's list, so stacks do not fragment into `ts` and `typescript` |
| `consume`     | yes      | How a reader actually uses it: `npm`, `pypi`, `gem`, `remote` or `oci`       |
| `links`       | yes      | `repository`, plus optional `site` and `inspector`                           |
| `dataset`     | no       | URL of your published resolved-config dataset (see below)                    |
| `added`       | yes      | The date of the pull request                                                 |

Fill only what is true. Leaving a field out is always better than guessing at it.

## A `remote` entry carries a hash

A reader executes what a `remote` entry points at, so its SHA-256 is mandatory and the pull request
downloads the file and verifies it:

```json
{
  "kind": "remote",
  "url": "https://github.com/you/datamitsu-config/releases/download/v1.2.0/datamitsu.config.js",
  "hash": "6fcd9a1edfaf713683380caa7fee64b9d5d40a2adec41db153ede44e230c74f7"
}
```

## Publish a dataset, and get a fingerprint

The showcase does not screenshot configurations — it draws each one's composition across runtimes as
a thin bar. That comes from a **dataset**: the resolved-config JSON the inspector's **Dataset**
button downloads, and which you can produce in CI:

```bash
datamitsu inspect --output - | grep -o '<script type="application/json" id="inspector-manifest">.*' # or
datamitsu inspect --output atlas.html
```

Publish it as a release asset next to your config and point `dataset` at the URL that follows your
latest release:

```
https://github.com/you/datamitsu-config/releases/latest/download/datamitsu-inspector-manifest.json
```

The dataset is **display data**: it is parsed and rendered as numbers and text, never executed, so it
is not pinned by hash — a weekly refresh would be pointless if the file could never change. What the
refresh job saw is recorded instead, in `showcases.generated.json`, where a changed composition shows
up in a diff. No dataset means no bar: an entry is never drawn with made-up proportions.

## What happens to your pull request

Automation checks the shape: the schema, the tag list, a valid GitHub handle, unique ids, every URL
reachable, every `remote` hash verified by download, and a dataset that parses as an inspector manifest.
It does not check intent — **listing is a maintainer's decision**, and an entry can be removed later.

A refresh job then keeps the derived half current: the latest release date, the last commit, and the
composition from your dataset. It runs weekly, opens a pull request with the regenerated file, and
never evaluates or runs a third-party configuration. An entry whose fetch fails keeps its previous
values and records the error rather than disappearing.

Star counts are collected but never shown and never sorted on: this is a directory of
configurations you can inherit, not a ranking. Freshness is the signal that protects a reader from
inheriting an abandoned configuration: an entry with no release in twelve months is marked, not
hidden. Search, sorting and the tag chips appear once there are six or more entries; below that the
page is short enough to read without them.

---

## Multiple Tool Versions


This example shows how to run ESLint v10 for most of your codebase while
keeping ESLint v9 with legacy plugins for a specific subdirectory.

## The Problem

A monorepo has modern code using flat config (`eslint.config.ts`) and a legacy
module still on `.eslintrc.js` with plugins that haven't been updated for
ESLint v10. You need both versions to coexist without interference.

## Configuration

### Runtimes

Define a managed Node runtime. Both ESLint versions will share the same
runtime binary but get completely isolated `node_modules` directories.

```typescript
const mapOfRuntimes: BinManager.MapOfRuntimes = {
  node: {
    kind: "node",
    mode: "managed",
    node: {
      nodeVersion: "26.2.0",
      pnpmRuntime: "pnpm",
    },
    managed: {
      binaries: {
        darwin: {
          amd64: {
            unknown: {
              contentType: "tar.xz",
              hash: "sha256:<digest>",
              url: "https://nodejs.org/dist/v26.2.0/node-v26.2.0-darwin-x64.tar.xz",
              binaryPath: "node-v26.2.0-darwin-x64/bin/node",
              extractDir: true,
            },
          },
          arm64: {
            unknown: {
              contentType: "tar.xz",
              hash: "sha256:<digest>",
              url: "https://nodejs.org/dist/v26.2.0/node-v26.2.0-darwin-arm64.tar.xz",
              binaryPath: "node-v26.2.0-darwin-arm64/bin/node",
              extractDir: true,
            },
          },
        },
        linux: {
          amd64: {
            glibc: {
              contentType: "tar.xz",
              hash: "sha256:<digest>",
              url: "https://nodejs.org/dist/v26.2.0/node-v26.2.0-linux-x64.tar.xz",
              binaryPath: "node-v26.2.0-linux-x64/bin/node",
              extractDir: true,
            },
            musl: {
              contentType: "tar.xz",
              hash: "sha256:<digest>",
              url: "https://unofficial-builds.nodejs.org/download/release/v26.2.0/node-v26.2.0-linux-x64-musl.tar.xz",
              binaryPath: "node-v26.2.0-linux-x64-musl/bin/node",
              extractDir: true,
            },
          },
        },
      },
    },
  },
  pnpm: {
    kind: "pnpm",
    mode: "managed",
    pnpm: { pnpmVersion: "12.4.1" },
    managed: {
      binaries: {
        // One SHA-256-pinned native pnpm archive per platform —
        // `datamitsu devtools pull-runtimes` generates it
      },
    },
  },
};
```

### Apps

Define two separate apps for the two ESLint versions. Each gets its own
isolated environment because the version (and dependencies) differ, producing
different store hashes.

```typescript
const mapOfApps: BinManager.MapOfApps = {
  // Modern ESLint v10 - no extra plugins needed
  eslint: {
    node: {
      packageName: "eslint",
      binPath: "node_modules/.bin/eslint",
      version: "10.0.0",
      lockFile: "br:<eslint-v10-lock>",
    },
  },

  // Legacy ESLint v9 with plugins that don't support v10 yet
  "eslint-legacy": {
    node: {
      packageName: "eslint",
      binPath: "node_modules/.bin/eslint",
      version: "9.17.0",
      lockFile: "br:<eslint-v9-lock>",
      dependencies: {
        "eslint-plugin-import": "2.31.0",
        "eslint-plugin-react": "7.37.3",
        "@typescript-eslint/eslint-plugin": "8.18.2",
        "@typescript-eslint/parser": "8.18.2",
      },
    },
  },
};
```

### Tools

Configure tools to target different file globs. The modern ESLint runs on
everything except the legacy module; the legacy version runs only on
`old-module/`.

```typescript
const toolsConfig: config.MapOfTools = {
  eslint: {
    name: "ESLint (Modern)",
    operations: {
      fix: {
        app: "eslint",
        args: ["--fix", "{files}"],
        scope: "per-project",
        globs: ["**/*.{ts,tsx,js,jsx}"],
        // Excludes handled by eslint.config.ts ignores
      },
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        globs: ["**/*.{ts,tsx,js,jsx}"],
      },
    },
    projectTypes: ["npm-package"],
  },

  "eslint-legacy": {
    name: "ESLint (Legacy)",
    operations: {
      fix: {
        app: "eslint-legacy",
        args: ["--fix", "{files}"],
        scope: "per-project",
        globs: ["old-module/**/*.{js,jsx}"],
      },
      lint: {
        app: "eslint-legacy",
        args: ["{files}"],
        scope: "per-project",
        globs: ["old-module/**/*.{js,jsx}"],
      },
    },
    projectTypes: ["npm-package"],
  },
};
```

## How Isolation Works

Each app's environment is stored under a hash-based path:

```
~/.cache/datamitsu/store/.apps/node/
  eslint/{hash-for-v10}/
    package.json          # {"dependencies": {"eslint": "10.0.0"}}
    node_modules/
      .bin/eslint         # ESLint v10 binary
      eslint/

  eslint-legacy/{hash-for-v9}/
    package.json          # {"dependencies": {"eslint": "9.17.0", ...plugins}}
    node_modules/
      .bin/eslint         # ESLint v9 binary
      eslint/
      eslint-plugin-import/
      eslint-plugin-react/
      @typescript-eslint/
```

The hash covers the app name, package/version, sorted dependencies, mandatory
lock file, app-provided files and archives, binary path, runtime identity, and
the resolved target. Changing any of these inputs produces a fresh environment.

## Cache Key Uniqueness

These configurations produce different cache keys because they differ in
version and dependencies:

| App           | Version | Dependencies | Hash        |
| ------------- | ------- | ------------ | ----------- |
| eslint        | 10.0.0  | (none)       | `a1b2c3...` |
| eslint-legacy | 9.17.0  | 4 plugins    | `d4e5f6...` |

Even if you had two apps with the same version but different dependencies,
they'd still get separate environments.

## Verification

After running `datamitsu init --all`:

```bash
# Both versions are installed in separate directories
ls ~/.cache/datamitsu/store/.apps/node/eslint/
ls ~/.cache/datamitsu/store/.apps/node/eslint-legacy/

# Each has its own node_modules with the correct version
datamitsu exec eslint -- --version
# v10.0.0

datamitsu exec eslint-legacy -- --version
# v9.17.0
```

## Different Runtime Versions

You can also use different runtime versions for the same tool type by defining
multiple runtimes:

```typescript
const mapOfRuntimes: BinManager.MapOfRuntimes = {
  "node-20": {
    kind: "node",
    mode: "managed",
    node: {
      nodeVersion: "20.18.0",
      pnpmRuntime: "pnpm",
    },
    managed: {
      binaries: {
        // node archive binaries...
      },
    },
  },
  "node-22": {
    kind: "node",
    mode: "managed",
    node: {
      nodeVersion: "22.12.0",
      pnpmRuntime: "pnpm",
    },
    managed: {
      binaries: {
        // node archive binaries...
      },
    },
  },
  // ...plus the "pnpm" runtime from the first example, shared by both
};

const mapOfApps: BinManager.MapOfApps = {
  eslint: {
    node: {
      packageName: "eslint",
      binPath: "node_modules/.bin/eslint",
      version: "10.0.0",
      runtime: "node-22", // Explicit runtime reference
      lockFile: "br:<eslint-node-22-lock>",
    },
  },
  "eslint-legacy": {
    node: {
      packageName: "eslint",
      binPath: "node_modules/.bin/eslint",
      version: "9.17.0",
      runtime: "node-20", // Uses the older Node.js
      lockFile: "br:<eslint-node-20-lock>",
    },
  },
};
```

When `runtime` is omitted, datamitsu uses the default runtime of the matching
kind (the first `node`-kind runtime it finds). Use explicit `runtime` references
when you need a specific version.

---

## PNPM Patterns

# PNPM Multi-Package Patterns

Examples of managing Node.js tools that require plugins or peer dependencies.

## Basic PNPM App

A simple Node.js tool with no extra dependencies:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  mmdc: {
    node: {
      packageName: "@mermaid-js/mermaid-cli",
      binPath: "node_modules/.bin/mmdc",
      version: "11.12.0",
      lockFile: "br:...",
    },
  },
};
```

This generates a `package.json` in the isolated environment:

```json
{
  "dependencies": {
    "@mermaid-js/mermaid-cli": "11.12.0"
  }
}
```

## Apps with Plugin Dependencies

Many Node.js tools rely on plugins installed as siblings in `node_modules`.
Use the `dependencies` field to install them together:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  eslint: {
    node: {
      packageName: "eslint",
      binPath: "node_modules/.bin/eslint",
      version: "9.17.0",
      lockFile: "br:...",
      dependencies: {
        "eslint-plugin-import": "2.31.0",
        "eslint-plugin-react": "7.37.3",
        "@typescript-eslint/eslint-plugin": "8.18.2",
        "@typescript-eslint/parser": "8.18.2",
      },
    },
  },
};
```

Generated `package.json`:

```json
{
  "dependencies": {
    "eslint": "9.17.0",
    "eslint-plugin-import": "2.31.0",
    "eslint-plugin-react": "7.37.3",
    "@typescript-eslint/eslint-plugin": "8.18.2",
    "@typescript-eslint/parser": "8.18.2"
  }
}
```

All packages are installed in the same `node_modules`, so ESLint can discover
its plugins through normal Node.js resolution.

## Spectral with Custom Rulesets

Spectral (OpenAPI linter) often needs custom ruleset packages:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  spectral: {
    node: {
      packageName: "@stoplight/spectral-cli",
      binPath: "node_modules/.bin/spectral",
      version: "6.14.2",
      lockFile: "br:...",
      dependencies: {
        "@stoplight/spectral-owasp-ruleset": "2.0.1",
      },
    },
  },
};
```

## Mandatory Lock Files

Every node app must pin its exact dependency tree with a `lockFile`. A normal
config load fails before any download if the field is absent:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  eslint: {
    node: {
      packageName: "eslint",
      binPath: "node_modules/.bin/eslint",
      version: "10.0.0",
      lockFile: "br:...", // brotli-compressed lock file content
    },
  },
};
```

For every Bun or Node app:

- PNPM runs with `--frozen-lockfile`, refusing to modify `pnpm-lock.yaml`
- The lock file content is written to the app directory before installation
- Content prefixed with `br:` is brotli-compressed and base64-encoded

To bootstrap lock file content:

1. Declare the app's package, version, dependencies, and binary path.
2. Run `datamitsu config lockfile <appName>`.
3. Add the output to the app's `lockFile` field.

The generation command deliberately permits a missing `lockFile`; every other
config load requires it.

## Workspace Overrides for Packages with Build Scripts

datamitsu writes a secure `pnpm-workspace.yaml` automatically before every Bun- or Node-app
install. When a package legitimately needs to run a build script — common
offenders include `puppeteer`, `sharp`, `esbuild`, and native modules — installs
fail with `ERR_PNPM_IGNORED_BUILDS`. Allowlist the package via
`App.files["pnpm-workspace.yaml"]`; your overrides are shallow-merged on top of
the secure baseline, so unspecified keys keep their hardened values.

```typescript
const mapOfApps: BinManager.MapOfApps = {
  mmdc: {
    files: {
      "pnpm-workspace.yaml": YAML.stringify({
        allowBuilds: { puppeteer: true },
      }),
    },
    node: {
      packageName: "@mermaid-js/mermaid-cli",
      binPath: "node_modules/.bin/mmdc",
      version: "11.15.0",
      lockFile: "br:...",
    },
  },
};
```

After adding `allowBuilds`, regenerate the lock file so pnpm records the approval:

```bash
pnpm exec datamitsu config lockfile mmdc
```

User-supplied keys always win on conflicts. Setting `strictDepBuilds: false` would
override the default — only do this if you fully trust every transitive dependency.

For the full list of baseline settings, the rationale behind each, and the
merged YAML format, see the
[Supply Chain Security guide](../guides/supply-chain-security.md#pnpm-bun-and-node-apps).

## PNPM Store Isolation

Each app has an isolated workspace and virtual store, while package content is
deduplicated in one shared content-addressable store:

```
~/.cache/datamitsu/store/
  .apps/node/eslint/{hash}/
    package.json
    pnpm-lock.yaml
    node_modules/
      .bin/eslint        # Executable symlink
      .pnpm/             # App-local virtual store
      eslint/
      eslint-plugin-*/
  .pnpm-store/           # Shared content-addressable package store
```

PNPM's content-addressable store means identical packages across apps are
hard-linked rather than duplicated, saving disk space while maintaining
isolation.

## Environment Variables

datamitsu sets these PNPM environment variables for isolation:

- `npm_config_store_dir` - PNPM content-addressable store location
- `npm_config_virtual_store_dir` - Virtual store for the project
- `npm_config_global_dir` - Global packages directory

These prevent any interference with system-level PNPM configurations.

---

## UV Isolation

# UV Isolation Patterns

Examples of managing Python tools with UV runtime isolation.

## Basic UV App

A Python linter installed via UV with version pinning:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  yamllint: {
    uv: {
      packageName: "yamllint",
      version: "1.38.0",
      lockFile: "br:...",
    },
  },
};
```

This creates an isolated UV tool environment at:

```
~/.cache/datamitsu/store/.apps/uv/yamllint/{hash}/
```

UV environment variables are set automatically:

- `UV_CACHE_DIR` - UV's download cache (per-app, under the app dir)
- `UV_PYTHON_INSTALL_DIR` - the managed CPython location, redirected into the store at `<store>/.uv/python/` (shared per-version) so the cached store is self-contained and each app's `.venv/bin/python` symlink resolves after a cache restore

## Mandatory Lock File

Every UV app must provide a `lockFile`. Normal config loading fails before any
download when it is absent. The field contains the app's `uv.lock` content:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  yamllint: {
    uv: {
      packageName: "yamllint",
      version: "1.38.0",
      lockFile: "br:...", // brotli-compressed lock file content
    },
  },
};
```

For every UV app:

1. The lock file content is written to the app directory as `uv.lock`
2. UV runs with `--locked --no-build`, refusing to modify `uv.lock` or build an
   sdist
3. Content prefixed with `br:` is brotli-compressed and base64-encoded
4. The lock records hashes for the resolved artifacts, catching changes where the same version resolves to
   different transitive dependencies
5. The install passes back the release-age window the lock recorded, and runs
   with `--no-config` (or the app's own `uv.toml`), so a user's uv settings
   cannot change it. See
   [Release Age of Transitive Dependencies](../guides/supply-chain-security.md#release-age-of-transitive-dependencies)

To bootstrap one, first declare the package name and version, then run
`datamitsu config lockfile <appName>` and paste its output into `lockFile`. That
command deliberately permits the missing field while generating it; normal
commands do not.

## Multiple Python Tools

Each Python tool gets its own isolated environment:

```typescript
const mapOfApps: BinManager.MapOfApps = {
  yamllint: {
    uv: { packageName: "yamllint", version: "1.37.1", lockFile: "br:..." },
  },
  ruff: {
    uv: { packageName: "ruff", version: "0.8.6", lockFile: "br:..." },
  },
  mypy: {
    uv: { packageName: "mypy", version: "1.14.1", lockFile: "br:..." },
  },
};
```

Store structure:

```
~/.cache/datamitsu/store/.apps/uv/
  yamllint/{hash-a}/    # yamllint + its dependencies
  ruff/{hash-b}/        # ruff + its dependencies
  mypy/{hash-c}/        # mypy + its dependencies
```

No dependency conflicts between tools - each has its own virtual environment.

## System UV Fallback

If you prefer to use a system-installed UV instead of the managed binary:

```typescript
const mapOfRuntimes: BinManager.MapOfRuntimes = {
  uv: {
    kind: "uv",
    mode: "system",
    system: {
      command: "uv",
    },
  },
};
```

This uses the `uv` command from your PATH. The app isolation still works
the same way - only the runtime binary source changes.

## Using UV Tools in Tool Definitions

```typescript
const toolsConfig: config.MapOfTools = {
  yamllint: {
    name: "yamllint",
    operations: {
      lint: {
        app: "yamllint",
        args: ["-f", "parsable", "{files}"],
        scope: "per-file",
        globs: ["**/*.yml", "**/*.yaml"],
      },
    },
  },
};
```

---

## Core Concepts


datamitsu is built around five core concepts: binary management, runtime management, managed configs, the tooling system, and configuration layers.

## Binary Management

datamitsu downloads, verifies, and stores tool binaries per platform. Every binary must have a SHA-256 hash — datamitsu refuses to download anything without one.

Binaries are kept at `~/.cache/datamitsu/store/.bin/{name}/{configHash}` and reused across runs. The internal store key is derived from the binary info and resolved target, so changing a version, hash, OS, architecture, or libc selects a fresh entry.

Supported archive formats include: `tar.gz`, `tar.xz`, `tar.bz2`, `tar.zst`, `zip`, and raw binaries.

### App Types

datamitsu supports seven types of applications:

| Type     | Description                                | Example Tools                       |
| -------- | ------------------------------------------ | ----------------------------------- |
| `binary` | Self-managed binaries with URLs and hashes | golangci-lint, hadolint, shellcheck |
| `bun`    | npm packages installed and run with Bun    | eslint                              |
| `uv`     | Python packages via managed UV runtime     | yamllint, ruff                      |
| `node`   | npm packages via managed Node.js + pnpm    | eslint, prettier, spectral          |
| `jvm`    | JVM applications via managed JDK           | openapi-generator-cli               |
| `go`     | Go tools built from source via managed SDK | govulncheck                         |
| `shell`  | Shell commands with custom environment     | custom scripts                      |

## Runtime Management

For tools that need a language runtime (Bun, Python, Node.js, Java, or Go), datamitsu manages the runtime itself. This provides complete isolation — each app gets its own environment with pinned dependencies.

### How Runtimes Work

1. **Managed mode** — datamitsu downloads the runtime binary (Bun, UV, Node.js, JDK, or Go SDK) with hash verification
2. **System mode** — Uses a runtime already installed on your system

Each runtime-managed app gets an isolated directory at
`~/.cache/datamitsu/store/.apps/{kind}/{app}/{hash}/`. The internal key includes
the effective runtime and app configuration, lock and managed-content inputs,
and applicable target dimensions (OS, architecture, and libc), so a relevant
change produces a fresh environment.

### Runtime Types

- **Bun** — Downloads and verifies a pinned Bun archive, runs the shared pnpm installer with Bun, and executes JavaScript entrypoints with Bun
- **UV** (Python) — Downloads UV, optionally pins a Python version, creates an isolated project environment with `pyproject.toml` + `uv sync`
- **Node** (Node.js) — Downloads and verifies (SHA-256) a pinned Node.js archive and extracts it, downloads pnpm from the npm registry, runs `pnpm install` in isolated app directories
- **JVM** (Java) — Downloads Temurin JDK, extracts the full JDK tree, downloads JAR files with hash verification, executes via `java -jar`
- **Go** — Downloads and verifies (SHA-256) a pinned Go SDK, builds tools from source with `go build -trimpath -mod=readonly` against a `go.mod` + `go.sum` lock file

### Lock Files

Bun, Node, UV, and Go apps require lock files (`pnpm-lock.yaml` for both JavaScript runtimes,
`uv.lock`, or a `go.mod` + `go.sum` payload). Normal config loading rejects a runtime-managed
app without one. Lock content can be embedded compactly with brotli compression.

Generate a lock file:

```bash
datamitsu config lockfile <appName>
```

## Managed Configs

datamitsu can distribute configuration files from runtime-managed apps to your project via symlinks in a `.datamitsu/` directory at your git root.

Apps declare what files they expose through `Links`:

```typescript
"eslint-config": {
  node: {
    packageName: "@company/eslint-config",
    binPath: "node_modules/.bin/eslint",
    version: "1.0.0",
    lockFile: "br:...",
  },
  links: {
    "eslint-config": "dist/eslint.config.js",
  },
}
```

After running `datamitsu init`, a symlink is created at `.datamitsu/eslint-config` pointing to the file inside the app's install directory. Your project configs can then reference it:

```typescript
// eslint.config.ts

export default config;
```

The `tools.Config.linkPath()` and `tools.Path.forImport()` JS APIs help generate correct relative paths in config files.

## Tooling System

datamitsu runs **fix** and **lint** operations on your code. Tools are configured with glob patterns, scope, and commands.

### Scopes

- **per-file** — Tool runs once per matched file (e.g., `hadolint {file}`)
- **per-project** — Tool runs once per detected project in a monorepo (e.g., `eslint {files}`)
- **repository** — Tool runs once from git root (e.g., `golangci-lint` with `scope: repository`)

### Operations

```typescript
const tools = {
  eslint: {
    name: "ESLint",
    operations: {
      fix: {
        app: "eslint",
        args: ["--fix", "{files}"],
        scope: "per-project",
        globs: ["**/*.{ts,tsx,js,jsx}"],
      },
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        globs: ["**/*.{ts,tsx,js,jsx}"],
      },
    },
    projectTypes: ["npm-package"],
  },
};
```

### Template Placeholders

Tool arguments support placeholders that resolve at execution time:

| Placeholder   | Resolves To                           |
| ------------- | ------------------------------------- |
| `{file}`      | Single file path (per-file scope)     |
| `{files}`     | Separate arguments per file           |
| `{root}`      | Git repository root                   |
| `{cwd}`       | Per-project working directory         |
| `{toolCache}` | Per-project, per-tool cache directory |

### Ignore Rules

Use `.datamitsuignore` files to disable specific tools for matching file patterns:

```
vendor/**/*: golangci-lint, gofmt
*.generated.ts: eslint, prettier
```

## Configuration Layers

datamitsu loads configuration in layers, each receiving the previous result:

```mermaid
graph TD
    A[defaultembedded config.js] --> B{getRemoteConfigsexported?}
    B -->|yes| C[resolve remote configsdepth-first]
    B -->|no| D[--before-config flagsfor library wrappers]
    C --> D

    D --> E{getRemoteConfigsexported?}
    E -->|yes| F[resolve remote configsdepth-first]
    E -->|no| BC[declared before-configsauto config's getBeforeConfigsskipped if --before-config flag set]
    F --> BC

    BC --> BCE{getRemoteConfigsexported?}
    BCE -->|yes| BCF[resolve remote configsdepth-first]
    BCE -->|no| G[datamitsu.config.tsat git root]
    BCF --> G

    G --> H{getRemoteConfigsexported?}
    H -->|yes| I[resolve remote configsdepth-first]
    H -->|no| J[--config flagsfor CI/testing overrides]
    I --> J

    J --> K[final Config]
```

Every config file must export `getMinVersion()` (the minimum datamitsu core version, as semver) and `getConfig(prev)` (the layer transform). The final resolved config also requires a top-level `version`: a nonempty, single-line label of at most 80 characters, without surrounding whitespace. It may be a release version or a static label such as `core`; semver is not required. Layers inherit and may override this scalar, independently of `getMinVersion()`.

Your git-root config can also export `getBeforeConfigs()` to declare local under-layers — the config-declared equivalent of `--before-config`. This lets a globally installed datamitsu load a shared wrapper config without the flag. It is skipped when `--before-config` is passed (the flag wins). See [Configuration → Declared Before-Configs](../guides/configuration.md#declared-before-configs-getbeforeconfigs).

### Remote Configs

Any config can declare parent configs it inherits from:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getRemoteConfigs() {
  return [
    {
      url: "https://example.com/shared-base.ts",
      hash: "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;
```

Remote configs require a SHA-256 hash (mandatory) and are cached locally; cache validity is determined by hash match (no TTL).

## Monorepo Support

datamitsu is designed for monorepos. It detects project boundaries by looking for markers like `package.json`, `go.mod`, `Cargo.toml`, and `pyproject.toml`.

Each project gets:

- **Isolated cache** at `~/.cache/datamitsu/cache/projects/{hash}/cache/{projectPath}/{toolName}/`
- **Scoped tool execution** in the project's working directory
- **Independent configuration** via managed config links

When running from a subdirectory, datamitsu restricts its scope to projects within that subtree.

## Next Steps

- [Configuration Guide](../guides/configuration.md) — Deep dive into config files and options
- [Binary Management Guide](../guides/binary-management.md) — Managing tool binaries in detail
- [Runtime Management Guide](../guides/runtime-management.md) — Bun, UV, Node, JVM, and Go runtimes

---

## Docker


Official images are published to both registries on every stable release:

- **Docker Hub** — `docker.io/datamitsu/datamitsu`
- **GitHub Container Registry** — `ghcr.io/datamitsu/datamitsu`

```bash
docker run --rm -v "$PWD:/workspace" datamitsu/datamitsu:latest lint
```

The image's entrypoint is the `datamitsu` binary, the working directory is
`/workspace`, and it runs as a non-root `datamitsu` user (UID 1000). Mount your
project at `/workspace` and pass any CLI command as arguments.

## Variants

- **Debian** (default) — glibc-based, e.g. `datamitsu/datamitsu:latest`
- **Alpine** — musl-based, suffixed `-alpine`, e.g. `datamitsu/datamitsu:latest-alpine`

## Tags

| Tag                    | Meaning                            |
| ---------------------- | ---------------------------------- |
| `latest`               | Latest stable release              |
| `stable`               | Latest stable release (alias)      |
| `0.1.13` / `0.1` / `0` | Pinned semver (full, minor, major) |
| `unstable`             | Latest unstable build (Docker Hub) |

Unstable builds are also published to `ghcr.io/datamitsu/datamitsu-unstable`.

Both `linux/amd64` and `linux/arm64` are supported via multi-arch manifests.

## Examples

```bash
# Lint the current project (pinned version, GHCR)
docker run --rm -v "$PWD:/workspace" ghcr.io/datamitsu/datamitsu:0.1.13 lint

# Fix formatting in place
docker run --rm -v "$PWD:/workspace" datamitsu/datamitsu:latest fix

# Inspect the effective runtime configuration
docker run --rm datamitsu/datamitsu:latest config runtime
```

:::tip
Tool downloads land in the container's datamitsu store and are lost when the
container exits. For repeated runs, persist the store with an extra volume:
`-v datamitsu-store:/home/datamitsu/.cache/datamitsu`.
:::

---

## GitHub Releases


Every stable release on the
[releases page](https://github.com/datamitsu/datamitsu/releases) ships:

- **Archives** — `datamitsu_<version>_<os>_<arch>.tar.gz` (Linux, macOS) and
  `.zip` (Windows) for `amd64` and `arm64`
- **Linux packages** — `.deb`, `.rpm`, and `.apk`
- **`checksums.txt`** — SHA-256 of every asset, plus
  `checksums.txt.sigstore.json`, its keyless
  [cosign](https://docs.sigstore.dev/) signature
- **SBOMs** — one per archive
- **`datamitsu_parsers_<version>.wasm`** — the parser module, downloaded by the
  CLI on demand and verified against the SHA-256 the config pins (the value
  `checksums.txt` records). This asset is one of two channels: the same module
  is also published as an OCI artifact at
  `ghcr.io/datamitsu/datamitsu-parsers`, which a config can pin instead — see
  [Output Parsers](../../reference/configuration-api.md#output-parsers-parsers)
- **`datamitsu-<version>.vsix`** — the [VS Code extension](./vscode.md) for
  manual installs

## Verify the release manifest

Obtain the SHA-256 values for the checksum manifest and its Sigstore bundle from
an independently authenticated release announcement or mirror manifest. If
either value is unavailable, stop: do not download or process that artifact.
Verify both files before asking Cosign to authenticate the manifest:

```bash
VERSION=0.2.1
CHECKSUMS_SHA256="<trusted-sha256-for-checksums.txt>"
SIGSTORE_BUNDLE_SHA256="<trusted-sha256-for-checksums.txt.sigstore.json>"
curl --fail --location --remote-name \
  "https://github.com/datamitsu/datamitsu/releases/download/v${VERSION}/checksums.txt"
curl --fail --location --remote-name \
  "https://github.com/datamitsu/datamitsu/releases/download/v${VERSION}/checksums.txt.sigstore.json"
printf '%s  %s\n' "$CHECKSUMS_SHA256" checksums.txt | sha256sum --check -
printf '%s  %s\n' "$SIGSTORE_BUNDLE_SHA256" checksums.txt.sigstore.json | sha256sum --check -
cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/datamitsu/datamitsu/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt
```

## Binary archive

Select the asset and extract its expected SHA-256 from the authenticated
manifest **before** downloading it. Verify the bytes before extraction:

```bash
ASSET="datamitsu_${VERSION}_linux_amd64.tar.gz"
EXPECTED_SHA256=$(awk -v asset="$ASSET" '$2 == asset { print $1 }' checksums.txt)
test "${#EXPECTED_SHA256}" -eq 64

curl --fail --location --remote-name \
  "https://github.com/datamitsu/datamitsu/releases/download/v${VERSION}/${ASSET}"
printf '%s  %s\n' "$EXPECTED_SHA256" "$ASSET" | sha256sum --check -
tar -xzf "$ASSET"
sudo install -m 0755 datamitsu /usr/local/bin/datamitsu
```

## Linux packages

Download the selected package only after obtaining its SHA-256 from the verified
manifest above, and run the same `sha256sum --check -` step before installing it:

```bash
# Debian / Ubuntu
sudo dpkg -i datamitsu_${VERSION}_linux_amd64.deb

# Fedora / RHEL
sudo rpm -i datamitsu_${VERSION}_linux_amd64.rpm

# Alpine
sudo apk add --allow-untrusted datamitsu_${VERSION}_linux_amd64.apk
```

## Unstable prereleases

Unstable builds are dispatched by hand (Actions > Release) and the GitHub
prerelease is an opt-in checkbox on that form, off by default. When it is
ticked, the prerelease carries the archives, `checksums.txt` with its cosign
bundle, the `.wasm` parser module built from that commit, and
`parsers-oci.json` — the registry pin (`ref`, `digest`, `sha256`) for that same
module, which every unstable build publishes to
`ghcr.io/datamitsu/datamitsu-parsers-unstable`. These builds exist for testing
something that has not shipped yet; install one only for that.

## Verify provenance

Release artifacts also carry
[GitHub build provenance attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations):

```bash
gh attestation verify datamitsu_${VERSION}_linux_amd64.tar.gz --repo datamitsu/datamitsu
```

See [Supply Chain Security](../../guides/supply-chain-security.md) for the full
verification model.

---

## Homebrew

# Homebrew (macOS / Linux)

```bash
brew tap datamitsu/tap
brew install datamitsu
```

To upgrade to the latest version:

```bash
brew upgrade datamitsu
```

---

## Installation


## Prerequisites

- **Git** — datamitsu uses your git root to locate configuration files and manage project-scoped caches
- **Platform support**: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64, arm64). Windows requires Developer Mode for symlinks.

## Install Methods

- [Homebrew](./homebrew.md) — macOS and Linux
- [Winget](./winget.md) — Windows
- [Scoop](./scoop.md) — Windows
- [npm](./npm.md) — any platform with Node.js
- [PyPI](./pypi.md) — any platform with Python
- [RubyGems](./rubygems.md) — any platform with Ruby
- [Docker](./docker.md) — official images on Docker Hub and GHCR (Debian and Alpine variants)
- [GitHub Releases](./github-releases.md) — direct binary downloads, deb/rpm/apk packages, checksum + cosign verification
- [Build from Source](./source.md) — requires Go 1.25.2+

## CI

- [GitHub Actions](../../how-to/use-in-github-actions.md) — the official `setup-datamitsu` action installs the CLI, provisions tools, and runs your checks in a single step

## Editor Integrations

- [VS Code Extension](./vscode.md) — Datamitsu Toolkit for VS Code, Cursor,
  Windsurf, VSCodium, and other VS Code-based editors: format on save with your
  datamitsu config. Works standalone too — if no `datamitsu` is on `PATH`, it
  downloads a pinned, SHA-256-verified binary.

## Verify Installation

Check that datamitsu is available:

```bash
datamitsu --help
```

You should see the available commands listed, including `exec`, `init`, `check`,
and `config`. Managed project files are handled by the explicit
`config reconcile` subcommand; use `config reconcile --dry-run` to preview them.

## Global Cache Directory

datamitsu stores data under `~/.cache/datamitsu/` (or `$XDG_CACHE_HOME/datamitsu/`), split into two subdirectories:

- **`store/`** — Downloaded binaries (`.bin/`), runtimes (`.runtimes/`),
  runtime-managed apps (`.apps/`), bundles (`.bundles/`), WASM parsers
  (`.parsers/`), remote configs (`.remote-configs/`), and package-manager data
- **`cache/`** — Per-repository execution state/source farms (`projects/`),
  machine-level farms (`configs/`), evaluated config chains (`config-eval/`),
  traces, and verification state

You can view the cache path with:

```bash
datamitsu cache path
```

## Next Steps

- [Quick Start](../quick-start.md) — Create your first configuration and run tools
- [Core Concepts](../core-concepts.md) — Understand how datamitsu manages tools

---

## npm


```bash
npm install -g @datamitsu/datamitsu
```

Or run directly without installing:

```bash
npx @datamitsu/datamitsu --help
```

---

## PyPI

# PyPI (pip / uv)

Install with pip:

```bash
pip install datamitsu
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install datamitsu
```

For a global CLI tool, use [pipx](https://pipx.pypa.io/) or [uv tool](https://docs.astral.sh/uv/guides/tools/):

```bash
pipx install datamitsu
# or
uv tool install datamitsu
```

---

## RubyGems

# RubyGems (gem)

Install with gem:

```bash
gem install datamitsu
```

Or add to your Gemfile:

```ruby
gem "datamitsu"
```

Then run:

```bash
bundle install
```

---

## Scoop

# Scoop (Windows)

Add the datamitsu bucket and install:

```powershell
scoop bucket add datamitsu https://github.com/datamitsu/scoop-bucket.git
scoop install datamitsu
```

To upgrade to the latest version:

```powershell
scoop update datamitsu
```

---

## Build from Source


Requires **Go 1.25.2+**.

Clone the repository and build:

```bash
git clone https://github.com/datamitsu/datamitsu.git
cd datamitsu
go build
```

This produces a `datamitsu` binary in the current directory. Move it to a directory in your `PATH`:

```bash
mv datamitsu /usr/local/bin/
```

## Using pnpm

If you have pnpm installed, you can also build via:

```bash
pnpm build
```

---

## VS Code Extension


[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/datamitsu.datamitsu-toolkit?label=VS%20Code%20Marketplace&color=0066b8)](https://marketplace.visualstudio.com/items?itemName=datamitsu.datamitsu-toolkit)
[![Open VSX](https://img.shields.io/open-vsx/v/datamitsu/datamitsu-toolkit?label=Open%20VSX&color=a60ee5)](https://open-vsx.org/extension/datamitsu/datamitsu-toolkit)

**Datamitsu Toolkit** brings datamitsu into your editor: "Format Document" and
format-on-save run your project's fix tools on the real file — the exact same
formatters as `datamitsu fix` on the command line, driven by one config.

The extension is a thin client around `datamitsu lsp`. It does not bundle any
formatters or reimplement any formatting logic: it starts the language server,
registers it as a document formatter, and shows long-running work (tool
downloads, installs, tool runs) in the status bar.

## Install

- **VS Code** — install [Datamitsu Toolkit from the Marketplace](https://marketplace.visualstudio.com/items?itemName=datamitsu.datamitsu-toolkit),
  or search for "Datamitsu Toolkit" in the Extensions view (`Ctrl+Shift+X`).
- **Cursor, Windsurf, VSCodium, and other VS Code-based editors** — install
  [Datamitsu Toolkit from Open VSX](https://open-vsx.org/extension/datamitsu/datamitsu-toolkit),
  the registry these editors use. Searching "Datamitsu Toolkit" in the editor's
  Extensions view finds the same extension.

Or from the command line:

```bash
code --install-extension datamitsu.datamitsu-toolkit
```

## Requirements

A `datamitsu` binary. By default the extension uses one found on your `PATH`; if
there is none, it downloads the version pinned to the extension build and
verifies it by SHA-256 before running it.

The extension activates only in a workspace that has a datamitsu config
(`datamitsu.config.js`, `datamitsu.config.mjs`, or `datamitsu.config.ts`).

## The repository it serves

The language server serves one repository: the one that holds the window's
first folder. A folder inside a submodule is served by its superproject, as the
CLI does. The output channel names the repository when the server starts, next
to the format policy.

- In a multi-root window, a folder that belongs to another repository is not
  formatted, and the output channel says so once for each such folder.
- A file outside the served repository is left alone: formatting it makes no
  edits, and the output channel notes it once per file.

If the server finds no repository, or the config does not load, it keeps
running: the output channel shows the error, and formatting makes no edits. Once
the config is fixed, the next format picks it up.

## Usage

Both triggers run your project's fix tools on the real file — which ones is
described in [What runs on save](#what-runs-on-save):

- **Format Document** (`Shift+Alt+F`), or set datamitsu as the default formatter.
- **On save** — enable format-on-save and pick datamitsu as the formatter:

```jsonc
{
  "editor.formatOnSave": true,
  "[go]": { "editor.defaultFormatter": "datamitsu.datamitsu-toolkit" },
  "[typescript]": { "editor.defaultFormatter": "datamitsu.datamitsu-toolkit" },
}
```

Because datamitsu's fix tools edit files in place, formatting runs on the file
on disk and therefore also saves it. A buffer with unsaved changes is written
first, and the edits the editor receives are the diff between that buffer and
the fixed result. A buffer that already matched the file on disk receives no
edits: the file is fixed in place and the editor reloads it. Either way the
editor stays in sync.

## What runs on save

Every fix operation has a
[granularity](../../reference/configuration-api.md#granularity) — the smallest
set of files its result is complete for — and that decides whether a save runs
it:

| Granularity | Example         | On save                                                                          |
| ----------- | --------------- | -------------------------------------------------------------------------------- |
| `file`      | prettier, shfmt | Always, on the saved file only                                                   |
| `unit`      | golangci-lint   | Over the saved file's project, unless `widenTo` is `target` or it has no `globs` |
| `repo`      | syncpack        | Never: a repository-wide fix does not run on save, `datamitsu fix` runs it       |

A save never runs a tool over another project: only the project that contains
the saved file is in reach.

Three controls adjust this. A `false` from the config or from
`datamitsu.format.tools` always wins:

- **`lsp: false`** on an operation in the config is the
  [author's veto](../../reference/configuration-api.md#keeping-an-operation-out-of-the-editor-lsp):
  that operation never runs from the editor, whatever the settings below say.
- **`datamitsu.format.tools`** is a per-tool switch, keyed by the tool's name in
  the config's `tools`. `false` keeps a tool off save. `true` runs a project-wide
  tool even when `widenTo` is `target` or it declares no `globs` — but never
  further than the project's own
  [`execution.widenTo.fix`](../../reference/configuration-api.md#executionwidento)
  allows, and never for a repository-wide tool.
- **`datamitsu.format.widenTo`** is `unit` (the default) or `target`. It can only
  narrow what the project allows: when the project sets
  `execution.widenTo.fix` to `target`, no project-wide tool runs on save under
  either value.

```jsonc
{
  // Only tools that take the saved file itself...
  "datamitsu.format.widenTo": "target",
  "datamitsu.format.tools": {
    // ...plus this project-wide formatter,
    "golangci-lint": true,
    // and never this one.
    "eslint": false,
  },
}
```

### Project-wide tools without globs

A project-wide operation that declares no `globs` does not run on save. Without
them it cannot tell which files it formats, so it would claim every save in its
project: saving a TypeScript file that lives in a Go module would run a
glob-less `golangci-lint fmt` over the whole module, holding up the formatters
the file actually needs. The output channel names such a tool with the reason
`declares no globs, so it cannot tell which files it formats`. Two remedies:

- **For the config author** — add `globs` to the operation (such as
  `["**/*.go"]`), so only the files it formats bring it in. A tool whose result
  for one file does not depend on its neighbours can also take `{files}` and
  declare [`granularity: "file"`](../../reference/configuration-api.md#granularity),
  so a save runs it on the saved file alone.
- **For you** — opt the tool in with `datamitsu.format.tools`. It then runs over
  the saved file's project on every save there, whatever the file's type, and
  still no further than the project's own `execution.widenTo.fix` allows.

### The watchdog

A save must not hang the editor. Tools run in
[priority groups](../../guides/architecture/execution.md#two-layer-execution-model),
and once `datamitsu.format.timeoutMs` (default `15000`) has elapsed no further
group starts. The first group always runs, a running tool is never interrupted —
a formatter killed halfway would leave a file carrying some tools' edits but not
others' — and time spent downloading or installing a tool does not count. When
the watchdog stops a save, a warning names the tools that did not run. `0`
disables it. A cancelled format, unlike the watchdog, can stop before the first
group: see [When a format is cancelled](#when-a-format-is-cancelled).

### When a format is cancelled

VS Code cancels a format it no longer needs, for example when the document
changes before the format finishes. The server then stops at its next
checkpoint instead of running the rest of the plan. A tool that is already
running always finishes, since killing a formatter in the middle of a write can
leave the file truncated, and a tool download or install that has started
completes, so the next save does not repeat it. What is on disk afterwards
depends on when the cancel arrived:

- **Before your unsaved changes were written** — the file is unchanged.
- **Before the first tool group** — the file holds your unsaved text,
  unformatted.
- **While a tool group runs** — that group and the ones before it have fixed the
  file; the later ones did not run.

The output channel logs `format: cancelled`. Once a tool group has run, the
server's notice also names the tools that did not; a cancel before the first
group only says that no tool ran. **datamitsu: Restart Language Server**, or
closing the window, cancels a running format the same way: the running tool
finishes and nothing after it starts. A restart after a settings change waits
for the format to finish instead.

### Where notices appear

- The **status bar** shows downloads, installs, and each tool while it runs.
- The **datamitsu output channel** (**datamitsu: Show Output Channel**) records
  the repository the server serves, the policy it runs with, configuration
  reloads, the tools a save left out and why, failed tools, and every warning —
  the server's own and those datamitsu logs while it loads the config or
  installs a tool. Each line appears at its level: `debug`,
  `info`, `warn` or `error`. Debug lines need both sides lowered: the server's
  level (`DATAMITSU_LOG_LEVEL=debug` in the environment VS Code starts from) and
  the channel's (**Developer: Set Log Level...**).
- The first warning or error of a session also pops up once, with a **Show
  Output** action.
- A save that runs no fix tool at all — none applies to the file's type, or the
  policy left them all out — shows a one-time hint.

### After a config change

There is nothing to restart. Before each format, the server checks whether the
configuration changed — an edited config file, a shared config package updated
by an install, a branch switch — and loads it again. The output channel records
`configuration reloaded`, followed by the policy the session now runs with. The
[`lsp` reference](../../reference/cli-commands.md#lsp-configuration-reload)
lists exactly what is checked.

A config that does not load — the usual state halfway through an edit — leaves
the session on the configuration that last loaded: one warning names the cause,
and saves keep formatting with the previous configuration until the config loads
again. The same broken content is not reported again on every save.

A reload does not run `datamitsu init`. When the new config changes a tool
config that datamitsu generates for you, formatting a file that tool covers
fails until that file is brought up to date, and the error names the command to
run, usually `datamitsu init`.

The extension restarts the server by itself only when its own settings change:
`datamitsu.format.*`, `datamitsu.path`, or `datamitsu.binaryMode`. Run
**datamitsu: Restart Language Server** for what a reload does not cover, such as
a new `datamitsu` binary installed at the same path.

When a `datamitsu` command has cached results under a different configuration
than the session's (a run with `--tools` counts as one), the session stops
writing the shared cache, so it cannot discard those results, and warns once for
each configuration it loads. The same happens, as a note in the output channel
rather than a warning, when the CLI runs another `datamitsu` version than the
editor: point `datamitsu.path` at the project's binary to share one cache.

## Settings

| Setting                      | Default | Description                                                                                               |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `datamitsu.binaryMode`       | `auto`  | `auto` (PATH, else pinned download), `system` (PATH only), or `bundled` (always the pinned download).     |
| `datamitsu.path`             | `""`    | Explicit path to the `datamitsu` binary; overrides `binaryMode`.                                          |
| `datamitsu.format.widenTo`   | `unit`  | `unit` also runs project-wide fix tools for the saved file's project; `target` runs only file-level ones. |
| `datamitsu.format.timeoutMs` | `15000` | Milliseconds after which no further tool group starts on a save; `0` disables the watchdog.               |
| `datamitsu.format.tools`     | `{}`    | Per-tool switch by tool name: `false` keeps a tool off save, `true` opts a project-wide tool in.          |
| `datamitsu.trace.server`     | `off`   | Trace JSON-RPC traffic to the output channel.                                                             |

The `datamitsu.format.*` settings reach the server only when you set them — in
user or workspace settings. In a single-folder window, the folder's
`.vscode/settings.json` is the workspace settings. In a multi-root workspace the
extension starts one server for the whole window, serving the
[first folder's repository](#the-repository-it-serves), so a folder's own
settings file cannot set them: put them in the `.code-workspace` file. An unset
one leaves the server on `DATAMITSU_LSP_FORMAT_WIDEN_TO` or
`DATAMITSU_LSP_FORMAT_TIMEOUT_MS` from its environment, and then on the default
above. The output channel shows the values the session actually runs with.

Other editors can pass the same settings to `datamitsu lsp` directly — see
[`lsp`](../../reference/cli-commands.md#lsp).

## Commands

- **datamitsu: Restart Language Server**
- **datamitsu: Show Output Channel**

## Source

The extension lives in the datamitsu monorepo under
[`editors/vscode`](https://github.com/datamitsu/datamitsu/tree/main/editors/vscode).
Each release also attaches the `.vsix` to the
[GitHub Release](https://github.com/datamitsu/datamitsu/releases) for manual
installation.

---

## Winget

# Winget (Windows)

```powershell
winget install datamitsu.datamitsu
```

To upgrade to the latest version:

```powershell
winget upgrade datamitsu.datamitsu
```

---

## Quick Start


This guide walks you through setting up datamitsu in a project, downloading tools, and running them.

## 1. Create a Configuration File

datamitsu looks for a configuration file at your git root. Create one of:

- `datamitsu.config.ts` (TypeScript — recommended)
- `datamitsu.config.js` (JavaScript)
- `datamitsu.config.mjs` (ES modules)

Here's a minimal example that adds [hadolint](https://github.com/hadolint/hadolint) (a Dockerfile linter). It uses `1.0.0` as the project's configuration version label:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

// datamitsu.config.ts
function getConfig(prev) {
  return {
    ...prev,
    version: "1.0.0",
    apps: {
      ...prev.apps,
      hadolint: {
        binary: {
          binaries: {
            linux: {
              amd64: {
                glibc: {
                  url: "https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64",
                  hash: "sha256:56de6d5e5ec427e17b74fa48d51271c7fc0d61571c37f4a4c87c04f911dc5f94",
                  contentType: "binary",
                },
              },
            },
            darwin: {
              amd64: {
                unknown: {
                  url: "https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Darwin-x86_64",
                  hash: "sha256:911006e5fe41981c319cf4ef331d12bd1c02b594e4a1e9a4b1dbe5fbab0e5b5c",
                  contentType: "binary",
                },
              },
              // arm64: no native ARM64 binary; omit or use x86_64 via Rosetta 2
            },
          },
        },
      },
    },
    tools: {
      ...prev.tools,
      hadolint: {
        name: "Hadolint",
        operations: {
          lint: {
            app: "hadolint",
            args: ["{file}"],
            scope: "per-file",
            globs: ["**/Dockerfile", "**/Dockerfile.*"],
          },
        },
      },
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

Each binary entry requires a `url` and a `hash` (SHA-256). datamitsu refuses to download any binary without a hash.

## 2. Initialize the Project

Run `init` from your git root to download all configured tools:

```bash
datamitsu init
```

This downloads and verifies binaries, installs runtime-managed apps, and creates any managed config symlinks in `.datamitsu/`.

Use `--all` to also download optional tools:

```bash
datamitsu init --all
```

## 3. Execute a Tool

Run any managed tool directly:

```bash
datamitsu exec hadolint -- Dockerfile
```

The `--` separates datamitsu arguments from the tool's arguments.

## 4. Run Checks

Run all configured lint and fix operations:

```bash
# Run fix then lint in sequence
datamitsu check

# Run only linting
datamitsu lint

# Run only auto-fixes
datamitsu fix
```

## 5. Reconcile Managed Project Configs

Reconciliation writes the project-owned files declared by the config and then
runs `datamitsu fix`. To inspect the changes without either action, use
`--dry-run`:

```bash
datamitsu config reconcile --dry-run
```

Then run the reconciliation:

```bash
datamitsu config reconcile
```

This detects your project type and creates, updates, links, or removes the
appropriate managed configuration files. It is different from `datamitsu init`:
`init` provisions tools and `.datamitsu` links, while reconciliation owns
project configuration files.

### Opt-in to tools one at a time

In a project with many configured tools, the default experience is "everything
runs at once". Pass `--opt-in-tools` to start with **all tools disabled** and turn
them on deliberately:

```bash
datamitsu config reconcile --opt-in-tools
```

As part of reconciliation, this writes a `.datamitsuignore` at your git root
that disables every configured tool via a single catch-all rule. The default
post-reconciliation fix then respects that opt-in state:

```bash
# Generated by `datamitsu config reconcile --opt-in-tools`.
# All configured tools are disabled by default (opt-in model).
# Enable a tool by removing it from the list below (or add "!**/*: <tool>").
**/*: eslint, golangci-lint, hadolint, prettier, shellcheck
```

Enable a tool by **removing its name** from the list (for example, delete
`prettier` to let prettier run). Reconciliation refuses to overwrite an existing
`.datamitsuignore`, so your manual selections are never lost — use
`datamitsu config reconcile --opt-in-tools --dry-run` to preview without writing. See
[Generating an all-disabled file](../reference/ignore-rules.md#generating-an-all-disabled-file).

## Configuration Layers

datamitsu loads config in layers, each extending the previous:

```mermaid
graph TD
    A[defaultembedded config] --> B{"--before-configsupplied?"}
    B -->|yes| C[--before-config files]
    B -->|no| D[declared before-configsfrom getBeforeConfigs]
    C --> E[auto-discoveredgit-root config]
    D --> E
    E --> F[--config filesoverrides]
    F --> G[final Config]
```

Every config exports `getMinVersion()` and `getConfig(prev)`. The final resolved config also requires a top-level `version`: a nonempty, single-line label of at most 80 characters, without surrounding whitespace. It may be a release version or a static label such as `core`; semver is not required. It is inherited normally and can be overridden by later layers. Unlike `version`, `getMinVersion()` must return a semver minimum for the datamitsu core. A project can begin with `version: "1.0.0"`.

## Next Steps

- [Core Concepts](./core-concepts.md) — Understand binary management, runtimes, and managed configs
- [Configuration Guide](../guides/configuration.md) — Deep dive into configuration options
- [CLI Commands Reference](../reference/cli-commands.md) — Full command documentation

---

## Caching Strategy


datamitsu has two execution-cache models. File-granularity operations record a
pass for each exact file content. Unit-granularity operations record a verdict
over a complete project/module input set; repository verdicts use the same model
but are opt-in. This page explains their keys and persistence behavior.

For context on how tasks reach the cache layer, see [Parallel Execution](./execution.md).

## Cache Invalidation Keys

Every project cache has a top-level **invalidation key**: an XXH3-128 hash of
four inputs. If it changes, both the file entries and stored verdicts are
discarded and rebuilt.

```mermaid
graph LR
    V["datamitsu version"] --> H["XXH3-128"]
    S["Cache semantics"] --> H
    C["Full config (JSON)"] --> H
    T["--tools selection"] --> H
    H --> K["Invalidation Key"]
    K --> D{"Matches stored key?"}
    D -->|"Yes"| U["Use cached results"]
    D -->|"No"| R["Discard cache, start fresh"]

    style H fill:#e8f4fd,stroke:#2196f3
    style U fill:#e8f5e9,stroke:#4caf50
    style R fill:#ffebee,stroke:#f44336
```

### What goes into the key

| Input                  | What it captures                              | Why it matters                                                               |
| ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
| **datamitsu version**  | The release version string                    | A new core may change planning, execution, or parsing                        |
| **Cache semantics**    | A constant naming what a stored pass means    | Every development build reports the same version, `dev`                      |
| **Full configuration** | The complete `Config` serialized as JSON      | Any effective config change invalidates results                              |
| **--tools selection**  | Selected tool names, sorted deterministically | A subset run must not claim the cache state produced by a different tool set |

App `dependsOn` and `runtimeEnv` are run-time contracts and stay outside binary
and runtime-app install identities. They are included in the full configuration
above, so changing either still invalidates execution results. Evaluated-config
caching preserves symbolic bindings; `${APP_BIN:<name>}` is resolved against
the current store when constructing an execution command. Docker build slices
include dependency definitions, so a dependency change also invalidates its
dependents' build stages without folding dependency identity into their app
install hashes.

The cache semantics change whenever the rule for recording a pass changes, so an
entry recorded under the old rule is never read as if the new one had recorded
it. The version alone cannot guarantee that: a locally built binary is always
`dev`. The price is that **every cache is cold once** after an upgrade that
changes the rule.

### Where `invalidateOn` fits

`invalidateOn` is not part of the top-level key. It adds inputs to the verdict
for a unit- or repository-granularity operation:

```javascript
tools: {
  eslint: {
    operations: {
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        granularity: "unit",
        invalidateOn: ["eslint.config.js", ".eslintignore"],
      },
    },
  },
  tsc: {
    operations: {
      lint: {
        app: "typescript",
        args: ["--noEmit"],
        scope: "per-project",
        invalidateOn: ["tsconfig.json"],
      },
    },
  },
},
```

Each path is resolved against the unit and every ancestor up to the git root.
Only existing files become guards; this lets a nested package inherit a root
config without spelling its relative depth. The verdict hashes file contents,
not just names. `invalidateOn` has no effect on per-file cache entries: an
operation whose result depends on shared configuration must use unit or repo
granularity rather than claim that each file is independent.

## Per-File Tracking

Within a valid cache (invalidation key matches), each file is tracked individually with three pieces of data:

| Field           | Description                                         |
| --------------- | --------------------------------------------------- |
| **ContentHash** | XXH3-128 hash of the file's contents                |
| **Lint**        | List of tool names that passed lint on this content |
| **Fix**         | List of tool names that passed fix on this content  |

### Cache hit decision

Before running a tool on a file, the executor reads the file — through the
[content-hash memo](#the-memo), so a file another tool already hashed in this run
costs a `stat` — and keeps the hash together with the `stat` it was taken under.
It then checks:

1. Does a cache entry exist for this file path?
2. Does the stored ContentHash match the hash just taken?
3. Is this tool name in the operation's list (Lint or Fix)?

All three must be true for a cache hit. If any check fails, the tool runs. The
lookup compares hashes under the cache's read lock; it never reads a file there,
so one slow disk read does not stall every other lookup.

### Recording a pass against the bytes the tool saw

A lint pass is recorded against the hash taken **before** the run: the bytes the
tool was handed, not whatever the file holds afterwards. After the tool exits, the
executor checks the file again with the same probe the
[unit verdict](#the-post-run-probe-bypasses-the-memo) uses: a `stat` settles it
when it can, and a file whose size, modification time or inode identity moved, or
that was written inside the current modification-time tick, is read again. Then:

| After the run                          | What is recorded                                       |
| -------------------------------------- | ------------------------------------------------------ |
| Unchanged, the entry holds other bytes | The entry is replaced: this content, this one tool     |
| Unchanged, the entry holds these bytes | The tool joins the entry's list                        |
| Changed while the tool ran             | Nothing — the pass would vouch for bytes it never read |
| The bytes could not be read before     | Nothing                                                |

The replace rule closes a gap the earlier writer had. It appended a tool to an
existing entry without comparing hashes, so:

1. A passes on content X — the entry is `{X, [A]}`.
2. The file becomes Y and B passes — the entry became `{X, [A, B]}`.
3. The file goes back to X — B was skipped on content it had never seen.

Now step 2 replaces the entry with `{Y, [B]}`, and step 3 runs B. A fix pass is
recorded against the content the fixer produced, as described
[below](#fix-resets-lint-cache).

### A lint pass means "nothing to report"

A cache hit is replayed as "this tool found nothing here" — by the terminal, and by
anything that reads a run's results after it. So for a tool whose output a parser
read — its declared [`outputParser`](./parsers.md#extraction-outcomes), or the
[fallback](./parsers.md#three-layers) built into datamitsu — a pass, of `lint` and
of `fix` alike, follows what the parser read, not the exit code:

- A file gets a pass only when the process that checked it succeeded, its output
  was parsed, no finding names the file, and every finding the process reported
  names one of the files it was given. A finding that names no file, or a file
  the process was not given, could be about any of them, and no file of that
  process gets a pass.
- Output that could not be parsed — the module did not load, does not know the
  parser key, failed, or neither it nor the fallback recognized the output —
  records nothing.
- Every finding counts, at every level: a `hint` blocks a pass as much as an
  `error` does.
- A tool without an `outputParser` whose output the fallback does not recognize
  keeps the exit-status rule: a success is a pass. Output the fallback does
  recognize is judged like a parser's, finding by finding.
- A fix pass follows the same rule. The
  [`failOn`](../../reference/configuration-api.md#failing-on-findings-failon) gate
  judges what a fixer leaves behind as it judges a linter's findings, so a fix pass
  recorded over a finding below one threshold would hide it from a stricter one.

Because a pass needs a run with no finding at any level, it holds at every
threshold: neither `failOn` nor `--fail-on` is part of any cache key.

The consequence is deliberate: a file with findings of a tool that exits 0 on them
— hadolint below its `failure-threshold`, a linter configured not to fail on
warnings — is checked again on every run, while every file the tool found nothing
in stays cached. `--no-parse` only changes what a failure prints, so it records
by the same rule.

### Managed config content in the tool name

An operation that names a managed config through `{managedConfig:<key>}` records
its passes under the tool name plus a digest of that config's current content —
`yamlfmt@<xxh3>`, not `yamlfmt`. Editing `.yamlfmt.yaml`, or `datamitsu init`
rewriting its copy in `.datamitsu/configs/`, is then a miss for that tool on every
file, while every other tool's entries stay valid. Folding the digest into the
cache-wide invalidation key instead would discard all of them.

An operation that hands its tool host variables through
[`inheritEnv`](../../reference/configuration-api.md#inheriting-host-variables-inheritenv)
records its passes the same way, under the tool name plus a digest of the
`NAME=value` pairs the tool was started with — `reporter+env:<xxh3>`. The
invalidation key hashes the configuration, which names the variables but never
holds their values, so without it a pass recorded under one value would answer
for another. A variable the host does not set adds nothing to the name.

### Why separate Lint and Fix tracking

Lint and fix are independent operations with different semantics. A file can pass lint without needing a fix, or be fixed without being re-linted yet. Tracking them separately enables precise cache behavior:

**Step-by-step example:**

1. **First run:** `datamitsu fix` runs prettier on `app.ts`
   - prettier reformats the file (contents change)
   - Cache records: ContentHash=`abc123`, Fix=`["prettier"]`, Lint=`[]`

2. **Then:** `datamitsu lint` runs eslint on `app.ts`
   - ContentHash matches (file unchanged since fix) — but eslint is not in Lint list
   - eslint runs and passes
   - Cache records: ContentHash=`abc123`, Fix=`["prettier"]`, Lint=`["eslint"]`

3. **Next run:** `datamitsu lint` again
   - ContentHash matches, eslint is in Lint list — cache hit, eslint skipped

4. **Developer edits `app.ts`:**
   - ContentHash no longer matches — both Lint and Fix lists are effectively invalidated
   - All tools run again on this file

### Fix resets lint cache

When a fix operation modifies a file, the lint cache for that file is reset:

- The fixer changes the file contents, producing a new ContentHash
- The Lint list is cleared to empty
- The Fix list records the successful fixer

This is necessary because the fixer's changes might introduce new lint issues. For example, an auto-formatter might reformat code in a way that triggers a different linter rule. Resetting the lint cache ensures linters always re-check after fixes.

## Unit Verdicts and the Content-Hash Memo

Per-file tracking answers "has this file changed?". A tool whose `granularity` is `unit` — the value
inferred for every `scope: "per-project"` operation — asks a coarser question: "has anything in this
unit changed?" — and the answer is a **verdict**, keyed by a hash over every member of the unit plus
every guard: the ancestor configs and lock files the unit inherits, any config path the operation's
`args` names as an absolute path, every managed config it names through `{managedConfig:<key>}` —
wherever that appears, including a `--config=PATH` argument or an `env` value — and its
`invalidateOn` entries resolved against the unit and each ancestor. The input hash also includes selected inherited environment variables whose names start
with `GO`, `CARGO`, `RUST`, `NODE_`, `NPM_`, `PYTHON`, `PIP_`, `UV_`, `JAVA_`, `TS_`,
`ESLINT_`, `RUFF_`, `TF_`, or `TFLINT_`.

A verdict is stored under the operation's identity: the tool, the operation, the unit, the
granularity and arity, the raw `args`, the declared `env`, the host values it inherits through
`inheritEnv`, and — because the parser decides
whether a lint run reported anything — the SHA-256 of the parser module the tool's
`outputParser` names and the parser key, and the content key of the fallback module the
binary embeds. Pinning another module, or running a build that embeds another fallback,
misses every verdict it did not decide. The per-file cache's key carries the fallback's
content key as well: every development build reports the version `dev`.

A `repo`-granularity operation gets a verdict too, but only when it opts in with `cache: true`.
`file` granularity and an explicit `cache: false` never produce one.

Only a successful task with **complete unit coverage** may write a verdict, and for
a lint operation only when the task reported nothing: every process parsed without
a finding, or run with nothing any parser recognized in its output. A
narrowed partial task can consume an earlier full verdict when its inputs still
match, but it cannot mint a new whole-unit pass. Verdict hits also have a TTL,
controlled by `DATAMITSU_UNIT_CACHE_TTL` (`1440` minutes by default; `0`
disables verdict caching). This bounds dependencies that the declared guard set
cannot see, such as network state or an undeclared file outside the unit.

Computing a verdict key means reading and hashing the unit. Without reuse, a
package with three thousand files would be read again for every per-project tool,
even though the content does not depend on which tool asks for it.

### The memo

datamitsu keeps a **process-scoped content-hash memo** — a
`path -> (hash, size, modification time, inode identity)` map, shared by every task of a run and safe
under the executor's worker pool. The unit verdict's pre-run pass and the per-file hash taken before
each run both read through it. The first tool to need a file reads and hashes it; every later
tool over the same file gets the hash back without touching the disk.

The scope is the _process_, not the run: a one-shot CLI invocation discards the memo when it exits,
while a long-lived `datamitsu lsp` server keeps it across every run it serves. Entries are never
expired on a timer — they are revalidated by `stat` on each use, and a `stat` that cannot clear an
entry is simply a miss. The map is capped so a session-long process cannot grow it without bound;
on reaching the cap it is dropped whole, which costs a re-read and nothing else.

This is a cache of a pure function (bytes → XXH3-128) behind a **validity check**, not an assumption
that files hold still. An entry is only handed out when all of the following are true:

| Condition                                                                      | What it rules out                                                                      |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| A fresh `stat` succeeds and reports the same **size**                          | A rewrite that changed the file's length                                               |
| ...and the same **modification time**                                          | Any write the filesystem recorded                                                      |
| ...and the same **inode number and inode-change time**, both actually reported | A same-length rewrite that restored the original mtime (`rsync -a`, `cp -p`, `tar -x`) |
| ...and that mtime was already **2 seconds** old when the bytes were read       | A rewrite inside the mtime tick the read landed in, at the same length                 |

The third condition exists because size and mtime are both restorable: anything that calls
`utimes` can rewrite a file to the same length and put the timestamp back, and a `(size, mtime)`
comparison sees nothing. The inode-change time is not restorable — the write moves it, and the call
that restores the mtime moves it again. The check is only sound when the platform actually reports a
change time, so an **unknown** identity is treated as proving nothing rather than falling back to
`(size, mtime)`: the entry is a miss and the bytes are re-read. Windows is that platform — no change
time is reachable from a path-only stat, so the memo never hits there and every file is hashed as it
was before the memo existed.

The fourth condition is the subtle one, and it is anchored to the **read**, not to the lookup.
Filesystem mtime granularity is coarse — FAT's tick is two seconds — so a file written, hashed, and
rewritten within one tick can present an identical `stat` while holding different bytes. Waiting
does not repair such an entry: the ambiguous write it cannot rule out already happened, and no later
`stat` can see it. An entry taken inside its own tick is therefore never handed out at all, however
long it sits in the map. Every uncertain answer is a miss, and a miss only ever costs a read.

### The post-run probe bypasses the memo

Before running a tool, datamitsu computes the unit's input hash. **After** the tool finishes, it
computes it again, and records the verdict only if the two agree. That second pass is the only thing
standing between "this unit passed" and a lie: it catches inputs that moved underneath the tool while
it ran.

The post-run probe **must not consult the memo**, and does not. The memo was populated by the pre-run
pass over those exact paths; answering the probe from it would compare the pre-run value against
itself, and the check would pass by construction no matter what happened on disk. A tautological
check is worse than no check, because it looks like a check.

The same rule applies to a `fix` operation from both directions. A fixer rewrites files by design —
mtime granularity is exactly the case that bites — so `fix` keeps the **full re-hash** for its second
pass rather than the stat-based probe a read-only `lint` uses, and neither pass reads through the
memo.

A `fix` pass does, however, **write** what it read back into the memo, replacing the pre-fix entries
for those paths. Reading past the memo answers the question honestly; overwriting keeps the answer
honest for everyone downstream. `datamitsu check` runs `fix` and then `lint` in one process, so
entries a fixer has just disproved would otherwise still be there for the next task to be handed —
and they describe bytes that no longer exist.

```mermaid
graph TD
    P["Pre-run: hash unit inputs"] -->|"reads through memo"| M[("Content-hash memopath → hash, size, mtime, inode identity")]
    P --> R["Run tool"]
    R --> Q{"Operation?"}
    Q -->|"lint (read-only)"| S["Re-stat every path,re-hash all a stat cannot clear"]
    Q -->|"fix"| F["Full re-hash"]
    S -->|"bypasses memo"| D{"Inputs unchanged?"}
    F -->|"bypasses memo on read,overwrites its entries"| G{"Inputs unchanged?"}
    F -.->|"replaces stale entries"| M
    D -->|"Yes"| W["Record verdict"]
    D -->|"No"| N["Record nothing"]
    G -->|"Yes"| W
    G -->|"No — expected,the fixer wrote them"| V["Record verdictover the produced state"]

    style M fill:#e8f4fd,stroke:#2196f3
    style W fill:#e8f5e9,stroke:#4caf50
    style V fill:#e8f5e9,stroke:#4caf50
    style N fill:#ffebee,stroke:#f44336
```

The read-only probe re-stats every member and guard and re-hashes every path a stat cannot prove
identical: one whose size, mtime, inode number or inode-change time moved, one that cannot be
stat'ed, one that was missing and now exists, one modified inside the current tick, and — on a
platform that reports no change time — every path, unconditionally. It never falls back to assuming
a path was unchanged.

The two operations then read the same answer differently. For a read-only `lint`, a mismatch means
the inputs moved underneath a tool that could not have moved them, so the pass describes a state that
no longer exists and nothing is recorded. For `fix`, a mismatch is the expected outcome — rewriting
those files is the job — so the verdict is recorded against the state the fixer **produced**, not the
one it started from. A `fix` also drops the matching `lint` verdict for that unit, which the rewrite
has just made unsound.

## Cache Invalidation Best Practices

### Declare tool configuration files

For a unit or repository verdict, list extra files that affect the tool in
`invalidateOn`. Files already inside the unit and inherited marker/config/lock
files are included automatically.

```javascript
// BAD: the unit verdict does not name its external config
tools: {
  eslint: {
    operations: {
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        granularity: "unit",
      },
    },
  },
},
```

```javascript
// GOOD: the inherited config participates in the unit verdict
tools: {
  eslint: {
    operations: {
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        granularity: "unit",
        invalidateOn: ["eslint.config.js"],
      },
    },
  },
},
```

### When to disable caching

Set `cache: false` for tools that are non-deterministic or have side effects:

```javascript
tools: {
  "custom-checker": {
    operations: {
      lint: {
        app: "custom-checker",
        args: ["--check"],
        cache: false, // Output depends on external state
      },
    },
  },
},
```

When `cache: false`, the tool always runs regardless of file state. For
repository granularity the default is already no verdict; `cache: true` is an
explicit claim that the operation is deterministic and the tracked repository
plus its guards form a closed input set.

### Conservative is safer

If a result may depend on sibling files or shared config, prefer unit granularity
and declare the extra guards. Declaring file granularity is a performance claim:
it is correct only when each file's result stands alone. Per-file entries contain
the file content, effective config, datamitsu version, and tool selection, and
the values of the variables the operation names in `inheritEnv`, but do not fold
in the rest of the inherited process environment; name such a variable in
`inheritEnv`, use unit granularity or disable the cache when its value can change
the answer.

## Concurrency Model

datamitsu runs tools in parallel (see [Parallel Execution](./execution.md)), which means multiple goroutines read and write the cache simultaneously. The cache uses a layered synchronization strategy to stay consistent without sacrificing performance.

### Read-write locking

Cache lookups (`Check`) acquire a read lock — multiple goroutines can check the cache concurrently with no blocking — and only compare hashes the executor took before asking. Cache updates (`AfterLint`, `AfterFix`) acquire an exclusive write lock; `AfterFix` hashes the fixed file before it takes the lock. No file is read while a lock is held. Hit/miss counters use lock-free atomic operations to avoid contention on the hot path.

### Debounced persistence

Rather than writing to disk after every tool completes, the cache uses a debounce pattern:

1. After a successful tool run, the cache is marked as dirty (atomic flag, non-blocking)
2. A 100ms timer starts (or resets if already running)
3. When the timer fires, the cache writes to disk if still dirty
4. Rapid updates (e.g., a batch of files being fixed) coalesce into a single disk write

This reduces I/O significantly when many files are processed in quick succession.

### Atomic writes

Cache persistence uses the temp-file-and-rename pattern: data is written to a temporary file, then atomically renamed to the final path. This prevents corruption if the process crashes mid-write — the cache file is either the old version or the new version, never a partial write. Every write gets a temporary file of its own, so two processes saving at once — a `datamitsu lsp` session and a CLI run — cannot interleave their bytes; the later rename wins.

Before saving, a process merges entries that another process has already written.
Matching file-content entries union their successful tool lists; conflicting
content hashes are dropped because neither can safely be called newer. Verdicts
keep the latest validation timestamp, while deletions and pruning leave
tombstones so the merge cannot resurrect them. The read-modify-write sequence is
not locked across processes, so an unlucky interleaving can still lose a warm
entry; that costs a later rerun, not an incorrect cache hit.

A file whose invalidation key differs from the process's own is not merged. A
command replaces it: the file belongs to a configuration this process has
already discarded, and refusing to write would leave the cache cold for good. A
long-lived `datamitsu lsp` server does the opposite. It reloads its config only
when a format request finds the config's inputs changed, and keeps the previous
config while a changed one fails to load, so its key can be the stale one. Every
write path — the debounced flush, an explicit save, the shutdown flush — then
leaves such a file alone and warns once per session, and once more after each
reload. Otherwise the server and the CLI would reset each other's cache on every
run. Once the two hold the same key again, because the server reloaded or the
CLI wrote the key the server holds, they merge as before.

### Shutdown safety

On process exit, the cache performs a final flush: any pending debounce timer is cancelled and a synchronous save executes if the dirty flag is set. This ensures no results are lost, even if the process exits immediately after the last tool completes. A `datamitsu lsp` server that reloads its config flushes the cache it replaces the same way, before building the new one.

### Pruning

To prevent unbounded growth, the cache prunes at most once per 24 hours. File
entries whose paths no longer exist are removed, and verdicts not validated for
30 days are aged out. The read path still applies the shorter configurable
verdict TTL; the 30-day limit only bounds unused data on disk.

## Performance Implications

The caching strategy provides compound speedups across repeated runs. XXH3-128 is 10-26x faster than SHA-256 on typical inputs (26x on Intel i9-14900K, 11-14x on Apple M1 Max), making per-file content hashing nearly free even in large monorepos.

- **First run:** Tools execute and complete runs populate file entries or verdicts
- **Unchanged file-granularity input:** Only changed files are rechecked
- **Changed unit input:** The affected unit-wide operation reruns as a whole
- **Changed repository input:** An opted-in repository verdict misses and reruns
- **Config changes:** The top-level key rebuilds the project cache automatically

For wrapper maintainers, the main correctness decision is `granularity`. Use
`invalidateOn` for additional unit/repository inputs and `cache: false` for
non-deterministic or side-effecting file/unit operations. Opt repository verdicts
in only deliberately.

## Cache Storage

The execution cache is stored as a single file per project:

```
~/.cache/datamitsu/cache/projects/{xxh3_128(gitRoot)}/toolstate.msgpack
```

All projects within the same git repository share a single cache file, keyed by the XXH3-128 hash of the git root path. Per-project isolation is achieved through per-file tracking within this file. The msgpack binary format keeps the file compact and fast to read/write.

Tool-specific caches (e.g., TypeScript's `tsbuildinfo`, ESLint's `.eslintcache`) are stored in a separate directory tree:

```
~/.cache/datamitsu/cache/projects/{xxh3_128(gitRoot)}/cache/{relativeProjectPath}/{toolName}/
```

These are managed by the tools themselves via the `{toolCache}` template placeholder — datamitsu just provides the directory path.

Evaluated config chains live in a sibling tree, keyed by the same project identity the source-mode farm uses:

```
~/.cache/datamitsu/cache/config-eval/{projects|configs}/{identity}/{key}.msgpack
```

`projects/` holds repository chains (identified by the git root), `configs/` holds machine-level `--config` chains (identified by the chain itself). The file name is the hash of every input the evaluation is a function of. See [the config-evaluation cache](./startup.md#the-config-evaluation-cache) for the key inputs and the invalidation rules.

---

## File Discovery & Project Detection


File discovery is the first stage of datamitsu's execution pipeline. It walks the repository tree to find files that match tool glob patterns, while project detection identifies independent project boundaries within monorepos. Together they determine _what_ files exist and _where_ projects live before the [planner](./planner.md) decides what to do with them.

## .gitignore-Aware Traversal

The file walker respects `.gitignore` rules at every directory level, plus the two repository-wide exclude files git reads: `.git/info/exclude` and your personal `core.excludesFile` (by default `~/.config/git/ignore`). This means datamitsu never processes files your version control system ignores — `node_modules/`, `dist/`, `.venv/`, build artifacts, and any other ignored paths are automatically excluded.

### How It Works

For a fix/lint/check run, the runner starts one walk at the git root and shares
its sorted result with every downstream consumer. At each level, the walker:

1. Checks for a `.gitignore` file and merges its rules with the parent's rules
2. Skips `.git` directories and symlinks (avoiding circular references)
3. Processes subdirectories in parallel (up to 8 concurrent goroutines)
4. Collects non-ignored files in a thread-safe accumulator

After the parallel walk finishes, the complete absolute-path list is sorted once.
That deterministic inventory is reused by bundled `.datamitsuignore` validation,
project detection, glob matching, unit membership, and both halves of
`datamitsu check`.

```mermaid
graph TD
    R["Git Root"] --> G["Collect excludes and .gitignore rules"]
    G --> W["Walk directory tree"]
    W --> C{".gitignore match?"}
    C -->|"Yes"| S["Skip file/directory"]
    C -->|"No"| D{"Directory?"}
    D -->|"Yes"| N["Enter subdirectory (parallel)"]
    D -->|"No"| F["Add to file list"]
    N --> G2["Merge child .gitignore rules"]
    G2 --> W

    style R fill:#e8f4fd,stroke:#2196f3
    style S fill:#ffebee,stroke:#f44336
    style F fill:#e8f5e9,stroke:#4caf50
```

### Why It Matters

- **No wasted work:** Ignored directories like `node_modules/` (which can contain hundreds of thousands of files) are skipped entirely, not entered and then filtered
- **Correct behavior:** The same files your `git status` sees are the files datamitsu processes — no surprising lint errors from generated code or vendored dependencies
- **Cascading rules:** A `.gitignore` in a subdirectory extends (not replaces) the parent's rules, matching how git itself handles ignore patterns
- **Git's precedence:** `core.excludesFile` is weakest, `.git/info/exclude` overrides it, and any `.gitignore` overrides both. In a linked worktree, `info/exclude` is read from the main repository, as git does

## Project Auto-Detection

In monorepos with multiple packages, tools need to know which project each file belongs to. datamitsu detects projects by looking for **marker files** — files whose presence indicates a project root.

### Marker-Based System

Each project type is defined by a list of marker glob patterns:

```javascript
export function getConfig(input) {
  return {
    ...input,
    projectTypes: {
      typescript: {
        markers: ["package.json"],
        description: "Node.js / TypeScript project",
      },
      golang: {
        markers: ["go.mod"],
        description: "Go module",
      },
      python: {
        markers: ["pyproject.toml"],
        description: "Python project",
      },
    },
  };
}
```

The detector scans the shared file inventory and matches each path against the
marker patterns; it does not traverse the repository again. Every directory
containing a matching marker becomes a detected project location. A single
repository can contain dozens of detected projects across multiple types.

### How Tools Use Project Types

Tools declare which project types they apply to via the `projectTypes` field. When the planner creates tasks, it only assigns a tool to projects that match:

```javascript
tools: {
  tsc: {
    projectTypes: ["typescript"],
    operations: {
      lint: {
        app: "typescript",
        args: ["--noEmit"],
        scope: "per-project",
        globs: ["**/*.ts", "**/*.tsx"],
        priority: 20,
      },
    },
  },
  "golangci-lint": {
    projectTypes: ["golang"],
    operations: {
      lint: {
        app: "golangci-lint",
        args: ["run"],
        scope: "per-project",
        globs: ["**/*.go"],
        priority: 20,
      },
    },
  },
},
```

With this configuration in a monorepo:

- `tsc` runs only in directories containing `package.json`
- `golangci-lint` runs only in directories containing `go.mod`
- Neither tool wastes time in projects it doesn't apply to

### What Happens When Markers Are Missing

If a tool specifies `projectTypes: ["typescript"]` but no `package.json` exists anywhere in the repository, that tool simply produces zero tasks. No error, no warning — the tool is silently skipped because there are no matching projects.

This is intentional: a shared configuration can define tools for many project types, and only the relevant ones activate based on what the repository actually contains.

### Monorepo Example

Consider this repository structure:

```
repo/
├── packages/
│   ├── frontend/
│   │   ├── package.json      ← typescript project detected
│   │   └── src/
│   ├── api/
│   │   ├── go.mod             ← golang project detected
│   │   └── main.go
│   └── shared/
│       ├── package.json      ← typescript project detected
│       └── src/
└── services/
    └── worker/
        ├── pyproject.toml     ← python project detected
        └── main.py
```

datamitsu detects four projects:

| Project              | Type       | Tools that apply      |
| -------------------- | ---------- | --------------------- |
| `packages/frontend/` | typescript | eslint, tsc, prettier |
| `packages/shared/`   | typescript | eslint, tsc, prettier |
| `packages/api/`      | golang     | golangci-lint         |
| `services/worker/`   | python     | ruff, mypy            |

Each tool runs independently in its project directory with isolated cache paths — see [Caching Strategy](./caching.md) for details on per-project cache isolation.

## How Discovery Feeds the Pipeline

The output of file discovery and project detection flows directly into the [planner](./planner.md):

1. **File list** — all non-ignored files in the repository, used to match tool glob patterns
2. **Project locations** — detected project directories and their types, used to scope per-project tools
3. **CWD restriction** — when running from a subdirectory, both file list and project locations are filtered to the current subtree (see [CWD-Subtree Restriction](./planner.md#cwd-subtree-restriction))

The expensive tree traversal is centralized, but the planner is not completely
filesystem-free. For unit/repository verdicts it stats and hashes the shared
inventory's members and resolves guard files such as ancestor markers, lock
files, absolute file arguments, and `invalidateOn` paths. A planner constructed
outside the normal runner can also fall back to its own discovery walk when no
inventory was seeded.

---

## Parallel Execution


The executor is the third stage of datamitsu's execution pipeline. It takes the ordered task groups from the [planner](./planner.md) and runs them — sequentially between groups, in parallel within groups — stopping at the first failure by default so errors surface immediately, or running everything to the end when fail-fast is off.

## Pre-Install Phase

Before any task runs, the runner installs **every app the plan needs** up front.
Immediately after planning and before the executor starts, it calls `EnsureTools`
with the plan's sorted, deduplicated app names. An operation's tool key and
`app` can differ, so installation follows the app reference carried by the task.
Planner names remain roots. Both OCI auto-seeding and installation expand those
roots to their transitive `dependsOn` closure, including dependencies that are
lazy or not required. A missing or unsupported dependency aborts provisioning
before the dependent tool executes.

This is a hard invariant: **all plan apps are installed before parallel execution
begins.** Installing ahead of time means no task triggers an on-demand install
while another task is resolving the same app. Distinct apps may still install in
parallel because they use separate content-addressed paths. Explain mode skips
installation. A failure here aborts before any task runs.

## Skipped Tools

A tool can end up **skipped** — neither run nor failed — for one of three
reported reasons, all decided during [planning](./planner.md) so they appear in
`--explain` and never reach the pre-install phase:

- **Disabled in config** — the tool sets `skip: true`. Use this instead of conditionally omitting the tool: an omitted tool is invisible, a skipped one is reported.
- **No binary for this platform** — the tool's binary has no build for the current OS/architecture/libc. This is a **soft skip**: the run still succeeds. (Previously this aborted the whole run with an install error.)
- **Cannot narrow** — the request selected less than the operation's declared
  granularity, and the active `execution.widenTo`/`--widen-to` policy does not
  allow expanding far enough to produce a sound verdict.

Skipped tools render as faint `⊘ <tool> skipped (<reason>)` lines, contribute a `· N skipped` count to the operation footer, and surface as a `skipped` array in `--explain=json`. Other non-runs — a tool that matched no files, doesn't apply to the detected project types, or is disabled by `.datamitsuignore` — stay silent, as before.

The `--fail-on-skip` flag (on `check`/`lint`/`fix`) makes the run exit 4
**only** for platform skips — a tool you expected to run had no binary for the
runner. Intentional config skips and not-narrowable skips do not fail that flag.
Use `--require-coverage=unit` or `--require-coverage=repo` when an incomplete
narrowed answer must fail CI.

## Two-Layer Execution Model

Execution follows a two-layer structure:

1. **Outer layer (sequential):** Task groups execute one after another, ordered by priority. Group 1 must fully complete before Group 2 starts.
2. **Inner layer (parallel):** Within each group, non-overlapping tasks run concurrently across available CPU cores.

```mermaid
graph TD
    subgraph "Group 1 — priority 10 (sequential gate)"
        direction LR
        P["prettier fix"]
    end

    subgraph "Group 2 — priority 20 (parallel)"
        direction LR
        E["eslint lint"]
        T["tsc lint"]
    end

    subgraph "Group 3 — priority 30 (sequential gate)"
        direction LR
        C["custom-lint"]
    end

    P -->|"all complete"| E
    P -->|"all complete"| T
    E -->|"all complete"| C
    T -->|"all complete"| C

    style P fill:#e8f5e9,stroke:#4caf50
    style E fill:#fff3e0,stroke:#ff9800
    style T fill:#fff3e0,stroke:#ff9800
    style C fill:#f3e5f5,stroke:#9c27b0
```

### Why This Design

The two-layer model balances two competing goals:

- **Correctness:** Formatters must finish before linters run, because formatters change files that linters check. Sequential groups enforce this ordering.
- **Performance:** Independent tools at the same priority level (like eslint and tsc checking different file types) can safely run at the same time. Parallel execution within groups exploits this.

A fully sequential approach would be too slow in large monorepos. A fully parallel approach would produce incorrect results when tools depend on each other's output.

## Fail-Fast Semantics

Fail-fast is the default: when any task fails, datamitsu cancels all remaining work rather than continuing to run tools that are likely to fail or produce misleading results.

The mechanism works in three steps:

1. **Failure detected:** A task in the current group exits with a non-zero status.
2. **Context cancelled:** The executor cancels the run's context with a fail-fast cause, signaling all in-flight and pending tasks.
3. **Cleanup:** Running tasks receive the cancellation signal and their process groups are stopped. Tasks that haven't started yet skip execution immediately.

Fail-fast stops a run at five levels. `--fail-fast=false` (or `DATAMITSU_FAIL_FAST=false`) turns every one of them off:

| Level                    | Fail-fast (default)                                  | `--fail-fast=false`                                                                                                                                |
| ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Priority groups          | Stop after the first failing group                   | Every group runs in order                                                                                                                          |
| Sequential sub-groups    | The sub-groups after the failure do not start        | All run                                                                                                                                            |
| Parallel siblings        | Waiting ones are cancelled, running ones are stopped | All finish; no process is stopped because another failed                                                                                           |
| Files of a per-file task | Stop at the first failing file                       | Every file runs; the task fails with the last failing file's exit code, every file's output, and each failing file named when more than one failed |
| Operations of `check`    | Lint is not run after a failed fix                   | Lint runs after the failed fix, and its footer says so                                                                                             |

The exit code is 1 when any task failed, in both modes. Ctrl-C and `SIGTERM` stop a run in both modes: the first signal cancels the run's context with an interruption cause, so every running tool is stopped and the run reports what it did not finish, then exits 130 or 143. A second signal ends the process at once, and so does a signal that arrives while the configuration is still loading, before the run has a context to cancel. A stopped tool gets `SIGTERM`; five seconds later whatever is left of it, the processes it started included, is killed.

### FailureReason Classification

Not all failures are equal. The executor classifies each failed task:

| FailureReason   | Meaning                                                     | Shown to User?                  |
| --------------- | ----------------------------------------------------------- | ------------------------------- |
| **Independent** | The tool failed on its own merit (real failure)             | Yes, with its output            |
| **Cancelled**   | The task was stopped by fail-fast after another task failed | As `cancelled` or `not started` |
| **Interrupted** | The task was stopped because the run was interrupted        | As `cancelled` or `not started` |

A cancelled task is not a failure: it never counts toward `(N failed)`, and its output is not shown. It is not hidden either. The runner lists every planned task the run stopped — `cancelled (fail-fast)` if it had started, `not started (fail-fast)` if it had not, including the tasks of groups the run never reached — and counts them in the footer, so a reader never takes "no output" for "clean". The JSON-L stream ends each such task with a `tool_run` event of status `skip`.

A task counts as stopped when the stop reached it while it was still running, whatever it then exits with: a tool that catches the signal and exits 1 is cancelled, not failed. A tool that had already exited when the stop went out keeps its own result.

### What a result records

Before it runs anything, the executor names every task of the plan `<tool>:<dir>:<seq>`, `seq` counting the plan's tasks from 1 in plan order, so two tasks of one tool in one directory — the files of a per-file tool — are told apart; each process is `<task>#<n>`. Every callback and every event of a task carries its name.

A task's result is more than one exit code. It lists **every process** the task planned to spawn — one per file for a tool that runs once per file, one per chunk for a list-taking tool — each with the files it was given, its state (`ran`, `cancelled`, `not-started`, `setup-failed` when its input could not be prepared or its command did not start), its exit code when it ran, its duration, the last 4 KiB of its output, its [extraction outcome](./parsers.md#extraction-outcomes) and its findings. It also has **one entry per file** the task was planned with: `ran` (with the process that checked it and that process's exit code), `cached` when the per-file cache answered, `verdict-hit` for every member of a unit whose [verdict](./caching.md#unit-verdicts-and-the-content-hash-memo) held, `cancelled`, `not-started` or `setup-failed`. The edits a formatter applied are recorded on the file they changed.

A tool whose arguments name no file — `tsc` reading `tsconfig.json` — answers for its unit, not for the files that selected the task, so its result lists the unit's members, each checked by its one process. The frame, the counts and the exit code still read the task's aggregate: every process's output joined, the last failing process's exit code and command, every finding.

A process fails when it exits non-zero, or when it exits 0 and its parsed output holds a finding at or above its operation's [`failOn`](../../reference/configuration-api.md#failing-on-findings-failon) — provided the parser module that read it takes levels only from what the tool printed. Such a process is marked as failed by its threshold, and so is its task when that is its only failure; in a batch process only the files its gating findings name count as failed. Under fail-fast it stops a run like any other failure.

A task that failed on its own and stopped short — the rest of a per-file loop after a failing file under fail-fast, the chunks a cancellation reached before they started — names the files it never checked, under its failure: `⊘ alpha  2 files not run (fail-fast): src/b.txt, src/c.txt`.

### The report of a run

When a run is asked for a report (`--report`), the runner folds every task's result into one record as the task completes, and builds the document once the last operation has ended: operations, then the tools of each, then one invocation per process with the files it answered for and the findings it reported, plus the tasks the planner skipped and the run stopped. Every renderer reads that record and nothing else, which is what lets a report of `check` be one document and a report be written after a failure. The record holds no command line and no environment, and is never cached. See the [Reports guide](../reports.md) and [Reports](../../reference/cli-commands.md#reports).

### Snapshots around the steps of a fix

Inside a priority group the parallel groups run one after another, and the tasks of one parallel group run over disjoint file sets. Each parallel group is a **step**, numbered from 1 through the operation. When a run records anything and the operation is `fix`, the runner snapshots the working tree — `git status --porcelain=v2 -z --untracked-files=all` without optional locks, plus a hash of each file it lists — right before the first step and after every step, including one that failed or was cancelled, and attributes what moved between two snapshots to the task of that step whose files hold it:

```mermaid
sequenceDiagram
    participant R as Runner
    participant E as Executor
    R->>R: snapshot 0
    R->>E: Execute(plan)
    E->>E: step 1 (tasks over disjoint files)
    E->>R: step 1 ended
    R->>R: snapshot 1, diff 0→1 → step 1's tasks
    E->>E: step 2
    E->>R: step 2 ended
    R->>R: snapshot 2, diff 1→2 → step 2's tasks
```

A snapshot that cannot be taken stops the observation for the rest of the operation, which then says it was not observed; `lint` takes none. A formatter that writes its result on stdout is applied by the executor itself, which keeps the unified diff of the change when `--report patch` asks for it — the only moment both versions exist.

**Example scenario:**

```
Group 2 contains: eslint (checking .ts files), tsc (checking .ts files)
Both start in parallel. Group 3 contains custom-check.

1. eslint finds errors → exits with code 1 → marked as Independent failure
2. Context cancelled with the fail-fast cause
3. tsc receives cancellation → marked as Cancelled
4. User sees: eslint's errors, then "⊘ tsc  cancelled (fail-fast)"
   and "⊘ custom-check  not started (fail-fast)"
```

## Tool Ordering Best Practices

Priority values directly control the execution order. Here's a recommended pattern for a typical JavaScript/TypeScript project:

```javascript
export function getConfig(input) {
  return {
    ...input,
    tools: {
      // Priority 10: Formatters run first
      // They modify files, so everything else must wait
      prettier: {
        name: "prettier",
        operations: {
          fix: {
            app: "prettier",
            args: ["--write", "{files}"],
            priority: 10,
            globs: ["**/*.{js,ts,tsx,css,json,md}"],
          },
        },
      },

      // Priority 20: Type checking and linting run after formatting
      // These read files but don't modify them, so they can run in parallel
      tsc: {
        name: "tsc",
        projectTypes: ["typescript"],
        operations: {
          lint: {
            app: "tsc",
            args: ["--noEmit"],
            priority: 20,
            globs: ["**/*.{ts,tsx}"],
            scope: "per-project",
          },
        },
      },
      eslint: {
        name: "eslint",
        operations: {
          lint: {
            app: "eslint",
            args: ["{files}"],
            priority: 20,
            globs: ["**/*.{js,ts,tsx}"],
          },
        },
      },

      // Priority 30: Custom checks that depend on lint passing
      "custom-check": {
        name: "custom-check",
        operations: {
          lint: {
            app: "custom-check",
            args: ["{files}"],
            priority: 30,
            globs: ["**/*.ts"],
          },
        },
      },
    },
  };
}
```

**Why this order matters with fail-fast (the default):**

- If prettier fails at priority 10, eslint and tsc never run — there's no point linting unformatted code.
- If eslint fails at priority 20, custom-check at priority 30 never starts — it would likely fail too.
- tsc and eslint share `.ts`/`.tsx` extensions, so at the same priority they run in separate sequential sub-groups within that group. Overlapping tools always run sequentially — the executor enforces this automatically.

**Common mistakes:**

- Putting formatters and linters at the same priority: formatters modify files, so linters might see stale content if they run simultaneously.
- Putting all tools at different priorities: this forces fully sequential execution, losing parallelism between independent tools.

## The Environment a Tool Receives

A tool started by `fix`, `lint` or `check` — the language server's format lane included — gets the environment datamitsu was started with, minus the variables that make tools change what they print: `GITHUB_ACTIONS`, the AI agent markers and `FORCE_COLOR`/`CLICOLOR_FORCE`. The variables its operation names in [`inheritEnv`](../../reference/configuration-api.md#inheriting-host-variables-inheritenv) come back with the host's values, the app's `env` and then the operation's `env` are layered on top, and `NO_COLOR=1` is set last, where nothing can override it. `CI` and every other CI variable pass through. Before a parser reads the output, ANSI sequences a tool printed anyway are removed; the failure frame keeps them. `datamitsu exec` does none of this. The generated [Tool Environment](../../reference/tool-environment.md) page lists every variable and why.

## Progress Tracking

The executor reports progress differently depending on the environment:

**Interactive terminal (non-CI):**

- A live progress bar shows task completion across the current group.
- Per-file progress updates the bar as each file is processed.
- The bar disappears when the group completes.

**CI environment:**

- No progress bar (CI terminals don't support carriage return rewriting).
- A start message is printed when each tool begins: `Starting prettier...`
- Percentage milestones are printed at 25% intervals to indicate liveness.
- Final results appear after all groups complete.

The environment is detected automatically. CI mode activates when the `CI` environment variable is set (a convention followed by GitHub Actions, GitLab CI, Jenkins, and most CI systems). Datamitsu never sets `CI=true` itself — it respects whatever the system provides.

### Concurrency Control

The number of parallel tasks is controlled by `DATAMITSU_MAX_PARALLEL_WORKERS`. The default is dynamic based on CPU count:

```
max(4, floor(NumCPU * 0.75)), capped at 16
```

On an 8-core machine, this means 6 parallel workers. On a 2-core machine, the minimum of 4 still applies. You can override this for CI environments where you want more or fewer workers:

```bash
# Use more workers on a beefy CI runner
DATAMITSU_MAX_PARALLEL_WORKERS=12 datamitsu check

# Use fewer workers to reduce memory pressure
DATAMITSU_MAX_PARALLEL_WORKERS=2 datamitsu check
```

### Batch Chunking

When a tool operates on many files, the executor may need to split them into multiple batches to stay within command-line length limits (OS-imposed limits on argument length). Each batch runs as a separate process, and batches within the same task run in parallel.

This is transparent to tool configuration — you don't need to handle batching yourself. The executor automatically chunks the file list and merges results.

---

## Internal Architecture


This section explains how datamitsu works under the hood. Understanding the internal execution model helps wrapper maintainers optimize tool configurations and advanced users debug unexpected behavior.

## How It All Fits Together

When you run `datamitsu check`, the system moves through a startup phase and then four stages:

```mermaid
graph LR
    S[Startup and Config Load] --> A[File Discovery]
    A --> B[Task Planning]
    B --> C[Parallel Execution]
    C --> D[Cache Update]

    style S fill:#fce4ec,stroke:#e91e63
    style A fill:#e8f4fd,stroke:#2196f3
    style B fill:#fff3e0,stroke:#ff9800
    style C fill:#e8f5e9,stroke:#4caf50
    style D fill:#f3e5f5,stroke:#9c27b0
```

0. **Startup and Config Load** resolves the repository root and evaluates every config source into the merged configuration everything downstream reads.
1. **File Discovery** performs one gitignore-aware repository walk, sorts the
   resulting inventory, and shares it with bundled checks and the planner.
2. **Task Planning** groups matched files into tasks based on tool priorities, scopes, and project boundaries. Overlapping globs are detected and resolved.
3. **Parallel Execution** runs task groups sequentially by priority level, but tasks within each group run in parallel across available CPU cores.
4. **Cache Update** records per-file passes for independent operations and
   complete unit/repository verdicts for coarser operations.

## Why This Matters

**For wrapper maintainers:** Understanding how priorities and overlap detection work lets you write tool configurations that maximize parallelism. Misconfigured priorities can serialize tools that could run in parallel, slowing down CI pipelines.

**For advanced users:** Knowing how file discovery and caching interact explains why certain files are or aren't processed, and how to force cache invalidation when needed.

## Components

Each stage has its own detailed documentation:

| Component                             | What It Does                                   | Key Concepts                                                           |
| ------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------- |
| [Startup & Config Load](./startup.md) | Resolves the repo root, evaluates config       | Config-evaluation cache, git-root memo, extension-based type stripping |
| [Task Planning](./planner.md)         | Groups inventory into prioritized tasks        | Granularity, widening, overlap detection, CWD selection                |
| [Parallel Execution](./execution.md)  | Runs tasks, fail-fast by default               | Two-layer model, context cancellation, progress tracking               |
| [File Discovery](./discovery.md)      | Builds one shared, sorted repository inventory | .gitignore traversal, project auto-detection, inventory reuse          |
| [Caching Strategy](./caching.md)      | Tracks file passes and unit/repo verdicts      | XXH3-128 keys, guards, TTL, concurrent persistence                     |
| [WASM Output Parsers](./parsers.md)   | Sandboxed parsers + formatting diff-in-core    | Rust→WASM, SHA-256 trust, https or OCI source, wazero, Myers diff      |

## Reading Order

If you're new to datamitsu's internals, read in this order:

1. **Startup and Config Load** -- what every invocation pays before anything else
2. **File Discovery** -- how files enter the system
3. **Task Planning** -- how files become tasks
4. **Parallel Execution** -- how tasks run
5. **Caching Strategy** -- how results persist between runs

If you're debugging a specific issue, jump directly to the relevant component page.

---

## WASM Output Parsers


datamitsu wraps third-party linters and formatters behind a single CLI. To turn a
tool's free-form text output into structured results, it loads small,
**hash-pinned Rust→WASM modules** — output parsers — into a sandboxed runtime.
This page explains the parser pipeline end to end, and the line-based
**diff-in-core** that the formatting path is built on.

The architectural invariant that governs the design: **a parser extracts only
what the tool actually emitted; the Go core fills defaults.**

## The Architectural Invariant

The dividing line between the WASM module and the Go core is deliberate:

- **The WASM module owns _extraction only_.** It reports exactly what the tool
  emitted. Every diagnostic field but the message is optional — absence means
  "the tool did not provide this", which is information, not an error.
- **The Go core owns _defaults and policy_.** Column fallbacks, severity
  defaults, range completion, and diffing all live in the core, next to the rest
  of datamitsu's shared behavior.

This "raw-with-holes / defaults-in-core" split keeps parsers tiny, dumb, and
trivially auditable, and keeps all judgement calls in one reviewable place.

### File attribution

Which file a diagnostic belongs to has two possible sources, and they compose:

- **The parser**, for formats that name a path per diagnostic (eslint's
  `filePath`). It fills `file` on the raw diagnostic.
- **The core**, otherwise. Most tool formats drop the filename, so when a process
  was handed exactly one file — a per-file run, or a list-taking tool whose
  `{files}` held one path — the executor stamps that file on every diagnostic the
  parser left without one.

This ordering is what makes list-taking tools work. A tool given `{files}`
(eslint over a whole project, one invocation, dozens of files) gives the core no
single file to stamp, and neither does a tool given no file at all (`tsc` reads
`tsconfig.json`), so a parser that does not report paths yields unattributed
diagnostics there. Tools in that class must extract the path.

Whatever spelling the tool printed, the core makes the path **absolute**, against
the working directory of the process that printed it, and cleans it: `./a.ts`,
`a.ts` and `/repo/pkg/a.ts` from a process run in `/repo/pkg` name one file. The
terminal shows a path relative to the failure frame's `Cwd`, and one outside it in
full, since `../../x` reads worse than the path it came from.

### Positions

Every position the core hands on follows one contract, whatever the tool printed:

| Field            | Contract                                                                     |
| ---------------- | ---------------------------------------------------------------------------- |
| `row`, `col`     | 1-based; missing or `0` becomes `1`                                          |
| `endRow`         | 1-based; missing means the start row                                         |
| `endCol`         | 1-based and **exclusive**: the span stops before the column it names         |
| a partial end    | an end row without an end column gives a point at the start                  |
| an end before it | an end that precedes the start, after the rules above, becomes a point there |

A point is an end equal to the start. Several tools print `0` for "no position"
(trivy, reek, npm-groovy-lint), which is why `0` is read as `1` rather than kept.

What the core cannot do is tell a 0-based positive column from a 1-based one, or
an inclusive end from an exclusive one: column 5 is column 5 either way. The
module corrects them, and the descriptor-schema-2 release audited every parser
for it: spectral, pylint, selene, cmake-lint, djlint, erb-lint, npm-groovy-lint,
ltrs and write-good read 0-based columns and add 1; actionlint, vale, mlint and
rubocop print the last column of a span and have 1 added to make the end
exclusive; and a parser no longer invents an end — or a start column — its tool
did not print. The module's `POSITIONS` table (`src/contract.rs`) records, per
parser, what its tool prints, and a new parser cannot be added without its row. A
configuration pinned to an older module keeps the positions that module reported.

Columns are counted in the unit the tool uses, which the descriptor declares as
`columnUnit` where it was measured on a line holding multi-byte characters and a
tab (every measured tool counts a tab as one column):

| Tool          | Version measured | Unit                   |
| ------------- | ---------------- | ---------------------- |
| actionlint    | 1.7.12           | `utf-8` (bytes)        |
| golangci-lint | 2.13.1           | `utf-8` (bytes)        |
| cspell        | 10.0.1           | `utf-16` (code units)  |
| eslint        | 10.9.0           | `utf-16` (code units)  |
| tsc           | 7.0.2            | `utf-16` (code units)  |
| harper-cli    | 2.8.0            | `utf-32` (code points) |
| protolint     | 0.57.0           | `utf-32` (code points) |
| vale          | 3.18.0           | `utf-32` (code points) |
| yamllint      | 1.38.0           | `utf-32` (code points) |

Every other parser declares none. checkmake and dotenv-linter print no column,
and dclint and hadolint print column 1 for every finding, so no measurement can
tell their unit.

### Levels

The core's scale has four levels: error, warning, info and hint. From descriptor
schema 2 a module declares, for every tool, the level words that tool prints —
its `severities` vocabulary, which the parser maps onto that scale. An empty
vocabulary says the tool prints no level at all. A module at schema 1 declares
nothing, and [`devtools parsers list`](../../reference/cli-commands.md#devtools-parsers)
shows no `levels` for its tools.

A parser sets a level only from a token the tool printed: a level word, a numeric
level, a `severity` field, or a key that is one (`errors[]`, `warnings[]`). It
reads the level through its vocabulary, so a level the tool never printed has no
way in: not one the parser's author thought fitting for every finding, not an
error for text on stderr or for output that would not decode. A finding without
a token has no level. The module's contract test holds every parser to this over
its samples and its recorded fixtures, and the
[parser catalogue](../../reference/parser-catalog.md) lists each vocabulary.

The core resolves a finding without a level from the exit code of the process
that printed it: **error when the tool failed, warning when it passed**. For a
tool with no level vocabulary the exit code is the only thing it says about
seriousness, so a checkmake finding under a failed run shows as an error and the
same finding under a passing run as a warning. A level the tool printed is never
changed by the exit code; a value outside the 1–4 scale counts as none.

A schema-1 module predates the rule: more than twenty of its parsers set a level
the tool never printed — "warning" for every finding of markdownlint, codespell or
golangci-lint, "error" for every finding of knip, kube-linter or cue — and its
golangci-lint and tfsec parsers dropped the level those tools do print. A
configuration pinned to it keeps those levels.

### Rule identity

`source` names the tool; `code` names the rule, whenever the tool prints one, and
nothing else — a rule is part of a finding's identity, and a location or a message
in it would split one finding into many. golangci-lint's `code` is the linter that
reported the issue (`errcheck`, `govet`); a linter's own rule id, when it prints
one, stays in the message. `url` carries the rule's documentation where the tool
prints a link (tfsec, dclint, buildifier, reek, …).

### Extraction outcomes

"No diagnostics" is only an answer when a parser actually read the output. Every
process a tool runs therefore records an **extraction outcome** next to its exit
code:

| Outcome              | When                                                                                    | Lint pass cached        |
| -------------------- | --------------------------------------------------------------------------------------- | ----------------------- |
| `parsed-clean`       | the parser ran without error and returned no diagnostic                                 | yes                     |
| `parsed-findings`    | the parser returned at least one diagnostic                                             | for the files it spared |
| `parser-unavailable` | the module did not load, or its `describe` does not list the declared key               | no                      |
| `parse-failed`       | the module returned an error, or neither it nor the fallback recognized the output      | no                      |
| `truncated`          | a stream or the findings exceeded a [parse cap](#parse-caps), or the answer was partial | no                      |
| `none`               | no parser declared, and the [fallback](#three-layers) recognized nothing                | on success              |

The last column is the [caching rule](./caching.md#a-lint-pass-means-nothing-to-report):
a cached lint pass is replayed as "nothing to report", so it is recorded only where
the parser said so.

A module answers a parser key it does not know with an empty list, which would
read as a clean run, so the core checks the key against the module's `describe`
before it parses. An unknown key is not a configuration error: checking it needs
the module, and loading a configuration never touches the network.

When any process of a task is `parse-failed` or `parser-unavailable`, the task
reports `ParseFailed`: its missing diagnostics mean "unknown", not "none". The
run warns once, after its last operation, however many invocations hit the same problem:

- `output parser failed for <tool>: <first error>`, once per tool;
- `parser module "<module>" could not be loaded, so <n> tool(s) that use it ran without parsing`,
  once per module, with the cause and a pointer to
  [`datamitsu devtools parsers prefetch`](../../reference/cli-commands.md#devtools-parsers);
- `parser module "<module>" has no parser "<key>"; caching of fix and lint results is disabled for <tools> because its output cannot be parsed`,
  once per key.

Both an unavailable module and a missing parser disable caching of fix and lint
results for the affected tools.

Whether a tool passed is decided by its exit code and, when a module at
descriptor schema 2 parsed its output, by its operation's
[`failOn`](../../reference/configuration-api.md#failing-on-findings-failon): a
finding at or above it fails a tool that exited 0. The extraction outcome decides
what the cache may record.

### Parse caps

What one process's output costs to parse is bounded, twice:

| Cap                                                                         | Default         | Over it                                   |
| --------------------------------------------------------------------------- | --------------- | ----------------------------------------- |
| `maxParseInputBytes` (`DATAMITSU_MAX_PARSE_INPUT_BYTES`), per stream        | 8 MiB (8388608) | the parser reads the first bytes up to it |
| `maxFindingsPerProcess` (`DATAMITSU_MAX_FINDINGS_PER_PROCESS`), per process | 10000           | the findings after it are dropped         |

A process over either records `truncated`, with the findings it kept: they are
shown and they gate as any finding does, but no pass is cached and a report marks
the tool incomplete. Both are runtime configuration, shown by
[`datamitsu config runtime`](../../reference/cli-commands.md#config-runtime); a
value that is not a positive integer stops `fix`, `lint` and `check` with exit 2
before anything runs.

### Noise tolerance

A tool's JSON rarely arrives alone on stdout. Something else in the process
prints ahead of it (`eslint-plugin-sonarjs` `console.debug`s a pnpm-catalog
warning; node and python wrappers do the same), or the tool appends a human
summary after it — `golangci-lint --output.json.path=stdout` follows its report
with `1 issues:` and a per-linter tally. Under a strict parse, either costs every
diagnostic in the run.

The shared JSON helper therefore parses **leniently**: it finds each document
opener, scans to its balanced close (tracking string literals, so braces inside a
message or a path don't shift the depth), and parses that span. Noise before and
after is ignored. Every candidate span is tried and the best one wins — most
diagnostics first, longest span as the tiebreak — because taking the first span
that merely parses would let a `{}` in the noise shadow the real report, or turn
a JSON log line printed ahead of it into a phantom diagnostic.

A document that never closes contributes nothing. A truncation that still leaves
whole inner elements intact yields those elements, which beats discarding a run's
findings over a cut-off tail.

The core keeps stdout and stderr **apart** whenever a tool declares a parser, in
both per-file and batch execution. Both streams are handed to the module (some
tools report on stderr — `tsc` falls back to it, `cue_fmt` uses it exclusively),
but they arrive as separate buffers, so wrapper noise on one can never interleave
into the other's JSON.

Both buffers reach the module without their ANSI control sequences (the `ESC [`
sequences that set a colour, move the cursor or erase a line). A tool that colours its output even into a pipe
would otherwise put an escape between a line parser and the position or level it
reads. The failure frame still shows what the tool printed.

## The Pipeline

A parser travels through six stages, from a config declaration to a result
returned into the core. The two delivery channels sign at opposite ends of the
step: the release asset is signed before it ships (cosign over `checksums.txt`,
which carries the module's hash), while the registry artifact can only be signed
after it is pushed, because what gets signed is the manifest digest the push
returns:

```mermaid
graph LR
    A["Declare(parsers entry:url XOR oci)"] --> B["Build(Rust → WASM, CI)"]
    B --> C1["Sign checksums.txt(cosign)"]
    C1 --> D1["Deliver(GitHub Release asset)"]
    B --> D2["Deliver(OCI artifact)"]
    D2 --> C2["Sign the manifestby digest (cosign)"]
    D1 --> E["Fetch + verify(SHA-256)"]
    C2 --> E
    E --> F["Load + invoke(wazero sandbox)"]

    style A fill:#e8f4fd,stroke:#2196f3
    style C1 fill:#fff3e0,stroke:#ff9800
    style C2 fill:#fff3e0,stroke:#ff9800
    style D1 fill:#ede7f6,stroke:#673ab7
    style D2 fill:#ede7f6,stroke:#673ab7
    style E fill:#e8f5e9,stroke:#4caf50
    style F fill:#f3e5f5,stroke:#9c27b0
```

### Declare

A parser is a `parsers` entry in the config — a **hash-pinned data artifact**,
modeled on archives and bundles, _not_ on an app (no runtime, no lockfile,
because it is data, not a process). A tool opts in with
[`tool.outputParser`](../../reference/configuration-api.md#output-parser-outputparser),
a by-name reference into `parsers`. A dangling reference is a config error. See
[Output Parsers in the Configuration API](../../reference/configuration-api.md#output-parsers-parsers).

An entry names **exactly one source** and one mandatory hash:

- `url` — an `https://` download. A local development build of datamitsu
  additionally accepts `file://`, for iterating on a module you just compiled;
  a released binary refuses it outright.
- `oci: { ref, digest }` — an artifact pulled from a registry, pinned by its
  manifest digest.
- `hash` — the module's canonical SHA-256 digest, `sha256:<64 lowercase hex>`, **mandatory for both**.

The two sources are **mutually exclusive and there is no fallback chain**.
Declaring both, or neither, fails at config load, before anything touches the
network. A fallback would defeat the point of the second source: an organization
that has removed its `github.com` egress must be able to prove from the config
alone that no code path can reach it. Switching an entry to a registry is what
config layers are for — a downstream layer replaces the entry, keeping the same
`hash`.

### Build

Parsers are a Rust workspace compiled to the `wasm32-unknown-unknown` target as a
freestanding `cdylib`. There is no `wasm-bindgen` — a small **manual-memory ABI**
keeps the artifact small. Each tool is **one module** under `src/tools/<tool>.rs`,
co-locating its parser with its `describe` recipe. A single dispatcher matches on
the tool name, so adding a tool is one `match` arm + one module + one `DESCRIPTORS` row.

Parsers are **hand-written**, porting the logic faithfully from the upstream
[none-ls](https://github.com/nvimtools/none-ls.nvim) builtin or
[efm-langserver](https://github.com/mattn/efm-langserver) errorformat for each
tool. The only external crate is **`tinyjson`** (a tiny, zero-dependency JSON
parser) for the JSON-output class — hand-rolling a correct JSON parser is a known
footgun and many tools emit JSON. Text/line parsers add no dependency. The bundled
set covers **~95 tools** — the none-ls diagnostics builtins plus a few ported
directly from their output (`eslint` JSON; `tsc`/`tsgo`; `cspell`; `harper-cli`;
`knip`, `droast` and `dclint` JSON),
spanning the parsing-difficulty classes — a representative few:

| Tool            | Output shape                               | Class          |
| --------------- | ------------------------------------------ | -------------- |
| `hadolint`      | JSON array of objects                      | structured     |
| `yamllint`      | `file:row:col: [level] msg (rule)` (line)  | simple regex   |
| `dotenv_linter` | `file:row CODE: msg` (no col, no severity) | missing fields |
| `cue_fmt`       | two lines per error (message + location)   | multiline      |
| `echo`          | pipe-test only                             | —              |

The single `.wasm` dispatches all of them by name (`tool.outputParser`). JSON
tools share one `from_json` helper (`src/json_diag.rs`), so each is a few lines.

## Three layers

Every output of `fix`, `lint` and `check` passes through up to three parsers, in
turn, until one recognizes it:

1. **The declared parser** — the tool's `outputParser`, a tool parser or a
   [format parser](#format-parsers) of the module the configuration pins. An
   answer that recognized the output decides, found or clean. A parser key the
   module does not list, or a module that did not load, is `parser-unavailable`:
   warned once per run and never cached, and the output still goes on to the
   fallback so its findings are not lost.
2. **The fallback** — the sniffer of the [module the binary embeds](#the-embedded-fallback),
   when no parser was declared, or the declared one failed, did not recognize the
   output, or (an array-answering module) answered with nothing under a non-zero
   exit. The first standard format it recognizes reads the output. The core never
   runs a declared module's own `fallback` key: the fallback is always the
   binary's.
3. **Nothing** — output no parser recognized. With a parser declared it is
   `parse-failed`: warned once per run, never cached, and the tool is incomplete in
   a report. Without one it is `none`: the exit code decides, as it always did, and
   a failed run is reported with one synthetic finding.

```mermaid
flowchart TD
    O[process output] --> D{parser declared?}
    D -- yes --> P[declared parser]
    P -- recognized --> R1[parser / format]
    P -- not recognized, error, unavailable --> F[embedded fallback]
    D -- no --> F
    F -- recognized --> R2[fallback:format]
    F -- nothing --> N{parser declared?}
    N -- yes --> PF[parse-failed]
    N -- no --> NO[none: the exit code decides]
```

A process records what read its findings — its **provenance**: `parser` (a tool
parser), `format` (a declared format parser) or `fallback:<format>` (the format the
fallback recognized); reports carry it per invocation and per finding. When the
fallback reads what a declared parser did not, the run warns once: `declared parser
"<key>" of module "<module>" did not recognize the output of <tool>; the fallback
parsed it as <format>`. Its findings gate like any other — the embedded module sets
levels only from what the tool printed — and block a cached pass like any other.

The language server reads the output of what it runs with the same fallback, and
with no declared module: the passes it records go into the execution cache the CLI
reuses, so it may record only one the CLI would. A tool with a declared parser
records none there.

The fallback reads a stdout-mode formatter's stderr only: its stdout is the file's
new content, which no parser ever reads. Every other tool's stdout and stderr are
captured apart, parser declared or not, so progress written to stderr never lands
inside a document on stdout; empty output is not read at all. One rule applies to the **line** formats it recognizes (`gcc`, `msvc`,
`github-annotations`, `azure-logissue`) and to no structured one: a line naming a
path that is not a file on disk — relative to the process's working directory, or
absolute — is not a match, so prose that happens to look like `path:1:2:` is not a
finding. When no line of the format the sniffer picked survives, the line formats
it would have tried after that one read the output in turn, and the first with a
line that survives is the one; when none has, the fallback recognized nothing.

`datamitsu devtools parsers sniff <file>` shows what the fallback makes of a
captured output, before a tool's format flag is declared as its format key.

## Format parsers

Many tools print a standard format on request. The module carries one parser per
such shape, dispatched by key like a tool parser, so a tool without a parser of its
own is parsed by naming the format its flag selects:

| Key                  | Recognizes                                                                    |
| -------------------- | ----------------------------------------------------------------------------- |
| `sarif`              | a JSON object with `version` and a `runs` array                               |
| `codeclimate`        | a JSON array whose every element has `check_name` and `location.path`         |
| `eslint-json`        | a JSON array whose every element has `filePath` and a `messages` array        |
| `json`               | a JSON array whose every element has `message` and `line` (none-ls's default) |
| `checkstyle-xml`     | a document whose root is `<checkstyle>`                                       |
| `junit-xml`          | a document whose root is `<testsuites>` or `<testsuite>`                      |
| `github-annotations` | a line `::error …::message` (also `warning`, `notice`)                        |
| `azure-logissue`     | a line `##vso[task.logissue type=…;…]message`                                 |
| `msvc`               | a line `path(line,col): error CODE: message`                                  |
| `gcc`                | a line `path:line:col: level: message`, or `path:line: message`               |

A structured format is recognized by its envelope, whatever it holds: a SARIF log
without a result, an ESLint report whose files have no message, a `<checkstyle/>`
without a file are recognized and clean. A bare `[]` or `{}` has no envelope and is
not, nor is a document cut off before it closes, JSON or XML, or XML with a tag
that cannot be read or an element left open: its findings may be missing. What a
cut-off document holds is part of it, not a document of its own — the messages of
a cut-off ESLint report are not a `json` array, a whole `<testsuite>` inside a
cut-off `<testsuites>` is not a suite. An XML root counts only where it opens a
line or follows the XML declaration, a comment or a `DOCTYPE` on it, and outside
any CDATA section and comment, so a message that quotes `<checkstyle/>` is not a
document. A SARIF result whose message is given by `id` is read from its rule's
`messageStrings`, or the driver's `globalMessageStrings`, with its `arguments` in
the placeholders. A line format is recognized
when one line matches. Each parser reads stdout and stderr, and a structured one
keeps the findings of every document in each — a command that ran a tool twice
printed two reports — so a clean report cannot hide findings in another; noise
around a document is skipped as it is for the tool parsers, however many bracketed
log lines come before it. A JSON value is a document that cannot be read only where
it begins as a report does — it opens its line, as an object whose first key
follows its brace or an array of objects — and is cut off, or closes but does not
parse; a bracket in a message, `expected {`, is neither. The [parser catalog](../../reference/parser-catalog.md#format-parsers)
names the flag of each tool that prints each shape.

A **declared** parser — a tool's or a format's — that found something recognized
the output. One that found nothing did not, whatever the exit code, when the output
holds a document that cannot be read whole — a JSON value or an XML document cut
off before it closes, or malformed — since its findings may be in the part that
could not be read; nor when the output holds findings in a standard format (the
tool printed another format than the parser reads, and the fallback reads it).
Otherwise it recognized the output when its own format was there — its envelope,
or for a JSON tool parser any JSON document — or when the run exited 0 and the
parser reads no structured format: a clean run of a line-format tool may print
nothing, or a summary no format describes. A parser of a JSON or XML format — the
structured format keys, and the tool parsers that read JSON — that finds no
document in a stream where the tool printed something has not read the output,
clean exit or not; empty output on exit 0 is clean for every parser. What remains,
a failed run whose output held nothing either parser reads, is not recognized.

The key `fallback` is the **sniffer**: it tries the formats in the order of the
table and answers with the first that recognizes the output, named by its format.
It recognizes only what a format matched, exit code or not — it guesses, and a guess
needs evidence.

Every answer, a declared parser's and the sniffer's, is **partial** when either
stream holds a document that cannot be read whole: the findings read beside it, or
out of the whole part of it, may not be all there were. A partial answer is
`truncated` in the core, whoever read it — for a tool without a parser too, where
output the fallback recognized nothing in but found a document cut off in is
`truncated`, not `none`. A fallback that fails outright (a module error) leaves such
a tool `parse-failed`. A JSON document nested deeper than 256 levels is not parsed
at all.

A format parser is one module under `parsers/datamitsu-parsers/src/format/`: its
`DESCRIPTOR` of kind `format`, a `parse` returning a `Response`, its `SAMPLES`, an
entry in `format::PARSERS` (which also sets the sniffer's order), in
`format::DESCRIPTORS` and in `format::samples`, and its rows in `FORMAT_POSITIONS`
and `FORMAT_UNKNOWN_COLUMN_UNITS` in `src/contract.rs`. Its sources are listed in
`embedded-sources.txt`, so adding one rebuilds the embedded fallback.

### The embedded fallback

The binary carries one module of its own: the format parsers and the sniffer,
built from the same crate without the tool parsers (the crate's `format` feature
alone, about 180 KiB). The core serves it under the module name `embedded`, beside
the declared ones — compiled once, pooled, described like them — and runs its
`fallback` key on output no declared parser recognized; it never runs a declared
module's `fallback`, so the fallback's version is always the binary's. `embedded`
is reserved: a `parsers` entry may not take the name, and no `outputParser` may
name it. `datamitsu devtools parsers list --embedded` describes it,
`devtools parsers run <key> --embedded` runs one of its parsers, and
`devtools parsers sniff <file>` shows which format its sniffer reads in a captured
output.

The module's content key — an XXH3 of its bytes — is part of the per-file cache
key and of the unit verdict identity: every development build reports the version
`dev`, and a pass recorded over what one build's fallback parsed must not be
replayed by a build whose fallback parses differently.

The bytes are committed as `internal/parsermanager/embedded/fallback.wasm`, and
two checks keep them honest:

- **A CI job rebuilds them and compares, byte for byte.** `task
  build:parsers:embedded` builds the module in a `linux/amd64` container from a
  digest-pinned `rust` image, as the caller's user, with a separate target
  directory and the cargo home, the toolchain's sources and the workspace
  remapped to fixed paths; built twice on one machine, or natively with the same
  flags, it gives the same SHA-256. The Rust release is one fact in three files —
  `parsers/rust-toolchain.toml`, `parsers/embedded.lock` and the image digest in
  `parsers/embedded.Dockerfile` — and the build refuses to run when they disagree
  or when the image's `rustc -vV` names another release. The job
  (`Embedded Parser Module` in `pr-checks.yml`) runs the same build and, when the
  result differs from the committed module, uploads it as the
  `embedded-fallback-wasm` artifact and fails.
- **A Go test compares the sources with the fingerprint committed beside the
  module.** `parsers/datamitsu-parsers/embedded-sources.txt` lists every file the
  build reads; `fallback.wasm.sources` holds their XXH3 fingerprint (sorted paths,
  each `path NUL length NUL bytes NUL`, CRLF read as LF), written by
  `go run ./internal/parsermanager/embedded/cmd/sourcehash`. A listed source that
  changed without a rebuild fails `go test` with "embedded module is stale", with
  no Rust needed to notice; a change to a tool parser does not, since the tool
  parsers are not in the build. The test also fails when a file the build
  compiles is missing from the list.

To change a format parser: edit the crate, run `task build:parsers:embedded`
(Docker), and commit the module with its `fallback.wasm.sources`. Without Docker,
push the source change, download the `embedded-fallback-wasm` artifact of the
failed job, commit it as `fallback.wasm`, and run the `sourcehash` command. A
Rust upgrade changes the toolchain file, the lock, the digest and the module in
one change.

The two XML formats are read by a tokenizer written for them (start and end tags,
attributes, text, CDATA, the predefined entities and character references; no
namespaces, no DTD), so the module keeps `tinyjson` as its only dependency.

A tool's own format is usually richer than a standard one, and its parser reads it
without a conversion in between. Prefer a tool's parser when the module has one, a
format key when the tool prints a standard shape; the line formats carry only a
file, a line, a column, a level and the text.

### Sign

Two different cosign signatures exist over a published module, and **datamitsu
verifies neither of them**.

- **The release channel signs `checksums.txt`.** CI builds the `.wasm` and hands
  it to the release tooling, so the module's SHA-256 lands in `checksums.txt`;
  the existing cosign `sign-blob` step signs that file (keyless, transparency
  logged). The module is covered transitively, as one line of a signed file.
- **The registry channel signs the artifact manifest.** After the artifact is
  pushed, CI cosign-signs it by digest. That signature covers the manifest, whose
  single layer digest _is_ the module's SHA-256 — the same module, covered by a
  different route.

The datamitsu binary has no sigstore or cosign dependency and consults no
transparency log on any fetch path. Both signatures are for **out-of-band**
verification: a maintainer runs `cosign verify-blob` on `checksums.txt`, or
`cosign verify` on the artifact reference, decides the module is trustworthy, and
writes its SHA-256 into a config. From that point the config's `hash` is the only
trust root the binary has for a declared module, which is why the core pins no
module version of its own: the public module updates independently of the core
binary. The one module the binary does carry, the
[embedded fallback](#the-embedded-fallback), is part of the binary and versioned
with it — it is not a distribution channel, and no configuration's module ever
comes from it.

:::warning `signer` is rejected, not ignored
Setting `oci.signer` is a **config error at load**, on a parser's `oci` and on
the bundle's top-level `oci` alike. A field that quietly did nothing would let a
config assert a guarantee this build does not deliver; a loud error is strictly
better. A bundle `signer` previously loaded and only failed later, at seed time —
it now fails at load, before any network. Remove the field; the mandatory `hash`
(and, for a bundle, the pinned digest) is what verifies the bytes.
:::

### Deliver

The built module reaches a machine over one of **two channels**, and a config
entry names exactly one of them.

**GitHub Release asset.** A versioned asset attached to the release
(`datamitsu_parsers_<version>.wasm`), exactly like the binaries, fetched by
`url` and verified against `hash`. Config maintainers take the `url` from the
release asset and the `hash` from the signed `checksums.txt`.

**OCI artifact.** The same bytes published to a registry as a small OCI 1.1
artifact, fetched by `oci.ref` + `oci.digest`. datamitsu publishes its own module
to `ghcr.io/datamitsu/datamitsu-parsers`, and unstable builds to
`ghcr.io/datamitsu/datamitsu-parsers-unstable`. This closes the last hole in the
"mirror one registry and everything works" story: the module used to be the one
artifact that always came from github.com, so an organization could mirror every
binary and still lose diagnostics parsing.

The artifact is deliberately minimal, and its shape is a contract the core
enforces on **every** pull, before it requests any payload:

| Part                | Required value                                                                                        |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| Manifest media type | `application/vnd.oci.image.manifest.v1+json`                                                          |
| `artifactType`      | `application/vnd.datamitsu.parsers.v1+wasm`                                                           |
| Layers              | exactly one, `application/wasm`, **uncompressed**                                                     |
| Layer digest        | exactly the entry's `hash` (the same `sha256:`-prefixed digest) — the pivot the whole design rests on |
| Layer size          | greater than zero and within the module size cap                                                      |
| `subject`           | absent — a manifest with one is a referrer (a signature, an SBOM), not the module                     |
| Index               | rejected — a wasm module is platform-independent, so there is nothing to select on                    |

The config blob is the empty-JSON descriptor. That is a **publishing** invariant,
asserted where the artifact is produced, and deliberately _not_ a consumer rule:
the core never fetches the config blob, and turning a producer detail into an
integrity gate would break every already-pinned config the day the publisher
changed. The trust anchor is the layer digest.

Tags are published for humans and for mirroring tools, and to keep the manifest
referenced so a registry does not garbage-collect it. **The core never resolves a
tag.** It cannot: the reference grammar excludes `@` entirely and `:` outside the
port position, so a `:tag` or `@digest` suffix inside `oci.ref` does not even
parse.

Neither channel bundles the module into a wrapper package (npm/Python/Ruby), and
the registry channel is opt-in — an entry that says nothing about `oci` keeps
fetching over https, so a plain install needs no registry access at all.

### Fetch + verify

When the core needs a parser it dispatches on the declared source — never falls
back from one to the other — and both branches end with the same mandatory
SHA-256 in charge of the content. A parser referenced by several tools is
coalesced into a **single** fetch.

The https branch reuses the binary download machinery: download with retry, then
verify. The registry branch fetches the **manifest first**, and that ordering is
the point. The manifest is small, its body is re-hashed against the pinned digest
(the `Docker-Content-Digest` header is never trusted), and the layer-digest check
runs against it. A registry serving a correctly-digested manifest that points at
different content is therefore rejected **before one payload byte is requested**.

```mermaid
graph TD
    P["parsers entrymandatory SHA-256"] --> K{"Declared source?"}
    K -->|"url"| H["Download with retry"]
    K -->|"oci"| M["Pull manifest by digest(body re-hashed)"]
    M --> C{"layers[0].digest ==the entry's hash?"}
    C -->|"No"| X["Integrity error(no blob requested)"]
    C -->|"Yes"| B["Pull layer blob(stream hashed)"]
    H --> V{"SHA-256 of thefile on disk?"}
    B --> V
    V -->|"Mismatch"| X
    V -->|"Match"| S["Store: .parsers/{name}/{key}(atomic rename)"]
    S --> L["LoadWASMBytes(name)"]

    style C fill:#fff3e0,stroke:#ff9800
    style V fill:#fff3e0,stroke:#ff9800
    style X fill:#ffebee,stroke:#f44336
    style S fill:#e8f5e9,stroke:#4caf50
```

On the registry path the hash is checked **three** times: as the manifest pivot,
against the streamed blob, and against the file on disk once it exists. The last
one is logically redundant and kept on purpose — it is the only check that names
the config hash _after_ the bytes have landed, which keeps "the config hash is
verified on every transport" true by reading the code rather than by reasoning
about it.

:::note `--no-oci` does not disable a parser's `oci` source
`--no-oci` / `DATAMITSU_NO_OCI` turns off OCI bundle store **seeding** — an
accelerator that degrades gracefully to fetching artifacts one at a time. A
parser that declares an `oci` source is not an accelerator: it is the only route
to those bytes, so switching it off would leave nothing to fall back to.
`DATAMITSU_OFFLINE` is the single hard network gate, and it refuses a registry
pull exactly as it refuses a download.
:::

#### Store key: content, not source

A module is stored at `{store}/.parsers/{name}/{key}`, where the key is an XXH3
hash of the module's SHA-256 **and nothing else** — not the URL, not the registry
reference. The same module therefore lands in the same directory however it
arrived: a release asset, a registry, a locally built `file://`, or a layer of an
[OCI bundle](../oci-bundles.md).

That is exactly what makes a bundle-seeded module and a registry-pulled module
interchangeable. Seeding lays a `.parsers/` subtree into the store at the path
the bundle's producer computed; at run time the core looks for the module at the
path _it_ computes. If the key mixed in the source, a bundle built from a config
pinning the release URL would land somewhere a consumer pinning their own mirror
never looks — the seed would appear to succeed, the parser would silently be
fetched over the network anyway, and under `DATAMITSU_OFFLINE` parsing would just
degrade to raw tool output. Keying on content alone removes the failure mode: a
bundle producer, a consumer and a mirror agree on the path without republishing
anything.

XXH3 is the correct choice here per the [hashing split](../supply-chain-security.md):
the key is internal and is never compared against a value from outside. The
SHA-256 is what gates the content. The layout is versioned inside the key, so
changing its inputs is a deliberate, named migration rather than a silent
relocation — and a migration costs one re-fetch per module, because the old
directories are simply orphaned.

The practical consequence for mirroring: copy the artifact **by digest** and
change only the host. `crane copy` and friends preserve digests, so the published
`digest` and `hash` stay correct, and everything already seeded for that module
keeps matching.

```javascript
// BAD: the module was rebuilt for the mirror, so both the manifest digest and
// the module hash are new. The pin no longer describes what upstream published,
// and every store directory or bundle layer seeded for it is unreachable.
parsers: {
  echo: {
    oci: { ref: "registry.corp/dm/datamitsu-parsers", digest: "sha256:aaaa…aaaa" },
    hash: "sha256:bbbb…bbbb",
  },
}
```

```javascript
// GOOD: the artifact was copied by digest, so only the host changed. The digest
// and the hash are the ones upstream published, and the module resolves to the
// same content-addressed store directory as before.
parsers: {
  echo: {
    oci: { ref: "registry.corp/dm/datamitsu-parsers", digest: "sha256:89ab…4567" },
    hash: "sha256:0123…cdef",
  },
}
```

#### The store re-verifies itself

A module already on disk is not trusted just for being there. Its bytes are
re-hashed against the declared SHA-256 on every use, and a mismatch means the
directory is discarded and the module fetched again — whatever put it there. A
`.parsers/` directory is filled by a verified fetch, but also by bundle seeding,
a restored CI cache, an image layer, or a person with a file manager, and only
the first of those has necessarily been checked against the config. The cost is
one hash of a roughly 400 KiB file per prewarm, nowhere near the per-parse path,
and it makes the mandatory hash mean what the policy says it means: nothing is
loaded that was not checked against it.

### Load + invoke

The verified bytes are instantiated into a **wazero** module (pure-Go WASM
runtime, no CGo — consistent with the core). The host drives the memory ABI:
allocate input buffers, write the raw `stdout`/`stderr`/`exit_code`, call the
exported `parse`, then read and free the output buffer. The raw bytes are passed
**whole — never host-line-split** — so multiline output (e.g. `cue_fmt`) is
preserved; the parser decides whether to split. The JSON result deserializes into
nullable Go structs (pointer fields, so a field the tool omitted stays `nil`).

The answer comes in one of two forms, and the core reads both; the module this
core is built with answers in the second:

| ABI | Answer                                                                                            | Recognized                                              |
| --- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| 1   | a JSON array of diagnostics                                                                       | inferred: at least one diagnostic, or the tool exited 0 |
| 2   | `{"recognized": true, "format": "sarif", "diagnostics": [ … ]}`, and `"partial": true` when it is | said by the parser                                      |

`recognized: false` means the parser found nothing it understands — no document of
its format, no line it matches — which is a different answer from understanding the
output and finding nothing in it (`recognized: true` with no diagnostics). An array
cannot tell the two apart, so an empty array from a tool that failed counts as not
recognized. `format` names the format a format parser read, or the tool for a tool
parser. `partial` says the output holds a document the parser could not read whole —
cut off, or malformed — so the findings it read, if any, may not be all of them: the
core records `truncated`, keeps the findings and caches no pass. A field the core
does not know, in the answer or in a diagnostic, is ignored.

Instances are **pooled**. Instantiating a module allocates a fresh linear memory,
and a run parses the output of many tool invocations of the same module, so after
a successful parse the instance goes back to the manager rather than being
closed. The pool is keyed by the module's **content key** — a re-pinned module
never draws an instance compiled from the bytes it replaced — and holds at most
eight idle instances per module; the excess is closed, so the pool is bounded by
that cap rather than by peak concurrency.

Three rules keep pooling invisible to callers, and all three are load-bearing:

- **Only an instance that was reset is pooled.** The ABI does not make a module
  stateless: mutable globals or retained linear memory would let one parse
  observe the previous one. A module declares it can be returned to its
  post-instantiation state by exporting `reset`, which the host calls before
  pooling the instance. A module that does not export it is never reused — its
  instances are closed after every parse, exactly as before pooling existed.
- **An instance whose parse returned an error is closed, never pooled.** A trap
  mid-ABI can leave the module's allocator in a state the next parse would
  inherit, and no state may leak from one tool's output into another's.
- **A failure on a _reused_ instance is retried once on a fresh one.** The
  failure may belong to the instance rather than to the input — it may have been
  closed underneath the pool — and pooling must never turn a parse that works
  into one that fails. A _fresh_ instance's failure is not retried: it is the
  module's answer to this input.

### Introspect

Every module also exports `describe` — a static counterpart to `parse` that takes
no input and returns a JSON **capability manifest**: which tools the module can
parse, how to invoke each (args + stdin), the upstream URL, and the module's
**build-injected version**. The version is baked at compile time like a Go ldflags
`-X` (CI sets `DATAMITSU_PARSERS_VERSION`); the module is the single source of
truth, which is why the `parsers` config entity carries **no `version` field**.

The manifest carries a `schemaVersion`. From schema 2 every tool also declares:

| Field        | Meaning                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------- |
| `severities` | the level words the tool prints; `[]` when it prints none ([Levels](#levels))            |
| `columnUnit` | what the tool counts columns in — `utf-8`, `utf-16` or `utf-32`; empty when not measured |
| `category`   | `security` for a security scanner; empty otherwise                                       |
| `kind`       | what the parser reads: `tool`, one tool's own output format                              |

Schema 3 adds `abi` at the top level: `2` for a module whose `parse` answers in
the object form above. A module without the field answers with arrays.

The core reads schemas 1 to 3 alike and ignores fields it does not know, so a
configuration pinned to an older module keeps working; its tools simply declare
none of the above. A module that declares a schema newer than any the core knows
is read as the newest one the core knows.

#### Older modules

A module a configuration pins always parses its own tools, however old it is. The
[fallback](#three-layers) runs only on its triggers — no parser, a key the module
does not list, a parse error, an answer that did not recognize the output, or an
empty array under a non-zero exit — and never because a module is old. A module of
response ABI 1 is supported while the latest wrapper release pins one, and for at
least two minor releases after the wrapper moves to a newer one.

An older module cannot say whether it recognized an output and has no format
parsers. That is reported where someone can act on it, once per module: on stderr
by `datamitsu config show` (for the modules already in the store; it fetches
nothing) and `datamitsu devtools parsers list`, and in a run's debug log (`-v`) —
never in a plain run, whose user cannot change a pin a wrapper chose.

To debug a parser against a real `datamitsu lint` run, pass **`--no-parse`** (or set
`DATAMITSU_NO_PARSE`): a failure frame shows each tool's raw output instead of its
parsed findings, so you can see exactly what the parser was given. The flag changes
only what is displayed. Parsing still runs, and parser modules are still fetched
and compiled, because what a run records must not depend on how it is shown.
`devtools parsers run` is the complementary tool for iterating on a parser against
piped output: it prints the module's whole answer — `abi`, `recognized`, `format`
and the diagnostics.

[`datamitsu devtools parsers list`](../../reference/cli-commands.md#devtools-parsers)
aggregates `describe` across every configured parser into a **deduplicated** view:
distinct modules (by content) are described exactly once, and tools are
deduplicated by name (a tool two different modules claim with diverging identity
is flagged as a conflict). The default rendering is human-readable; `--json` emits
the machine-readable catalog for driving configs and build pipelines, and
`--wasm <path>` describes a local `.wasm` file with no config or network access.

Which source an entry actually resolves to is queryable without touching the
network, which matters once a config is assembled from layers:

```bash
# The effective declaration — source, digest and hash as the core sees them
datamitsu config show | jq '.parsers'

# Every artifact this config pins on the registry side: what must I mirror?
datamitsu store refs --oci-only
```

## diff-in-core (Formatting)

Formatting needs **no parser at all** — it is text in, text out. It is the first
real consumer of the pipeline's sibling piece: a **line-based Myers diff written
in the Go core**.

A formatter that reads stdin and writes stdout is run through the executor's
[stdin → stdout capture mode](../tooling-system.md#formatting-stdin--stdout--diff).
The core then treats the captured stdout as the full new file text and computes a
minimal edit set against the original:

```mermaid
graph LR
    O["Original file content"] --> C["ComputeEdits(line-based Myers)"]
    N["Formatted candidate(tool stdout)"] --> C
    C --> E{"Edits?"}
    E -->|"nil"| K["No change → file untouched"]
    E -->|"edits"| A["Apply minimal edits → write back"]

    style C fill:#fff3e0,stroke:#ff9800
    style K fill:#f3e5f5,stroke:#9c27b0
    style A fill:#e8f5e9,stroke:#4caf50
```

Why diff in the core rather than letting the tool rewrite the file:

- **Minimal, precise edits.** A one-line change in a large file produces a
  one-line edit, not a whole-file rewrite — better for review, version control,
  and incremental work.
- **No-op is truly free.** Identical input and output yield `nil` edits; the file
  (and its mtime) is left untouched.
- **Reusable shape.** Edits are produced as range-based text edits, shaped to
  serve both the CLI apply path now and editor `TextEdit` ranges later, with
  column math done over runes to stay correct on multibyte content.

Because diffing is shared policy, it lives with the defaults in the core — the
same place that will own diagnostic defaults — keeping the WASM modules limited
to pure extraction.

## Trust Model Summary

The two channels differ only in how the bytes are addressed. Everything after
"the bytes exist" is shared.

| Concern                         | Release asset (`url`)                      | OCI artifact (`oci`)                                                                          |
| ------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------- |
| What the config pins            | the module's SHA-256                       | the module's SHA-256 **and** the artifact manifest digest                                     |
| Pre-flight rejection            | none — the payload is fetched, then hashed | the manifest pivot: `layers[0].digest` must equal the entry's `hash`, checked before any blob |
| Hash checks per fetch           | once, on the finished file on disk         | three: the manifest pivot, the streamed blob, then the file on disk                           |
| Signature checked by the binary | none                                       | none                                                                                          |
| Signature available out-of-band | cosign over `checksums.txt`                | cosign over the artifact manifest                                                             |
| Credentials sent                | none                                       | `GITHUB_TOKEN`, and only when the reference's host is `ghcr.io`                               |
| Disabled by `--no-oci`          | no                                         | no — that flag governs bundle seeding only                                                    |
| Blocked by `DATAMITSU_OFFLINE`  | yes                                        | yes                                                                                           |

| Shared property    | Mechanism                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Trust root         | the mandatory 64-hex SHA-256 in the config, validated at load before any network                                        |
| Internal cache key | XXH3 over that SHA-256 alone — content-addressed, never used for verification                                           |
| Store integrity    | every module on disk is re-hashed against the declared SHA-256 on each use, and discarded if it does not match          |
| Atomic publish     | the verified temp file is renamed inside its content-addressed directory, so no torn module is observable               |
| Not trusted        | `Docker-Content-Digest`, the registry's TLS identity as a content guarantee, a redirect target, any tag, any annotation |
| Execution sandbox  | wazero (pure-Go WASM), raw bytes in, JSON out — no host filesystem                                                      |

:::caution Mirroring has one hard limit
datamitsu can authenticate to exactly one registry: GHCR, using `GITHUB_TOKEN`,
and only when the reference's own host is `ghcr.io`. There is no docker
`config.json`, no credential helper and no custom CA bundle. A mirror registry
must therefore allow **anonymous pull**; an authenticated private mirror is not
supported yet. This is the same limit the [OCI bundle](../oci-bundles.md) path
has always had, not a new one.
:::

See the [Supply Chain Security](../supply-chain-security.md) guide for the wider
trust model and the [Configuration API](../../reference/configuration-api.md#output-parsers-parsers)
for the `parsers` and `lsp` reference.

---

## Task Planning


The planner is the second stage of datamitsu's execution pipeline. It takes the list of discovered files and transforms them into an ordered execution plan — deciding what runs when, what can run in parallel, and what must wait.

## Shared Repository Inventory

The runner performs one gitignore-aware traversal at the git root and sorts the
result. That same immutable inventory feeds the bundled `.datamitsuignore`
fix/lint checks and is seeded into the planner for glob matching, project
detection, unit membership, and narrowing. A `check` run therefore does not walk
the same tree once for fix, again for lint, and again for planning.

`Planner` can still initialize itself with a fallback walk when used outside the
normal runner path. Invalidating a planner discards an earlier seed, so a stale
inventory is never silently reused.

## Skip Detection

As it enumerates tools in stable name order, the planner records three kinds of
**skipped tools** alongside the runnable task groups. A tool is reported as
skipped when, after it is found applicable to the project and operation:

- it sets `skip: true` in config, or
- its backing binary has no build for the current OS/architecture/libc, or
- a narrowed selection needs a wider unit/repository verdict than the active
  widening policy permits.

Plan-time detection makes all three visible in `--explain` and keeps
platform-unsupported apps out of the [pre-install phase](./execution.md#pre-install-phase).
Tools that are merely inapplicable (no matching files, wrong project type, or
disabled by `.datamitsuignore`) remain silent. A not-narrowable skip counts
against `--require-coverage`; only platform skips participate in
`--fail-on-skip`.

## Priority-Based Chunking

Every tool operation has a `priority` value (a number). The planner groups all tasks by priority and creates one **TaskGroup** per unique priority level:

```mermaid
graph TD
    subgraph "Input: All Tasks"
        T1["prettier (priority: 10)"]
        T2["eslint (priority: 20)"]
        T3["tsc (priority: 20)"]
        T4["custom-lint (priority: 30)"]
    end

    subgraph "Group 1 (priority: 10)"
        G1T1["prettier"]
    end

    subgraph "Group 2 (priority: 20)"
        G2T1["eslint"]
        G2T2["tsc"]
    end

    subgraph "Group 3 (priority: 30)"
        G3T1["custom-lint"]
    end

    T1 --> G1T1
    T2 --> G2T1
    T3 --> G2T2
    T4 --> G3T1

    G1T1 -->|"completes"| G2T1
    G1T1 -->|"completes"| G2T2
    G2T1 -->|"completes"| G3T1
    G2T2 -->|"completes"| G3T1

    style G1T1 fill:#e8f5e9,stroke:#4caf50
    style G2T1 fill:#fff3e0,stroke:#ff9800
    style G2T2 fill:#fff3e0,stroke:#ff9800
    style G3T1 fill:#f3e5f5,stroke:#9c27b0
```

**Execution behavior:**

- Groups execute **sequentially** — Group 1 must finish before Group 2 starts.
- Tasks **within** a group execute **in parallel** across available CPU cores.
- Lower priority numbers run first (priority 10 before priority 20).

This design lets you express ordering constraints. Formatters should run before linters because formatters may change files that linters need to check:

```javascript
export function getConfig(input) {
  return {
    ...input,
    tools: {
      prettier: {
        name: "prettier",
        operations: {
          fix: {
            app: "prettier",
            args: ["--write", "{files}"],
            priority: 10, // Runs first — formats files
            globs: ["**/*.{js,ts,tsx,css,json,md}"],
          },
        },
      },
      eslint: {
        name: "eslint",
        operations: {
          lint: {
            app: "eslint",
            args: ["{files}"],
            priority: 20, // Runs after formatters finish
            globs: ["**/*.{js,ts,tsx}"],
          },
        },
      },
      tsc: {
        name: "tsc",
        operations: {
          lint: {
            app: "tsc",
            args: ["--noEmit"],
            priority: 20, // Same priority as eslint — runs in parallel with it
            globs: ["**/*.{ts,tsx}"],
            scope: "per-project",
          },
        },
      },
    },
  };
}
```

All tasks at the same priority level are placed in one group. Within each group, the executor forms parallel sub-groups of non-overlapping tasks (see next section). Sub-groups run sequentially, but tasks within each sub-group run in parallel. This ensures overlapping tasks never execute concurrently while maximizing parallelism for non-overlapping tasks.

## Overlap Detection

Before running tasks in parallel, the planner checks whether two tasks might operate on the same files. This prevents race conditions where two tools write to the same file simultaneously.

The overlap detection algorithm uses a multi-level approach:

```mermaid
graph TD
    Start["Two tasks to compare"] --> RepoScope{"Either task hasrepository scope?"}
    RepoScope -->|Yes| Overlap["OVERLAP ⚠️"]
    RepoScope -->|No| DiffProject{"Differentproject paths?"}
    DiffProject -->|Yes| NoOverlap["NO OVERLAP ✓"]
    DiffProject -->|No| PerFile{"Both per-file scopewith different files?"}
    PerFile -->|Yes| NoOverlap
    PerFile -->|No| GlobCheck{"Glob extensionsoverlap?"}
    GlobCheck -->|Yes| Overlap
    GlobCheck -->|No| NoOverlap
    GlobCheck -->|"Can't determine"| Overlap

    style Overlap fill:#ffebee,stroke:#f44336
    style NoOverlap fill:#e8f5e9,stroke:#4caf50
```

**Key rules:**

1. **Repository-scope tasks always overlap** with everything — they operate on the entire repository.
2. **Different project paths never overlap** — tasks in `packages/frontend/` and `packages/backend/` are guaranteed disjoint.
3. **Per-file tasks with different files never overlap** — each processes exactly one file.
4. **Glob pattern analysis** — the planner extracts file extensions from glob patterns and checks for shared extensions.

### Glob Extension Analysis

The planner extracts extensions from patterns like `*.js`, `**/*.{ts,tsx}`, and checks whether two tools share any extensions:

| Tool A Globs | Tool B Globs    | Overlap?    | Reason                                  |
| ------------ | --------------- | ----------- | --------------------------------------- |
| `**/*.ts`    | `**/*.css`      | No          | Different extensions                    |
| `**/*.ts`    | `**/*.{ts,tsx}` | Yes         | `.ts` shared                            |
| `**/*.ts`    | `**/*.d.ts`     | Yes         | `.ts` is a suffix of `.d.ts`            |
| `Makefile`   | `**/*.go`       | Assumed yes | Can't extract extension from `Makefile` |

The algorithm is **conservative** — when it can't prove two patterns are disjoint, it assumes overlap. This is safer than incorrectly allowing parallel writes to the same file.

### Practical Impact on Configuration

Understanding overlap detection helps you write configurations that maximize parallelism:

```yaml
# These tools will NOT run in parallel due to overlapping extensions:
prettier:
  fix:
    priority: 10
    globs: ["**/*.{js,ts,tsx,css,json,md}"]

stylelint:
  lint:
    priority: 10
    globs: ["**/*.css"] # css overlaps with prettier — placed in separate sub-group

# Better: put stylelint at a different priority, or accept sequential execution
```

```yaml
# These tools CAN run in parallel (different project paths in a monorepo):
# Tool A runs in packages/frontend/, Tool B runs in packages/backend/
# Even with the same globs, they operate on disjoint file sets
```

## CWD-Subtree Restriction

When you run datamitsu from a subdirectory instead of the repository root, that
subtree becomes the initial selection. File-complete work remains inside it;
coarser operations may widen to a containing unit when policy permits. This is
useful in large monorepos where you want to start with only the package you are
working on without silently accepting an incomplete project-wide answer.

**Behavior from different directories:**

```bash
# From repository root — processes everything
~/repo$ datamitsu check
# → Runs all tools on all files across all projects

# From a subdirectory — starts with that subtree as the selection
~/repo$ cd services/api
~/repo/services/api$ datamitsu check
# → File-complete work stays inside services/api/
# → Unit-complete work may widen to the containing project (default policy)
# → Whole-repository work is reported as not narrowable
```

Scope chooses the working directory; granularity decides whether narrowing is
sound:

| Operation shape                        | Behavior from a subdirectory                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------- |
| File-granularity, any compatible scope | Uses only selected matching files                                               |
| Unit-granularity, `per-project` scope  | Runs complete selected/containing units when `widenTo` permits (default `unit`) |
| Repo-granularity, `repository` scope   | Reported not narrowable unless `--widen-to=repo`; then runs the whole repo      |

A repository-scoped operation with `{file}` or `{files}` is normally inferred
as file-granularity, so it can still run once from the git root with a narrowed
file list. Repository **scope** alone is not a reason to skip it.

**Example monorepo:**

```
repo/
├── packages/
│   ├── frontend/   (package.json)
│   ├── backend/    (go.mod)
│   └── shared/     (package.json)
└── services/
    └── api/        (go.mod)
```

```bash
# From repo/packages/ — processes frontend, backend, and shared
~/repo/packages$ datamitsu check

# From repo/packages/frontend/ — processes only frontend
~/repo/packages/frontend$ datamitsu check

# From repo/services/ — processes only the api service
~/repo/services$ datamitsu check
```

The restriction uses path-component-aware containment checks, so sibling paths
with similar prefixes are excluded (`services/api` does not include
`services/api-admin`). For unit work, the nearest detected project containing
the selection can also be retained when the widening policy permits it.

## File-to-Project Assignment

When a tool has `per-project` scope with file globs, the planner needs to decide which project each matched file belongs to. It uses a **nearest-parent algorithm**:

1. Sort all detected projects by path depth (deepest first).
2. For each matched file, walk through the sorted projects.
3. The first project whose path is a parent of the file path wins.
4. Files not under any detected project are assigned to the repository root.

This matters in monorepos with nested projects:

```
repo/
├── packages/
│   ├── frontend/        (package.json)  ← Project A
│   │   └── src/
│   │       └── app.ts                   ← Assigned to Project A
│   └── shared/          (package.json)  ← Project B
│       └── src/
│           └── utils.ts                 ← Assigned to Project B
└── config.ts                            ← Assigned to repo root
```

Each file belongs to exactly one project — its nearest parent. This prevents duplicate processing when projects are nested. The tool then runs once per project with only that project's files, using the project directory as the working directory.

---

## Startup and Config Load


Every `datamitsu` CLI invocation does the same work before [file discovery](./discovery.md) even begins: it resolves the repository root, evaluates the JavaScript configuration, and builds the engines that expose datamitsu's APIs to that configuration. This page describes what that costs, which parts are memoized, and how to measure the rest — so an optimization is never undone by a change that looks harmless.

:::note One invocation shape skips all of this

Under [source mode](../source-mode.md), a tool run by bare name execs the same datamitsu binary under the tool's name. That invocation is decided by `argv[0]` in `main`, before the cobra command tree or the UI is built, and in the steady state it never loads a config at all: it reads the farm manifest, stats the watch set, and `syscall.Exec`s the target. Everything below describes the CLI path — which source mode still takes whenever the manifest is stale and a rebake is needed.

:::

## The Load Sequence

```mermaid
graph TD
    A["process startpackage init"] --> S{"argv[0] is afarm entry?"}
    S -->|yes| S1["read farm manifestlstat watch set"]
    S1 --> S2["execve the tool(no config load)"]
    S -->|no| B["resolve git root"]
    B --> C["pre-pass engineread declared before-configs"]
    C --> D["per source: read file"]
    D --> E{"extension.js / .mjs?"}
    E -->|yes| G["evaluate in goja VM"]
    E -->|no| F["strip types(esbuild)"]
    F --> G
    G --> H["merged config"]

    style B fill:#e8f4fd,stroke:#2196f3
    style S fill:#fff3e0,stroke:#ff9800
    style E fill:#fff3e0,stroke:#ff9800
    style F fill:#fff3e0,stroke:#ff9800
    style G fill:#f3e5f5,stroke:#9c27b0
```

Config is assembled from several sources — the embedded default, any declared before-configs, and the project's own `datamitsu.config.{js,mjs,ts}`. Each source gets its own engine and its own JavaScript VM, so anything done per engine is done several times per invocation.

## The Cost Model

Three rules explain nearly all of the remaining startup time.

**Per-engine work is multiplied.** An operation added to engine construction runs once per config source, not once per process. This is the single easiest way to make startup slow again: a 20 ms call added to the engine constructor costs 80 ms on a project with four sources.

**Anything that forks a process dominates.** A `git` subprocess costs roughly 10 ms — comparable to the entire Go process floor. Filesystem walks in pure Go are two to three orders of magnitude cheaper.

**Config evaluation is proportional to source size, not source complexity.** A large before-config is parsed and executed in full whenever it is evaluated, even when it only contributes a handful of entries. On a 2 MB chain that is roughly 30 ms — which is why the evaluated result is cached across processes; see [The Config-Evaluation Cache](#the-config-evaluation-cache) below.

## The Git-Root Memo

The repository root is a pure function of the working directory within one process — a command never changes directory mid-run, and the long-lived `datamitsu lsp` changes it only to find the root it serves and to load the config there, one step at a time, never while another lookup or load is running. It is therefore resolved **once per process** for each working directory and memoized for the process lifetime, keyed by the directory the lookup started from. Overlapping callers collapse onto a single resolution rather than racing to duplicate it, and failures are cached too, because a directory does not become a repository mid-run.

:::warning Do not resolve the git root per engine
The memo exists because the root was previously resolved once per engine plus once in the loader — ten forked `git` processes per invocation, about half of all startup overhead. If you add a call site, call the memoized helper (`facts.GetGitRoot`, which takes no directory argument and answers for the process working directory); do not shell out to `git rev-parse` directly.
:::

Two helpers resolve the root today. `facts.GetGitRoot` is the memoized one described here, used by the config loader, by every engine construction, and by `lsp`, which resolves the root it serves with the same helper as the config it loads there. `traverser.GetGitRoot` takes an explicit directory and is used by command handlers (`exec`, `init`, `config reconcile`, `cache`) and the runner; it is not memoized, has no pure-Go path, and ignores `DATAMITSU_FORCE_GIT_SUBPROCESS`. Consolidating the two is follow-up work.

Resolution itself has two paths. The fast path is a pure-Go walk up from the working directory, which reproduces two behaviors a naive walk gets wrong: it reports a _physical_ path with symlinks resolved, and inside a submodule it climbs to the **topmost superproject** rather than stopping at the nearest `.git`. The walk answers only for layouts it can prove and defers to a `git` subprocess for everything else — a bare repository, a repository nested inside another repository's working tree, a separate git directory, an unreadable or malformed `.git` file. A wrong root silently produces wrong project cache keys, so declining is always preferred to guessing.

The superproject climb is gated on a proof rather than on the presence of a `.git` file pointing into a `modules/` directory. Git calls a directory a submodule only while the superproject's **index** records a gitlink (a mode 160000 entry) at that path, and it leaves the submodule's working tree and its `.git` file behind when you check out a branch without it or run `git rm --cached`. In those states `git rev-parse --show-superproject-working-tree` is empty and climbing would answer with a root git disagrees with, so the walk reads both `.gitmodules` and the superproject index and declines unless both name the path. Anything about the index it cannot account for byte for byte — index version 4, whose entry paths are prefix-compressed, an unrecognized entry shape, an implausibly large file — is also a decline.

The walk also declines when the repository config says there is no working tree at the directory holding `.git`. That covers `core.worktree` and the `extensions.worktreeConfig` that lets a per-worktree config set it — the working tree may have moved elsewhere — and `core.bare`, where an otherwise ordinary `.git` directory is marked bare and `git rev-parse --show-toplevel` fails outright with "this operation must be run in a work tree". The `core.bare` check reads the value, not just the key, because `git init` writes `bare = false` into every repository config.

Two further declines reproduce checks git performs that a plain walk up the tree does not have:

- **Ownership.** Git refuses a repository owned by another user ("detected dubious ownership") unless `safe.directory` allows it. The walk declines rather than answering for such a repository, because answering would mean loading and executing a `datamitsu.config.js` that git itself would not touch. Where `safe.directory` _does_ allow it, `git` answers on the fallback path as before.
- **Filesystem boundaries.** Git stops discovery at a mount boundary unless `GIT_DISCOVERY_ACROSS_FILESYSTEM` is set, so a repository above a mount point is not the root for a directory inside it. The walk stops at the same boundary.

Both checks read POSIX ownership and device data, which Windows does not expose. On Windows the walk therefore always declines and `git` resolves the root — correct, but without this page's speedup. `DATAMITSU_STARTUP_TIMINGS=1` shows the difference directly: a declining layout puts `facts.GetGitRoot` back at subprocess cost.

Set `DATAMITSU_FORCE_GIT_SUBPROCESS=1` to skip the walk entirely and always ask `git`. This is the escape hatch for an unforeseen repository layout; it affects the memoized lookup only, not the separate `traverser.GetGitRoot` helper. Both toggles on this page are reported by `datamitsu config runtime` (`startupTimings`, `forceGitSubprocess`).

## Type Stripping Is Skipped for JavaScript

Config sources are run through esbuild to strip TypeScript types — but only when the source may contain them. The decision is made on the **file extension alone**: `.js` and `.mjs` pass through untouched, everything else is stripped.

The rule is deliberately asymmetric. Stripping a file that has no types is wasted work but harmless; skipping a file that _does_ have types hands raw TypeScript to the JavaScript VM and fails far from its cause. So an unrecognized extension always strips. Content sniffing is not used for the same reason — a heuristic that guesses wrong produces a syntax error deep inside the VM.

The embedded default config is the bundler's own JavaScript output, so it skips the pass for the same reason rather than paying an identity transform on every invocation.

Remote and OCI-sourced configs route through the same check. The extension is read from the path component of the source reference only, so a `.js` hostname is not mistaken for a JavaScript file and a query string cannot hide the real extension.

## The Config-Evaluation Cache

Evaluating a 2 MB config chain costs about 30 ms of every invocation: goja parses it, runs its top level, the merged graph is exported out of the VM, and eleven validators run over the result. None of that depends on anything but the inputs, so the **evaluated, validated result** is written to disk and replayed on the next process. Reading and decoding it costs about 2 ms — a 15× reduction on the load, and the largest single saving left in startup.

A JavaScript VM cannot be snapshotted: goja exposes no serialization for a compiled program and no heap snapshot, so only the result can cross a process boundary. That is the whole reason the cache is shaped the way it is.

### What Is in the Key

The key is an XXH3-128 digest — an internal cache key over local files, which is what the hashing policy requires — over inputs chosen so that a hit can only ever be a config a miss would have produced. A key that is too wide costs a miss; a key that is too narrow serves a wrong config silently, so everything a config can observe is folded in:

- The **content hash of every file in the chain, in chain order**. Content, not mtime and size: hashing 2 MB costs a fraction of a millisecond and survives `git checkout`, `git stash` and rebuilds that reset modification times, which mtime does not.
- The **resolved chain shape** — absolute paths in order, `--no-auto-config`, `--skip-remote-config`, and the existence of every auto-config candidate that was _not_ chosen, so creating a higher-priority config invalidates the entry.
- The **whole environment**, sorted.
- Every field of `datamitsuConfigInputs`, the allowlisted values config JS is permitted to branch on.
- The JS-visible [facts](../../reference/configuration-api.md) — os, arch, libc, version, package name, binary path, whether this is a git repository or a monorepo.
- The **working directory and the git root separately**, since managed config content receives paths computed relative to the working directory.
- The resolved `.git/HEAD`, because a branch switch can add, delete or change chain files.
- Whether **colors render**, since the `colors` config global emits ANSI escapes only when they are enabled, and that falls back to whether stdout is a terminal — which no environment variable records.
- The **identity of the binary**: its version, a format version for the artifact schema, and — because every local build reports the version `dev` — a hash of the embedded default config plus the executable's size and modification time.

**Why the whole environment and not the `DATAMITSU_*` subset.** Source mode's staleness key hashes `env.Environ()`, which is deliberately narrow. Config JS sees the entire environment through `facts().env`, and real configs branch on `CI`, so a `DATAMITSU_*`-only key would be defeated by `CI` alone — a CI machine and a developer's shell would share one entry. Only the purely observational variables (`DATAMITSU_TRACE`, `DATAMITSU_TRACE_DIR`, and `DATAMITSU_CONFIG_CACHE` itself) are dropped: a key that folded in the trace flag would make the first traced run miss _because_ it was traced, so the instrument would change the measurement it was reaching for. Those same three are hidden from `facts().env`, so config JS cannot branch on a variable the key does not carry — dropping one from the fingerprint while leaving it readable would turn it into a config input no key could distinguish. Source mode's extra exclusions — the activation markers that say which farm a shell is in, and the execution-only variables such as `DATAMITSU_FAIL_FAST` that change how far one run goes but never what a farm contains — deliberately do **not** carry over, because config JS can read them and there is no rebake loop on this side to protect against.

**Why the binary's identity and not just its version.** Validation and merging run in Go, after the JS, and the head of every chain is a config embedded in the binary — so two builds reporting the same version can produce different evaluations. Released builds carry distinct versions, but every local build says `dev`, and a developer rebuilding after editing the embedded config would otherwise be served the previous build's result until the entry expired.

The key is computed after the chain is resolved, because declared before-configs are only known once the auto config has been read. The one file read before that — the auto config — is snapshotted first, and every chain file is re-hashed after evaluation before the artifact is written, so a file edited mid-evaluation reads as stale instead of being stamped fresh.

### Refusing a Config the Artifact Cannot Reproduce

A config that reads the clock or the entropy source is not a pure function of its inputs, and an artifact holding its result would be served forever without ever erroring — the one failure mode with no external symptom. goja routes `new Date()`, `Date()`, `Date.now()` and `Math.random()` through a time source and a random source, so datamitsu installs recording hooks on both. They are transparent: same values, same types, only an observation flag is set. If any engine in the chain trips it, the load evaluates normally and **writes nothing**.

The refusal is deliberately narrow. `new Date(2020, 0, 1)` never reaches the time source, so a config that builds dates from explicit arguments keeps its cache entry.

**Enumeration order is pinned, not refused.** The chained input and `facts()` are Go maps, and goja enumerates a Go map by ranging over it — so `Object.keys(input.tools)`, a spread and `JSON.stringify(facts().env)` would each observe Go's randomized iteration order. A config that turned that order into an ordered output would produce a different result per run, and the first result would then be the one the cache served. Both surfaces are therefore materialized with their map keys in sorted order before JavaScript sees them; the shapes are goja's own (a nil map is still `{}`, a nil pointer still `null`), only the order is fixed. A duplicated environment variable is collapsed the same way on both sides — last occurrence wins, in `facts().env` and in the hashed environment alike — so two environments that read differently cannot hash the same.

Console output is refused for the same reason from the other direction: a hit runs no JavaScript, so a config that called `console.log` would print on the cold run and fall silent on every run afterwards. A config that logs therefore evaluates every time — which is exactly what it did before this cache existed.

Everything else a miss produces is carried in the artifact rather than lost: the config-validation warnings and the remote-config URLs the chain resolved are stored alongside the config and replayed on a hit, so a command's output does not depend on whether a cache happened to be warm.

### The Artifact Store

Artifacts live under `{cache}/config-eval/{namespace}/{key}.msgpack` — in the cache tree, not the store, so deleting it is always safe. The namespace mirrors the source-mode farm identity: a hash of the git root for a repository chain, or the explicit-config identity for a machine-level `--config` chain. There is no working-directory fallback, which would let two directories share one entry.

msgpack rather than JSON: decoding the ~1.8 MB artifact takes 0.8 ms against 7 ms for JSON of the same graph.

Writes go to a temporary file in the same directory, are flushed, and are renamed into place, never written in place. Entries are immutable per key, so reads need no lock and two processes racing to write the same key are harmless. The stored entry is a nested blob covered by a hash recorded in the envelope: a rename is atomic against a concurrent reader but not against a crash, and a file whose tail is zeros would otherwise decode as a structurally valid but silently truncated config that skipped every validator. A decode failure, a truncated file, a payload that does not match its hash, or an unknown format version is a **miss**, never an error — the bad entry is removed and the config is evaluated — so a corrupt cache degrades to the old cost rather than to a broken CLI. Entries unread for 14 days are pruned on the miss path, so garbage collection never costs a hit anything, and a hit refreshes an entry's timestamp at most once an hour so a config in daily use never expires. Age alone bounds only the rate at which the tree grows — the working directory, the environment, `HEAD` and the binary are all key inputs, so a project mints fresh multi-megabyte artifacts far faster than 14 days retires them — so each project (or machine-level chain) also keeps at most its 8 most recently read entries. `datamitsu cache clear` removes the tree.

### When the Cache Is Bypassed

Three paths always evaluate:

- **`datamitsu config reconcile`** uses the returned JavaScript VM to evaluate managed file content, and a hit has no VM to return.
- Anything that needs **evaluated managed config content** — including `datamitsu config chain-hash` — because that content is a live JavaScript function that cannot be serialized. A hit returns an empty managed-config layer map rather than a partial one, and the callers that need it are gated out instead.
- Loads that **skip lockfile validation**. That path validates less than every other one, so an artifact it wrote could let a later strict load skip an error it exists to raise.

Setting `DATAMITSU_CONFIG_CACHE=0` turns the cache off entirely — nothing is read and nothing is written, so the tree is never created. The value is reported by `datamitsu config runtime` as `configCache`.

Caching the validated result is sound because the validators are a pure function of the merged config, and a binary that validates differently produces a different key — which is why the binary's identity is in the key and is not optional.

## Measuring Startup

Set `DATAMITSU_STARTUP_TIMINGS=1` to get a per-phase breakdown on stderr. Phases are aggregated by name across the process and reported once:

```bash
DATAMITSU_STARTUP_TIMINGS=1 datamitsu exec actionlint -- --version
```

Reported phases cover the total config load, the before-config pre-pass, each engine construction, each git-root resolution, each type-stripping call, and each config evaluation. A phase whose count is higher than you expect is the signal that something moved into a per-source path.

The repository also ships `scripts/bench-overhead.sh`, which measures launch overhead against a bare `bash -c` spawn so the datamitsu-attributable share is isolated from the process floor.

When comparing numbers, use the **minimum** wall time over at least 40 runs. Medians are contaminated by contention on a loaded machine; the minimum is the closest available estimate of the real cost.

---

## Binary Management


datamitsu downloads, verifies, and stores tool binaries so your entire team uses the exact same versions across all platforms. Once configured, binaries are managed automatically with no manual installation required.

## How It Works

When you run a tool through datamitsu (e.g., `datamitsu exec lefthook`), the binary manager:

1. Checks the global store for a matching binary
2. If absent, downloads the binary from the configured URL
3. Verifies the SHA-256 hash of the downloaded file
4. Extracts the binary from its archive format
5. Stores the result at a content-addressed path
6. Executes the binary with your arguments

All of this happens transparently. After the first download, subsequent runs use the stored binary instantly.

## Defining a Binary App

Binary apps are defined in your configuration with platform-specific URLs and hashes:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      lefthook: {
        binary: {
          binaries: {
            darwin: {
              amd64: {
                unknown: {
                  url: "https://github.com/evilmartians/lefthook/releases/download/v1.6.1/lefthook_1.6.1_MacOS_x86_64.gz",
                  hash: "sha256:abc123...",
                  contentType: "gz",
                },
              },
              arm64: {
                unknown: {
                  url: "https://github.com/evilmartians/lefthook/releases/download/v1.6.1/lefthook_1.6.1_MacOS_arm64.gz",
                  hash: "sha256:def456...",
                  contentType: "gz",
                },
              },
            },
            linux: {
              amd64: {
                glibc: {
                  url: "https://github.com/evilmartians/lefthook/releases/download/v1.6.1/lefthook_1.6.1_Linux_x86_64.gz",
                  hash: "sha256:789abc...",
                  contentType: "gz",
                },
              },
            },
          },
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

The `binaries` map uses a three-level nested structure: `os → arch → libc → BinaryOsArchInfo`. Linux platforms use `"glibc"` or `"musl"` as the libc key; non-Linux platforms use `"unknown"`.

## Hash Verification

Every binary download requires a SHA-256 hash. This is a strict security requirement -- datamitsu will refuse to download any binary without a hash.

The hash is verified after download and before extraction. If the hash doesn't match, the download is rejected and an error is returned. This protects against:

- Corrupted downloads
- Tampered binaries
- Supply chain attacks

Hashes are canonical SHA-256 digests — `sha256:` followed by 64 lowercase hex characters:

```javascript
hash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
```

A bare 64-hex pin is rejected at config load.

## Supported Archive Formats

datamitsu supports extracting binaries from these archive formats:

| Format    | Extension  | Description                |
| --------- | ---------- | -------------------------- |
| `tar.gz`  | `.tar.gz`  | Gzip-compressed tar        |
| `tar.xz`  | `.tar.xz`  | XZ-compressed tar          |
| `tar.bz2` | `.tar.bz2` | Bzip2-compressed tar       |
| `tar.zst` | `.tar.zst` | Zstandard-compressed tar   |
| `tar`     | `.tar`     | Uncompressed tar           |
| `zip`     | `.zip`     | Zip archive                |
| `gz`      | `.gz`      | Single gzip file           |
| `bz2`     | `.bz2`     | Single bzip2 file          |
| `xz`      | `.xz`      | Single xz file             |
| `zst`     | `.zst`     | Single zstandard file      |
| `binary`  | -          | Raw binary (no extraction) |

## Platform Support

datamitsu supports a three-dimensional target model:

- **Operating Systems**: darwin (macOS), linux, freebsd, openbsd, windows
- **Architectures**: amd64, arm64, aarch64
- **Libc** (Linux only): glibc, musl, unknown

On Linux, datamitsu automatically detects the libc implementation (glibc vs musl) via multi-stage detection (ldd parsing, ELF interpreter reading, loader path globbing). When a musl-specific binary is available, it is selected automatically. When only a glibc binary exists, datamitsu falls back with a warning.

Not every tool needs to support all platforms. Define only the OS/arch/libc
combinations for which the tool publishes downloads. A direct
`datamitsu exec <app>` fails with a platform error when none matches; a
`fix`/`lint`/`check` plan reports that tool as skipped. Add `--fail-on-skip` in
CI when an unavailable platform binary must fail the run.

## Content-Addressed Storage

Binaries live in the global content-addressed store:

```
{store}/.bin/{name}/{configHash}/
```

On Windows a single-file binary is stored as `{configHash}.exe`: Windows starts a program only by its
extension, so a file without one could be downloaded and verified but never run. Archives extracted
as a directory keep the bare hash on every platform.

The store key (`configHash`) is computed from:

- The binary's URL, hash, format, and extraction metadata
- The resolved target (OS, architecture, and libc)

This means changing any configuration detail (like upgrading to a new version) or running on a different libc variant selects a new store path and triggers a fresh download. Glibc and musl binaries get separate entries.

### Store Location

By default, the store is a child of the standard user cache directory:

- **All platforms**: `~/.cache/datamitsu/store/`

You can override this location by setting the `DATAMITSU_CACHE_DIR` or `XDG_CACHE_HOME` environment variable.

Use `datamitsu store path` to see the exact path, and `datamitsu store clear` to remove all stored binaries.

## Concurrent Downloads

When running `datamitsu init`, binaries are downloaded concurrently. The default concurrency is 3, controllable via the `DATAMITSU_CONCURRENCY` environment variable:

```bash
DATAMITSU_CONCURRENCY=10 datamitsu init
```

Progress bars are displayed during downloads so you can see what's being fetched.

## Download Timeouts and Retries

Downloads have **no overall timeout** — a large archive on a slow link is a healthy download that simply takes a while. Instead, each attempt is watched for progress: if no data arrives for 2 minutes, the attempt is aborted with a `stalled: no data received` error and retried automatically (up to 4 attempts with exponential backoff).

The end-to-end time of a single app install (download + extract + verify) is bounded by `DATAMITSU_INSTALL_TIMEOUT` (600 seconds by default; `0` disables the deadline). On very slow connections raise it for the affected runs:

```bash
DATAMITSU_INSTALL_TIMEOUT=3600 datamitsu init
```

The effective value is introspectable via `datamitsu config runtime | jq .installTimeoutSeconds`.

## Version Checks

Apps can optionally configure version checks used by `datamitsu devtools verify-all`:

```javascript
lefthook: {
  binary: {
    // ... binaries definition
  },
  versionCheck: {
    args: ["version"],  // default is ["--version"]
  },
}
```

Set `versionCheck: { disabled: true }` to skip version checking for tools that don't support it.

## ExtractDir Mode

Some tools need their entire archive extracted as a directory tree rather than a single binary: a JDK distribution, or `protoc`, which finds its well-known types in the `include/` directory beside its own binary and fails on `import "google/protobuf/timestamp.proto"` when only the executable is installed. Set `extractDir: true` in the OS/arch info, and name the command inside the tree with `binaryPath`:

```javascript
binary: {
  binaries: {
    linux: {
      amd64: {
        glibc: {
          url: "https://github.com/protocolbuffers/protobuf/releases/download/v36.2/protoc-36.2-linux-x86_64.zip",
          hash: "sha256:0000000000000000000000000000000000000000000000000000000000000000", // replace with the expected SHA-256 digest
          contentType: "zip",
          binaryPath: "bin/protoc",
          extractDir: true,
        },
      },
    },
  },
}
```

The whole tree is installed under one store directory and `binaryPath` is what runs, so the binary sees its files where the archive put them. `binaryPath` is required with `extractDir`, must be exact, and the `contentType` must be a tar or zip archive. Install fails when the archive does not contain the path, and `devtools verify-all` checks that the path is an executable.

Exact means more than it does for a single-file entry. Extracting one file finds `binaryPath` by its last component when the full path is not in the archive, so a guessed path like `protoc-36.2/protoc` extracts `bin/protoc` and passes `--verify-extraction`; an extracted directory is not searched, so the same guess fails the install. `devtools pull-releases` writes neither `extractDir` nor a path it could not guess, so set both after loading a registry, per operating system:

```javascript
for (const [os, archMap] of Object.entries(apps.protoc.binary.binaries)) {
  for (const libcMap of Object.values(archMap)) {
    for (const entry of Object.values(libcMap)) {
      entry.extractDir = true;
      entry.binaryPath = os === "windows" ? "bin/protoc.exe" : "bin/protoc";
    }
  }
}
```

---

## Config Inspector

Open the resolved configuration for your repository, inspect a tool's scope and file patterns,
then export the same view as a single HTML artifact.

## Open this repository

```bash
datamitsu inspect
```

Open the printed URL. Universe is the default view. The server listens on loopback port 7744;
press Ctrl+C to stop it. It serves a snapshot, so restart after changing the config.
Use `datamitsu inspect --port 0` to let the OS choose a free port.

Normal config flags apply: `--config`, `--before-config`, and `--no-auto-config`.
The command resolves config through the same loader as `config show`; it does not run tools.

## Find out why a tool did not run

Search Operations for the tool. Inspect its enabled/skipped status, configured skip reason,
project types, operation scope, priority, and include/exclude patterns.
The Metadata tab exposes the exported tool definition.

**Status here is the config's declared status, not the result of an execution plan.** A tool
can be enabled in the inspector but skipped for a particular file selection or platform.
Ask the planner about that exact selection:

```bash
datamitsu lint package.json --explain
```

Use `--explain=json` for machine-readable planned tasks and skips. See
[narrowed runs](../reference/cli-commands.md#narrowed-runs) for whole-repository verdicts
and the widening policy.

## Compare config layers

The inspector shows the merged result. It does **not** record which layer introduced,
overrode, or removed a tool, and it does not expose artifact hashes. To inspect a base
in isolation, launch it with `--no-auto-config --config` pointing to that config file,
then compare with the normal repository snapshot. For the ordered inputs and override rules,
see [configuration chaining](configuration.md).

## Export and hand it to someone else

```bash
datamitsu inspect --output atlas.html
```

Open the file directly, upload it as a CI artifact, or publish it on any static host, including
in a subdirectory. It contains all scripts, styles, images, and display metadata. There are no
external asset or data requests. Node.js is needed only to build the interface during development.

To write to stdout:

```bash
datamitsu inspect --output - > atlas.html
```

`--output` and `--port` are mutually exclusive. Export replaces an existing file; its parent
directory must already exist.

The snapshot contains the configuration's own name; app names, descriptions, versions, runtime
families, dependencies and links (`officialUrl`, with `officialUrlDerived` saying whether the
configuration chose the page or datamitsu worked it out — see
[officialUrl](../reference/configuration-api.md#where-to-read-about-an-app-officialurl));
project markers; tool status and reasons; operation scopes, priorities and patterns; and
managed-file ownership. It omits environment values, arguments, file contents, hashes,
lockfiles, and download URLs. Review descriptions and other included text before publishing.
**Dataset** downloads it as JSON — the **inspector manifest**,
`datamitsu-inspector-manifest.json`, not executable config. The artifact carries the same document
in its `inspector-manifest` script element, and the showcase reads it to draw a configuration's
runtime fingerprint.

## Explore the views

- **Universe:** the starting view, with an app directory and an illustrative orbit. Colors show
  runtime membership; positions do not encode dependency relationships. Drag, zoom, or change layouts.
  A selected app links out where its configuration points: **Documentation** when the configuration
  named a page, **Package** or **Repository** when datamitsu derived one.
- **Operations:** filter tools, switch table/cards, and inspect a definition.
- **Blueprints:** configuration totals and runtime distribution, downloadable as SVG.

The search box, the project type and the runtime strip are one selection, and every view reads it:
pick `python-package` and the counters, the orbit, the tables and the diagrams all narrow to it, and
**Reset** returns all of them to the whole snapshot. In Universe the apps left out are dimmed rather
than removed — the sphere keeps its shape, so you read "39 of 111 lit", and a dimmed point answers
neither hover nor click. Operations and Blueprints drop what does not match instead, because a table
row or a bar has to be exactly what it claims. A shared link carries all three filters, so whoever
opens it sees the same selection in every view.

Quick find opens with **Cmd+K**, **Ctrl+K**, or **/**; arrows select and Enter opens a result.
On phones and tablets, selecting an item opens a modal detail panel; Escape or Close returns
to the list. The Auto theme follows the browser's color preference; Light and Dark override it.
Reduced motion stops automatic rotation. The Auto rotation control can also pause it.

This example is the reference wrapper `@shibanet0/datamitsu-config`, version
`0.6.3`, captured on 2026-10-26: 117 apps, 69 tool definitions,
17 project types and 66 managed-file definitions. Native binary: 78; Node.js: 15;
Python: 10; Bun: 6; Go: 4; JVM: 3; Shell: 1. These are one maintainer's choices, not defaults.

<ConfigEmbed view="universe" />

[Open the full atlas](https://datamitsu.com/atlas.html). Environment-dependent settings in this
snapshot may differ from your repository or CI.

## Share or embed your own snapshot

Publish your HTML first. **Share view** copies a URL; **Embed** opens a section picker: Universe
(full section or the minimal orbit), runtime distribution, or tool definitions.
**Copy HTML** copies just that section as an iframe and nothing else: numbers printed beside the
frame would be a second copy of what the frame shows, and would disagree with it the first time
the configuration changes. Local-file and loopback URLs only work
on the same machine. Clipboard access can be unavailable; a dialog then lets you copy manually.
Label your embed with the config owner, version and capture date.

The query contract is the same for hosted and exported files:

| Parameter     | Values / behavior                                                                     |
| ------------- | ------------------------------------------------------------------------------------- |
| `view`        | `universe` (default), `operations`, `blueprints`                                      |
| `embed`       | `universe`, `runtimes`, or `operations` selects only that section; `1` follows `view` |
| `preset`      | `minimal`, with `embed=universe`: the orbit and its runtime strip only                |
| `theme`       | `auto` (default), `light`, `dark`                                                     |
| `tool`        | A tool ID in Operations; opens its detail, or limits an Operations embed to that tool |
| `runtime`     | Runtime family, for example `binary`, `node`, `python`, `jvm`, `go`, `shell`, `bun`   |
| `projectType` | A project-type ID declared in the snapshot                                            |

Unknown values fall back to defaults or no selection. Additional query parameters preserve
search (`q`), status, operation, list style, layout, selected app, detail section and diagram.

Hash bookmarks such as `atlas.html#/operations?tool=eslint&section=metadata` still work.
Outside embed mode, a `#/…` hash takes precedence over query view/filter values; `theme` and `embed` are always
read from the query. Embed mode ignores hashes so an old bookmark cannot change the section. In-page navigation uses hashes and supports back/forward without server
route rewrites. Share emits the current state entirely in the query, without a conflicting hash.

### Frame and sizing

```html
<iframe
  src="atlas.html?embed=runtimes&amp;theme=auto"
  loading="lazy"
  sandbox="allow-scripts"
  referrerpolicy="no-referrer"
  title="My configuration — runtime distribution"
  style="width:100%;aspect-ratio:6 / 1;min-height:180px;border:0;color-scheme:inherit"
></iframe>
```

Blueprints embeds are a single horizontal runtime strip. Reserve **6:1 with a 180px minimum
height**. Operations and Universe use **4:3 with a 420px minimum height**. The minimums keep
labels readable on phones; long tool lists scroll inside the frame. No messaging or parent
script is required. Universe embeds start still, support dragging, and have an accessible directory.

### The minimal orbit preset

`?embed=universe&preset=minimal` is the preset for a README or a landing page: the orbit and its
runtime strip, without the headline, the statistics, the search, the project-type filter, the view
switcher, the layout and zoom controls, or the app inspector panel.

```html
<iframe
  src="atlas.html?embed=universe&amp;preset=minimal&amp;theme=auto"
  loading="lazy"
  sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox"
  referrerpolicy="no-referrer"
  title="My configuration — app orbit"
  style="width:100%;height:clamp(430px, 74svh, 780px);border:0;color-scheme:inherit"
></iframe>
```

- Hovering a point names its app, runtime and pinned version. Focusing a point label does the same.
- Selecting a point or a label opens that app in the full inspector, in a new tab.
- Selecting a runtime in the strip lights up its apps and dims the rest.
- The orbit rotates slowly and can be dragged. `prefers-reduced-motion: reduce` stops the rotation.
- Below the orbit: the runtime strip, the configuration's name and a link to the full inspector.
  The app directory is there for a screen reader and the keyboard, without taking visible room.

The sphere is fitted to the frame, so any height works and none of it is cut off. The extra
sandbox tokens let the frame open the full inspector in a new tab; with `allow-scripts` alone
selecting a point does nothing — an embed never navigates itself to the full site. The canvas takes the pointer, so on phones offer a poster image
with a control that loads the frame rather than letting a drag fight the page scroll. Its runtime
strip sits on a 1560px content rail with the documentation site's gutters, so a full-bleed frame
lines the strip up with the text above it while the orbit keeps the whole width.

### Following a host page's theme toggle

`theme=auto` follows the operating system, which is the wrong answer on a site with its own light
and dark switch. Post the mode to the frame instead:

```js
frame.contentWindow.postMessage({ type: "datamitsu:theme", value: "light" }, "*");
```

`value` is `light`, `dark` or `auto`. The frame applies it and answers its sender with
`{ type: "datamitsu:theme-ack", value }`. Treat a missing acknowledgement as an artifact too old to
know the message and reload the frame with `theme=` in the URL instead. The message only chooses
colors, and a sandboxed frame has no origin of its own to check yours against, so any origin may
send it — never send anything else through it.

The iframe's `color-scheme` inherits from its parent. Set `color-scheme: light` or
`color-scheme: dark` on the embedding container when your site has a manual theme; otherwise
use `color-scheme: light dark` to follow the OS. `theme=auto` reacts to that preference inside
the frame. No browser storage is needed.

**Write your own text beside the frame where a frame may not reach the reader.** A README
renderer may strip iframes entirely, a CSP may block one, and Markdown readers see neither;
a sentence of your own and a link to the hosted atlas cover all three. Add source, version and
capture date in plain Markdown as well. The snippet no longer generates that text for you: a
generated copy of the numbers goes stale the moment the configuration changes, while a sentence
you wrote stays yours to update.

The HTML must be reachable by your readers. A cross-origin host must permit framing (check
its `frame-ancestors` and `X-Frame-Options` headers). Your site's CSP needs the host in
`frame-src`, or `'self'` for same-origin hosting. The exported artifact contains inline scripts
and styles; a host CSP must permit them, for example with hashes computed from the final file.
The recommended sandbox grants scripts only; it grants neither same-origin access nor parent
navigation. Embeds do not fetch data, fonts, or assets.

## Restyle it with a theme file

Every color the inspector draws is a token. A theme file overrides the ones you name and keeps the
rest:

```json
{
  "$schema": "https://datamitsu.com/schemas/inspector-theme.schema.json",
  "dark": {
    "surface": { "base": "#151009" },
    "accent": { "base": "#e2a63e" },
    "runtime": { "node": "#7fd1b9" }
  },
  "light": { "surface": { "base": "#f7f3ea" } }
}
```

```bash
datamitsu inspect --theme ./inspector-theme.json
datamitsu inspect --theme ./inspector-theme.json --output atlas.html
datamitsu inspect --print-theme > inspector-theme.json
```

`--print-theme` writes the theme that would be applied — with no `--theme`, that is the complete
built-in one, which is the starting point for an override. Serving applies the merged theme; an
export bakes it into the HTML, so the file carries its colors wherever it is hosted.

| Group     | Tokens                                                             | Where they show                                                                                                                 |
| --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `surface` | `base`, `panel`, `raised`, `scrim`, `shadow`                       | Page, panels, controls, modal backdrops, shadows                                                                                |
| `text`    | `base`, `muted`                                                    | Body text and secondary text                                                                                                    |
| `line`    | `base`, `orbit`                                                    | Borders, table rules and dividers; `orbit` draws the sphere's rings and the ring around its center, and carries its own opacity |
| `accent`  | `base`, `display`, `glow`                                          | Links and selected states; `display` is the accent at heading size, and `glow` the orbit's rings and core                       |
| `focus`   | `ring`                                                             | The keyboard focus outline                                                                                                      |
| `status`  | `enabled`, `skipped`                                               | Tool status text and the status meter                                                                                           |
| `runtime` | `binary`, `bun`, `go`, `jvm`, `node`, `python`, `shell`, `unknown` | Runtime membership everywhere it is shown                                                                                       |

Both modes and every group and token are optional; `{}` is exactly the built-in theme. A `dark`
override never affects `light`. Colors are `#rgb`, `#rrggbb` or `#rrggbbaa`. Anything else — an
unknown mode, group or token, or a value that is not a color — is an error naming the full key
path, such as `dark.runtme.node: unknown key`, so a typo fails loudly instead of quietly doing
nothing. After merging, the command warns on stderr when text or accent colors fall below the
WCAG AA contrast minimum against their surface — 4.5:1 for body text, and 3:1 for `accent.display`,
which is only ever used at heading sizes; the theme still applies, because that is your call.

Changing the runtime colors breaks the correspondence with this site's orbit and strip, where a
reader has learned which color means which runtime. That is a trade worth making deliberately.

## Publish once, update from the config repository

An embed can point directly at the HTML hosted by your config repository. Generate it after
updating the config, and publish it at the same URL on each deployment:

```bash
datamitsu inspect --output atlas.html
```

Use that published URL in the iframe `src`, followed by `?embed=universe`,
`?embed=runtimes`, or `?embed=operations&tool=eslint`. Each mode renders a dedicated content
section, without the surrounding inspector. The documentation site does not need to rebuild
when you replace the artifact. Readers see the new snapshot on their next page load, subject
to the host's cache policy; configure HTML to revalidate instead of caching it as immutable.
An already-open frame does not poll for changes.

The website's `ConfigEmbed` component also accepts `src` for an external artifact. With an
external source it links to that artifact rather than showing counts or a capture date from
the bundled example. Leave `src` unset for the local demonstration. Publishing a wrapper's
HTML does not make that wrapper mandatory: datamitsu accepts your own configuration too.

---

## Configuration


datamitsu uses JavaScript configuration files to define your tools, runtimes, and project settings. The configuration system supports layered composition, remote inheritance, and dynamic generation through a full JavaScript runtime.

## Configuration Files

datamitsu automatically discovers configuration at your git repository root. It looks for one of these files:

- `datamitsu.config.js`
- `datamitsu.config.mjs`
- `datamitsu.config.ts`

If more than one exists, datamitsu returns an error. You can disable auto-discovery with `--no-auto-config`.

Every configuration file exports `getMinVersion()` and `getConfig(config)`, and
the final resolved config must contain a top-level `version`.

- `getMinVersion()` — Returns the minimum datamitsu version required (semver string). For stable builds, the loader fails with upgrade instructions if the current version is too old. Unstable builds (`0.0.0-unstable.<date>.<sha>`, produced from non-tagged commits) skip the check and emit an advisory warning instead — users on those builds have already opted into a non-released binary.
- `getConfig(config)` — Receives the accumulated configuration from previous layers and returns a new config.

`version` identifies the configuration release and is required on the final
resolved config. The embedded default supplies `core`, inherited as a normal
scalar; a standalone config that discards the incoming config must still supply
its own value. Use a nonempty, single-line label of at most 80 characters, with
no leading or trailing whitespace; it may be a package release version or a
static label such as `core` and does not need to follow semver. Later layers may
override it, and validation checks the final value. It differs from
`getMinVersion()`, the semver minimum compatible datamitsu core version.

The `/// <reference path=".datamitsu/datamitsu.config.d.ts" />` directive at the top of config files enables IDE autocomplete and type checking. This file is automatically generated in the `.datamitsu/` directory when you run `datamitsu init` and contains TypeScript type definitions for the configuration API.

A minimal configuration file:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    version: "1.0.0",
    apps: {
      ...config.apps,
      // your app definitions
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

If `getMinVersion()` is missing, the config fails to load with: "config must export getMinVersion() function returning semver string".

## Config Loading Order

Configuration is loaded in layers, where each layer receives the result of the previous one:

```
default (embedded config.js)
  ↓ [getRemoteConfigs() resolved]
--before-config flags
  ↓ [getRemoteConfigs() resolved]
declared before-configs (auto config's getBeforeConfigs(), only if no --before-config flag)
  ↓ [getRemoteConfigs() resolved]
auto (datamitsu.config.js at git root)
  ↓ [getRemoteConfigs() resolved]
--config flags
  ↓
final Config
```

Each layer can modify, extend, or override the configuration from previous layers.

### Default Configuration

datamitsu ships with a built-in default configuration that provides common tools and sensible defaults. This is always the starting point.

### Before-Config (--before-config)

Use `--before-config` to load configuration files before auto-discovery. This is intended for wrapper packages and shared libraries that provide base configurations:

```bash
datamitsu check --before-config ./node_modules/@myorg/datamitsu-config/base.js
```

### Declared Before-Configs (getBeforeConfigs())

`getBeforeConfigs()` is the config-declared equivalent of the `--before-config` flag. Export it from your auto-discovered git-root config to load local config files as under-layers — without passing `--before-config` on the command line:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getBeforeConfigs() {
  return [{ path: "./node_modules/@myorg/datamitsu-config/datamitsu.config.js" }];
}
globalThis.getBeforeConfigs = getBeforeConfigs;

function getConfig(config) {
  // config already includes the declared before-config's changes
  return { ...config };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

The declared paths are inserted into the loading order **before** the auto config, giving them exact parity with `--before-config` (init-layer merging, `getMinVersion()` checks, remote-config resolution).

Key rules:

- **Why use it:** a wrapper's `bin/datamitsu` shim injects `--before-config` only when datamitsu is invoked through it. A **globally installed** datamitsu run in the same repo never gets that flag and so skips the shared config. Declaring `getBeforeConfigs()` in your git-root config makes the global binary reproduce the wrapper's behaviour automatically — see [Maintaining Wrapper Packages](../how-to/maintain-wrapper.md#global-install-parity-declaring-getbeforeconfigs).
- **Path resolution:** relative paths resolve against the directory of the git-root config file; absolute paths are used as-is. Duplicate paths are deduplicated, declared order is preserved, and a missing file is an error.
- **No hash required:** local paths are in the same trust domain as the root config — they are not network downloads, so the mandatory-hash policy (which applies to `getRemoteConfigs()`) does not apply.
- **Root-only scope:** `getBeforeConfigs()` is honoured **only** in the auto-discovered git-root config. A declaration in any other layer (default, `--before-config`, a remote config, `--config`, or a declared before-config itself) is ignored — there is no chaining.
- **Precedence:** if `--before-config` is passed on the CLI, `getBeforeConfigs()` is **not evaluated at all**. The flag wins, which avoids double-loading the shared config when the wrapper is used.

### Auto-Discovery

datamitsu automatically finds and loads your project's configuration file at the git root. Disable this with `--no-auto-config` when you want full control over which configs are loaded.

### Config Overrides (--config)

Use `--config` to load additional configuration files after auto-discovery. This is useful for CI-specific overrides or testing:

```bash
datamitsu check --config ./ci-config.js
```

## Remote Configs

Any configuration file can export a `getRemoteConfigs()` function to inherit from remote configurations:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getRemoteConfigs() {
  return [
    {
      url: "https://example.com/shared-datamitsu-config.js",
      hash: "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", // SHA-256 digest (required)
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;
```

Remote configs are resolved depth-first before the current config's `getConfig()` runs. This creates an inheritance chain where your local config can build on top of shared organization-wide settings.

Key requirements:

- Every remote config **must** have a SHA-256 `hash` for security verification — write it canonically (`sha256:<64 lowercase hex>`); a bare or uppercase value is accepted there and normalized
- Remote configs are stored under `{store}/.remote-configs`; cached bytes are
  accepted only when their SHA-256 matches (no TTL)
- Circular dependencies are detected and produce an error
- HTTPS-to-HTTP redirects are rejected for security

### Wrapper Package Pattern

Remote configs enable a wrapper package pattern for sharing configuration across teams:

```javascript
// @myorg/datamitsu-config/index.js
function getRemoteConfigs() {
  return [
    {
      url: "https://config.myorg.com/datamitsu/base.js",
      hash: "sha256:abc123...",
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;

function getConfig(config) {
  return {
    ...config,
    // organization-specific overrides
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";
```

Teams use this via `--before-config`:

```bash
datamitsu check --before-config ./node_modules/@myorg/datamitsu-config/index.js
```

## Ignore Rules

Ignore rules can be defined both in `.datamitsuignore` files and in the configuration:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    ignoreRules: [
      "*.generated.ts: eslint, prettier",
      "vendor/**/*: *",
      "!vendor/important.go: golangci-lint",
    ],
  };
}
globalThis.getConfig = getConfig;
```

Config-defined ignore rules use append semantics across config layers -- previous rules are preserved and new rules are added.

See the [Ignore Rules reference](/docs/reference/ignore-rules) for full syntax documentation.

## JavaScript Runtime

Configuration files run in a JavaScript VM (goja) with access to several built-in APIs:

- **Format utilities**: `YAML.parse()`/`YAML.stringify()`, `TOML.parse()`/`TOML.stringify()`, `INI.parse()`/`INI.stringify()` for parsing and generating config file content
- **Nested settings**: `merge(base, overrides, ...)` recursively combines plain objects into a new object. Later values win, including `false`, `0` and `null`; arrays replace rather than append. Nested objects and arrays are copied without mutating inputs. Cyclic settings and non-object sources are rejected.
- **Path utilities**: `tools.Path.join()`, `tools.Path.abs()`, `tools.Path.rel()`, `tools.Path.forImport()`
- **Config links**: `tools.Config.linkPath()` for computing paths to `.datamitsu/` symlinks
- **Ignore utilities**: `tools.Ignore.parse()`, `tools.Ignore.stringify()` for working with ignore patterns
- **Facts**: `facts()` returns platform, process, and environment information
  (`os`, `arch`, `libc`, `binaryPath`, `binaryCommand`, repository flags, and
  `env`). `env` is the whole observable process environment except
  observation-only tracing/config-cache controls.
- **pnpm defaults**: frozen `pnpmWorkspaceDefaults` publishes the recommended
  pnpm workspace security policy from the Go source of truth
- **Config inputs**: frozen `datamitsuConfigInputs` exposes only runtime values
  config is explicitly allowed to branch on; currently
  `minimumReleaseAgeMinutes`
- **Console**: `console.log()`, `console.warn()`, `console.error()` for debugging

See the [Configuration API reference](/docs/reference/configuration-api) for complete API documentation.

The evaluated result is cached on disk per set of inputs, so an unchanged config chain is not re-evaluated on the next command (see [the config-evaluation cache](/docs/guides/architecture/startup#the-config-evaluation-cache)). A config that reads the clock (`Date.now()`, `new Date()` with no arguments), calls `Math.random()`, or writes to `console.*` still evaluates normally — it simply never gets a cache entry, because a cache hit runs no JavaScript and could not reproduce the value or the output. Dates built from explicit arguments (`new Date(2020, 0, 1)`) are pure and cost nothing.

## Environment Variables

Frequently used variables are below. See the
[CLI environment reference](/docs/reference/cli-commands#environment-variables)
for the complete list and effective defaults.

| Variable                          | Description                                | Default                                      |
| --------------------------------- | ------------------------------------------ | -------------------------------------------- |
| `DATAMITSU_CONCURRENCY`           | Concurrent downloads during `init`         | 3                                            |
| `DATAMITSU_MAX_PARALLEL_WORKERS`  | Max parallel tool workers                  | `max(4, floor(NumCPU * 0.75))`, capped at 16 |
| `DATAMITSU_UNIT_CACHE_TTL`        | Minutes a project-level verdict is trusted | `1440` (24h)                                 |
| `DATAMITSU_FAIL_FAST`             | Stop at the first failing tool             | `true` (`false` runs everything)             |
| `DATAMITSU_FAIL_ON`               | Raise every operation's `failOn`           | - (`warning`, `info` or `hint` raises it)    |
| `DATAMITSU_LSP_FORMAT_WIDEN_TO`   | Editor format-on-save widening             | `unit`                                       |
| `DATAMITSU_LSP_FORMAT_TIMEOUT_MS` | Editor format-on-save watchdog, in ms      | `15000` (`0` disables)                       |
| `DATAMITSU_CONFIG_CACHE`          | Serve the evaluated config chain from disk | `1` (`0`/`false`/`off`/`no` disables)        |
| `DATAMITSU_NO_SPONSOR`            | Suppress sponsor messages                  | -                                            |
| `NO_COLOR`                        | Disable color output                       | -                                            |
| `FORCE_COLOR`                     | Force color output                         | -                                            |

## Inspect a resolved tool

This reference snapshot selects ESLint from the wrapper `@shibanet0/datamitsu-config`,
`0.6.3`, captured on 2026-10-26. It is enabled,
runs per project, and declares fix priority 6 and lint priority 12. These are
the wrapper's choices, not core defaults. The inspector shows the merged result,
not layer provenance.

<ConfigEmbed view="operations" tool="eslint" />

[Open the full atlas](https://datamitsu.com/atlas.html).
See the [Config Inspector guide](config-inspector.md) to inspect or embed your own configuration.

---

## Managed Configs


datamitsu can distribute configuration files from runtime-managed apps (Bun/Node/UV) to your project via symlinks. This lets you share tool configurations like ESLint configs, Prettier configs, or any other files that tools need to find at your project root.

## The .datamitsu/ Directory

When you run `datamitsu init`, it creates a `.datamitsu/` directory at your git root containing symlinks to files inside the install directories of installed apps:

```
project-root/
├── .datamitsu/
│   ├── datamitsu.config.d.ts  # auto-generated type definitions
│   ├── configs/               # ejectable managed configs the project has not ejected
│   ├── eslint-config → {store}/.apps/node/my-eslint-config/{hash}/dist/eslint.config.js
│   └── prettier-config → {store}/.apps/node/my-prettier-config/{hash}/.prettierrc.json
├── eslint.config.js          # imports from .datamitsu/eslint-config
└── .prettierrc.json          # symlink via ManagedConfig
```

The `.datamitsu/` directory is:

- Recreated atomically on each `datamitsu init` run; `configs/` is carried over, and rewritten by init itself
- Listed in `.gitignore` (not committed to the repository)
- Contains an auto-generated `.gitignore` file with `*` as a defensive measure — prevents accidental commits if `.datamitsu/` is not listed in your root `.gitignore`
- Contains a `datamitsu.config.d.ts` file with TypeScript type definitions for IDE autocomplete when editing `datamitsu.config.js`/`.ts`/`.mjs` files
- Verified after creation (symlink existence, correct target, target file exists)

## App Links

Apps declare links using the `links` field, which maps link names to relative paths within the app's install directory:

```javascript
apps: {
  "my-eslint-config": {
    node: {
      packageName: "@myorg/eslint-config",
      version: "2.0.0",
      binPath: "node_modules/.bin/eslint",
      lockFile: "br:...",
    },
    links: {
      "eslint-config": "dist/eslint.config.js",
      "eslint-plugin": "dist/plugin.js",
    },
  },
}
```

This creates symlinks at `.datamitsu/eslint-config` and `.datamitsu/eslint-plugin` pointing to the respective files in the app's install directory.

### When links are created

`.datamitsu/` links follow installation — a link exists only once its source app is installed:

- **Eager apps (default)** — every app that declares `links` is installed during `datamitsu init`, so its links are created then. This covers apps a tool runs, as well as apps whose links are consumed by git hooks or `managedConfigs` entries (for example, commitlint, run by the commit-msg hook with its config imported from a `.datamitsu/` symlink).
- **Lazy apps** — an app that sets `lazy: true` is **not** installed at init. It installs the first time you run it with `datamitsu exec <app>`, and its `.datamitsu/` links are materialized at that point. Use this for user-invoked CLIs whose dependencies are heavy and aren't needed until the app is actually run (for example, a presentation tool like slidev, which would otherwise pull a headless browser at init).

Mark an app `lazy` only when nothing else depends on it being present right after `init` — a tool, hook, or generated config that references the app's link needs the app eager (the default).

### Path Safety

Link paths are validated for security:

- No absolute paths allowed
- No parent directory traversal (`..`)
- No symlink escapes outside the install directory

## App Files

Apps can also include static file content that gets written to the install directory before the package manager runs:

```javascript
apps: {
  "my-tool": {
    node: {
      packageName: "my-tool",
      version: "1.0.0",
      binPath: "node_modules/.bin/my-tool",
      lockFile: "br:...",
    },
    files: {
      ".npmrc": "registry=https://registry.myorg.com\n",
      "tsconfig.json": '{"compilerOptions": {"target": "es2022"}}',
    },
  },
}
```

## App Archives

For distributing full directory trees, apps support archives via the `archives` field:

### Inline Archives

Small directory trees can be embedded directly in the configuration as brotli-compressed tar archives:

```javascript
archives: {
  "config-files": {
    inline: "tar.br:...",  // brotli-compressed, base64-encoded tar
  },
}
```

Generate inline archives with:

```bash
datamitsu devtools pack-inline-archive ./my-config-dir
```

### External Archives

Larger archives can be downloaded from URLs with mandatory SHA-256 hash verification
(canonical `sha256:<64 lowercase hex>` digests):

```javascript
archives: {
  "config-bundle": {
    url: "https://example.com/config-v2.tar.gz",
    hash: "sha256:abc123def456789012345678901234567890123456789012345678901234abcd",
    format: "tar.gz",
  },
}
```

### Extraction Order

1. Archives are extracted first (sorted alphabetically by name; later archives overwrite earlier ones for overlapping paths)
2. Files are written next (always overwrite archive contents)
3. The runtime package manager runs last (`pnpm install` / `uv sync`)

## Using tools.Config.linkPath()

In your JavaScript configuration, use `tools.Config.linkPath()` to compute relative paths from a project directory to a `.datamitsu/` symlink:

```javascript
const managedConfigs = {
  "eslint.config.js": {
    content: (context) => {
      const configPath = tools.Config.linkPath(
        "my-eslint-config", // app name
        "eslint-config", // link name
        context.cwdPath, // from this directory
      );
      return `import config from "${tools.Path.forImport(configPath)}";\nexport default config;\n`;
    },
  },
};
```

The `tools.Config.linkPath()` function validates that the link name exists and belongs to the specified app.

## Using tools.Path APIs

The Path API helps generate correct file paths in configuration files:

```javascript
// Join path segments
tools.Path.join("src", "config", "eslint.js");
// → "src/config/eslint.js"

// Make a path suitable for ES module imports
tools.Path.forImport(tools.Path.join(context.datamitsuDir, "eslint.config.js"));
// → "./.datamitsu/eslint.config.js"
// (forImport adds ./ prefix needed by ES module import statements)
```

`tools.Path.forImport()` ensures relative paths start with `./` or `../`, which JavaScript/TypeScript `import` statements require. It's idempotent -- paths already starting with `./` or `../` are returned unchanged.

## Managed Config Files and Root Symlinks

Beyond `.datamitsu/` links, `managedConfigs` entries describe files and
symlinks owned directly in your project. Preview their reconciliation with
`datamitsu config reconcile --dry-run`; run `datamitsu config reconcile` to
write them and then run `datamitsu fix`.

```javascript
const managedConfigs = {
  // Write file content, associated with the eslint tool
  ".eslintrc.js": {
    tools: ["eslint"],
    content: (context) => `module.exports = { /* ... */ };`,
  },
  // Create a symlink instead of writing content
  ".prettierrc": {
    tools: ["prettier"],
    linkTarget: ".datamitsu/prettier-config",
  },
};
```

Optionally associate an entry with one or more tools via `tools`. When you run
[`datamitsu config reconcile --tools <names>`](../reference/cli-commands.md#config-reconcile), only the
config files whose `tools` intersect the selected set are considered and
everything else is left untouched — ideal for iterating on a single tool's config
without rewriting your whole project. Entries with no `tools` (shared
infrastructure like `.gitignore` or `lefthook.yaml`) are skipped whenever
`--tools` is passed. Add `--dry-run` to preview the scoped plan, or
`--skip-fix` to write it without running the scoped fix afterward.

The `content()` function receives a context object with:

- `projectTypes` - detected project types in the directory
- `projectLocations` - every detected `{ type, path }` pair, relative to the git root; populated during reconciliation
- `rootPath` - git repository root
- `cwdPath` - current working directory
- `isRoot` - whether cwdPath is the repository root
- `datamitsuDir` - relative path from cwdPath to `{rootPath}/.datamitsu/`
- `existingContent` - previous config layer's generated content for this file (undefined if no prior layer generated content)
- `originalContent` - unmodified content of the file as it exists on disk during reconciliation
- `existingPath` - path to the existing file on disk during reconciliation, if it exists
- `placement` - `"repo"` for a file written into the repository, `"internal"` for a render into `.datamitsu/configs/`
- `outputPath`, `outputDir` - where the returned content is written
- `datamitsuDirFromOutput` - relative path from `outputDir` to `{rootPath}/.datamitsu/`, for references the file resolves against its own location

### Keeping tool configs out of the repository

Most tools need their config only to run. An entry marked `ejectable` lives in
`.datamitsu/configs/` instead of the repository, and the tool is handed its path
through the `{managedConfig:<key>}` placeholder:

```javascript
const managedConfigs = {
  ".yamlfmt.yaml": {
    scope: "git-root",
    tools: ["yamlfmt"],
    ejectable: true,
    content: () => "formatter:\n  type: basic\n",
  },
};
// tools.yamlfmt.operations.fix.args: ["-conf", "{managedConfig:.yamlfmt.yaml}", "{files}"]
```

Who writes the file depends on where it lives:

| Placement                                | Written by                   | Changed by                                 |
| ---------------------------------------- | ---------------------------- | ------------------------------------------ |
| `.datamitsu/configs/<key>` (not ejected) | `datamitsu init`             | the configuration; never edit it           |
| `<key>` in the repository (ejected)      | `datamitsu config reconcile` | you, and reconcile's merge on the next run |

A project that needs to change the file — to allow a gitleaks finding, say — ejects
it by naming the tool:

```javascript
return { ...input, ejectConfigs: ["gitleaks"] };
```

then runs `datamitsu config reconcile --tools gitleaks` to write
`.gitleaks.toml` into the repository, where the tool now reads it. Removing the
tool from `ejectConfigs` reverses it: reconciliation deletes the repository copy
if it holds nothing of the project's own, and refuses — naming the file —
if it does. Until the file is where the configuration says, `lint` and `fix`
report which command to run instead of running the tool against a missing or
ignored file.

Only tool operations receive the path. `datamitsu exec <app>`, source-mode
shims, CI actions and editor extensions that run a tool themselves do not, so an
author keeps every file those read by name — `.editorconfig`, ESLint and Prettier
configs, `lefthook.yaml` — in the repository. See the
[configuration reference](../reference/configuration-api.md#keeping-configs-out-of-the-repository-ejectable--ejectconfigs)
for the exact rules.

### Detecting upstream drift (`expectChainHash`)

Configs are produced by **layering**: a shared config (plus any remote/before
layers) generates a baseline, and your root config — at the git root, or an
explicit `--config` — runs last on top, where you apply project-specific
overrides. Those overrides are written against a particular baseline. If the
shared config later changes, a plain `datamitsu config reconcile` re-derives the file and can
silently overwrite your tweaks.

Set `expectChainHash` on a root-layer entry to pin the baseline your overrides
assume — the XXH3-128 hash of the content entering your layer, _before_ your layer
transforms it:

```javascript
const managedConfigs = {
  "eslint.config.mjs": {
    expectChainHash: "xxh3:0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    content: (context) => {
      /* overrides layered on top of the shared config */
    },
  },
};
```

`datamitsu config reconcile` recomputes that hash during both dry-runs and
normal reconciliation.
If it still matches, reconciliation proceeds; if the upstream chain **drifted**, reconciliation aborts **before writing
anything** and prints the new hash and incoming content so you can reconcile your
overrides and update the pin. The check is opt-in per file, honoured only on the
root layer, byte-for-byte (no normalization), and can be bypassed with
`datamitsu config reconcile --no-verify-hash`.

To get the initial value, declare the entry (a placeholder pin is fine) and read
the real hash with `datamitsu config chain-hash <file>` — it prints exactly what
the gate checks, so no fake-failure dance is needed. See the
[`expectChainHash` reference](../reference/configuration-api.md#pinning-the-upstream-chain-expectchainhash)
for the full contract.

:::note Which files to pin
Configs whose handler folds your own on-disk file into the result (e.g. a YAML
linter config merged with what you already have) will see the hash move when
**you** edit the file too, not just on upstream changes. Pinning is most useful
for files generated from a fixed template (the import-style shims like
`eslint.config.mjs`, `prettier.config.mjs`), where the incoming content is a pure
function of the upstream version.
:::

:::tip Architecture
Learn more about how datamitsu plans and schedules tool execution in [Task Planning](./architecture/planner.md).
:::

## Smart Init

`datamitsu init` uses smart initialization: it scans your tool definitions to find which apps are actually referenced, then installs only those apps that have Links defined. You don't need to mark apps as `required: true` for their links to work.

Use `--all` to download all configured binaries regardless of usage:

```bash
datamitsu init --all
```

## Windows Support

On Windows, symlinks require Developer Mode to be enabled. datamitsu uses symlinks only -- there is no fallback to file copies.

---

## Managed Content (Bundles)


Bundles distribute managed content (files and directory trees) to repositories
through symlinks. Unlike apps, bundles are not executable: static content lives
in a hash-keyed directory in the global store and is exposed through
`.datamitsu/`.

## The Problem

Without bundles, `datamitsu init` writes files (e.g. `agents.md`, skill definitions) directly into repositories. When the content changes in the config, every repository must be manually patched — causing git conflicts or silent staleness.

With bundles, content lives in a hash-keyed store directory. The repository only
holds a symlink in `.datamitsu/`. Running `datamitsu init` atomically updates the
symlink to point to the new hash directory — no git conflicts and no manual
patching.

## Defining a Bundle

Bundles are configured under the top-level `bundles` field in your config:

```javascript
const config = {
  bundles: {
    "agent-skills": {
      version: "1.0",
      files: {
        "agents.md": "# Agent instructions\n\nFollow these guidelines...",
        "skills/search.md": "# Search skill\n\nUse this skill to...",
      },
      links: {
        "agent-skills-dir": ".", // link to entire bundle directory
        "agents-md": "agents.md", // link to a single file
      },
    },
  },
};
```

### Bundle Fields

| Field      | Type                          | Description                                                  |
| ---------- | ----------------------------- | ------------------------------------------------------------ |
| `version`  | `string`                      | Version identifier included in the store key                 |
| `files`    | `Record<string, string>`      | Filename to content mapping (written to install dir)         |
| `archives` | `Record<string, ArchiveSpec>` | Named archives (inline or external) extracted to install dir |
| `links`    | `Record<string, string>`      | Link name to relative path mapping for `.datamitsu/`         |

A bundle must have at least `files` or `archives` (or both). The `links` field defines what gets exposed via `.datamitsu/` symlinks.

## Directory Links

Link values can point to files or directories within the bundle's install directory. Use `"."` to link to the entire bundle directory:

```javascript
bundles: {
  "my-content": {
    version: "2.0",
    files: {
      "config.yaml": "key: value\n",
      "templates/main.html": "<html>...</html>",
      "templates/partial.html": "...",
    },
    links: {
      "my-content": ".",              // symlink to entire bundle dir
      "my-templates": "templates",    // symlink to a subdirectory
      "my-config": "config.yaml",     // symlink to a single file
    },
  },
}
```

After `datamitsu init`, the `.datamitsu/` directory will contain:

```
.datamitsu/
├── my-content → ~/.cache/datamitsu/store/.bundles/my-content/{hash}/
├── my-templates → ~/.cache/datamitsu/store/.bundles/my-content/{hash}/templates/
└── my-config → ~/.cache/datamitsu/store/.bundles/my-content/{hash}/config.yaml
```

## How Store Keys Work

Bundles are stored at `{store}/.bundles/{name}/{hash}/`, where the hash is computed from:

- Bundle name
- Version string
- Content of all files
- Content/configuration of all archives

When you change the version, file content, or archive content, the hash changes. On the next `datamitsu init`:

1. A new directory is created with the new hash
2. Files and archives are written to the new directory
3. The `.datamitsu/` symlinks are updated to point to the new directory

This is atomic — the old content remains until the symlink is switched.

## Using Archives in Bundles

Bundles support the same archive types as apps:

### Inline Archives

Small directory trees embedded directly in the config:

```javascript
bundles: {
  "config-bundle": {
    version: "1.0",
    archives: {
      "configs": {
        inline: "tar.br:...",  // brotli-compressed, base64-encoded tar
      },
    },
    links: {
      "configs": ".",
    },
  },
}
```

Generate inline archives with:

```bash
datamitsu devtools pack-inline-archive ./my-directory
```

### External Archives

Larger content downloaded from URLs with mandatory SHA-256 hash verification:

```javascript
bundles: {
  "large-content": {
    version: "3.0",
    archives: {
      "data": {
        url: "https://example.com/content-v3.tar.gz",
        hash: "sha256:0000000000000000000000000000000000000000000000000000000000000000", // replace with the expected SHA-256 digest
        format: "tar.gz",
      },
    },
    links: {
      "large-content": ".",
    },
  },
}
```

:::note
Bundles with only inline files/archives install regardless of `--skip-download`. Bundles with external archives respect `--skip-download`.
:::

## Bundle Management Commands

```bash
# List all configured bundles with install status
datamitsu devtools bundles list

# Show install path and file tree for a bundle
datamitsu devtools bundles inspect my-bundle

# Print the install directory path
datamitsu devtools bundles path my-bundle
```

## Bundles vs Apps

Bundles and apps serve different purposes:

| Feature       | Bundle                      | App                                    |
| ------------- | --------------------------- | -------------------------------------- |
| Executable    | No                          | Yes (`datamitsu exec`)                 |
| Runtime       | None                        | binary, Bun, UV, Node, JVM, Go, shell  |
| Content       | Files + archives            | Bun/UV/Node content or managed package |
| Links         | Yes (`.datamitsu/`)         | Yes (`.datamitsu/`)                    |
| Version check | No                          | Optional (`versionCheck`)              |
| Use case      | Static content distribution | Tool/binary management                 |

Link names must be unique across both apps and bundles since they share the `.datamitsu/` directory.

## Shared Storage

Shared Storage is a `map[string]string` field on `Config` that flows through the config chain. It provides a standardized way to pass arbitrary data between config layers that doesn't fit the typed config structure.

### When to Use Shared Storage

- Passing vendored content (e.g., `llms.txt`) between config layers
- Feature flags that downstream configs can read
- Any key-value data that needs to survive config layer merging

### Example

In a root config (e.g., a remote config or `--before-config`):

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(input) {
  return {
    ...input,
    sharedStorage: {
      ...input.sharedStorage,
      "llms-txt": "# Project documentation for LLMs...",
      "feature-new-lint": "true",
    },
  };
}
```

In a downstream config (e.g., your repo's `datamitsu.config.js`):

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(input) {
  const llmsTxt = input.sharedStorage?.["llms-txt"];
  const useNewLint = input.sharedStorage?.["feature-new-lint"] === "true";

  return {
    ...input,
    // Use the shared data however you need
    bundles: {
      ...input.bundles,
      "llms-txt": llmsTxt
        ? {
            version: "1.0",
            files: { "llms.txt": llmsTxt },
            links: { "llms-txt": "llms.txt" },
          }
        : undefined,
    },
  };
}
```

### How It Works

`sharedStorage` is a regular field on `Config`. Each config layer receives the previous config as `input`, so `input.sharedStorage` contains whatever the previous layers set. Unlike structured fields like `apps` where replacement loses upstream data, `sharedStorage` is designed for explicit spread-and-extend patterns.

## Limitations

- Bundles require `datamitsu init` to refresh — changes to bundle content are not reflected until you re-run init
- Bundle link names share the `.datamitsu/` namespace with app links — names must be unique across both
- External archive bundles require network access during `datamitsu init` (unless `--skip-download` is used)

---

## OCI Bundles


An OCI bundle packages the datamitsu tool store as a standard OCI image: one layer per store subtree (a binary, a runtime, a runtime-managed app, or a WASM output-parser module), annotated so datamitsu can pull exactly the pieces it needs — **without docker or podman**. The bundle is a cache accelerator and an airgap seed, not a replacement for resolution: whatever is in the bundle is taken from it, whatever is not gets downloaded the usual way.

WASM output-parser modules (the `parsers` config entity) ship as their own `.parsers/<module>` layers, materialized in the build by a `devtools parsers prefetch` stage and re-verified against their published SHA-256. So in an airgapped deployment a tool's `outputParser` resolves from the bundle instead of reaching out to the GitHub Release. A parser entry can also pin a registry artifact of its own, independently of any bundle — see [Mirroring everything](#mirroring-everything).

Prepared app state (the [prepare](/docs/reference/configuration-api#one-time-preparation-step-prepare) step's output) ships as its own `.prepared/<app>` layer, built in the app's stage and keyed by the prepared key the consumer's config computes. Seeding that layer makes the state ready **without ever running the step** — the main reason the airgap scenario stays closed end to end. A state directory only counts when its readiness marker is present, so an interrupted placement never masks a missing layer: the next seed (or run) moves the remnant aside and replaces it.

```mermaid
flowchart LR
    subgraph Producer["Producer (CI, community toolchain)"]
        DF["devtools dockerfile--emit-oci-map"] --> BX["docker buildx(per-subtree COPY --link)"]
        BX --> PP["post-process(regctl: annotations, bundle index)"]
        PP --> REG[("OCI registryghcr.io/owner/tool-store")]
    end
    subgraph Consumer["Consumer (no docker)"]
        REG -->|"pull by digest,sha256-verified"| SEED["datamitsu store seed /auto-seed"]
        SEED --> STORE[("~/.cache/datamitsu/store")]
    end
```

## Declaring a bundle

The config gains a top-level [`oci` key](/docs/reference/configuration-api#oci-bundle-oci):

```javascript
function getConfig(input) {
  return {
    ...input,
    oci: {
      ref: "ghcr.io/owner/tool-store",
      digest: "sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b",
    },
  };
}
```

The digest is mandatory — a tag never pins content. The declaration chains through config layers as a scalar (last writer wins, `{...input}` inherits), so a wrapper config can ship it and a project config keeps it automatically.

## How seeding works

Two paths use the same machinery:

- **Auto-seed (demand-driven).** Before `check`/`fix`/`lint` pre-install, `install`, and `init`, datamitsu computes the store paths the current operation needs (tools plus their execution-time runtime dependencies, including shared CPython for uv apps) and pulls **only those layers**. pnpm is an install-time dependency for Bun and Node apps and is not bundled once an app environment has been built. A bundle of 50 tools costs a project that needs 3 of them one cached manifest GET plus 3–5 blob downloads. If everything is already in the store, no network request is made at all.
- **`datamitsu store seed` (full pull).** Pulls every annotated layer — the airgap workflow. A completed full pull writes a marker inside the store, so repeating it is a no-op; `store clear` removes the marker together with the content.

Multi-platform bundles are a single OCI index. os/arch are matched via the standard platform fields; **libc** (glibc vs musl) via the `com.datamitsu.libc` descriptor annotation inside the digest-verified index bytes. When libc detection fails (e.g. distroless hosts), datamitsu refuses to guess — set `DATAMITSU_LIBC=glibc` or `DATAMITSU_LIBC=musl`.

A bundle entry missing for your platform is a degradation, not a failure: datamitsu warns and falls back to direct downloads.

### Slow links and retries

Blob downloads have **no overall timeout** — a 400 MiB layer on a 1 Mbps VPN is a healthy download that simply takes a while. Instead, each attempt is watched for **progress**: if no data arrives for 2 minutes, the attempt is aborted with a clear `stalled: no data received` error and retried (up to 4 attempts with exponential backoff). Registry metadata requests (manifests, auth token handshake) carry small bodies and keep a flat 120-second deadline.

The store commands also work without a usable git context (no `git` binary, `dubious ownership` errors in containers): they operate on the global store, so a broken project repo only skips the project-level config with a warning instead of failing the command.

## Trust model

The bundle is **not a trust boundary by itself**:

- Every manifest body and blob is verified against its SHA-256 descriptor **before** extraction — not a single unverified byte enters the chain. Trusting `oci.digest` is equivalent to trusting the config source that declares it (same as the per-binary `hash` fields today).
- Single-file binaries and JVM jars are **re-hashed after extraction against the published SHA-256 from the config** — a bundle whose content was swapped relative to the config fails hard.
- Runtime app directories (bun/uv/node/go) have no published content hash (they are built, not downloaded); their integrity rests on the digest chain plus the mandatory lockfiles.
- Each layer may only write into the single store subtree it declares (`com.datamitsu.subtree`); content outside it — including hardlinks pointing elsewhere — fails the pull loudly.
- `oci.signer` is **rejected at config load** — on the bundle's `oci` and on a parser's `oci` alike. This build carries no sigstore dependency and verifies **no signatures at all**, so a config that pins a signer would assert a guarantee the binary does not deliver; a loud error before any network beats silent non-verification. Integrity rests on the digest chain and the mandatory hashes above. (Breaking change: a config that set `signer` used to load and fail later, at seed time.)

## Offline mode

`DATAMITSU_OFFLINE` is a full "don't touch the network" switch, **orthogonal** to bundles: it never auto-pulls; the store must be seeded beforehand — `store seed` while online, [`store import`](/docs/reference/cli-commands#store-import) from an OCI layout directory, or a volume mount. With a seeded store, tools resolve with zero network; a miss fails with a clear message instead of a hanging download.

```bash
# online machine
datamitsu store seed

# air-gapped machine (same store, e.g. copied or mounted)
DATAMITSU_OFFLINE=1 datamitsu check
```

Both the offline switch and the seeding state are introspectable:

```bash
datamitsu config runtime | jq '.offline, .noOci, .libc'
datamitsu store status
```

## Mirroring everything

A parser module can be pinned to a registry as well: a `parsers` entry declares either an https `url` **or** an [`oci` reference](/docs/reference/configuration-api#output-parsers-parsers), never both, never a fallback from one to the other. That closes the last gap in "mirror one registry and everything works" — the bundle carries the binaries, the runtimes and the runtime-managed apps, and the parser artifact carries the WASM module that otherwise comes from a GitHub Release.

A bundle and a parser `oci` pin are complements rather than competitors. A module is stored at `{store}/.parsers/{name}/{key}`, and that key is derived from its SHA-256 alone — so for a given entry a bundle-seeded module and a registry-pulled one are the same directory: whichever arrives first satisfies the other. A module already on disk is re-hashed against the declared SHA-256 on every use and discarded if it no longer matches, whatever put it there.

Start by asking the config what it pins. [`store refs`](/docs/reference/cli-commands#store-refs) reads the effective config and makes no registry request, so it runs from inside a firewall:

```bash
datamitsu store refs --oci-only
# ghcr.io/datamitsu/datamitsu-parsers@sha256:8f0e…
# ghcr.io/owner/tool-store@sha256:6c3c…
```

Copy both with the community toolchain (`crane`, `regctl` and `skopeo` all do this; `crane` shown here). Tag the mirrored copies — an untagged manifest is a garbage-collection target, and a collected artifact fails every pinned config:

```bash
crane copy ghcr.io/owner/tool-store@sha256:6c3c… harbor.corp/dm/tool-store:mirror
crane copy ghcr.io/datamitsu/datamitsu-parsers@sha256:8f0e… harbor.corp/dm/datamitsu-parsers:mirror
```

A copy moves manifest and blob bytes verbatim, so **every digest survives the move unchanged**. Only the host segment of each reference is edited; `digest` and `hash` stay exactly as published, and both references keep pointing at the same bytes as before:

```javascript
function getConfig(input) {
  return {
    ...input,
    oci: { ...input.oci, ref: "harbor.corp/dm/tool-store" },
    parsers: {
      ...input.parsers,
      core: {
        ...input.parsers.core,
        oci: { ...input.parsers.core.oci, ref: "harbor.corp/dm/datamitsu-parsers" },
      },
    },
  };
}
```

Both spreads assume the inherited config already pins the parser to a registry. If it declares a `url` instead, **replace** the entry's source rather than spreading `oci` alongside it: the two sources are mutually exclusive and an entry carrying both fails at config load.

Move both keys or neither. A half-mirrored config still resolves its tools, so the mistake is easy to miss: a parser that cannot be fetched is only logged as a warning and the tool's output degrades to raw text.

```javascript
// BAD: the bundle is mirrored, the parser is not — a host behind the firewall
// loses structured diagnostics and the run only warns about it
oci: { ...input.oci, ref: "harbor.corp/dm/tool-store" },

// GOOD: both references move to the mirror, digests and hashes untouched
oci: { ...input.oci, ref: "harbor.corp/dm/tool-store" },
parsers: {
  ...input.parsers,
  core: { ...input.parsers.core, oci: { ...input.parsers.core.oci, ref: "harbor.corp/dm/datamitsu-parsers" } },
},
```

The mirror is not a trust boundary either. A parser artifact's single layer must have exactly the digest the parser's mandatory `hash` names (the same `sha256:`-prefixed value), so a manifest that points at different content is rejected **before one payload byte is requested**; the bytes are hashed again while streaming and once more on the file on disk. A registry that rewrites manifests while proxying them changes their digest and fails the pull closed instead of serving something unexpected.

:::warning Limitations of a mirrored registry
datamitsu can authenticate to exactly one registry: **GHCR**, using `GITHUB_TOKEN`, and only when the configured `ref` host is `ghcr.io` — the token is never attached to any other host. There is no docker `config.json`, no credential helper, no user/password, no custom CA bundle. A Harbor, Artifactory or Nexus mirror must therefore allow **anonymous pull** of the mirrored repositories; an authenticated private mirror is not supported yet.

GHCR is also the only channel for the parser artifact today — unlike the datamitsu container images, it is not published to Docker Hub.
:::

## Kill switches

- `--no-oci` (any command) or `DATAMITSU_NO_OCI=1` — disable bundle seeding entirely; tools download directly as before. It switches off an accelerator, so it does **not** disable a parser that declares an `oci` source: that registry is the only route to those bytes. `DATAMITSU_OFFLINE` remains the hard network gate.
- Bundles change **where bytes come from**, never which versions run: tool
  resolution and content-addressed store keys are identical with and without a
  bundle.

## Producing a bundle

Bundle production deliberately reuses the community toolchain instead of reimplementing a registry client push:

1. `datamitsu devtools dockerfile --emit-oci-map map.json` generates the multi-stage Dockerfile (whose final stage already emits one `COPY --link` layer per store subtree — including a `.prepared/<app>` layer for every app with a `prepare` step, `kind: "prepared"` in the map) plus the layer→subtree map.
2. `docker buildx` builds and pushes the image(s) per platform/libc.
3. A CI post-process (regctl/crane) writes the `com.datamitsu.subtree` layer annotations and the `com.datamitsu.store-root` manifest annotation from `map.json`, assembles the bundle index with libc descriptor annotations, tags it (untagged indexes are vulnerable to registry cleanup), and optionally signs it with cosign.

A mapping mistake in step 3 is not a security hole: the consumer's per-subtree write-allowlist validates layer content against the declared subtree and fails loudly at pull time.

---

## Reports


A report is the record of one `fix`, `lint` or `check` run: which tools ran, on
which files, what they found, and how sure datamitsu is that the list is
complete. Every report format is written from that one record, so two formats of
one run never disagree, and a report is written after a run that failed as well
as after one that passed — the run that fails is the one a pipeline needs to
read.

```bash
datamitsu lint --report json=out/run.json
```

`json` writes datamitsu's own document, `datamitsu.report/1`, which carries
everything the record holds; `markdown` writes the same run for a person — the
tools, the findings the terminal would show and what the run left out; `sarif`
writes it for GitHub code scanning ([Code scanning](#code-scanning)); `junit`,
`codequality`, `checkstyle` and `rdjsonl` write it for the CI systems and
review tools that read test results, code quality reports, Checkstyle and
reviewdog's diagnostics ([Other CI systems](#other-ci-systems)); `history`
appends one line of counts per run to a trend file ([History](#history)). The
flags, the variable twins and the exit codes are in the
[CLI reference](../reference/cli-commands.md#reports).

## What a report holds

```mermaid
graph TD
    R["run: selection, failFast, complete, incomplete, exports, ci"] --> O["operations: fix, lint"]
    O --> T["tools: app, parser, failOn, complete, incomplete"]
    T --> I["invocations: one per process — state, exit code, extraction"]
    I --> F["files: path, state"]
    I --> D["findings: fingerprint, rule, level, message, location"]
```

- **The run** — what it was asked to cover (`selection`: the whole repository,
  a subdirectory, named files, a `--tools` filter), whether fail-fast was on,
  whether the run is complete, every report it was asked for with its
  status, and the CI job it ran in (`ci`: the `vendor` — empty outside CI —
  and the commit, ref, base branch and pull request number the vendor names,
  as [`facts().ci`](../reference/configuration-api.md#platform-information)
  reads them).
- **Operations** — `fix` and `lint` in the order they ran; `check` writes one
  document holding both. An operation the run never reached is listed with
  `ran: false`. Each lists the tools the planner skipped, with the reason, and
  the tasks the run stopped.
- **Tools** — the app a tool ran as configured (name, kind, pinned version),
  its output parser and the version of the module that read its output, the
  threshold its findings were judged by (`failOn`), and whether that threshold
  was enforced.
- **Invocations** — one per process a task planned: its state (`ran`,
  `cancelled`, `not-started`, `setup-failed`), its exit code, whether and how
  its output was read into findings, the files it answered for and the findings
  it reported. The files a cache answered appear as one `cached` or
  `verdict-hit` invocation of their task.
- **Findings** — the rule, the level, whether it is at or above the threshold
  (`reported`), whether it failed its tool (`gates`) and whether the terminal
  shows it (`shown`, which the annotations, `markdown` and `--output agent`
  follow), whether a [baseline](#baselines) held it (`baselined`), the
  message, where it is — the path relative to the repository root, 1-based
  rows and columns with an exclusive end — and its fingerprint, whose version
  the run states (`fingerprint`).
- **Changes** — for a `fix`, the files it changed (see
  [Changed files](#changed-files)): on each invocation, with the `step` it ran
  in, and on the operation for a file no invocation was given; whether they
  were observed (`changesObserved`, `changesReason`) and within what
  (`changesScope`). A file result holds the `patch` a formatter applied when
  `--report patch` was asked for.

Everything is sorted, so one run gives one document byte for byte, and the time
it is stamped with comes from `SOURCE_DATE_EPOCH` when that is set.

## What a report never contains

- **No command line and no environment.** An app is named by its name, kind and
  pinned version; the arguments a tool ran with and the variables it saw stay
  out. (`--explain=json`, a plan for debugging on your own machine, keeps the
  arguments.)
- **No secret the environment names.** Before a report is written, the value of
  every variable — in the environment, and in every app's and operation's `env`
  — whose name contains `TOKEN`, `SECRET`, `PASSWORD` or `CREDENTIAL`, or ends
  in `_KEY`, and that is at least 8 characters long, is replaced by `***`
  wherever it appears. This is best effort: a secret a tool prints that no
  variable holds is not caught.
- **No output of a security tool.** A failed invocation keeps the last 4 KiB of
  its output in the own JSON (`outputTail`), without colour codes and masked —
  except for a tool whose parser module puts it in the `security` category,
  whose output is never kept, nor that of a tool whose parser the run could not
  describe — its module did not load, or does not list it — which may be one.
- **Nothing from a cache.** A report is never stored and never replayed; each is
  written from the run that produced it.

The same holds for the JSON-L stream's events. Under `--verbose` the stream
carries datamitsu's debug log lines too, as `log` events, with what a tool
printed and the arguments it ran with withheld; the console keeps them for the
person who ran the command.

A tool that exits non-zero without a finding its parser could read is not
listed as clean: it gets one `synthetic` finding of level `error` and no
location — `tsc exited 2 without parsable findings`, or
`gitleaks failed (exit 1); output withheld for a security tool` — whose message
carries none of the tool's output.

## How complete a report is

A report that lists no finding for a tool means "clean" only when the tool
covered what the report claims. Every tool is judged on three facts, and each
one that fails adds a reason to its `incomplete` list:

| Fact       | Complete when                                                                                        | Reasons                                                                                                             |
| ---------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| scope      | the run covered the whole repository and every task its whole unit                                   | `narrowed-selection`, `partial-unit`                                                                                |
| execution  | every planned task ran to the end                                                                    | `cancelled`, `not-started`, `setup-failed`, `platform-skip`                                                         |
| extraction | every output was read into findings by a parser, or a cache replayed a pass its parser read as clean | `no-extraction`, `parser-unavailable`, `parse-failed`, `truncated`, `unparsed-cache-hit`, `failed-without-findings` |

A complete result in one project says nothing about the projects a narrowed run
left out, which is why scope needs the whole repository. A tool whose output no
parser read — neither a declared one nor the
[fallback](./architecture/parsers.md#three-layers) built into datamitsu — is never
complete (`no-extraction`, or `parse-failed` when a parser was declared): its exit
code says whether it passed, not what it found. Neither is a tool that exited
non-zero while the parser that recognized its output found nothing in it
(`failed-without-findings`): the failure is not in what it printed, and a report
that listed the tool would read it as clean — code scanning would close every
alert the tool had.

A cached pass carries no record of what read the output it stands for, so a
cache hit of a tool without a declared parser is `unparsed-cache-hit` even when
the fallback had read that output clean: warm runs of such a tool are incomplete
until a parser is declared for it.

The run is `complete` when every tool is, every operation ran, and the run left
nothing out: a narrowed selection, a `--tools` filter (the tools it left out are
listed as `selection.excludedTools`; the selected tools can still be complete),
a tool that could not be narrowed, an operation that did not run. A tool
disabled with `skip: true` counts against nothing.

Two rules keep a report from claiming more than it holds:

- **A narrowed run is refused.** A report that lists findings, asked for from
  a run narrowed before it starts — files named, a subdirectory, `--file-scoped`,
  `--tools` — would read as the findings of the repository. The run exits 2
  before anything runs. `--allow-partial` writes it anyway, with every reason in
  the document; it never makes the run complete. `sarif` is written: it leaves
  out every tool whose completeness is not established instead of listing it
  ([Code scanning](#code-scanning)).
- **A report turns fail-fast off.** A run that stopped at the first failing tool
  could not list every finding, so a report runs everything to the end, and a
  report together with an explicit `--fail-fast=true` is refused.

A run can still end up incomplete — a tool cancelled, an output its parser
could not read, a tool without a parser — and a format has to say so. The own
JSON and `markdown` say it themselves, and `sarif` leaves such a tool out. A
format whose shape has no place for the claim — `junit`, `codequality`,
`checkstyle`, `rdjsonl` — is written in full and gets a **completeness
companion** beside it, `<path>.completeness.json`:

```json
{
  "schema": "datamitsu.completeness/1",
  "format": "junit",
  "complete": false,
  "incomplete": [],
  "tools": [
    { "operation": "lint", "name": "eslint", "complete": true, "incomplete": [] },
    { "operation": "lint", "name": "tsc", "complete": false, "incomplete": ["cancelled"] }
  ],
  "exports": []
}
```

Read alone, a report of that format cannot tell a clean run from a tool that did
not cover everything, and a service that compares one run with the last reads a
finding that is missing as fixed. A job checks the companion before it
publishes: `jq -e .complete <path>.completeness.json`. `complete` is true when
every tool the report holds is complete and the run left nothing out; `tools`
names each one, `incomplete` the run-level reasons, and `omitted` counts the
findings the format could not carry, by tool and reason. Every tool that is not
complete also gets one `WARN` line on stderr naming the reports that leave it
out or flag it, and the report's entry in the own JSON's `exports` names its
companion. A report written to stdout has no companion, and its warning says so.

A report left on its path by an earlier run is not deleted: it is the user's
file. A run that is refused, or whose report could not be written, leaves it
there, so a pipeline that uploads the report whatever the outcome removes it
first — then an old report cannot pass for the new one — and fails on the exit
code of the run:

```yaml
- run: rm -f out/run.json
- run: datamitsu lint --report json=out/run.json
- if: always()
  uses: actions/upload-artifact@v4
  with:
    name: datamitsu-report
    path: out/run.json
    if-no-files-found: warn
```

The job fails on the lint step's exit code, and the upload step runs anyway. A
tool failure (1) outranks a report that could not be written (5), so a missing
file on a failed step is reported by the upload, and by the step's own
`error: report json: …` line.

## In GitHub Actions

CI runs `lint`: `fix` and `check` change the working tree, which a pipeline has
no one to review. A job that annotates a pull request, keeps every finding and
fails on the exit code of the run:

```yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 2
      - run: rm -f out/run.json
      - run: datamitsu lint --fail-fast=false --report json=out/run.json
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: datamitsu-report
          path: out/run.json
          if-no-files-found: warn
```

- **Annotations need nothing.** In a GitHub Actions job the run prints its
  findings as workflow commands, which GitHub shows in the Checks tab and on the
  changed lines of the pull request
  ([GitHub annotations](../reference/cli-commands.md#github-annotations)).
  GitHub keeps ten of each type per step: the findings in the files the pull
  request touched come first, then one per file, and a notice counts the rest
  and names where they are. Several datamitsu commands in one step
  share those ten.
- **The step summary holds the rest.** The run appends its `markdown` report
  to the job's summary page, as much of it as fits in the 1 MiB GitHub takes
  from a step; `json` holds everything.
- **`fetch-depth: 2`** fetches the base branch's tip, the first parent of the
  merge commit a `pull_request` checks out, which is how the run learns which
  files the pull request touched. Without it the order is the same, less that
  priority, and one `info` line says so.
- **`--fail-fast=false`** runs every tool, so the annotations and the report
  cover the whole repository; the report turns fail-fast off by itself.
- **`if: always()`** uploads the report of the run that failed, which is the one
  worth reading; `rm -f` first keeps an old report from passing for the new one.

A tool's own output never becomes an annotation: the run prints it inside a
`::stop-commands::` region, and a tool that would print its own workflow
commands when it sees `GITHUB_ACTIONS` does not see it
([Tool Environment](../reference/tool-environment.md)). The problem matchers of
`actions/setup-go` and `actions/setup-node` still read every line; the only
ones that can match what the run prints are `go` and `eslint-compact`, on a
tool's raw output in their formats, which GitHub then annotates without a
location.

### Code scanning

`--report sarif=<path>` writes the run in SARIF 2.1.0, which GitHub code
scanning keeps as alerts: it shows a finding on the pull request that brings it
in, and closes the alert once a later upload of the tool no longer holds it.

```yaml
jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 2
      - run: rm -rf sarif
      - run: datamitsu lint --fail-fast=false --report sarif=sarif/
      # One step per file, each uploaded on its own.
      - if: always() && hashFiles('sarif/datamitsu-1.sarif') != ''
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: sarif/datamitsu-1.sarif
      - if: always() && hashFiles('sarif/datamitsu-2.sarif') != ''
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: sarif/datamitsu-2.sarif
```

- **One run per tool, of `lint`.** A file holds one run per tool of the lint
  operation — `check` writes its lint, a `fix` run its fix — because GitHub
  rejects a file with two runs of one tool in one category.
- **A tool that did not cover everything is left out.** An alert is closed when
  the next upload of its tool does not hold it, so a tool whose completeness is
  not established ([How complete a report is](#how-complete-a-report-is)) is
  not written at all, and its alerts stay as they were. The run says so on
  stderr, one line per tool, and the own JSON records it in the report's
  `exports` entry (`omitted`). That holds for a tool that failed without a
  parsable finding too: GitHub closes every alert of a tool whose run holds no
  result, even one whose invocation says it did not succeed. For the same
  reason a narrowed run is not refused: `--tools` writes each selected tool
  that is complete and leaves the others' alerts alone, and named files, a
  subdirectory or `--file-scoped` leave every tool out. GitHub refuses a SARIF
  file without a run, so a report that would hold none is not written at all:
  a file an earlier run left at its path, or its directory's
  `datamitsu-<n>.sarif` files, are removed, the export is recorded as
  `omitted`, a `WARN` line says so, and every alert stays as it is. A tool with
  more than 25 000 results is left out too: GitHub would keep the 5 000 most
  severe and close the alerts of the rest.
- **Twenty tools per file.** GitHub reads at most twenty runs from one file. A
  path that ends in `/` names a directory: `datamitsu-1.sarif`,
  `datamitsu-2.sarif` and so on, twenty tools each, sorted by name, and the
  `datamitsu-<n>.sarif` files an earlier run left there that this one did not
  write are removed. Upload each file in a step of its own: `upload-sarif`
  combines the files of a directory into one upload, which GitHub refuses
  above twenty runs just the same. A configuration of up to twenty tools
  writes `datamitsu-1.sarif` alone, and needs one more step for every twenty
  more. A file, or `-`, for a
  run that plans more than twenty tools exits 2 before anything runs. GitHub
  refuses an upload of more than 10 MB gzipped.
- **The category is in the file.** Every run is written under the category
  `datamitsu` (`automationDetails.id` `datamitsu/`). The upload action's
  `category` input does not change a file that already names one, so a job
  that uploads more than once — a matrix — names its own:
  `--report "sarif=sarif/?category=lint-${{ matrix.os }}"`. Uploads in one
  category replace each other's alerts tool by tool. An alert is one rule at
  one fingerprint, whatever the category: the same finding uploaded under two
  categories is one alert with an instance in each, which stays open until the
  next upload of every one of them leaves it out.
- **Findings keep their alerts.** A result's
  `partialFingerprints.primaryLocationLineHash` is the finding's
  [fingerprint](#fingerprints), the key GitHub matches alerts on from one upload
  to the next; two tools never share one. Columns count code points
  (`columnKind: unicodeCodePoints`) and are left out where the report could not
  convert them. The upload action computes a fingerprint of its own for every
  result and, where it differs from datamitsu's, logs a warning and keeps
  datamitsu's: expect one "Calculated fingerprint … inconsistent" warning per
  result in the upload step's log.
- **What else a run holds.** `ruleId` is the finding's rule, or
  `<tool>/unknown` without one, each rule listed once with its documentation
  link; the tool's app version and official URL; one `invocations` entry per
  process. A finding without a file is a notification of its invocation: code
  scanning shows a result only at a location. A file outside the repository is
  an absolute `file://` URI.

Before turning it on:

- The job needs `security-events: write`. A pull request from a fork gets a
  read-only token and cannot upload.
- A private repository needs GitHub's code scanning licence.
- A tool that is never uploaded again — removed from the configuration,
  renamed (the run is named by the tool's key in the configuration), or skipped
  by a condition — keeps its alerts open. Deleting its analyses
  (`DELETE /repos/{owner}/{repo}/code-scanning/analyses/{id}?confirm_delete`)
  removes them, and their history with them.
- `rm -rf` before the run and `hashFiles` on the upload keep a file an earlier
  step left from passing for this run's, and skip the upload when there is
  nothing to upload: a run refused before it starts (exit 2) writes nothing,
  and neither does one whose every tool is left out. `if: always()` uploads the
  file of a run whose tools failed, which is the one worth reading.

## Other CI systems

Every CI system has a place for what a run found that a log line cannot reach.
Each recipe runs `lint --fail-fast=false`, so every tool runs to the end, and
publishes its report whatever the outcome.

### Test results (JUnit)

`--report junit=<path>` writes the run as JUnit XML, which GitLab, Jenkins,
Azure Pipelines, CircleCI, Buildkite and Bitbucket read as test results. A test
report fails a build on one failed case, so a case fails only where the run
failed:

- **One suite per operation and tool**, named `<operation>/<tool>`, with its
  completeness in `properties`: `complete`, `incomplete`, `cached` (the files a
  cache answered), and the run's `run.complete` and `run.incomplete`. `check`
  gives suites for both operations.
- **One case per file** a tool answered for. A file fails
  (`<failure type="threshold">`) when a finding on it is at or above the
  operation's `failOn` and failed its tool; its findings are the failure's text,
  one per line as `path:row:col: level source(code): message`. Findings below
  the threshold are the case's `<system-out>`, and the file passes. Clean and
  cached files pass, and so does every clean file of a tool that failed.
- **One extra case for each process that failed without such a finding**,
  named after the directory it ran in (`.` for the repository root), with the
  process's ID after it when several of the tool's ran there: a process that
  exited non-zero on findings below the threshold is a `<failure type="exit">`
  listing them — unless a file it answered for already fails on a gating
  finding, which says the same — and one that failed without any is an
  `<error type="exit">`
  carrying the last lines of its output, masked — never a `security` tool's.
  A process that could not be set up is an `<error type="setup">`, and a
  finding without a file is on its process's case too. A failed tsc run over a
  project fails one case, not every file in it.
- **Skipped cases** for what did not run: `cancelled: fail-fast` and
  `not started: fail-fast` for the tasks the run stopped, `not started` for
  one it never reached on its own account (its tool could not be installed),
  `skip: true`,
  `platform-skip` and `narrowed` for the tools the planner skipped, and
  `did not run` for an operation that never started.

The failure count is the number of files that failed the gate, not the number
of findings. A narrowed run refuses the report unless `--allow-partial`, and the
completeness companion is written beside it.

GitLab reads the report from `artifacts:reports:junit`:

```yaml
lint:
  script:
    - rm -rf reports
    - datamitsu lint --fail-fast=false --report junit=reports/junit.xml
  after_script:
    # GitLab reads a test missing from the report as fixed.
    - jq -e .complete reports/junit.xml.completeness.json > /dev/null || rm -f reports/junit.xml
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml
    paths:
      - reports/
```

Every other consumer compares runs or fails builds on what the report lists
too, so each recipe publishes it only when its companion says it is complete.
Jenkins' JUnit plugin is in the recipe under [Checkstyle](#checkstyle).

Azure Pipelines publishes it with `PublishTestResults@2`:

```yaml
steps:
  - script: rm -rf reports
  - script: datamitsu lint --fail-fast=false --report junit=reports/junit.xml
  - script: jq -e .complete reports/junit.xml.completeness.json || rm -f reports/junit.xml
    condition: always()
  - task: PublishTestResults@2
    condition: always()
    inputs:
      testResultsFormat: JUnit
      testResultsFiles: reports/junit.xml
```

CircleCI reads every JUnit file under the directory `store_test_results` names:

```yaml
steps:
  - run: rm -rf reports
  - run: datamitsu lint --fail-fast=false --report junit=reports/datamitsu/junit.xml
  - run:
      when: always
      command: jq -e .complete reports/datamitsu/junit.xml.completeness.json || rm -f reports/datamitsu/junit.xml
  - store_test_results:
      path: reports
```

Buildkite Test Engine takes it through the test collector plugin, which needs
the suite's `BUILDKITE_ANALYTICS_TOKEN`:

```yaml
steps:
  - command: |
      rm -f junit.xml junit.xml.completeness.json
      status=0
      datamitsu lint --fail-fast=false --report junit=junit.xml || status=$?
      jq -e .complete junit.xml.completeness.json || rm -f junit.xml
      exit "$status"
    plugins:
      - test-collector#v1.12.0:
          files: junit.xml
          format: junit
```

Bitbucket Pipelines reads the files it finds under `test-results/` on its own:

```yaml
pipelines:
  default:
    - step:
        script:
          - rm -rf test-results
          - status=0
          - datamitsu lint --fail-fast=false --report junit=test-results/datamitsu.xml || status=$?
          - jq -e .complete test-results/datamitsu.xml.completeness.json || rm -f test-results/datamitsu.xml
          - exit "$status"
```

### Azure Pipelines and TeamCity

Both read commands from the log, so the run needs no step of its own: under
`TF_BUILD` it logs each error and warning as an issue of the task, under
`TEAMCITY_VERSION` it reports each finding as an inspection and each tool that
failed without one as a build problem.

```yaml
# azure-pipelines.yml
steps:
  - checkout: self
    fetchDepth: 0 # the target branch, for touched-file priority
  - script: datamitsu lint --fail-fast=false --report json=$(Build.ArtifactStagingDirectory)/run.json
    displayName: lint
```

```text
# TeamCity command line build step
datamitsu lint --fail-fast=false
```

- **Azure keeps ten issues of each type per task.** Findings in the files the
  pull request touched come first — they are read from
  `origin/<target branch>`, so fetch it — and a plain line says how many did not
  fit and where they are; `info` and `hint` have no issue type and are left out.
  Publish the JSON report as an artifact for the rest.
- **TeamCity keeps everything.** Inspections appear in the build's Inspections
  tab; a finding without a file cannot be an inspection and is counted instead.
- **No tool output issues a command.** Azure runs `##vso[` wherever it appears
  in a line, TeamCity reads `##teamcity[` the same way, on stdout and stderr.
  In either CI — whatever `--annotations` says — and in either mode, datamitsu
  rewrites the prefix, with a space, in every line it prints that holds tool
  output or a repository path: raw output, parsed messages, command lines,
  directories, file names, progress labels, agent records, the debug log of
  `--verbose`, the plan of `--explain`, the annotations of another CI and the
  JSON-L events. That is one space of difference in a raw line. TeamCity's
  results block is also wrapped in `disableServiceMessages` …
  `enableServiceMessages`.
- **A document on stdout keeps its meaning.** A report written to stdout (`-`),
  by a run or by `report render`, has the bracket after `##vso` and
  `##teamcity` spelled `\u005b` in a JSON format and `&#91;` in an XML one,
  which read back as the same text; Markdown and `patch` get the space.
- **A run killed in the middle** — a second interrupt, a timeout that kills the
  process — leaves TeamCity's reading suspended for the rest of the build step,
  as it leaves GitHub's stop-commands region open; a run interrupted once
  closes it.

### GitLab Code Quality

`--report codequality=<path>` writes GitLab's Code Quality report, the array
GitLab reads from `artifacts:reports:codequality`, merges across a pipeline's
jobs and compares with the target branch's, to show in a merge request what it
brings in and what it fixes:

```yaml
lint:
  script:
    - rm -f gl-code-quality.json junit.xml *.completeness.json
    - datamitsu lint --fail-fast=false --report codequality=gl-code-quality.json --report junit=junit.xml
  after_script:
    # An incomplete report would show every finding it misses as fixed.
    - |
      for companion in *.completeness.json; do
        jq -e .complete "$companion" > /dev/null || rm -f "${companion%.completeness.json}"
      done
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality.json
      junit: junit.xml
    paths:
      - "*.completeness.json"
```

- One issue per finding of the `lint` operation (`check` writes its lint, a
  `fix` run its fix), every level: `check_name` is `<source>/<rule>`,
  `description` the message, `fingerprint` the finding's
  [fingerprint](#fingerprints), unique in the report. `severity` is `major`
  for an error, `minor` for a warning and `info` for info and hints; datamitsu
  never writes `critical` or `blocker`, which no core level means.
  `categories` is `Security` for a `security` tool and `Style` otherwise.
- `location.path` is relative to the repository root. `positions` carries the
  columns in characters where the report could convert them, `lines` the rows
  where it could not. A finding without a file, and one outside the
  repository, cannot be placed and is left out; the companion counts them
  (`omitted`) and one `WARN` line says so.
- GitLab compares the merged report of the merge request's pipeline with the
  target branch's, so a finding a report misses reads as fixed. A tool that is
  not complete is kept, with the findings it has, and the companion says it is
  not; the `after_script` above keeps GitLab from comparing such a report, and
  from reading tests missing from an incomplete JUnit report as fixed.

### Checkstyle

`--report checkstyle=<path>` writes Checkstyle XML: one `<file>` per file, one
`<error>` per finding of the `lint` operation (fix for a `fix` run), every
level, with `line`, `column` (characters, left out where the report could not
convert it), `severity` (`error`, `warning`, and `info` for info and hints),
`message` and `source` (`<source>/<rule>`). A finding without a file, the
`synthetic` finding of a tool that failed without a parsable one included, is
under `<file name="">`; a file outside the repository keeps its absolute path.

Jenkins' Warnings Next Generation plugin reads it, or the SARIF file, and
compares each build with a reference build to tell new findings from fixed
ones — which is why a narrowed run refuses the report and an incomplete tool is
flagged in the companion rather than left out:

```groovy
stage('Lint') {
  steps {
    sh 'rm -rf reports'
    sh 'datamitsu lint --fail-fast=false --report checkstyle=reports/checkstyle.xml --report junit=reports/junit.xml'
  }
  post {
    always {
      script {
        // An incomplete report would show what it misses as fixed.
        if (sh(returnStatus: true, script: 'jq -e .complete reports/checkstyle.xml.completeness.json') == 0) {
          recordIssues tools: [checkStyle(pattern: 'reports/checkstyle.xml')]
        }
        if (sh(returnStatus: true, script: 'jq -e .complete reports/junit.xml.completeness.json') == 0) {
          junit 'reports/junit.xml'
        }
      }
    }
  }
}
```

`recordIssues tools: [sarif(pattern: 'reports/datamitsu-*.sarif')]` reads the
SARIF files of `--report sarif=reports/` instead. Azure Pipelines shows SARIF
files published as the `CodeAnalysisLogs` build artifact in the Scans tab of
the SARIF SAST Scans Tab extension.

### reviewdog

`--report rdjsonl=<path>` writes reviewdog's rdjsonl, one diagnostic per line:
`message`, `location` (the path, and a range whose columns are UTF-8 bytes with
an exclusive end, as reviewdog counts them, left out where the report could not
convert them), `severity` (`ERROR`, `WARNING`, and `INFO` for info and hints),
`source` (the tool, with its app's official URL) and `code` (the rule and its
documentation). A finding without a file is a line without a location.
reviewdog turns it into review comments on the forge it reports to, filtered to
the lines a change touched:

```bash
rm -f rd.jsonl
status=0
datamitsu lint --fail-fast=false --report rdjsonl=rd.jsonl || status=$?
if [ -f rd.jsonl ]; then
  reviewdog -f=rdjsonl -reporter=github-pr-review < rd.jsonl
fi
exit "$status"
```

The run's exit code is kept for the end, so a lint that fails still gets its
comments — the run whose comments matter most — and still fails the job.

reviewdog itself compares nothing between runs, but the rdjsonl stream lists
findings like the other formats, so a narrowed run refuses it and the
companion is written beside it. Suggested fixes are not written.

## Fingerprints

Every finding carries a `fingerprint`, 64 hexadecimal characters that identify
it across runs, so that a service tracking alerts can tell a finding that stayed
from one that was fixed and one that is new:

```text
fingerprint = sha256("dmfp1" NUL tool NUL rule NUL path NUL lineHash NUL ordinal)
lineHash    = sha256(the finding's first line, without trailing whitespace)
ordinal     = position among the tool's findings with the same rule on the same line
```

- **A line inserted above a finding moves its row, not its fingerprint:** the
  line's text is hashed, not its number.
- **A reworded message changes nothing:** the message is not an input.
- **Two findings of one rule on one line stay two:** the ordinal counts them by
  column, across every process of the tool, so how a tool's work was split into
  processes does not change it. A finding two processes both reported is listed
  once.
- **Two tools never share one:** the tool comes first.
- **Paths are relative to the repository root with `/`**, so one finding has one
  fingerprint on Windows and elsewhere.

When the file cannot be read — it was deleted, or lies outside the repository,
which is never read — the row stands in for the line, and `fingerprintBasis` says `row` instead of
`line`; a finding without a file rests on nothing (`none`). The fingerprint is
SHA-256 rather than a faster hash because it is not an internal key: another
system stores it and compares it with the next upload's.

The columns of a finding are the ones its tool printed, in the unit its parser
declares (`unit`: `utf-8`, `utf-16` or `utf-32`). While the file is still on
disk they are converted into code points (`chars`), UTF-8 bytes (`bytes`) and
UTF-16 units (`utf16`), so a report rendered later needs no source. `precision`
is `exact`; `ascii` when no unit was declared but the line is ASCII, where every
unit counts alike; or `unknown` when there was nothing to convert from, and a
consumer that needs another unit then leaves the column out.

A report settles a finding's ordinal once its tool has finished, across all
of the tool's processes. The fingerprint a finding has while its own process is
judged — before the threshold decides — is counted within that process; the two
agree whenever one process reports the findings of a line, which is every tool
that runs once per file and every tool whose findings name the files it was
given.

## Changed files

A `fix` changes the working tree, and whoever reads its result — an agent that
holds the files in memory, a job that commits the fix — has to know which files.
The report records them: a snapshot of the working tree is taken before the
first group of tools that run together and after every group, and each file
whose state moved between two of them is a change, `created`, `modified`,
`deleted` or `reverted` (a dirty file a formatter restored to what the commit
holds).

```mermaid
graph LR
    S0["snapshot"] --> G1["group 1: prettier, gofmt"]
    G1 --> S1["snapshot"]
    S1 --> G2["group 2: eslint --fix"]
    G2 --> S2["snapshot"]
```

The tools of one group ran over disjoint files, so a change between two
snapshots belongs to the tool of that group that was given the file — it is
listed on that invocation — and to the operation when none was. A snapshot is
taken after a group that failed or was cancelled too: a formatter may have
written part of its files.

- **What is observed.** Tracked and untracked files under the repository root,
  as `git status` lists them. Ignored files and the contents of submodules and
  nested repositories are not; a rename is a deletion and a creation.
  `changesScope` says so in the report.
- **What "not observed" means.** Without git, outside a repository, or when a
  status fails, `changesObserved` is `false` with the reason — never an empty
  list that would read as "nothing changed". A `lint` operation takes no
  snapshot (`no-fix-task`).
- **For an agent.** `--output agent` prints
  `fix changed 2 files: src/a.ts, src/b.ts` — read those files again before
  editing them — or `fix changes not observed: <reason>`, after which every file
  the fix could have touched has to be read again.
- **For a person.** The Markdown report and the step summary list the changed
  files under the fix operation.

`--report patch=<path>` writes the diffs the formatters that write their result
on stdout applied, in the order they were applied, as one patch `git apply`
takes. A tool that rewrites files itself leaves no patch; its files are among
the changes with `patch: false`.

What datamitsu itself rewrites before the tools run — the `.datamitsuignore`
normalization — happens before the first snapshot and is not among the changes.

The snapshot costs one `git status` per group: on a repository of about 1 800
tracked files, 5–8 ms with a fresh index and about 40 ms when every file's
timestamp moved since the index was written.

## Baselines

A project that adopts a linter with hundreds of findings cannot fix them in the
change that adds it. A baseline lets the run fail only on what is new: it holds
the fingerprints of the findings a run reported, and a later run given it
neither reports those findings nor lets them gate.

```bash
datamitsu lint --report json=.datamitsu-baseline-run.json
datamitsu report baseline .datamitsu-baseline-run.json --output .datamitsu-baseline.json
datamitsu lint --baseline .datamitsu-baseline.json
```

Commit the baseline beside the configuration, and the run it was made from if
you want to compare later runs with it. `--baseline` takes a run's own JSON as
well, and a run that was not complete warns there too. A finding is matched by its
[fingerprint](#fingerprints), so it stays baselined when lines are inserted
above it and when its message is reworded; it becomes new when its rule, its
file or the text of its line changes. A baseline made from an incomplete run —
narrowed, a tool cancelled or unread — holds fewer fingerprints: it is written
with a warning and suppresses fewer findings, never more.

**A baseline cannot silence an exit code.** The tool's exit code still gates: a
tool that exits non-zero fails the run whatever the baseline holds, and its
frame shows the baselined findings it failed on. ESLint, golangci-lint and most
linters exit 1 on the findings they print, so for a baseline to make the run
fail only on new findings, the tool has to exit 0 on findings and leave the
decision to the threshold: add its exit-zero flag to the operation's `args` —
`--exit-zero` for Ruff, Flake8 and Pylint, `--issues-exit-code=0` for
golangci-lint — and keep the operation's
[`failOn`](../reference/configuration-api.md#failing-on-findings-failon). The
threshold gates only where the tool's parser module declares the severity
contract; elsewhere a tool that exits 0 passes whatever it found.

**Baselines rot.** A committed baseline hides its findings for as long as it
exists. Regenerate it on purpose — after a sweep that fixed some of them, so it
stops hiding them — never on a schedule, which would bake every new finding in.
`report diff` against the current run shows what it still hides:

```bash
datamitsu lint --report json=out/run.json
datamitsu report diff .datamitsu-baseline-run.json out/run.json --format markdown
```

A finding is matched while its own process is judged, before the report has
numbered the findings of a line across the tool's processes. So the baseline is
read as a count: holding the fingerprints of n findings of a rule on a line, it
marks at most n distinct findings of that rule on that line in an operation,
whichever processes report them — a new finding beside a baselined one is never
silenced, and a finding two processes both report is one. Which of several findings of one rule on one line is marked follows their
order on the line within one process, and the order the processes are judged
across processes: the fingerprint cannot say which of them is the old one, only
how many there were.

What else shows a baselined finding: a tool that failed on its exit code shows
every finding it failed on, baselined ones marked `(baselined)` in the terminal,
JUnit and Markdown; the annotations and `--output agent` show them unmarked.
SARIF, GitLab Code Quality, Checkstyle and rdjsonl list every finding, as they
list those below the threshold; SARIF marks a baselined one in
`properties.baselined`.

## Comparing two runs

`datamitsu report diff <before.json> <after.json>` compares two own reports by
fingerprint, tool by tool: `new`, `unchanged`, `moved` (another row), `fixed`,
`unknown` and `unobserved`. A finding that disappeared is `fixed` only when the
second run covered the whole repository and the tool was complete in it; when
the tool was cancelled, narrowed or unread it is `unknown`, with the reasons,
because the second run did not look. A tool only one run holds is `unobserved`.
`--format markdown` writes it for a pull request comment. See
[`report diff`](../reference/cli-commands.md#report-diff).

## Rendering a report later

`datamitsu report render` reads a run's own JSON and writes it in a format,
offline, through the same renderers and the same completeness rule:

```bash
datamitsu report render --input out/run.json --format json --output -
```

The document holds everything a renderer needs — the columns in every unit
were converted while the files were on disk — so this works on another machine,
without the checkout, and after the sources changed, and every format comes out
byte for byte as the run wrote it, completeness companion included. A pipeline
can therefore write the own JSON once and publish it in whatever formats its
consumers read:

```bash
datamitsu lint --fail-fast=false --report json=out/run.json
datamitsu report render --input out/run.json --format sarif --output out/sarif/
datamitsu report render --input out/run.json --format codequality --output out/gl-code-quality.json
```

A document of a narrowed run is refused for a format that lists findings unless
`--allow-partial`, as the run would have been — `sarif` is written, without its
incomplete tools — and a document without its completeness fields is read as
incomplete. A companion is written beside `--output`, never on stdout.

## History

A report answers what is wrong now. `history` answers how the numbers move:
each run appends one line to a file you name, `datamitsu.history/1`, and a trend
is whatever you build from those lines — a spreadsheet, a chart, a CI job that
compares the last two.

```bash
datamitsu lint --report history=.datamitsu-history/lint.jsonl
```

A line holds counts and durations, never a finding, a path or the paths a run
was given, so the file can be kept, shared and committed:

```json
{
  "schema": "datamitsu.history/1",
  "startedAt": "2026-09-28T10:00:00Z",
  "datamitsu": { "version": "0.4.0", "configuration": "my config" },
  "ci": { "vendor": "github", "sha": "3f2a…", "ref": "refs/heads/main" },
  "selection": { "mode": "all", "fileScoped": false, "toolsFiltered": false },
  "complete": true,
  "failFast": false,
  "operations": [
    {
      "name": "lint",
      "ran": true,
      "success": true,
      "durationMs": 7900,
      "tools": [
        {
          "name": "eslint",
          "runs": 3,
          "cached": 120,
          "failed": 0,
          "complete": true,
          "incomplete": [],
          "findings": { "error": 0, "warning": 4, "info": 0, "hint": 0 }
        }
      ]
    }
  ]
}
```

(shown indented; the file holds each entry on one line). `runs` counts the
processes a tool ran, `cached` the files a cache answered, `failed` the
invocations that failed, and `findings` every finding by level, whether or not
it was shown.

- **The file is yours.** It is written only where you name it — never under
  datamitsu's cache — created on the first run, and never rewritten: each run
  adds its line in one append, which a local file system keeps whole beside
  another run appending to the same file; on a network file system that is
  best effort.
- **A narrowed run writes it too.** A line lists no finding, so it cannot pass
  for the findings of the repository: its `selection` and `complete` say what
  the run covered, and `--allow-partial` is not needed. For the same reason it
  leaves fail-fast as it is — a line of a run that stopped at the first failure
  says `failFast: true` and `complete: false`.
- **Compare like with like.** Counts of a narrowed or incomplete run are not
  the repository's. A tool without a parser of its own is complete on a cold
  run and `unparsed-cache-hit` on a warm one, where the cache replayed a pass
  no parser read: that is the cache at work, not a regression, which the
  tool's `incomplete` reasons tell apart.

## Findings as they happen

Under `--log-format jsonl` the same findings arrive as `diagnostic` events, one
per finding, once its tool has finished — by default those at or above the
operation's `failOn`, every one with `--events diagnostics=all`. Each carries
the finding's fingerprint, the same one the report holds. See
[Run events](../reference/cli-commands.md#run-events).

---

## Runtime Management


datamitsu manages language runtimes alongside your tools. Instead of requiring team members to install specific versions of Bun, Python, Node.js, Java, or Go, datamitsu downloads and manages these runtimes automatically, creating isolated environments for each tool.

## Runtime Types

datamitsu supports five runtime types:

| Runtime  | Language   | Package Manager | Use Case                                    |
| -------- | ---------- | --------------- | ------------------------------------------- |
| **Bun**  | JavaScript | pnpm            | npm packages executed directly with Bun     |
| **UV**   | Python     | uv              | Python tools like yamllint, ruff            |
| **Node** | Node.js    | pnpm            | npm packages like ESLint, Prettier          |
| **JVM**  | Java       | -               | JAR-based tools like openapi-generator      |
| **Go**   | Go         | go modules      | Go tools built from source like govulncheck |

:::tip Updating Runtimes
To update runtime versions using devtools workflows, see [Maintaining Wrapper Packages](../how-to/maintain-wrapper.md).
:::

## Managed vs System Mode

Each runtime can operate in two modes:

### Managed Mode (Default)

datamitsu downloads and manages the runtime binary itself. This ensures everyone uses the exact same runtime version:

```javascript
runtimes: {
  uv: {
    kind: "uv",
    mode: "managed",
    managed: {
      binaries: {
        linux: {
          amd64: {
            glibc: {
              url: "https://github.com/astral-sh/uv/releases/download/0.6.0/uv-x86_64-unknown-linux-gnu.tar.gz",
              hash: "sha256:...", // canonical digest (mandatory)
              contentType: "tar.gz",
              binaryPath: "uv",
            },
          },
        },
      },
    },
    uv: {
      pythonVersion: "3.12",
    },
  },
}
```

### System Mode

Use the runtime already installed on the system. This is useful when the runtime is managed externally:

```javascript
runtimes: {
  uv: {
    kind: "uv",
    mode: "system",
    system: {
      command: "uv",
      systemVersion: "1.0",
    },
    uv: {
      pythonVersion: "3.12",
    },
  },
}
```

The optional `systemVersion` field moves runtime-dependent apps to a new store
key when the system runtime changes (for example, after a system upgrade).

## UV Runtime (Python)

UV apps use [uv](https://github.com/astral-sh/uv) to create isolated Python environments for each tool.

### How UV Apps Work

1. datamitsu ensures the UV runtime is available (downloads it in managed mode)
2. Creates an isolated environment at `{store}/.apps/uv/{appName}/{hash}/`
3. Writes a `pyproject.toml` and runs `uv sync` to install the package
4. Executes the tool from the isolated environment

### Defining a UV App

```javascript
apps: {
  yamllint: {
    uv: {
      packageName: "yamllint",
      version: "1.35.1",
      lockFile: "br:...", // required; generated with config lockfile
    },
  },
}
```

### Python Version

The Python version is configured on the runtime, not individual apps:

```javascript
uv: {
  pythonVersion: "3.12",
}
```

If using system mode without specifying `pythonVersion`, datamitsu will warn you since the Python version becomes implicit.

### Store Layout and the Managed Python Interpreter

In managed mode, uv downloads a CPython interpreter and reuses it across uv apps. datamitsu redirects that interpreter into the store at `<store>/.uv/python/` (via `UV_PYTHON_INSTALL_DIR`), one CPython per version shared across apps, alongside uv's per-app cache. This keeps the store **self-contained**: when the store is cached (e.g. in CI) and restored onto a fresh runner, each app's `.venv/bin/python` symlink still resolves, because the interpreter it points at travels with the store rather than living in uv's default data dir (`~/.local/share/uv/python`).

datamitsu also validates the venv interpreter at install time. If `.venv/bin/python` dangles (for example, after restoring a partial or stale cache), the venv is treated as not installed and rebuilt, so a broken interpreter self-heals instead of being trusted forever.

## Bun Runtime

Bun apps use [pnpm](https://pnpm.io/) for dependency installation and a managed [Bun](https://bun.sh/) runtime for JavaScript execution. pnpm is a native binary, and the lifecycle scripts it runs reach Bun through a `node` alias, so selecting Bun does not download Node merely to install dependencies. Bun remains a separate app kind: selecting it is an explicit configuration choice and does not change how Node apps run. Managed x64 targets use Bun's standard optimized archives and therefore require AVX2-capable hardware.

### How Bun Apps Work

1. datamitsu downloads and verifies the SHA-256-pinned Bun release archive
2. Creates an isolated environment at `{store}/.apps/bun/{appName}/{hash}/`
3. Acquires the pnpm runtime named by the Bun runtime's `pnpmRuntime` (a SHA-256-pinned native pnpm archive for the host platform) and writes `package.json`, `pnpm-workspace.yaml`, and the configured `pnpm-lock.yaml`
4. Runs `pnpm install --frozen-lockfile` with datamitsu's `node` → Bun alias first on `PATH`, so lifecycle scripts that call `node` run on Bun
5. Executes the configured JavaScript entrypoint with `bun run --bun --no-install`

Both Bun and Node apps share pnpm's content-addressable store at `{store}/.pnpm-store/`, while every app keeps its own `node_modules` directory. During execution, `--bun` and the same alias keep Node-shebang commands launched by the tool on the selected runtime.

The alias at `.datamitsu-runtime-bin/node` is a link to the Bun executable rather than a wrapper script, because Bun emulates the node CLI only when it is invoked under the name `node` — called under its own name it would read `node build` as its bundler and `node install` as its package manager.

Runtime auto-install is disabled, and datamitsu passes `--no-env-file` plus an empty Bun config when it executes the tool, so a target repository's `.env` files and `bunfig.toml` cannot change a managed tool's behavior. The same guards travel in `BUN_OPTIONS`, which every Bun process started under the app inherits, so they hold for the `node` processes a lifecycle script or the tool starts itself too.

### Defining a Bun App

```javascript
apps: {
  eslint: {
    bun: {
      packageName: "eslint",
      version: "10.9.0",
      binPath: "node_modules/eslint/bin/eslint.js",
      lockFile: "br:...", // required; generated with config lockfile
    },
  },
}
```

### Bun Version

The Bun version is configured on the runtime:

```javascript
bun: {
  bunVersion: "1.4.1",
}
```

## Node Runtime (Node.js)

Node apps use a managed Node.js runtime — downloaded as a pinned, SHA-256-verified archive (exactly like the JVM runtime downloads a JDK) — together with [pnpm](https://pnpm.io/) as the package manager.

### How Node Apps Work

1. datamitsu downloads and verifies (SHA-256) the configured Node.js archive and extracts it
2. Acquires the pnpm runtime named by the Node runtime's `pnpmRuntime` (a SHA-256-pinned native pnpm archive for the host platform)
3. Creates an isolated environment at `{store}/.apps/node/{appName}/{hash}/`
4. Runs `pnpm install --frozen-lockfile` with the managed Node.js first on `PATH`, so lifecycle scripts run on the pinned interpreter
5. Executes the tool via Node.js

### Defining a Node App

```javascript
apps: {
  eslint: {
    node: {
      packageName: "eslint",
      version: "9.0.0",
      binPath: "node_modules/.bin/eslint",
      lockFile: "br:...", // required; generated with config lockfile
    },
  },
}
```

### JavaScript Runtimes and the pnpm Runtime

Since pnpm 12, pnpm is a native binary with no JavaScript implementation, so it is a runtime of its own (kind `pnpm`), defined once and referenced by every Node and Bun runtime through `pnpmRuntime`:

```javascript
runtimes: {
  pnpm: {
    kind: "pnpm",
    mode: "managed",
    managed: {
      binaries: {
        linux: {
          amd64: {
            glibc: {
              url: "https://github.com/pnpm/pnpm/releases/download/v12.4.1/pnpm-linux-x64.tar.gz",
              hash: "sha256:66e98862...", // canonical SHA-256 digest (mandatory)
              contentType: "tar.gz",
              binaryPath: "pnpm",
              extractDir: true,
            },
          },
        },
        // ... other platforms — `datamitsu devtools pull-runtimes` generates the full map
      },
    },
    pnpm: { pnpmVersion: "12.4.1" },
  },
  node: {
    kind: "node",
    mode: "managed",
    managed: { binaries: { /* Node.js archives */ } },
    node: { nodeVersion: "26.2.0", pnpmRuntime: "pnpm" },
  },
  bun: {
    kind: "bun",
    mode: "managed",
    managed: { binaries: { /* Bun archives */ } },
    bun: { bunVersion: "1.4.1", pnpmRuntime: "pnpm" },
  },
}
```

`pnpmRuntime` is required and must name a runtime of kind `pnpm`. Several Node and Bun runtimes can share one pnpm runtime or point at different ones. No app runs on a pnpm runtime: an app whose `runtime` names one fails validation.

The archives come from the pnpm GitHub release and are extracted whole: besides the binary they carry the `node-gyp` that pnpm uses to build native dependencies. As with any managed runtime, datamitsu downloads only the entry for the host platform and falls back from musl to glibc; a system pnpm works too (`mode: "system", system: { command: "pnpm" }`, where `pnpmVersion` becomes optional). `datamitsu init` downloads the pnpm runtime along with the Node or Bun runtime whenever a required app needs it. pnpm is only needed to install apps, so it is not part of the runtimes a built Docker image or OCI bundle ships for execution.

Runtimes, pnpm included, are stored under `{store}/.runtimes/{name}/{configHash}/`. The pnpm runtime's identity is part of every Node and Bun app's environment hash but not of the Node or Bun runtime's own hash, so a pnpm bump reinstalls the apps without downloading Node or Bun again. A shared pnpm content-addressable store at `{store}/.pnpm-store/` deduplicates packages across Bun and Node apps.

:::warning Breaking change: pnpm moved into its own runtime

A Node or Bun runtime that still pins pnpm with `pnpmVersion` and `pnpmHash` (the SHA-256 of the npm `pnpm` tarball, which only works for pnpm 11 and earlier) no longer loads, because it has no `pnpmRuntime`. Add a runtime of kind `pnpm` and point the Node and Bun runtimes at it — `datamitsu devtools pull-runtimes <file> --update` writes all three entries. Existing `pnpm-lock.yaml` lock files (`lockfileVersion: '9.0'`) keep working unchanged.

:::

## JVM Runtime (Java)

JVM apps download JAR files and execute them with a managed JDK.

### How JVM Apps Work

1. datamitsu downloads a Temurin JDK distribution (full directory extraction)
2. Downloads the app's JAR file with SHA-256 verification
3. Executes via `java -jar` (or `java -cp <jar> <mainClass>` when `mainClass` is specified)

### Defining a JVM App

```javascript
apps: {
  "openapi-generator": {
    jvm: {
      jarUrl: "https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.0.0/openapi-generator-cli-7.0.0.jar",
      jarHash: "sha256:...", // canonical digest (mandatory)
      version: "7.0.0",
    },
  },
}
```

### Java Version

Configured on the runtime definition:

```javascript
jvm: {
  javaVersion: "21",
}
```

## Go Runtime

Go apps build a command-line tool from source using a managed Go SDK, producing a single self-contained binary.

### How Go Apps Work

1. datamitsu downloads and verifies (SHA-256) the pinned Go SDK and extracts it
2. Writes the app's `go.mod` and `go.sum` (from its lock file) into an isolated build directory
3. Builds with `go build -trimpath -mod=readonly` in a hardened environment (`GOTOOLCHAIN=local`, `GOSUMDB` enabled, `GOPRIVATE`/`GONOPROXY`/`GONOSUMDB`/`GOINSECURE` cleared)
4. Executes the built binary directly

### Defining a Go App

```javascript
apps: {
  govulncheck: {
    go: {
      packageName: "golang.org/x/vuln/cmd/govulncheck",
      version: "v1.3.0",
      lockFile: "br:...", // carries go.mod + go.sum (required)
    },
  },
}
```

### Go SDK Version

Configured on the runtime definition:

```javascript
go: {
  goVersion: "1.26.3",
}
```

A Go app's lock file is a JSON wrapper carrying both `go.mod` and `go.sum`. Because the build runs with `-mod=readonly`, any drift from the pinned `go.sum` fails the build instead of silently rewriting it. Regenerate it after a version bump with `datamitsu config lockfile <appName>`. See [Supply Chain Security](./supply-chain-security.md#go-go-apps) for the full defense model.

## Lock Files

Bun, Node, UV, and Go apps require lock files. They pin exact dependencies and their
integrity data so installs and builds are reproducible across environments.

### Generating a Lock File

First declare the app's package and version. Then use the special
`config lockfile` command to generate its lock content:

```bash
datamitsu config lockfile eslint
```

This outputs brotli-compressed, base64-encoded lock file content that you paste into your configuration:

```javascript
eslint: {
  bun: {
    packageName: "eslint",
    version: "10.9.0",
    binPath: "node_modules/eslint/bin/eslint.js",
    lockFile: "br:...",
  },
}
```

### How Lock Files Work

- **Bun and Node apps**: The lock file is written as `pnpm-lock.yaml` and pnpm runs with `--frozen-lockfile`, refusing to install if dependencies don't match. pnpm runs as the native binary of the referenced pnpm runtime, with the selected Bun or Node runtime serving lifecycle scripts
- **UV apps**: The lock file is written as `uv.lock` and uv runs with `--locked --no-build`, ensuring exact version matching and permitting wheels only
- **Go apps**: The JSON payload is expanded into `go.mod` and `go.sum`, and the tool is built with `go build -trimpath -mod=readonly`

The generation command deliberately loads config without enforcing the missing
field so it can create that field. Every normal config load rejects a Bun, Node,
UV, or Go app without `lockFile` before downloading or executing anything.

## Isolated Environments

Each runtime-managed app gets its own isolated environment. This prevents version conflicts between tools:

```
{store}/.apps/
├── bun/
│   └── eslint/{hash}/       # isolated Bun app
├── uv/
│   ├── yamllint/{hash}/     # isolated Python env
│   └── ruff/{hash}/         # separate isolated env
├── node/
│   ├── eslint/{hash}/       # isolated Node.js env
│   └── prettier/{hash}/     # separate isolated env
└── jvm/
    └── openapi-generator/{hash}/  # JAR + metadata
```

The `{hash}` covers the runtime identity, app configuration (including the lock
file and any files or archives), and resolved target. Changing one creates a new
isolated environment; the old entry remains in the store until it is cleared.

## Runtime Resolution

When an app references a runtime by name, datamitsu resolves it through this chain:

1. App-level runtime override (if specified)
2. Global default runtime for the app's kind

This allows you to have multiple runtimes of the same kind (e.g., different Node.js versions for different apps) while keeping a sensible default.

## Libc Detection and Alpine Linux

datamitsu detects the host libc at startup using a multi-stage process (ldd output, ELF interpreter, loader paths). This detection feeds into binary app resolution, where musl-specific binaries are preferred on musl systems.

Managed runtimes need extra handling on musl because their upstreams' default channels are glibc-oriented:

- **Bun**: official releases provide separate glibc and musl archives for both amd64 and arm64; datamitsu pins and selects them directly
- **pnpm**: releases provide glibc and musl builds for both amd64 and arm64; datamitsu pins both and selects by the detected libc
- **Node.js**: the default `nodejs.org/dist` archives are glibc-only. The registry therefore carries static musl entries (url + SHA-256) sourced from [unofficial-builds.nodejs.org](https://unofficial-builds.nodejs.org/download/release). On a musl host datamitsu downloads and verifies the musl Node archive directly, so node apps work on Alpine out of the box. musl Node additionally requires `libstdc++` (`apk add libstdc++`). See [Use in Alpine Linux](../how-to/use-in-alpine) for details.
- **Python** (UV): uv downloads glibc Python builds
- **JDK** (JVM): Temurin JDK releases are glibc-only

### Automatic Fallback to System Mode

When running on a musl system (e.g., Alpine Linux), datamitsu automatically detects when a managed runtime lacks a musl-compatible binary and falls back to system mode if the corresponding system binary is available on PATH.

The fallback logic works as follows:

1. Detects the host is musl
2. Checks if the runtime's managed binaries include a musl variant
3. If no musl binary exists, looks for the system binary (`node`, `uv`, `java`, or `pnpm`) via PATH
4. If found, automatically switches to system mode using the system binary
5. If not found, falls through to the existing glibc fallback behavior

Note that the Node runtime ships static musl archive entries in the registry, so it installs in managed mode on Alpine out of the box — no system fallback needed. `uv` is not available in Alpine's default package repositories, so the auto-fallback does not help there; for UV on Alpine, use [manual system mode](#manual-system-mode) configuration instead. The auto-fallback is most useful for the JVM runtime (where `apk add openjdk17` provides the `java` binary).

When auto-fallback triggers, you will see a log message:

```
INFO: automatic fallback to system mode  runtime=jvm  reason="musl binary unavailable"  system_command=/usr/bin/java
```

### Manual System Mode

If you prefer explicit control, you can still configure runtimes in **system mode** manually:

```sh
# Install runtimes via apk
apk add nodejs npm python3 openjdk17
```

```javascript
runtimes: {
  node: {
    kind: "node",
    mode: "system",
    system: { command: "node" },
    node: { nodeVersion: "26.2.0", pnpmRuntime: "pnpm" },
  },
  pnpm: {
    kind: "pnpm",
    // pnpm can stay pinned and downloaded while Node comes from the system,
    // or use mode: "system" with system: { command: "pnpm" }
    mode: "managed",
    managed: { binaries: { /* per-platform pnpm archives */ } },
    pnpm: { pnpmVersion: "12.4.1" },
  },
  uv: {
    kind: "uv",
    mode: "system",
    system: { command: "uv" },
    uv: { pythonVersion: "3.12" },
  },
  jvm: {
    kind: "jvm",
    mode: "system",
    system: { command: "java" },
    jvm: { javaVersion: "17" },
  },
}
```

Binary apps (type `binary`) are not affected by this limitation. They use target-based resolution with automatic libc detection and will select musl-specific builds when available. See [Use in Alpine Linux](../how-to/use-in-alpine) for details.

## See the runtime distribution

The reference wrapper `@shibanet0/datamitsu-config`, `0.6.3`,
captured on 2026-10-26, contains 117 apps: native binary 78, Node.js 15,
Python 10, Bun 6, Go 4, JVM 3 and Shell 1. This is a real configuration, not a default.

<ConfigEmbed view="blueprints" />

[Open the full atlas](https://datamitsu.com/atlas.html).
See the [Config Inspector guide](config-inspector.md) to inspect or embed your own configuration.

---

## Source Mode


Source mode makes the project's declared toolchain available as ordinary commands on `PATH`. After activation `tofu`, `terragrunt` and `prettier` are the versions **this repository pins**, not whatever happens to sit in `/usr/local/bin`.

```bash
eval "$(datamitsu source bash)"      # bash / zsh
tofu plan                            # the pinned version, not the system one
```

Activation is a per-shell act. It downloads nothing, costs a manifest read when the farm is already current, and is safe to put in a shell rc file or a tmux profile.

## Activating

```bash
# bash / zsh
eval "$(datamitsu source bash)"
eval "$(datamitsu source zsh)"
```

```fish
# fish
datamitsu source fish | source
```

The emitted code does three things and nothing else: it exports `DATAMITSU_ROOT` and `DATAMITSU_FARM`, it puts the farm directory first on `PATH` (removing any earlier copy of itself, so re-activating never duplicates the entry), and it flushes the shell's command hash table. That is the entire contract — stdout carries shell code and nothing else, so the output is always safe to `eval`.

```bash
$ datamitsu source bash
export DATAMITSU_ROOT=$'/home/you/infra'
export DATAMITSU_FARM=$'/home/you/.cache/datamitsu/cache/projects/02982286cbc2c265e43806925d7f4907/bin'
__datamitsu_path=":$PATH:"
__datamitsu_path="${__datamitsu_path//:"$DATAMITSU_FARM":/:}"
__datamitsu_path="${__datamitsu_path#:}"
__datamitsu_path="${__datamitsu_path%:}"
PATH="$DATAMITSU_FARM${__datamitsu_path:+:$__datamitsu_path}"
export PATH
unset __datamitsu_path
hash -r
```

Warnings — tools not downloaded yet, system binaries the farm shadows — go to **stderr**, never into the stream being evaluated. A repository's own config JS can `console.log`; that output is redirected to stderr too, so a config cannot inject text into your shell.

Source mode requires a project. Run it inside a repository whose git root holds a `datamitsu.config.{js,mjs,ts}`, or name one explicitly with the global `--config` flag. Outside a project it exits non-zero and writes nothing to stdout, rather than silently activating the small built-in default config.

## How it works

```mermaid
flowchart TD
    CFG["datamitsu.config.ts+ wrapper configs"] --> RES["Resolve every declared app(no downloads, no network)"]
    RES --> PLAN["Planentries · exclusions · shadows"]
    PLAN --> FARM["Farm directory{cache}/projects/{hash}/bin"]
    PLAN --> MAN["manifest.jsonwatch set + staleness key"]
    FARM --> ACT["Activationfarm first on PATH"]
    ACT --> RUN["tofu plan"]
    RUN --> DISP["argv[0] dispatchread manifest, check freshness"]
    MAN -.->|"stat the watch set"| DISP
    DISP --> EXEC["syscall.Exec the pinned binary"]

    style FARM fill:#e8f4fd,stroke:#2196f3
    style MAN fill:#e8f4fd,stroke:#2196f3
    style EXEC fill:#e8f5e9,stroke:#4caf50
```

### The farm

Activation bakes a **farm**: one directory holding one entry per declared app, plus the manifest describing it.

```text
~/.cache/datamitsu/cache/projects/{XXH3-128(gitRoot)}/
  bin/
    tofu         -> {abs path to datamitsu}
    terragrunt   -> {abs path to datamitsu}
    prettier     -> {abs path to datamitsu}
    tflint       -> {abs path to datamitsu}     # not downloaded yet
  manifest.json
  lock
```

Every entry is a symlink to the datamitsu binary itself — a **shim**. When the shell execs `tofu`, datamitsu starts, sees it was invoked under a farm name, reads the manifest, and `syscall.Exec`s the real target. One process, not two: signals, exit codes and stdin/stdout wiring are the target's, and your argv is passed through **verbatim** (unlike `datamitsu exec`, which needs a `--` separator because cobra parses the flags first).

The farm is baked atomically into a sibling temp directory and renamed into place, under a per-root advisory lock, so ten tmux panes activating at once cannot observe a half-built directory.

### Branch switching is invisible

This is the property that shapes the whole design. Inside an already-activated shell:

```bash
git checkout v2 && tofu version    # runs v2's pinned tofu
git checkout v1 && tofu version    # runs v1's pinned tofu
```

No re-activation, no prompt hook. That matters because a prompt hook — how `mise activate` and direnv work — fires when a prompt renders, and the line above renders no prompt between the two commands. The hook would never run and the **old binary would execute silently, exiting 0 with plausible output**. The same applies inside `make`, inside a git hook, and inside `tmux new-window 'tofu plan'`.

Instead, the shim revalidates on every invocation. The manifest carries a **watch set**: every file in the config chain (including `pnpm-lock.yaml` and any declared before-configs) with its mtime, size and existence, plus `.git/HEAD`. Comparing them is a handful of `lstat` calls — microseconds — not a config load. `.git/HEAD` is load-bearing rather than belt-and-braces: a branch that _deletes_ `datamitsu.config.ts` leaves no mtime to compare, and `HEAD` is rewritten by a checkout but not by a commit, so it causes no spurious re-bakes.

When the comparison fails, the shim takes the lock, re-bakes once, and execs the new target.

### Downloads are lazy

Activation downloads nothing, even for tools that have never been fetched. A declared app that is not in the store yet gets a farm entry marked not-installed; the first time you actually run it, the shim installs it, re-resolves, and execs. Subsequent invocations take the steady-state path.

This is why activation is cheap enough for a shell rc file: a repository declaring a hundred tools costs the same at activation time as one declaring three.

Activation also skips the config load entirely when the baked manifest still matches the tree — the same freshness comparison the shim makes — and renders the shell code from the manifest it reads back. Only an activation that finds a changed tree pays a full resolve. `--before-config` and `--no-auto-config` always re-resolve: the manifest's watch set describes the config chain that baked it, and it cannot speak for a file it has never seen. A farm baked with those flags is likewise not served back to a later plain `datamitsu source`. `--config` is the exception, and takes the fast path like any other activation: an explicit-config farm's manifest lives at the path the chain itself hashes to, so the only manifest such an invocation can find is one already baked from those very files. `--no-auto-config` with no `--config` to replace it is refused outright, because baking the built-in default config would overwrite the farm this root's real config owns.

### A bake that fails still activates

If the farm cannot be re-baked — a config that does not evaluate on this branch, a remote config unreachable offline — activation warns on stderr, activates the farm already on disk and exits 0. Emitting nothing would exit 0 with a shell that was never activated, and every declared tool would then fall through `PATH` to whatever the system has, which is the failure this feature exists to prevent.

The toolchain you get is therefore the previous one, not the branch's. `datamitsu source refresh` is the repair command and inverts the rule: a failed bake exits non-zero, so a CI step can trust its exit code where it cannot trust `source`'s.

### A declared name never falls through

If a name is declared for this project but cannot be resolved for the current tree, the shim **exits 127** naming the app, the farm — its git root, or the config chain for a [machine-level farm](../how-to/machine-level-toolchain.md) that has no root — and `datamitsu source status`. It never searches the rest of `PATH`.

That is deliberate and it is the single most important failure-mode decision in the feature. The alternative — falling through to a stale `/usr/local/bin/terragrunt` — exits 0 and prints plausible output, which is strictly worse than not shipping source mode at all. For the same reason, a farm baked for a different repository is never used implicitly: `cd` into a repository you have never activated and a tool name exits 127 telling you to run `datamitsu source` there. Baking it implicitly would mean evaluating that repository's JavaScript merely because you typed a tool name; explicit activation is the act of trust.

### What is deliberately excluded

Some declared names never become farm entries. They appear in `datamitsu source status` under `excluded` **with a reason** — a name that silently does not appear would be undebuggable.

| Excluded                                   | Reason                                                                                                                                                                                          |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shell` apps                               | A shell app resolves its command through the **inherited** `PATH`. Shimming one would make it call itself, recursively, forever.                                                                |
| `sudo`, `su`, `doas`, `sudoedit`           | Privilege boundaries are not something a project config gets to redefine.                                                                                                                       |
| `sh`, `bash`, `zsh`, `fish`, `dash`, `env` | Shimming the interpreter that runs the shim is a loop.                                                                                                                                          |
| `ssh`, `scp`, `sftp`, `git`, `ldd`         | Too load-bearing to redirect from a repository's own config. `git` and `ldd` are also spawned by datamitsu itself (git-root discovery, libc detection), so shimming either re-enters datamitsu. |
| `datamitsu`                                | A shimmed `datamitsu` turns the shim's own installer spawn into an infinite `exec` loop.                                                                                                        |

App names themselves are validated as filesystem entries: `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`, no path separators, no Windows reserved device names, and no two names that differ only by case (macOS filesystems would collapse them into one file).

## Inspecting the farm

`datamitsu source status` is the first command to run when a tool is missing or resolves to the wrong version.

```bash
$ datamitsu source status
origin:   git-root
root:     /home/you/infra
farm:     /home/you/.cache/datamitsu/cache/projects/02982286cbc2c265e43806925d7f4907/bin
manifest: /home/you/.cache/datamitsu/cache/projects/02982286cbc2c265e43806925d7f4907/manifest.json (fresh)

entries (4):
  prettier    shim  installed
  terragrunt  shim  installed
  tflint      shim  not installed
  tofu        shim  installed

excluded (1):
  rustfmt  shell apps resolve through the inherited PATH

shadowed (2):
  terragrunt  /usr/local/bin/terragrunt
  tofu        /opt/homebrew/bin/tofu
```

The manifest state is one of `fresh`, `stale`, `missing` or `unreadable`. All three non-fresh states mean the same re-bake, but they tell you very different things: `missing` is "never activated here" — the state the shim reports as exit 127 — while `unreadable` is a corrupted farm.

`origin` is always present in both forms. A [machine-level farm](../how-to/machine-level-toolchain.md) reports `explicit-config` and prints `config:` lines in place of `root:`, because it has no repository to `cd` to — the chain is what you would pass to `--config` again.

`--json` emits the same information as one document and writes no human text to stdout; warnings still go to stderr. It carries `origin` alongside the fields above, and `configPaths` for an `explicit-config` farm. `status` resolves and reports — it never downloads and never re-bakes, so it can be used to observe a broken farm rather than silently repairing the thing it is meant to describe.

## `which` shows the farm, not the store

```bash
$ which tofu
/home/you/.cache/datamitsu/cache/projects/02982286cbc2c265e43806925d7f4907/bin/tofu
```

Every farm entry points at the datamitsu binary, so `which`, `type -a` and `command -v` all report the farm path and tell you nothing about which version will actually run. There is no way around this: the indirection is exactly what makes branch switching work, and a direct symlink into the store — which `which` would resolve usefully — has nowhere to put the freshness check.

`datamitsu source status` prints the real target for every entry, and `--json` carries it in the `command` field. That is the answer to "which binary is this actually going to run".

## The performance contract

Honest numbers, measured on an Apple M1 Max against a 111-app config:

| Situation                                               | Cost                                                                |
| ------------------------------------------------------- | ------------------------------------------------------------------- |
| Activation, farm already current                        | **~15 ms**. Reads the manifest back; downloads nothing.             |
| Activation, after a config change or branch switch      | **~110 ms**, once. One full config load, then back to ~15 ms.       |
| Steady-state tool invocation                            | **~10–12 ms** on top of the tool's own startup.                     |
| First invocation after a config change or branch switch | **~145 ms**, once. One full config load, then back to steady state. |
| First invocation of a tool never downloaded             | The download, once.                                                 |

The ~10–12 ms is the shim process itself, and it is paid by every tool regardless of kind. An earlier design gave installed `binary` apps a direct store symlink for a genuine 0 ms — that was withdrawn, because a symlink runs none of datamitsu's code and therefore keeps executing the previous branch's version after a checkout, silently. The 10 ms buys the guarantee that the version you get is the version the repository pins.

The per-invocation freshness check itself is not the cost: it is a handful of `lstat` calls and does not appear above process startup at all.

## When re-baking is not automatic

The staleness check compares the config chain's **files**. A config that decides what it produces from something other than those files can change its answer without changing anything the check can see.

The known hole is `facts().env`: config JS receives the whole environment, so a config that branches on a variable outside datamitsu's own `DATAMITSU_*` namespace will not invalidate the farm when that variable changes.

```bash
datamitsu source refresh --force
```

`--force` re-bakes unconditionally and is the documented escape hatch for exactly that case. Plain `datamitsu source refresh` re-bakes only when the tree actually changed, exits 0 either way, prints its summary to stderr, and downloads nothing — so it is safe to call from the same shell function that runs the activation.

:::note
Closing this hole soundly needs read-instrumentation inside the JavaScript VM, so datamitsu can fingerprint the variables a config actually read rather than guessing. That is deliberately deferred; `--force` is the answer until then.
:::

## See also

- [Machine-Level Toolchain](/docs/how-to/machine-level-toolchain) — the same guarantees for a config outside any repository, activated from a shell rc file
- [`source` command reference](/docs/reference/cli-commands#source) — every flag, in detail
- [Binary Management](/docs/guides/binary-management) — how the content-addressed store makes two branches' versions coexist
- [Supply Chain Security](/docs/guides/supply-chain-security) — the hash verification that happens at download time, not on this path

---

## Supply Chain Security


datamitsu treats supply chain integrity as a non-negotiable property of every install. This guide explains the defenses applied to pnpm (Bun and Node apps), UV (Python apps), and Go dependencies, and how to configure overrides when a real workload requires them.

## Hash Verification (All Downloads)

Every artifact downloaded from the internet must have a SHA-256 hash, pinned as
a canonical digest — `sha256:` followed by 64 lowercase hex characters; a bare
64-hex pin is rejected at config load. This includes binary apps, managed
runtimes, JVM JAR files, external app and bundle archives, pnpm itself, remote
config files, and WASM output parsers. If a hash is missing, datamitsu refuses
to download — there is no permissive fallback mode. (The `getRemoteConfigs()`
pin is the one lenient exception: a bare or uppercase value copied from a
release page is accepted there and normalized to canonical.)

The hash is verified before the artifact is unpacked or executed. Lock files
are mandatory for all Bun, Node, UV, and Go apps; their package managers then
enforce the integrity values carried by `pnpm-lock.yaml`, `uv.lock`,
or `go.sum`.

See the [Binary Management](./binary-management.md) guide for the verification pipeline applied to binary apps.

### Registry-Sourced Parser Modules

A [WASM output parser](./architecture/parsers.md) declares its module either as an `https` URL or as an OCI artifact (`oci: { ref, digest }`) — exactly one of the two. Declaring both, or neither, is a config error at load, and there is no fallback between them: a config that pins a registry never reaches back to a URL.

`hash` stays mandatory for both sources, in the canonical `sha256:<64 lowercase hex>` form. For an OCI source it does double duty: it is also the expected digest of the artifact's single layer — the layer's digest is the same `sha256:`-prefixed value, so the registry digest chain and the config hash are the same number rather than two independent claims. A registry serving a correctly-digested manifest that points at different content is rejected before one payload byte is requested.

The module is therefore hash-checked three times on its way into the store:

1. **Manifest** — the manifest body is re-hashed against the pinned digest (the registry's `Docker-Content-Digest` header is never trusted), then its layer digest is compared against the config `hash`. Nothing is requested from the blob endpoint until both hold.
2. **Stream** — the blob bytes are hashed as they are written; a size or digest mismatch is a permanent failure, not a retry.
3. **File** — the finished file is verified against the config `hash` before it is published into the store.

After that the store is self-healing: a parser module already on disk is re-hashed against the declared `hash` on every use and discarded when it does not match — whatever put it there (a download, an OCI bundle seed, a restored CI cache, a copy by hand). A module is stored at `{store}/.parsers/{name}/{key}`, where the key is derived from the module's SHA-256 alone — so one entry resolves to one directory no matter which channel delivered the bytes.

:::note `--no-oci` does not disable a declared parser source
`--no-oci` (or `DATAMITSU_NO_OCI`) turns off OCI **bundle store seeding**, an accelerator that degrades gracefully when it is unavailable. A parser that declares an `oci` source keeps using it, because that is the only route to its bytes. `DATAMITSU_OFFLINE` is the single hard network gate.
:::

### A Registry `ref` Is a Trusted-Host Setting

The `ref` on a parser or a bundle decides which host datamitsu talks to, and datamitsu can be holding a `GITHUB_TOKEN` while it does. Changing a `ref` is a credential decision, not only a mirroring one.

That token is sent as Basic auth to a registry's token endpoint only when the configured registry host is `ghcr.io` **and** the token realm advertised in that registry's own `WWW-Authenticate` challenge is `ghcr.io`. Both conditions are required: the realm arrives in a header the registry controls, so checking the realm alone would let any host name `ghcr.io` as its realm and be handed a real GitHub token. A `ref` pointed at any other host pulls anonymously. The hash chain protects the bytes; it does not protect a credential handed to the wrong host.

List every registry reference a config pins, without touching the network:

```bash
datamitsu store refs --oci-only
# ghcr.io/datamitsu/datamitsu-parsers@sha256:...
```

### Signatures Are Not Verified

This build verifies no signatures at all — there is no sigstore dependency in the binary. A `signer` set on a bundle's `oci` or on a parser's `oci` is rejected at config load rather than accepted and ignored, so a config can never assert a guarantee the binary does not deliver.

Signatures still exist upstream: CI signs `checksums.txt` and the published parser artifact manifest with keyless cosign, and both can be verified out of band (`cosign verify-blob`, `cosign verify`). What the binary enforces is the hash chain above.

## Minimum Release Age (Version Selection)

When you pin a tool or runtime version with the `devtools pull-*` commands, datamitsu refuses to select a release that is too fresh. A brand-new release is the most likely to be a typosquat, a compromised publish, or an accidental break that gets yanked within hours. A short soak time lets the ecosystem catch and pull bad releases before you adopt them.

The global default is **10080 minutes (7 days)**. It applies to every command that selects a concrete version from a registry:

| Command         | Age-filtered registries                               |
| --------------- | ----------------------------------------------------- |
| `pull-releases` | GitHub, GitLab, Gitea and Forgejo releases            |
| `pull-node`     | npm                                                   |
| `pull-uv`       | PyPI                                                  |
| `pull-runtimes` | npm (pnpm), GitHub (Bun, uv, and JVM binary releases) |

Major-version-line lookups are **not** age-filtered, because they select a release _line_ rather than a specific build: the Node.js LTS line and Python stable line (endoflife.date), the Temurin major version (Adoptium API), and the Go release listing (go.dev). Only the concrete binary release or package version chosen within those lines passes through the age filter. When the newest Temurin feature release has no build old enough yet — in the days after it ships, its only GA build is younger than the cutoff — the JVM pull takes the previous feature release instead.

### The `--min-age` flag

Every `pull-*` command accepts `--min-age <minutes>`:

- `--min-age -1` (the default) — use the global effective minimum release age
- `--min-age 0` — disable age filtering and take the latest release
- `--min-age 43200` — a custom cutoff (here, 30 days)

```bash
# Pin only releases at least 7 days old (the default)
datamitsu devtools pull-releases apps/binaryApps.json --update

# Require 30 days of soak time
datamitsu devtools pull-node apps/nodeApps.json --update --min-age 43200

# Bypass the filter and take the newest release
datamitsu devtools pull-releases apps/binaryApps.json --update --min-age 0
```

Each command prints the effective cutoff in its status banner (`Minimum release age: 10080 minutes`, or `disabled` when set to 0).

### When no release is old enough

`pull-releases` reads release lists across the configured provider until an empty
page proves the end, requesting up to 100 entries per page. It compares stable
semantic versions across the collected pages and applies the age cutoff. A
server may clamp the page size, so a short non-empty page does not stop the
lookup. If the listing does not finish within ten pages, the command fails and
asks for an explicit tag instead of silently choosing from an incomplete list.
The runtime GitHub updater retains its separate bounded lookup.

If every available release is younger than the cutoff, datamitsu's behavior depends on whether a safe fallback exists:

- **`pull-releases`** — an _existing_ app keeps its current tag with a warning; a _new_ app (no prior binary) is a **hard error**, since there is nothing safe to pin.
- **`pull-node` / `pull-uv`** — the package is skipped with a warning and keeps its current version.
- **`pull-runtimes`** — a hard error for that runtime, since runtimes must resolve to a concrete version; it keeps its previous entry, and the other runtimes are still saved.

The error message always points at the `--min-age 0` escape hatch.

### Overriding the global default

Set `DATAMITSU_MIN_RELEASE_AGE` (in minutes) to change the effective default for all commands without passing `--min-age` each time. It also moves the [Go lock-file check](#release-age-at-lock-generation). `0` disables filtering globally.

```bash
# Require 14 days globally
DATAMITSU_MIN_RELEASE_AGE=20160 datamitsu devtools pull-uv apps/uvApps.json --update
```

Verify the effective value mechanically with `datamitsu config runtime`:

```bash
datamitsu config runtime | jq .minimumReleaseAgeMinutes                                   # -> 10080
DATAMITSU_MIN_RELEASE_AGE=20160 datamitsu config runtime | jq .minimumReleaseAgeMinutes   # -> 20160
```

:::note Distinct from the install-time filters
This version-selection filter — applied when _you_ pin versions with `pull-*` — is separate from the windows the package managers apply to an app's _transitive_ dependencies when they resolve them: the `minimumReleaseAge` key in `pnpm-workspace.yaml`, which pnpm applies to Bun and Node apps, and `exclude-newer`, which uv applies to UV apps. Both are 7 days, and `DATAMITSU_MIN_RELEASE_AGE` does not change them: what they resolve is written into a lock file, and a lock file has to come out the same whichever machine generates it. Change them per app instead; see [pnpm (Bun and Node Apps)](#pnpm-bun-and-node-apps) and [Release Age of Transitive Dependencies](#release-age-of-transitive-dependencies).
:::

### Transitive dependencies

`pull-*` ages only the version an app names. Everything that version depends on is resolved later, when `datamitsu config lockfile` generates the app's lock file, and each runtime covers it differently:

| App         | Transitive versions picked by | How the minimum release age reaches them                                                                                                                                                                         |
| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bun, Node   | pnpm                          | `minimumReleaseAge: 10080` in the app's `pnpm-workspace.yaml` filters the whole tree, top-level package included. See [pnpm (Bun and Node Apps)](#pnpm-bun-and-node-apps).                                       |
| UV          | uv                            | `--exclude-newer P7D` filters the whole tree; the lock records the window and every install reuses it. See [Release Age of Transitive Dependencies](#release-age-of-transitive-dependencies).                    |
| Go          | minimal version selection     | Go has no such setting. `config lockfile` checks every resolved module against the effective minimum release age. See [Release Age at Lock Generation](#release-age-at-lock-generation).                         |
| JVM, binary | nothing — one file            | The artifact is a single file pinned by SHA-256, with no dependency tree. The age applies where its version is chosen: `pull-releases` for binary apps. JAR versions are pinned by hand and are not age-checked. |

## Bun Apps

The Bun runtime is downloaded from an official GitHub release archive and verified against the SHA-256 digest published in that release's asset metadata. Bun apps use the same mandatory `pnpm-lock.yaml`, hardened workspace policy, and pinned native pnpm build as Node apps:

```bash
pnpm install --frozen-lockfile   # PATH starts with datamitsu's node → bun alias
```

The workspace policy blocks unapproved dependency lifecycle scripts, and `--frozen-lockfile` rejects any dependency graph that would modify the configured lock. Approved lifecycle scripts that call `node` resolve to the selected Bun through the alias, so installation never acquires Node. At execution, `--bun` keeps Node-shebang commands on the selected runtime and `--no-install` disables Bun's automatic dependency installation. datamitsu also disables Bun's automatic `.env` loading and supplies an empty Bun config when it executes the tool, preventing a target repository's `.env` files or `bunfig.toml` from changing a managed tool process. The app therefore cannot turn a cache miss into an unpinned network fetch during tool execution.

## pnpm (Bun and Node Apps)

The Node.js runtime itself is acquired as a direct, SHA-256-pinned archive download (like the JVM runtime), and pnpm — a native binary since pnpm 12 — is a runtime of its own, pinned the same way: one archive per platform from the pnpm GitHub release, each with the SHA-256 digest published in that release's asset metadata, referenced by the Node and Bun runtimes through `pnpmRuntime`. The toolchain executing your installs is integrity-verified before any package is fetched, and `datamitsu store refs` lists the pnpm archives as ordinary `runtime-binary` entries alongside the other downloads to mirror.

pnpm ships strict supply chain defaults (since pnpm 11) that block lifecycle scripts for unapproved packages. datamitsu integrates with these defaults rather than disabling them: when a Bun or Node app is installed, datamitsu writes a `pnpm-workspace.yaml` containing a secure baseline. Any per-app overrides supplied via `App.files["pnpm-workspace.yaml"]` are shallow-merged on top.

### Recommended Defaults

The baseline `pnpm-workspace.yaml` that datamitsu writes for every Bun and Node app:

```yaml
strictDepBuilds: true
blockExoticSubdeps: true
enablePrePostScripts: false
dangerouslyAllowAllBuilds: false
minimumReleaseAge: 10080 # 7 days in minutes
trustPolicy: no-downgrade
lockfile: true
preferFrozenLockfile: true
```

What each setting does:

| Setting                     | Purpose                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `strictDepBuilds`           | Blocks lifecycle scripts for unapproved packages (the pnpm default since v11)           |
| `blockExoticSubdeps`        | Rejects transitive deps from non-registry sources (git URLs, local paths) added by deps |
| `enablePrePostScripts`      | Disables `pre*`/`post*` script execution across all packages                            |
| `dangerouslyAllowAllBuilds` | Must stay `false`; setting `true` neutralizes `strictDepBuilds`                         |
| `minimumReleaseAge`         | Refuses to install packages published less than 7 days ago — defeats most typosquats    |
| `trustPolicy: no-downgrade` | Blocks unsigned/older provenance from replacing a previously-trusted version            |
| `lockfile`                  | Requires a lockfile in every install                                                    |
| `preferFrozenLockfile`      | Prefers frozen-lockfile semantics; datamitsu also passes `--frozen-lockfile` explicitly |

:::note Too-young dependencies stop the install

Since pnpm 12.3, `minimumReleaseAgeStrict` defaults to `true` whenever `minimumReleaseAge` is set explicitly, as datamitsu does. A dependency version younger than the cutoff is gated instead of being silently added to `minimumReleaseAgeExclude`, which in datamitsu's non-interactive installs stops the install. Wait until the version ages past the cutoff, or pin an older one.

:::

### Per-App Overrides via `App.files`

When a package legitimately needs build scripts (puppeteer, sharp, esbuild, etc.), allowlist it via `App.files["pnpm-workspace.yaml"]`. Your overrides are shallow-merged on top of the defaults — keys you do not set keep the secure baseline.

```typescript
const mapOfApps: BinManager.MapOfApps = {
  mmdc: {
    files: {
      "pnpm-workspace.yaml": YAML.stringify({
        allowBuilds: { puppeteer: true },
      }),
    },
    node: {
      packageName: "@mermaid-js/mermaid-cli",
      binPath: "node_modules/.bin/mmdc",
      version: "11.15.0",
      lockFile: "br:...",
    },
  },
};
```

The merged file written to the app environment includes both the secure defaults (e.g., `strictDepBuilds: true`) and the user's `allowBuilds` entry. The original `pnpm-workspace.yaml` from `App.files` is consumed by the merge and never written as a raw file.

### Overriding a Security Setting

User intent wins. If you explicitly set a key, it overrides the default — including security keys. For example, setting `strictDepBuilds: false` disables strict build approval. Use this sparingly and only when you understand the trade-off.

```typescript
files: {
  "pnpm-workspace.yaml": YAML.stringify({
    strictDepBuilds: false, // overrides the default
  }),
}
```

### Your Environment Cannot Override the Workspace

pnpm lets a `pnpm_config_<setting>` environment variable, in lower or upper case, win over `pnpm-workspace.yaml`. Exported for your own work, `pnpm_config_minimum_release_age=0` would drop the release-age window from every lock file you generate, and `pnpm_config_dangerously_allow_all_builds=true` would run dependency scripts at every install.

datamitsu therefore removes two groups of variables from the environment pnpm inherits: the one for every setting the merged `pnpm-workspace.yaml` holds, and the whole `pnpm_config_minimum_release_age*` family, whose exclude list loosens the window without touching `minimumReleaseAge` itself. Every other `pnpm_config_*` variable passes through — pnpm 12 reads its registry from `pnpm_config_registry`, not `npm_config_registry`. To change a setting for one app, set it in `App.files["pnpm-workspace.yaml"]`.

### Reusing Defaults in Project Repos via `sharedStorage`

For users who want to write a secure `pnpm-workspace.yaml` into a project repository (not into a datamitsu-managed Bun or Node app environment), the default `config.js` publishes the recommended defaults via `sharedStorage["pnpm-workspace-defaults"]`. Your config can read, extend, and write them.

```typescript
function getConfig(config: BinManager.Config): BinManager.Config {
  const pnpmDefaults = YAML.parse(config.sharedStorage?.["pnpm-workspace-defaults"] ?? "{}");

  const repoPnpmConfig = {
    ...pnpmDefaults,
    packages: ["packages/*"],
    allowBuilds: { esbuild: true, sharp: true },
  };

  return {
    ...config,
    bundles: {
      "project-pnpm-config": {
        files: {
          "pnpm-workspace.yaml": YAML.stringify(repoPnpmConfig),
        },
        links: { "pnpm-workspace": "pnpm-workspace.yaml" },
      },
    },
  };
}
```

This pattern is for **repo-level** configuration — a project's own `pnpm-workspace.yaml`. It is separate from the per-app node merge above, which is fully automatic.

### Lockfile Enforcement

Node apps require a `lockFile` field. datamitsu runs `pnpm install --frozen-lockfile`, so any drift between the lock file and `package.json` fails the install. Regenerate lock files after version bumps via `datamitsu config lockfile <appName>`.

## UV (Python Apps)

UV apps use [uv](https://github.com/astral-sh/uv) to install Python packages into isolated environments. Several defenses are layered:

### `--locked` Enforces the Lock File

Every UV app requires `lockFile`, and `uv sync` runs with `--locked`. UV refuses
to modify `uv.lock` and exits non-zero if it would need to resolve versions
differently.

### `--no-build` Blocks Source Distributions

datamitsu also passes `--no-build`. UV will install only pre-built wheels —
never source distributions (sdists), which would otherwise execute arbitrary
build code during install.

The pair `--locked --no-build` is intentional. A locked dependency without a
wheel for the target platform fails rather than falling back to executing a
build backend.

**Trade-off**: if a locked version has no wheel for your platform (e.g., a niche arch, or a pure-Python package without a wheel), the install fails. This is intentional — the failure surfaces a security-relevant gap rather than silently executing setup.py.

```typescript
const mapOfApps: BinManager.MapOfApps = {
  yamllint: {
    uv: {
      packageName: "yamllint",
      version: "1.38.0",
      lockFile: "br:...", // mandatory; triggers --locked + --no-build
    },
  },
};
```

### Release Age of Transitive Dependencies

`devtools pull-uv` ages only the package an app names. Everything that package depends on is resolved when `datamitsu config lockfile` generates the lock, and without a window uv takes the newest release it finds, including one uploaded minutes earlier. datamitsu passes one: `--exclude-newer P7D`, the built-in 7-day minimum release age. uv records it in the lock:

```toml
[options]
exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values.
exclude-newer-span = "P7D"
```

`uv sync --locked` accepts a lock only when it is given the same window again, in the same unit: `P7D` and `10080 minutes` count as different. So an install never passes the current default. It reads the window back from the lock's `[options]` and passes exactly that:

- a lock generated before datamitsu passed a window has no `[options]` and keeps installing without one;
- a lock generated since carries its window;
- changing the built-in default never invalidates a lock that is already published.

Configs that ship uv lock files adopt the window by regenerating them with `datamitsu config lockfile <appName>`. The window is the built-in default rather than `DATAMITSU_MIN_RELEASE_AGE`, because the lock records it and must come out the same whichever machine generates it.

A version younger than the window cannot resolve. `pull-uv` never selects one, but a hand-pinned version can; the error then names the minimum release age as the reason.

#### Per-App Window via `uv.toml`

An app that ships a `uv.toml`, through `App.files` or an archive, gets it as its uv configuration, for generating the lock and for installing it alike. `exclude-newer` there replaces the default window for that app. `exclude-newer-package` sets a cutoff for one package, which is the way out when a fix exists only in a release younger than the window: a timestamp, a duration, or `false` to exempt the package. The lock records both, and an install passes them back the same way.

```typescript
files: {
  "uv.toml": TOML.stringify({
    "exclude-newer-package": { "example-package": false },
  }),
}
```

Regenerate the lock file after changing it.

#### Your Own uv Settings Stay Out

uv runs with `--no-config`, or with `--config-file` pointing at the app's own `uv.toml`, so a user- or system-level `uv.toml` cannot change what a managed install resolves or checks the lock against. `UV_CONFIG_FILE`, `UV_EXCLUDE_NEWER` and `UV_EXCLUDE_NEWER_PACKAGE` are removed from the environment uv inherits; exported for your own work, any of them would otherwise make `uv sync --locked` reject every managed lock. Settings for reaching the network, such as `UV_NATIVE_TLS`, `SSL_CERT_FILE` or the proxy variables, still pass through, so set them in the environment rather than in a `uv.toml`.

### Hash Verification

UV's lock file format embeds hashes for every resolved artifact. Combined with `--locked`, this gives end-to-end integrity for the dependency tree.

## Go (Go Apps)

Go apps build a command-line tool from source with the managed Go SDK. Three layers of defense apply before the resulting binary runs.

### Hash-Pinned Go SDK

The Go toolchain itself is downloaded as a SHA-256-pinned archive (like the Node.js and JVM runtimes), so the compiler building your tool is integrity-verified before any source is fetched. `GOTOOLCHAIN=local` is forced, so the pinned SDK can never silently swap itself for a different toolchain version.

### Mandatory Lock File (`go.mod` + `go.sum`)

Go apps require a `lockFile` field. datamitsu stores it as a JSON wrapper carrying both `go.mod` and `go.sum`, writes both files into an isolated build directory, and builds with `-mod=readonly`. Any drift between the resolved modules and the pinned `go.sum` fails the build instead of silently rewriting it. The checksum database ([sum.golang.org](https://sum.golang.org/)) is consulted via `GOSUMDB`, and `GOPRIVATE`/`GONOPROXY`/`GONOSUMDB`/`GOINSECURE` are explicitly cleared so no module can opt out of verification.

```typescript
const mapOfApps: BinManager.MapOfApps = {
  govulncheck: {
    go: {
      packageName: "golang.org/x/vuln/cmd/govulncheck",
      version: "v1.3.0",
      lockFile: "br:...", // mandatory; carries go.mod + go.sum
    },
  },
};
```

### Reproducible Builds

The build runs `go build -trimpath -mod=readonly`. `-trimpath` strips local filesystem paths so the output is reproducible, and `-mod=readonly` forbids any `go.mod`/`go.sum` mutation. Regenerate the lock file after a version bump via `datamitsu config lockfile <appName>`.

### Release Age at Lock Generation

Go has no setting that makes resolution skip recent releases, but minimal version selection does most of the work: `go get` only takes versions that some `go.mod` in the graph names, so a dependency is normally older than the module that requires it. What remains is the version you pin — there is no `pull-*` command for Go apps — and an import that no `go.mod` requires, which `go get` resolves to the newest release.

`datamitsu config lockfile` therefore checks the result. After `go get`, it lists every module in the build (`go list -m -json all`) and fails if any is younger than the effective minimum release age, or reports no time at all:

```text
modules resolved for "tool" are younger than the minimum release age of 10080 minutes:
  example.com/tool v1.4.0 (2026-09-20T10:00:00Z)
pin an older version, or set DATAMITSU_MIN_RELEASE_AGE=0 to skip this check
```

Unlike the pnpm and uv windows, this check follows `DATAMITSU_MIN_RELEASE_AGE`, like the `pull-*` commands do. It only accepts or rejects a result, and nothing records the value, so the lock file comes out the same whatever it is set to.

The times come from the Go module proxy and are commit times, not publish times. The check stops an accidentally fresh pin. It cannot stop an attacker who backdates a commit.

### Securing Your Own Repository's Go Code

datamitsu manages Go _apps_ (tools it builds for you); your repository's own Go modules are still managed by `go` itself. Enforce the standard defenses in CI:

```bash
# Verify go.sum checksums against the local module cache
go mod verify

# Ensure go.mod and go.sum are current and committed
go mod tidy && git diff --exit-code

# Build without silently mutating go.mod or downloading new modules
GOFLAGS=-mod=readonly go build ./...

# Scan for known vulnerabilities in dependencies and stdlib
govulncheck ./...
```

## Common Patterns

### Adding a Package that Requires Build Scripts

1. Identify the package — the install error will name it: `ERR_PNPM_IGNORED_BUILDS`
2. Add it to `App.files["pnpm-workspace.yaml"]` under `allowBuilds`
3. Regenerate the lock file: `pnpm exec datamitsu config lockfile <appName>`
4. Commit both the config change and the new `lockFile` value

### Tightening `minimumReleaseAge`

The 7-day default catches typosquats and rushed compromised releases. For higher-security environments, override per app:

```typescript
files: {
  "pnpm-workspace.yaml": YAML.stringify({
    minimumReleaseAge: 43200, // 30 days
  }),
}
```

For a UV app, set `exclude-newer` in the app's `uv.toml`, then regenerate its lock file:

```typescript
files: {
  "uv.toml": TOML.stringify({
    "exclude-newer": "30 days",
  }),
}
```

### CI Hardening

A reasonable CI pipeline for repositories that consume datamitsu:

```bash
datamitsu init  # on a fresh runner, materialize the hash-pinned store
datamitsu check # run the full check pipeline
go mod verify                    # if your repo has Go code
datamitsu exec govulncheck -- ./... # if your repo has Go code
```

For wrapper packages, also run `datamitsu devtools verify-all` to confirm every platform's binaries and runtimes still hash-match.

## Related

- [Maintaining Wrapper Packages](../how-to/maintain-wrapper.md) — keeping tool versions, hashes, and lock files current
- [PNPM Patterns](../examples/pnpm-patterns.md) — workspace and dependency examples for node apps
- [UV Isolation](../examples/uv-isolation.md) — Python app isolation patterns
- [Binary Management](./binary-management.md) — hash verification for binary apps and runtimes

---

## Tooling System


datamitsu orchestrates your development tools (linters, formatters, type checkers) through a unified system. You define tool operations in your configuration, and datamitsu handles file discovery, task planning, parallel execution, and output formatting.

:::tip Deep Dive
For a deep dive into task planning and execution, see [Architecture](./architecture/index.md).
:::

## Operations

datamitsu supports three operations that you run through CLI commands:

| Command           | Operation | Purpose                                           |
| ----------------- | --------- | ------------------------------------------------- |
| `datamitsu fix`   | fix       | Auto-fix code issues (formatting, import sorting) |
| `datamitsu lint`  | lint      | Report code issues without modifying files        |
| `datamitsu check` | check     | Run fix then lint in sequence                     |

`datamitsu check` is the most common command -- it fixes what it can, then reports remaining issues. If fix fails, lint is skipped, unless `--fail-fast=false` runs it anyway.

## Defining Tools

Tools are defined in the `tools` record of your configuration. Each tool has a name and operations:

```javascript
const tools = {
  eslint: {
    name: "ESLint",
    projectTypes: ["npm-package"],
    operations: {
      fix: {
        app: "eslint",
        args: ["--fix", "{files}"],
        scope: "per-project",
        globs: ["**/*.{js,ts,jsx,tsx}"],
      },
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        globs: ["**/*.{js,ts,jsx,tsx}"],
      },
    },
  },
  "golangci-lint": {
    name: "golangci-lint",
    projectTypes: ["golang-package"],
    operations: {
      lint: {
        app: "golangci-lint",
        args: ["run", "--timeout", "5m"],
        scope: "repository",
        globs: ["**/*.go"],
      },
    },
  },
};
```

## Scopes

Tools operate at different scopes depending on how they process files:

### Per-Project Scope (with file batching)

The tool runs once per detected project and receives a batch of matching file paths. datamitsu discovers files (by extension), groups them by project, and passes them to the tool:

```javascript
prettier: {
  name: "Prettier",
  operations: {
    fix: {
      app: "prettier",
      args: ["--write", "{files}"],
      scope: "per-project",
      globs: ["**/*.{js,ts,css,md}"],
    },
    lint: {
      app: "prettier",
      args: ["--check", "{files}"],
      scope: "per-project",
      globs: ["**/*.{js,ts,css,md}"],
    },
  },
}
```

The `{files}` placeholder expands to the list of matching files.

### Per-Project Scope (without file lists)

The tool runs once per detected project directory, without receiving file lists:

```javascript
tsc: {
  name: "TypeScript",
  projectTypes: ["npm-package"],
  operations: {
    lint: {
      app: "tsc",
      args: ["--noEmit"],
      scope: "per-project",
      globs: ["**/*.{ts,tsx}"],
    },
  },
}
```

In a monorepo, this runs `tsc` separately in each directory that has a `package.json`.

### Repository Scope

The tool runs once from the git root, regardless of monorepo structure:

```javascript
"golangci-lint": {
  name: "golangci-lint",
  projectTypes: ["golang-package"],
  operations: {
    lint: {
      app: "golangci-lint",
      args: ["run"],
      scope: "repository",
      globs: ["**/*.go"],
    },
  },
}
```

## Exclude Patterns

Use `excludeGlobs` to remove files from a tool's matched set. The patterns use doublestar syntax (`*`, `**`, `?`, `[...]`, `{alt1,alt2}`) — the same as `globs`. The `!` negation prefix is not supported; use `excludeGlobs` instead.

```javascript
prettier: {
  name: "Prettier",
  operations: {
    fix: {
      app: "prettier",
      args: ["--write", "{files}"],
      scope: "per-project",
      globs: ["**/*.{js,ts,css,md}"],
      excludeGlobs: ["**/*.generated.*", "**/vendor/**"],
    },
  },
}
```

Filtering order: `globs` (include) → `excludeGlobs` (exclude) → subdirectory scope restriction → `.datamitsuignore` (per-tool disable).

`globs` is optional. Omit it for tools that handle their own file discovery (e.g. `golangci-lint run`, `eslint .`) — the tool runs without a file list. `excludeGlobs` only narrows the set of files datamitsu matches via `globs`; it has no effect when `globs` is empty, because the tool, not datamitsu, decides which files to read.

## Template Placeholders

Tool operation arguments support placeholders that datamitsu resolves before execution:

| Placeholder   | Description                            |
| ------------- | -------------------------------------- |
| `{file}`      | Single file path (per-file scope)      |
| `{files}`     | Expands to separate arguments per file |
| `{root}`      | Git repository root                    |
| `{cwd}`       | Per-project working directory          |
| `{toolCache}` | Per-project, per-tool cache directory  |

See the [Template Placeholders reference](/docs/reference/template-placeholders) for detailed usage.

## Per-Operation Environment Variables

Each operation can set environment variables:

```javascript
operations: {
  lint: {
    app: "golangci-lint",
    args: ["run"],
    scope: "per-project",
    globs: ["**/*.go"],
    env: {
      "GOLANGCI_LINT_CACHE": "{toolCache}",
    },
  },
}
```

Environment variables are merged in layers: OS env without the variables datamitsu strips -> the operation's `inheritEnv` -> app env -> operation env -> `NO_COLOR=1`. Later layers override earlier ones, and nothing overrides `NO_COLOR=1`. The stripped variables (`GITHUB_ACTIONS`, AI agent markers, `FORCE_COLOR`) are listed on the [Tool Environment](../reference/tool-environment.md) page.

## Parallel Execution

datamitsu runs tools in parallel across projects. The maximum number of parallel workers is controlled by `DATAMITSU_MAX_PARALLEL_WORKERS` (default: `max(4, floor(NumCPU * 0.75))`, capped at 16).

## Fail-Fast Behavior

By default, when a tool fails, datamitsu cancels all remaining tasks:

1. The failing tool's error is captured
2. A cancellation signal is sent to prevent new tasks from starting
3. Already-running processes are cleaned up via process group signals
4. The failure is shown in full; the tasks it stopped are listed as `cancelled` or `not started`, never as failures

`--fail-fast=false` (or `DATAMITSU_FAIL_FAST=false`) turns this off and runs every tool, file and operation to the end, so one run reports every failure. The exit code is still non-zero when anything failed. See [Keep-going runs](../reference/cli-commands.md#keep-going-runs).

## Output Handling

datamitsu follows a single-print-layer rule:

- Tool executors capture all stdout/stderr silently into results
- The runner is the only component that prints output to the user
- Failed tools show a structured error block with: tool name, scope, directory, command, exit code, and captured output

## Formatting (stdin → stdout → diff)

Most fix tools mutate files in place. A **formatter** that reads a document on
standard input and writes the formatted result to standard output uses a
different contract: datamitsu feeds the file content in, captures the formatted
output, computes a **minimal line-based diff** in the core, and applies only the
changed lines back to the file.

Opt in with two operation fields:

- `input: "stdin"` — pipe the target file's content to the tool's standard input
- `output: "stdout"` — capture the tool's stdout (kept apart from stderr) as the
  candidate new file content

```javascript
// BAD: a stdin/stdout formatter routed through the default in-place vehicle.
// It never receives the file, and its formatted output is swallowed into the
// report instead of being written back.
const tools = {
  shfmt: {
    name: "shfmt",
    operations: {
      fix: { app: "shfmt", args: ["{file}"], scope: "per-file" },
    },
  },
};

// GOOD: feed content on stdin, capture stdout, let the core diff + apply.
const tools = {
  shfmt: {
    name: "shfmt",
    operations: {
      fix: {
        app: "shfmt",
        args: [], // tool reads stdin, writes the formatted document to stdout
        scope: "per-file",
        input: "stdin",
        output: "stdout",
      },
    },
  },
};
```

The flow per file:

```mermaid
graph LR
    A[Read original content] --> B[Run tool: content on stdin]
    B --> C[Capture stdout = candidate]
    C --> D[Line-based diff: original vs candidate]
    D --> E{Any edits?}
    E -- yes --> F[Apply minimal edits to file]
    E -- no --> G[Leave file untouched]

    style A fill:#e8f4fd,stroke:#2196f3
    style D fill:#fff3e0,stroke:#ff9800
    style F fill:#e8f5e9,stroke:#4caf50
    style G fill:#f3e5f5,stroke:#9c27b0
```

Key properties:

- **Minimal edits.** Changing one line in a 2000-line file touches only that
  line, not the whole file.
- **No-op is free.** If the formatted output equals the original, there are no
  edits and the file (including its mtime) is left untouched.
- **Diff lives in the core**, not the tool — the same diff-in-core contract is
  reused by the editor formatting path later.

The diff itself is documented under
[WASM Output Parsers → diff-in-core](./architecture/parsers.md#diff-in-core-formatting).

## Filtering

You can narrow what datamitsu processes:

### By Tool

Run only specific tools:

```bash
datamitsu check --tools eslint,prettier
```

### By Scope

Run only file-scoped tools:

```bash
datamitsu check --file-scoped
```

### By Directory

When you run datamitsu from a subdirectory, it automatically restricts scope:

- Repository-scope tasks are skipped entirely
- Per-project tasks run only for projects within the subdirectory
- Per-file tasks process only files within the subdirectory

## Explain Mode

Use `--explain` to see what datamitsu would run without executing anything:

```bash
datamitsu check --explain
```

This shows the planned tasks, matched files, and commands that would be executed.

## Ignore Rules

You can disable specific tools for certain files or directories using `.datamitsuignore` files or config-defined ignore rules. See the [Ignore Rules reference](/docs/reference/ignore-rules) for details.

## Monorepo Support

datamitsu is designed for monorepos with multiple projects. Each project gets:

- Its own tool execution with isolated working directory
- Its own cache namespace at `~/.cache/datamitsu/cache/projects/{hash}/cache/{projectPath}/{toolName}/`
- Independent results and error reporting

See the [Core Concepts](/docs/getting-started/core-concepts#monorepo-support) page for more on monorepo architecture.

## Bundled Operations

datamitsu includes built-in lint and fix operations for its own file formats:

- `.datamitsuignore` files are automatically formatted during fix operations
- `.datamitsuignore` files are validated during lint operations (unknown tool names produce warnings)

These bundled operations run before your configured tools.

---

## Using Wrapper Packages


Wrapper packages are pre-configured bundles of tools and configurations distributed via package managers (npm, gem, pypi). They allow teams to standardize development tooling across all projects with a single dependency.

## What are Wrapper Packages?

Instead of configuring linters, formatters, and other tools separately in each project, you install a wrapper package that brings everything pre-configured:

```bash
# Traditional approach (manual per project)
npm install eslint prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin
# Then create .eslintrc.js, .prettierrc, etc.

# With datamitsu wrapper
npm install @company/datamitsu-config
datamitsu config reconcile
# Everything configured automatically
```

Wrapper packages contain:

- Tool definitions (versions, download URLs, hashes)
- Pre-configured settings (ESLint rules, Prettier options, etc.)
- Managed project files (configs, ignore files, git hooks)
- Project-specific customization logic

## Installing a Wrapper Package

### Step 1: Install datamitsu

First, ensure you have the datamitsu binary installed. See [Installation](../getting-started/installation/index.md).

### Step 2: Install the Wrapper Package

Install your team's wrapper package as a dev dependency:

<Tabs>
  <TabItem value="pnpm" label="pnpm" default>

    ```bash
    pnpm add -D @company/datamitsu-config
    ```

  </TabItem>
  <TabItem value="npm" label="npm">

    ```bash
    npm install --save-dev @company/datamitsu-config
    ```

  </TabItem>
  <TabItem value="yarn" label="yarn">

    ```bash
    yarn add -D @company/datamitsu-config
    ```

  </TabItem>
  <TabItem value="bun" label="bun">

    ```bash
    bun add -D @company/datamitsu-config
    ```

  </TabItem>
  <TabItem value="deno" label="deno">

    ```bash
    deno add npm:@company/datamitsu-config
    ```

  </TabItem>
</Tabs>

The wrapper package typically includes a `datamitsu` binary in its bin/ folder that wraps the core binary with `--before-config`.

### Step 3: Initialize Tools

Download all configured tools:

```bash
# Using the wrapper's binary
npx datamitsu init

# Or if datamitsu is globally installed
datamitsu --before-config node_modules/@company/datamitsu-config/config/datamitsu.config.js init
```

This downloads and stores all binaries defined in the wrapper package.

### Step 4: Reconcile Managed Configs

Reconciliation writes managed files and then runs `datamitsu fix`. Preview the
changes without either action first:

```bash
npx datamitsu config reconcile --dry-run
```

Then reconcile the managed files:

```bash
npx datamitsu config reconcile
```

This creates config files (`.eslintrc.js`, `.prettierrc`, `.golangci.yml`, etc.)
in your project based on the wrapper's `managedConfigs` entries. It is separate
from `init`, which provisions the toolchain and `.datamitsu` links.

### Step 5: Run Checks

Run linters and fixers:

```bash
# Fix automatically fixable issues
npx datamitsu fix

# Run lint checks
npx datamitsu lint

# Run both (fix first, then lint)
npx datamitsu check
```

## Using the Wrapper Package

Once installed, the wrapper package becomes your team's standard toolchain.

### Running Commands

Use the wrapper's `datamitsu` binary:

```bash
# All commands automatically use the wrapper config
npx datamitsu init
npx datamitsu config reconcile
npx datamitsu check
npx datamitsu exec golangci-lint run
```

### Integrating with npm Scripts

Add datamitsu commands to your `package.json`:

```json
{
  "scripts": {
    "lint": "datamitsu lint",
    "fix": "datamitsu fix",
    "check": "datamitsu check",
    "reconcile-config": "datamitsu config reconcile"
  }
}
```

Then run via your package manager:

```bash
npm run lint
npm run fix
npm run check
```

### Integrating with CI/CD

Pre-cache tools in Docker for fast CI builds:

```dockerfile
FROM node:20-alpine

# Install wrapper package globally
RUN npm install -g @company/datamitsu-config

# Download ALL tools to global cache
RUN datamitsu init --all

# This layer is cached - only re-runs when tools change

# Copy project files
COPY . /app
WORKDIR /app

# Run checks (tools already cached)
RUN datamitsu check
```

Only changed tools re-download on updates, dramatically speeding up CI builds.

:::tip
If you maintain the wrapper package itself (rather than just consuming it), you can publish a pre-built image instead of running `datamitsu init --all` at build time. `datamitsu devtools dockerfile` generates an optimized multi-stage Dockerfile with a digest-pinned base and one cacheable layer per tool. See [Generating a Docker image](/docs/how-to/maintain-wrapper#generating-a-docker-image-devtools-dockerfile).
:::

## Customizing Wrapper Configs

Wrapper packages provide opinionated defaults, but you can override them in your project.

### Project-Level Config

Create `datamitsu.config.ts` at your git root:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(prev) {
  return {
    ...prev,
    apps: {
      ...prev.apps,
      // Disable a tool from the wrapper
      unwantedTool: undefined,

      // Override tool settings
      "golangci-lint": {
        ...prev.apps["golangci-lint"],
        operations: {
          lint: {
            args: ["run", "--timeout=10m"], // Longer timeout for this project
          },
        },
      },
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### Replace Managed Config Files

Override the wrapper's managed config files by providing your own:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(prev) {
  return {
    ...prev,
    managedConfigs: {
      ...prev.managedConfigs,
      ".eslintrc.js": {
        content: () => `
export default {
  // Your custom ESLint config
  rules: {
    "no-console": "error",
  },
};
`,
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

### Add Project-Specific Tools

Extend the wrapper with tools unique to your project:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(prev) {
  return {
    ...prev,
    apps: {
      ...prev.apps,
      "custom-linter": {
        binary: {
          binaries: {
            linux: {
              amd64: {
                glibc: {
                  url: "https://example.com/custom-linter-linux-amd64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "custom-linter",
                },
              },
            },
          },
        },
      },
    },
    tools: {
      ...prev.tools,
      "custom-linter": {
        name: "custom-linter",
        operations: {
          lint: {
            app: "custom-linter",
            args: ["check"],
            scope: "repository",
          },
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

## Migration-Free Updates

One of datamitsu's key features is migration-free updates. Update your wrapper package without breaking your project customizations.

### How It Works

The patching mechanism merges new defaults with your project-specific changes:

1. **Wrapper provides base config** — Tool versions, default settings
2. **Your project customizes** — Overrides specific settings
3. **Wrapper updates** — New tool versions, new defaults
4. **Re-run reconciliation** — Customizations preserved, new defaults applied

### Example Workflow

```bash
# Initial install
npm install @company/datamitsu-config@1.0.0
datamitsu config reconcile

# Customize .eslintrc.js manually
# ... make changes ...

# Months later: wrapper updates
npm update @company/datamitsu-config  # Now 2.0.0

# Reconcile managed config changes, then run fix
datamitsu config reconcile

# Your customizations preserved
# New defaults from wrapper applied
```

### What Gets Updated

- **Tool versions** — Automatically updated to wrapper's versions
- **New tools** — Added to your project if configured in wrapper
- **Default configs** — Merged with your customizations
- **Ignore patterns** — Merged with existing patterns

### What Gets Preserved

- **Manual customizations** — Changes you made to generated files
- **Project-specific overrides** — Settings in `datamitsu.config.ts`
- **Custom tools** — Tools you added locally

## Finding Wrapper Packages

### Official Wrappers

- **[@shibanet0/datamitsu-config](https://github.com/shibanet0/datamitsu-config)** — Reference implementation with Go, TypeScript, Rust, Docker tooling

### Company Wrappers

Your company may provide internal wrapper packages:

- `@company/dev-standards` — Company-wide tool standards
- `@team/frontend-config` — Team-specific configurations
- `@project/shared-config` — Project template configurations

### Community Wrappers

Search on npm, rubygems, or pypi for third-party wrappers:

```bash
npm search datamitsu
```

## Example: Using shibanet0/datamitsu-config

Install the reference wrapper:

```bash
npm install --save-dev shibanet0/datamitsu-config
```

Initialize tools, optionally preview managed config changes, then reconcile them:

```bash
npx datamitsu init
npx datamitsu config reconcile --dry-run
npx datamitsu config reconcile
```

This installs and configures:

- **Go tools** — golangci-lint
- **TypeScript tools** — eslint, prettier, tsc
- **Docker tools** — hadolint
- **Shell tools** — shellcheck
- **Git hooks** — lefthook

All pre-configured with opinionated defaults.

Customize for your project:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

// datamitsu.config.ts
function getConfig(prev) {
  return {
    ...prev,
    apps: {
      ...prev.apps,
      // Use stricter golangci-lint timeout
      "golangci-lint": {
        ...prev.apps["golangci-lint"],
        operations: {
          lint: {
            args: ["run", "--timeout=5m"],
          },
        },
      },
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

## Docker Optimization

Wrapper packages enable powerful Docker caching strategies.

### Pre-Cache All Tools

In your Dockerfile:

```dockerfile
FROM node:20-alpine

# Install wrapper globally
RUN npm install -g @company/datamitsu-config

# Download all tools (--all flag)
RUN datamitsu init --all

# This layer is cached until wrapper version changes
# Tools are stored in global cache, available to all projects

# Later: copy your project
COPY . /app
WORKDIR /app

# Install project dependencies
RUN npm install

# Run checks (tools already cached)
RUN datamitsu check
```

### Incremental Updates

When the wrapper updates:

- Only changed tools re-download
- Unchanged tools remain cached in the layer
- No full re-download on every build

This can reduce CI build times from minutes to seconds.

## Troubleshooting

### Wrapper Binary Not Found

If `npx datamitsu` doesn't work after installing the wrapper:

```bash
# Check if wrapper installed correctly
ls node_modules/@company/datamitsu-config/bin/datamitsu

# Use explicit path
./node_modules/.bin/datamitsu init

# Or install datamitsu globally
npm install -g @datamitsu/datamitsu
datamitsu --before-config node_modules/@company/datamitsu-config/config/datamitsu.config.js init
```

### Tool Versions Conflict

If the wrapper provides tool versions that conflict with your needs:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

// Override specific tool version in datamitsu.config.ts
function getConfig(prev) {
  return {
    ...prev,
    apps: {
      ...prev.apps,
      "golangci-lint": {
        ...prev.apps["golangci-lint"],
        binary: {
          binaries: {
            linux: {
              amd64: {
                glibc: {
                  url: "https://github.com/golangci/golangci-lint/releases/download/v1.60.0/...",
                  hash: "sha256:<new-digest>",
                  contentType: "tar.gz",
                  binaryPath: "...",
                },
              },
            },
          },
        },
      },
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### Managed Config Files Not Generated

If `datamitsu config reconcile` doesn't create expected files:

1. Check that the wrapper defines files under `managedConfigs`
2. Verify you're in a git repository (reconciliation only runs in git repos)
3. Check project type detection (managed config entries may be conditional)

### Cache Issues

Clear cache if tools behave unexpectedly:

```bash
# Clear project cache
datamitsu cache clear

# Clear all project caches
datamitsu cache clear --all

# Clear global store (binaries, runtimes)
datamitsu store clear
```

## Next Steps

- [Maintaining Wrapper Packages](../how-to/maintain-wrapper.md) — If you're maintaining a wrapper, learn about version update workflows
- [Creating Wrappers](../contributing/creating-wrappers.md) — Build your own wrapper package
- [Configuration API](../reference/configuration-api.md) — Full config reference for customization
- [CLI Commands](../reference/cli-commands.md) — Complete command reference
- [Core Concepts](../getting-started/core-concepts.md) — Understand datamitsu architecture

Wrapper packages are the key to datamitsu's value: install once, get everything configured. Build your team's wrapper to set the toolchain up once, for every repository that inherits it.

## Explore the reference wrapper

The reference wrapper `@shibanet0/datamitsu-config`, `0.6.3`,
captured on 2026-10-26: 117 apps across seven runtime families - native binary 78,
Node.js 15, Python 10, Bun 6, Go 4, JVM 3 and Shell 1. These are one maintainer's choices.
The orbit is illustrative; colors represent runtime membership.

<ConfigEmbed view="universe" />

[Open the full atlas](https://datamitsu.com/atlas.html).
See the [Config Inspector guide](config-inspector.md) to inspect or embed your own configuration.

---

## Add a New Tool


This guide walks through adding each type of tool to your datamitsu configuration.

## Adding a Binary App

Binary apps are standalone executables downloaded directly from release URLs.

### 1. Find the release URLs

Locate the download URLs for each platform you need. Most tools publish releases on GitHub with platform-specific archives.

### 2. Obtain and verify the SHA-256 hashes

Obtain each archive's SHA-256 from an authenticated upstream release manifest
or signature before downloading it. Never treat a digest computed only after an
untrusted download as the trust anchor. Then verify the download against that
expected value:

```bash
EXPECTED_SHA256="<sha256-from-the-upstream-manifest>"
curl -L -o tool.tar.gz "https://github.com/org/tool/releases/download/v1.0.0/tool_linux_amd64.tar.gz"
printf '%s  %s\n' "$EXPECTED_SHA256" tool.tar.gz | sha256sum --check -
```

### 3. Add the app definition

Add the app to `apps` in your config file:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      mytool: {
        binary: {
          binaries: {
            darwin: {
              amd64: {
                unknown: {
                  url: "https://github.com/org/mytool/releases/download/v1.0.0/mytool_darwin_amd64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "mytool",
                },
              },
              arm64: {
                unknown: {
                  url: "https://github.com/org/mytool/releases/download/v1.0.0/mytool_darwin_arm64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "mytool",
                },
              },
            },
            linux: {
              amd64: {
                glibc: {
                  url: "https://github.com/org/mytool/releases/download/v1.0.0/mytool_linux_amd64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "mytool",
                },
              },
            },
          },
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### 4. Test the tool

```bash
datamitsu init
datamitsu exec mytool -- --version
```

### 5. Verify cross-platform hashes (optional)

Use `devtools verify-all` to download and verify hashes for all configured platforms:

```bash
datamitsu devtools verify-all
```

## Adding a UV App (Python)

UV apps are Python packages installed in isolated environments.

### 1. Find the package on PyPI

Check that your tool is available on [PyPI](https://pypi.org) and note the version.

### 2. Add the app definition

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      yamllint: {
        uv: {
          packageName: "yamllint",
          version: "1.35.1",
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

The `runtime` field references a UV runtime defined in `runtimes`. The default configuration already includes one.

### 3. Generate the mandatory lock file

The `config lockfile` command deliberately permits this app's initially missing
`lockFile` so it can generate one. All normal commands reject the config until
you paste the result back:

```bash
datamitsu config lockfile yamllint
```

Copy the output into your app definition:

```javascript
yamllint: {
  uv: {
    packageName: "yamllint",
    version: "1.35.1",
    lockFile: "br:...",  // paste the output here
  },
},
```

### 4. Test the tool

```bash
datamitsu init
datamitsu exec yamllint -- --version
```

## Adding a Bun App

Bun apps are npm packages installed by pnpm and executed with an isolated Bun runtime. Bun launches the pnpm script directly, so no Node runtime is acquired for installation.

### 1. Add the app definition

```javascript
apps: {
  eslint: {
    bun: {
      packageName: "eslint",
      version: "10.9.0",
      binPath: "node_modules/eslint/bin/eslint.js",
      lockFile: "", // generated next
    },
  },
}
```

Use the package's JavaScript entrypoint for `binPath`. datamitsu invokes it explicitly with Bun rather than relying on an npm `.bin` shebang that may select Node.

### 2. Generate the mandatory lock file

```bash
datamitsu config lockfile eslint
```

Paste the resulting `br:...` value into `lockFile`. It contains `pnpm-lock.yaml`; normal installs use pnpm's frozen lockfile and the shared hardened workspace policy.

### 3. Test the tool

```bash
datamitsu exec eslint -- --version
```

## Adding a Node App (Node.js)

Node apps are npm packages managed with pnpm in isolated Node.js environments.

### 1. Find the package on npm

Check that your tool is available on [npm](https://www.npmjs.com) and note the version.

### 2. Add the app definition

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      prettier: {
        node: {
          packageName: "prettier",
          version: "3.2.0",
          binPath: "node_modules/.bin/prettier",
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### 3. Generate the mandatory lock file

```bash
datamitsu config lockfile prettier
```

Add the output to your app definition as the `lockFile` field.

### 4. Add managed config links (optional)

If the app provides configuration files that your projects need, add `links`:

```javascript
prettier: {
  node: {
    packageName: "prettier",
    version: "3.2.0",
    binPath: "node_modules/.bin/prettier",
    lockFile: "br:...",
  },
  links: {
    "prettier-config": "dist/prettier.config.js",
  },
},
```

After `datamitsu init`, this creates a symlink at `.datamitsu/prettier-config` pointing to the file inside the app's install directory.

### 5. Test the tool

```bash
datamitsu init
datamitsu exec prettier -- --version
```

## Adding a JVM App

JVM apps are JAR files executed with a managed JDK.

### 1. Find the JAR URL

Locate the direct download URL for the JAR file, typically from Maven Central or the project's releases.

### 2. Obtain the SHA-256 hash

Obtain the digest from the repository's authenticated checksum metadata or a
signed upstream release manifest. As with binary apps, set `jarHash` — a
canonical `sha256:<64 lowercase hex>` digest — before allowing datamitsu to
download the JAR; a missing hash is a config error.

### 3. Add the app definition

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      "openapi-generator": {
        jvm: {
          jarUrl:
            "https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.0.0/openapi-generator-cli-7.0.0.jar",
          jarHash: "sha256:...", // canonical digest (mandatory)
          version: "7.0.0",
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### 4. Test the tool

```bash
datamitsu init
datamitsu exec openapi-generator version
```

## Adding a Go App

Go apps are built from a pinned module version with a managed, hash-verified Go
SDK. Their lock payload contains both `go.mod` and `go.sum`.

### 1. Add the package and version

The initial definition may omit `lockFile` only while running the generation
command:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      govulncheck: {
        go: {
          packageName: "golang.org/x/vuln/cmd/govulncheck",
          version: "v1.3.0",
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

### 2. Generate the mandatory lock file

```bash
datamitsu config lockfile govulncheck
```

Paste the output into the app:

```javascript
govulncheck: {
  go: {
    packageName: "golang.org/x/vuln/cmd/govulncheck",
    version: "v1.3.0",
    lockFile: "br:...", // contains go.mod + go.sum
  },
},
```

The subsequent build uses `go build -trimpath -mod=readonly`; dependency drift
that would modify either module file fails instead.

### 3. Test the tool

```bash
datamitsu init
datamitsu exec govulncheck -- --version
```

## Wiring a Tool to the Tooling System

After adding an app, you can wire it into the fix/lint/check workflow by adding a tool definition:

```javascript
const tools = {
  ...config.tools,
  mytool: {
    name: "mytool",
    projectTypes: ["golang-package"],
    operations: {
      lint: {
        app: "mytool",
        args: ["check", "{files}"],
        scope: "per-project",
        globs: ["**/*.go"],
      },
      fix: {
        app: "mytool",
        args: ["fix", "{files}"],
        scope: "per-project",
        globs: ["**/*.go"],
      },
    },
  },
};
```

Now `datamitsu check` will include your tool in its workflow. See the [Tooling System guide](/docs/guides/tooling-system) for details on scopes, placeholders, and environment variables.

## Version Checks

Add a `versionCheck` to enable `datamitsu devtools verify-all` to check your tool:

```javascript
mytool: {
  binary: {
    // ... binaries definition
  },
  versionCheck: {
    args: ["version"],  // default is ["--version"]
  },
}
```

Set `versionCheck: { disabled: true }` for tools that don't support version reporting.

---

## Configure Linters


This guide shows how to set up common linters and formatters in datamitsu's tooling system.

## Setting Up golangci-lint

golangci-lint is a Go linter aggregator. Since it operates on Go modules rather than individual files, configure it with `scope: "repository"`.

### 1. Ensure the app is defined

The default configuration includes golangci-lint as a binary app. If you need a custom version, override it in your config:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      "golangci-lint": {
        binary: {
          binaries: {
            // platform-specific URLs and hashes
          },
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

### 2. Define the tool

```javascript
const tools = {
  ...config.tools,
  "golangci-lint": {
    name: "golangci-lint",
    projectTypes: ["golang-package"],
    operations: {
      lint: {
        app: "golangci-lint",
        args: ["run", "--timeout", "5m"],
        scope: "repository",
        globs: ["**/*.go"],
        env: {
          GOLANGCI_LINT_CACHE: "{toolCache}",
        },
      },
    },
  },
};
```

Key points:

- `scope: "repository"` runs it once from the git root, not per-project
- `{toolCache}` gives golangci-lint an isolated cache directory
- Only a `lint` operation is defined since golangci-lint doesn't auto-fix

## Setting Up ESLint via the Node Runtime

ESLint is a JavaScript/TypeScript linter managed through the Node runtime.

### 1. Define the app

```javascript
apps: {
  ...config.apps,
  eslint: {
    node: {
      packageName: "eslint",
      version: "9.0.0",
      binPath: "node_modules/.bin/eslint",
      lockFile: "br:...",  // generated via: datamitsu config lockfile eslint
    },
    links: {
      "eslint-config": "dist/eslint.config.js",
    },
  },
}
```

### 2. Define the tool

```javascript
const tools = {
  ...config.tools,
  eslint: {
    name: "ESLint",
    projectTypes: ["npm-package"],
    operations: {
      fix: {
        app: "eslint",
        args: ["--fix", "{files}"],
        scope: "per-project",
        globs: ["**/*.{js,ts,jsx,tsx}"],
      },
      lint: {
        app: "eslint",
        args: ["{files}"],
        scope: "per-project",
        globs: ["**/*.{js,ts,jsx,tsx}"],
      },
    },
  },
};
```

### 3. Reference the config link

In your project's ESLint config, use `tools.Config.linkPath()` to reference the managed configuration:

```javascript
// In a ManagedConfig content function
const eslintConfigPath = tools.Path.forImport(
  tools.Config.linkPath("eslint", "eslint-config", context.cwdPath),
);
```

## Setting Up Ruff via UV

Ruff is a fast Python linter and formatter managed through the UV runtime.

### 1. Define the app

```javascript
apps: {
  ...config.apps,
  ruff: {
    uv: {
      packageName: "ruff",
      version: "0.3.0",
      lockFile: "br:...",  // generated via: datamitsu config lockfile ruff
    },
  },
}
```

### 2. Define the tool

```javascript
const tools = {
  ...config.tools,
  ruff: {
    name: "Ruff",
    projectTypes: ["python"],
    operations: {
      fix: {
        app: "ruff",
        args: ["format", "{files}"],
        scope: "per-project",
        globs: ["**/*.py"],
      },
      lint: {
        app: "ruff",
        args: ["check", "{files}"],
        scope: "per-project",
        globs: ["**/*.py"],
      },
    },
  },
};
```

## Configuring Ignore Rules

Use ignore rules to skip tools for specific files or directories.

### Using .datamitsuignore files

Create a `.datamitsuignore` file in any directory:

```bash
# Disable all tools for vendor code
vendor/**/*: *

# Disable prettier for auto-generated files
**/*.generated.ts: prettier

# Disable eslint for test fixtures
tests/fixtures/**/*: eslint, prettier
```

### Using config-defined ignore rules

Add ignore rules directly in your configuration:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    ignoreRules: [
      "vendor/**/*: *",
      "**/*.generated.go: golangci-lint, gofmt",
      "!vendor/patches/**/*: *", // re-enable for patches
    ],
  };
}
globalThis.getConfig = getConfig;
```

### Re-enabling tools

Use the `!` prefix to re-enable tools disabled by broader rules:

```bash
# Disable eslint for all markdown
**/*.md: eslint

# But re-enable for documentation
!docs/**/*.md: eslint
```

See the [Ignore Rules reference](/docs/reference/ignore-rules) for full syntax details.

## Previewing Tool Execution

Before running tools, use `--explain` to see what would execute:

```bash
# Summary of planned tasks
datamitsu check --explain

# Detailed breakdown
datamitsu check --explain detailed

# Machine-readable output
datamitsu check --explain json
```

## Running Specific Tools

Use `--tools` to run only certain tools:

```bash
# Run only ESLint and Prettier
datamitsu check --tools eslint,prettier

# Fix only with Ruff
datamitsu fix --tools ruff
```

## Git Hook Integration

Use `--file-scoped` to check only staged files in a pre-commit hook:

```bash
datamitsu check --file-scoped
```

This pairs well with tools like lefthook for git hook management.

---

## Machine-Level Toolchain


[Source mode](../guides/source-mode.md) puts a **project's** declared toolchain on `PATH`. This
page covers the other half: a toolchain that belongs to **your machine** rather than to one
repository — the tier a dotfiles setup usually installs with `curl | sh`, `eget`, `go install`
or an npm global.

```bash
# in ~/.config/fish/config.fish
datamitsu source fish --config ~/.config/datamitsu/datamitsu.config.ts | source
```

Nothing about it is a new discovery rule: `--config` is the ordinary global flag, and naming
the file is the whole mechanism. The tools that config declares are then on `PATH` in every
shell, pinned and hash-verified, downloaded on first use.

## Write the config

The config is an ordinary datamitsu config file. It does not need to be inside a repository,
and datamitsu will never find it on its own — you name it.

```javascript title="~/.config/datamitsu/datamitsu.config.js"
globalThis.getMinVersion = () => "0.0.1";

globalThis.getConfig = (config) => ({
  ...config,
  apps: {
    ...config.apps,
    jq: {
      binary: {
        binaries: {
          darwin: {
            arm64: {
              unknown: {
                url: "https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-macos-arm64",
                hash: "sha256:<digest of that file>",
                contentType: "binary",
              },
            },
          },
          linux: {
            amd64: {
              glibc: {
                url: "https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-amd64",
                hash: "sha256:<digest of that file>",
                contentType: "binary",
              },
            },
          },
        },
      },
    },
  },
});
```

Every platform you actually use needs an entry, and every entry needs a `hash` — a canonical
SHA-256 digest, `sha256:` plus a real 64-character lowercase hex value, not the placeholder above.
That is not a lint rule you can turn off: a config with a missing or malformed hash fails to load.
See [Hash verification is the point](#hash-verification-is-the-point) below.

Writing those hashes by hand is not the intended workflow.
[`datamitsu devtools pull-releases`](./maintain-wrapper.md#binary-apps-devtools-pull-releases)
resolves releases through source profiles and records their expected SHA-256
digests or explicit pins for selected available platforms. It downloads binaries
only with `--verify-extraction`; the same `devtools pull-node` / `pull-uv` commands do it for npm and PyPI tools, which are
declared as [runtime-managed apps](../guides/runtime-management.md) with a lock file rather than
a URL.

## Activate it from a shell rc file

```bash title="~/.bashrc / ~/.zshrc"
eval "$(datamitsu source bash --config ~/.config/datamitsu/datamitsu.config.js)"
```

```fish title="~/.config/fish/config.fish"
datamitsu source fish --config ~/.config/datamitsu/datamitsu.config.js | source
```

Activation downloads nothing, and costs a manifest read when the farm is already current — the
same contract project activation has, for the same reason: an rc file runs in every shell and
every tmux pane. A tool is fetched the first time it is actually run.

The emitted code exports the farm directory and puts it first on `PATH`:

```console
$ datamitsu source fish --config ~/.config/datamitsu/datamitsu.config.js
set -e -g DATAMITSU_ROOT
set -gx DATAMITSU_FARM '/home/you/.cache/datamitsu/cache/configs/8d1f…/bin'
set -gx DATAMITSU_FARM_CONFIG '/home/you/.config/datamitsu/datamitsu.config.js'
fish_add_path --global --move --path '/home/you/.cache/datamitsu/cache/configs/8d1f…/bin'
```

`DATAMITSU_ROOT` is deliberately **unset** rather than set to an empty value: this farm has no
git root, and an empty one would read as "the repository could not be determined". Unsetting it
also clears whatever a project activation left behind in the same shell.
`DATAMITSU_FARM_CONFIG` records the config chain it was baked from, joined like `PATH`. Both are
informational — no tool resolves through them.

The farm itself lives in its own namespace, keyed by the resolved config chain rather than by a
root:

```text
~/.cache/datamitsu/cache/projects/{XXH3-128(gitRoot)}/     ← project farms
~/.cache/datamitsu/cache/configs/{XXH3-128(config chain)}/ ← machine-level farms
```

The chain is resolved to absolute paths with symlinks followed before it is hashed, so
`--config ./datamitsu.config.js` and `--config ~/.config/datamitsu/datamitsu.config.js` from that
directory are one farm, not two. Order matters, because the chain is a merge order: naming two
configs in the other order is a different toolchain and therefore a different farm.

An explicit-config activation never merges a discovered config, even when you run it from inside
a repository. The chain is exactly what you named.

## How it layers with project activation

Both can be active at once. The mechanism is `PATH` order and nothing else:

```text
{cache}/cache/projects/{hash}/bin   ← added by `datamitsu source` inside a repository
{cache}/cache/configs/{hash}/bin    ← added by `datamitsu source --config …`
…the rest of your PATH…
```

If a repository pins `jq` and your machine-level config also declares it, the project's pin wins,
because the project farm sits ahead on `PATH`. There is no merge, no precedence table and no
resolution logic to get wrong — `echo $PATH` shows you the whole answer.

A tool that only the machine-level config declares stays reachable from inside the project: the
project farm does not answer for that name, and `PATH` continues to the config farm.

Order follows activation order in your rc file, so activate the machine-level config first and
let per-project activation prepend itself later:

```bash title="~/.bashrc"
eval "$(datamitsu source bash --config ~/.config/datamitsu/datamitsu.config.js)"
# then, in a project shell, deliberately:
#   eval "$(datamitsu source bash)"
```

## The trust boundary

**A machine-level farm never evaluates a project's config.** A shell activated against
`~/.config/datamitsu/datamitsu.config.js` that `cd`s into a clone you have not read keeps running
the machine-level tools. It does not start resolving that repository's toolchain, and it does not
run that repository's JavaScript.

This is a security property, not a missing feature. A config is evaluated JavaScript. Making a
tool name enough to trigger that evaluation would mean any repository you happen to `cd` into
runs code the moment you type a common command. Getting into a repository's toolchain stays a
deliberate act:

```bash
cd ~/src/some-clone
eval "$(datamitsu source bash)"    # you decided to evaluate this repository's config
```

The two farm origins differ in exactly this, and in nothing else:

```text
origin: git-root           shim re-resolves from cwd's git root   (branch switching)
                           watch = config chain + .git/HEAD

origin: explicit-config    shim revalidates its own recorded chain, never walks up for .git
                           watch = config chain
```

So branch switching still works normally inside a project you _have_ activated, with the
machine-level farm sitting underneath, and a machine-level tool run from inside any repository
is still the version your own config pins.

The same [exclusions](../guides/source-mode.md#what-is-deliberately-excluded) apply here — `sudo`,
the shells, `git`, `ssh`, `datamitsu` itself and every `shell`-kind app are refused, with the
reason listed in `source status`. Shadow reporting matters more for a machine-level farm than for
a project one, because this farm is first on `PATH` in every shell: the list of system binaries it
takes over is the thing you most need to be able to read.

## Inspect it

`status` and `refresh` take the same `--config` flag, and report which origin the farm has:

```console
$ datamitsu source status --config ~/.config/datamitsu/datamitsu.config.js
origin:   explicit-config
config:   /home/you/.config/datamitsu/datamitsu.config.js
farm:     /home/you/.cache/datamitsu/cache/configs/8d1f…/bin
manifest: /home/you/.cache/datamitsu/cache/configs/8d1f…/manifest.json (fresh)

entries (2):
  jq          shim  installed
  shellcheck  shim  not installed

excluded (1):
  sudo  name is on the source-mode deny-list

shadowed (1):
  jq  /opt/homebrew/bin/jq
```

`--json` emits the same information as one document, with `origin` and `configPaths` fields.
`status` never downloads and never re-bakes, so it can describe a broken farm instead of quietly
repairing it.

Editing the config is enough: the next tool invocation notices the file changed and re-bakes
itself, exactly as a branch switch does for a project farm. `source refresh --config <path>` is
the repair command for the case the watch set cannot see — a config that branches on an
environment variable — and `--force` re-bakes unconditionally.

A name your config declares but that cannot be resolved **exits 127** naming the farm and the
`--config` invocation to repair it. It never falls through to whatever the system has under that
name, because exiting 0 with the wrong binary is worse than not running at all.

## Hash verification is the point

Every artifact datamitsu downloads carries a mandatory SHA-256, verified before it is used. A
missing hash is a configuration error, not a warning, and there is no hash-less fallback mode.
Lock files are likewise mandatory for npm- and PyPI-sourced tools.

That is the actual difference this makes. `curl https://example.com/install.sh | sh` verifies
nothing, pins nothing, and re-downloads whatever is at that URL today; `go install tool@latest`
resolves whatever `latest` means at that moment. Moving a tool into a machine-level datamitsu
config replaces that with a pinned version and a hash you can review in a diff — and, because
the config is a file, with a record of what your machine actually has on it.

See [Supply Chain Security](../guides/supply-chain-security.md) for what is verified where, and
for the minimum-release-age filter that keeps `pull-*` from adopting a release published minutes
ago.

## Migrating from install scripts

The honest scope: datamitsu can take over the tier of **user-space CLI binaries** — the things
that end up in `~/.local/bin` or `/usr/local/bin` by unverified download. That tier is exactly
where hash verification is usually absent.

| Move it to datamitsu                            | Leave it where it is                                    |
| ----------------------------------------------- | ------------------------------------------------------- |
| Single-binary CLIs from GitHub releases         | System packages needing a package manager or `sudo`     |
| npm globals and `uv`/`pipx` tools               | The package managers and language installers themselves |
| `go install`-ed tools                           | GUI application installers                              |
| `curl \| sh` installers for user-space binaries | Fonts, system libraries, kernel-adjacent things         |

Your system package manager does not go away. It stops being the thing that downloads unverified
binaries.

A migration that will not ruin your week:

1. Move **a few tools first**, not the whole list.
2. **Leave the previously installed binaries in place.** They stay on `PATH` behind the farm, so
   if activation is not working you get the old behavior rather than a missing command.
3. Run `datamitsu source status --config <path>` and read the `shadowed` section. That is the
   authoritative list of what the farm has taken over, with the absolute path each system binary
   was found at.
4. Delete the old copies only once that list says what you expect.
5. Run with the activation line in your rc file for a week before recommending it to anyone.
   Shell-startup regressions are noticed immediately and forgiven slowly.

`which jq` will report the farm path rather than the store, because every farm entry is a shim
pointing at the datamitsu binary. `datamitsu source status` prints the real target for every
entry — that is the answer to "which binary is this actually going to run".

## What this is not

There is no `~/.config/datamitsu` auto-discovery. datamitsu will not read a config you did not
name, in any location, for any command — `lint`, `fix` and `check` in a project are byte-for-byte
unaffected by whatever machine-level config exists on your disk, including their cache keys.

Naming the file is the trust boundary, and it is the cheapest one available for something that
executes JavaScript.

## See also

- [Source Mode](../guides/source-mode.md) — the project-scoped half, farms, shims and branch switching
- [`source` command reference](../reference/cli-commands.md#source) — every flag, in detail
- [Supply Chain Security](../guides/supply-chain-security.md) — what is hashed, verified and pinned
- [Maintain a Wrapper](./maintain-wrapper.md) — the `devtools pull-*` commands that compute hashes for you

---

## Maintaining Wrapper Packages


This guide covers the day-to-day workflows for maintaining a datamitsu wrapper package — keeping tool versions current, verifying integrity across platforms, and automating updates.

## Overview

A **wrapper package** is a datamitsu configuration that bundles a curated set of tools for a specific use case (e.g., a company's standard linting stack). As a wrapper maintainer, your responsibilities include:

- Updating tool versions when new releases are published
- Regenerating lock files for reproducible installs
- Verifying SHA-256 hashes across all supported platforms
- Testing that updated tools work correctly

datamitsu provides `devtools` commands to automate these tasks.

## Global-install parity: declaring `getBeforeConfigs()`

A wrapper package typically ships a `bin/datamitsu` shim that injects `--before-config <shared config>` so the shared configuration loads ahead of the project's own. That shim only fires when datamitsu is invoked **through** it (e.g. via `pnpm exec datamitsu`). A **globally installed** datamitsu run inside the same repo never receives the flag — it skips the shared config, the effective configuration diverges, and the user has to hand-edit the command to reproduce the wrapper's behaviour.

`getBeforeConfigs()` closes that gap. Export it from the project's git-root config to declare the shared config as a local under-layer, so the global binary reproduces the wrapper automatically:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getBeforeConfigs() {
  return [{ path: "./node_modules/@myorg/datamitsu-config/datamitsu.config.js" }];
}
globalThis.getBeforeConfigs = getBeforeConfigs;

function getConfig(config) {
  // config already includes the shared wrapper config's changes
  return { ...config };
}
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

The declared path is inserted into the loading order immediately before the auto config — exact parity with the `--before-config` flag (init-layer merging, `getMinVersion()` checks, remote-config resolution all apply identically).

**When to use which:**

| Situation                                          | Mechanism                                                      |
| -------------------------------------------------- | -------------------------------------------------------------- |
| Wrapper-managed repo, always run via the shim      | The shim's `--before-config` is enough — declaring is optional |
| Same repo also run with a **global** `datamitsu`   | Declare `getBeforeConfigs()` so both invocations match         |
| Debugging — want to run the global binary directly | Declare `getBeforeConfigs()`; no command rewriting needed      |

**Precedence (the flag always wins):** when `--before-config` is passed on the CLI, `getBeforeConfigs()` is **not evaluated at all**. This is deliberate — when the wrapper shim is in use, the flag already loads the shared config, and skipping the declaration avoids loading it twice. So adding `getBeforeConfigs()` is safe even for repos that are sometimes run through the shim and sometimes via the global binary.

A few rules to keep in mind:

- Relative paths resolve against the git-root config's directory; absolute paths are used as-is. A missing file is a hard error.
- No hash is required — a local path is in the same trust domain as the root config, not a network download (unlike `getRemoteConfigs()`, which mandates a SHA-256 hash).
- It is honoured **only** in the auto-discovered git-root config. A `getBeforeConfigs()` declared inside the shared config itself (or any other layer) is ignored — there is no chaining.

See [Configuration → Declared Before-Configs](../guides/configuration.md#declared-before-configs-getbeforeconfigs) for the full reference.

## Wrapping a private binary

A Bun proxy can call a managed native executable through an explicit app
binding. Keep the upstream's existing SHA-256-pinned binary declaration and
supported-platform map. The example below assumes your config build supplies
`upstreamBinary` (that declaration) and `proxyLockFile` (the generated pnpm
lockfile for your published proxy package, here named
`@example/lefthook-proxy`). It also retains the existing managed Bun runtime and
its pinned pnpm runtime.

```javascript
function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      "dm-internal-lefthook-upstream": {
        binary: upstreamBinary,
      },
      lefthook: {
        bun: {
          packageName: "@example/lefthook-proxy",
          version: "1.0.0",
          binPath: "node_modules/@example/lefthook-proxy/proxy.js",
          lockFile: proxyLockFile,
        },
        dependsOn: ["dm-internal-lefthook-upstream"],
        runtimeEnv: {
          DATAMITSU_LEFTHOOK_UPSTREAM: "${APP_BIN:dm-internal-lefthook-upstream}",
        },
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

The proxy package's `proxy.js` can forward the invocation directly:

```javascript
const child = Bun.spawn([process.env.DATAMITSU_LEFTHOOK_UPSTREAM, ...process.argv.slice(2)], {
  stdin: "inherit",
  stdout: "inherit",
  stderr: "inherit",
});
process.exit(await child.exited);
```

The child receives one exact, version-specific executable path. Avoid scanning
`${STORE}/.bin/<name>` and probing candidate versions; `required: true` on the
upstream is unnecessary. The `dm-internal-` prefix is a naming convention, not
an access-control or shim-exclusion setting.

When `init` selects `lefthook`, it installs the upstream too. `install lefthook`,
`exec lefthook`, and tools using it through `check`, `lint`, `fix`, or LSP all
provision its transitive closure, regardless of the dependency's `required` or
`lazy` flags. `store seed --apps lefthook` includes the dependency's store
subtree and the runtimes needed by the selected apps; automatic seeding uses
the same closure. This selects expected seed content without changing the
bundle's existing coverage/failure policy.

Source-mode activation stays download-free. Its farm records dependency health
paths even for names excluded from the shim farm. If an upstream file is later
removed, invoking the root shim delegates repair to `datamitsu install lefthook`
and restores the dependency before execution. Neither `dependsOn` nor
`runtimeEnv` changes the proxy's install hash. A binding must target a direct
native binary dependency; a runtime-managed dependency needs its full command
and cannot be represented by `${APP_BIN:...}`.

## Updating Tool Versions

### Minimum release age (`--min-age`)

All `pull-*` commands refuse to select a release younger than the **minimum release age** (7 days / 10080 minutes by default). This soak time lets the ecosystem catch typosquats and compromised or broken publishes before you pin them. Every command accepts the shared `--min-age <minutes>` flag and prints the effective cutoff in its banner:

- `--min-age -1` (default) — use the global effective minimum release age
- `--min-age 0` — disable filtering and take the newest release
- `--min-age 43200` — custom cutoff (30 days)

```bash
# Default 7-day filter
datamitsu devtools pull-releases apps/binaryApps.json --update

# Require 30 days of soak time
datamitsu devtools pull-node apps/nodeApps.json --update --min-age 43200

# Bypass the filter (e.g. to adopt a same-day security release)
datamitsu devtools pull-releases apps/binaryApps.json --update --min-age 0
```

Set `DATAMITSU_MIN_RELEASE_AGE` (minutes) to change the default for every command, including the check `config lockfile` runs on a Go app's resolved modules. When no release is old enough, `pull-releases` keeps an existing app's current tag (with a warning) but records a failure for a brand-new app; `pull-node`/`pull-uv` skip the package with a warning; `pull-runtimes` hard-errors. See [Supply Chain Security → Minimum Release Age](../guides/supply-chain-security.md#minimum-release-age-version-selection) for the full behavior table and the registries it covers.

### Order and progress

Every `pull-*` command works through its entries in alphabetical order — apps, packages and runtimes alike, except that `pull-runtimes` takes pnpm first because the Node and Bun entries name it — and prints a counter with each (`=== Processing snyk [12/80] ===`, `[12/80] snyk  1.0.0  up-to-date`), so a long run says how far along it is. The file it writes has the keys of every object sorted, whatever the order they were declared in, so the diff of a pull shows what changed and nothing else. A file written by an older build is rewritten in that order the first time a pull saves it.

### Failures, retries and exit codes

A registry pull is how versions and hashes enter a configuration, so an app that is silently skipped is a version that silently stays behind. Every `pull-*` command therefore:

- **retries transient failures** — network errors, timeouts, 5xx responses and rate limits that name a short wait — making up to four attempts with backoff, printing each retry with the request, the attempt and the reason; under `--verify-extraction` the asset downloads retry the same way;
- **keeps going** past an app or package that fails, so one bad entry does not cost the run;
- **ends with a report** naming every failure, the stage it failed at and the error, with a hint when the fix is a setting (a GitHub rate limit → set `GITHUB_TOKEN`);
- **exits with status 1** when anything failed after the retries, so a script or a CI job sees it.

Permanent failures — a 404, a release whose assets carry no digest, a validation error, a rate limit that resets later than two minutes — are not retried, but they are in the report and in the exit code all the same.

Under `--verify-extraction`, only a fault in the asset itself — a hash mismatch, an archive that does not extract, a file that is not an executable — makes `pull-releases` fall back to the next-ranked asset for the platform. A download that fails is not the asset's fault, so the platform is not handed to whatever ranks below (an attestation file, or a variant that happens to verify): it fails the app, whose previous entry is kept, and the report names the platform and the asset (`verify linux/amd64/glibc`).

Every `pull-*` command that writes its file saves it after each entry that changed, before it starts the next, and replaces the file whole each time. After a failed or interrupted run every entry is therefore either the previous state of one that failed or was not reached, or the complete new state of one that succeeded, never a partial one; rerun the command to pick up the rest. A save that fails stops the run. `pull-runtimes` pulls pnpm before the runtimes that name it, and does not record a Node or Bun entry whose `pnpmRuntime` the file does not define: that runtime fails and keeps its previous entry.

Run large pulls with `GITHUB_TOKEN` set: the unauthenticated GitHub API allows 60 requests an hour, which a registry of a few dozen apps exhausts part-way.

### Inspecting the effective runtime config (`datamitsu config runtime`)

`datamitsu config runtime` prints the full effective runtime configuration as JSON — the env-resolved view of execution limits, the per-app install timeout, and the minimum release age. Use it to mechanically confirm what the tool will actually run with, including any `DATAMITSU_*` overrides, before kicking off a pull or an install:

```bash
# Inspect the full snapshot
datamitsu config runtime

# Confirm the effective minimum release age (minutes)
datamitsu config runtime | jq .minimumReleaseAgeMinutes                                   # -> 10080

# Confirm an env override took effect
DATAMITSU_MIN_RELEASE_AGE=20160 datamitsu config runtime | jq .minimumReleaseAgeMinutes   # -> 20160

# Verify the per-app install timeout (seconds; 0 = disabled)
DATAMITSU_INSTALL_TIMEOUT=1200 datamitsu config runtime | jq .installTimeoutSeconds       # -> 1200
```

The snapshot is introspection-only — it is **not** injected into the config JS VM. Wrapper config authors who need to branch on the effective minimum release age inside their `config.js` read the bounded, frozen `datamitsuConfigInputs` global instead:

```js
function getConfig(config) {
  // Only `minimumReleaseAgeMinutes` is exposed today, and the object is frozen.
  if (datamitsuConfigInputs.minimumReleaseAgeMinutes === 0) {
    // age filtering is disabled — branch accordingly
  }
  return config;
}
```

`datamitsuConfigInputs` is a deliberately minimal allowlist: it carries only the runtime values config evaluation is permitted to depend on (currently just `minimumReleaseAgeMinutes`). The full `config runtime` snapshot is **never** exposed to config JS — that boundary keeps hidden config inputs from leaking into fingerprinting and caching.

### Binary Apps: `devtools pull-releases`

Binary apps are downloaded from GitHub, GitLab, Gitea or Forgejo releases through named source profiles. Use `pull-releases` to fetch the latest release versions and published SHA-256 digests.

The registry uses `sources` aliases and per-app `source`, `repository` and `tag`.
There is no schema version or implicit GitHub fallback. See the
[release provider reference](/docs/reference/cli-commands#devtools-pull-releases)
for instance URLs, token references, integrity pins and migration from the old
`owner`/`repo` registry.

**Apply updates:**

```bash
datamitsu devtools pull-releases apps/binaryApps.json --update
```

With `--update`, the command fetches the latest release tags, detects binaries for all platform tuples (Darwin/Linux/Windows/FreeBSD/OpenBSD on amd64/arm64, Linux with glibc/musl), resolves their mandatory SHA-256 digests, fetches the repository description from the source API, and writes the results back to the JSON file.

To keep only specific platforms, add a top-level list to `binaryApps.json`:

```json
"platforms": ["darwin/arm64", "linux/amd64/musl"]
```

The list strictly matches supported identifiers and removes unselected existing
binary records before the pull. Those deletions remain saved if the pull fails.
Unavailable selected platforms are reported and omitted when another selected
platform is available. For releases that publish Linux only as musl, include
`linux/amd64/musl` to retain that record; a musl asset is never relabeled as glibc.
Changing the set or removing the field reruns detection even at the same tag.
See [the command reference](/docs/reference/cli-commands#devtools-pull-releases)
for supported values and validation rules.

**Verify binary extraction after update:**

```bash
datamitsu devtools pull-releases apps/binaryApps.json --update --verify-extraction
```

The `--verify-extraction` flag additionally downloads each binary (retrying a failed download like any other request), extracts it, and checks that the result is an executable: an ELF, Mach-O or PE file, or a script starting with `#!`. This catches changed archive structures, renamed binaries inside archives, and a `binaryPath` that picks a completion script or a man page instead of the binary.

`pull-releases` learns `binaryPath` from the entries already in the file. An asset published under the same name as before keeps the `binaryPath` recorded for it. Otherwise the closest entry lends its layout — the same OS, architecture and libc first, then the same OS and architecture, then the same OS — with the new asset's name substituted into the path component named after the old asset (`tombi-cli-1.5.0-x86_64-apple-darwin/tombi` becomes `tombi-cli-1.5.5-x86_64-apple-darwin/tombi`), or else only the version. A layout that names another architecture or libc than the asset is never borrowed. A `binaryPath` you corrected by hand therefore survives the next release instead of being guessed again.

An asset that names an operating system datamitsu does not run on — illumos, Solaris, NetBSD, DragonFly, Haiku, Android, AIX, Plan 9 — is never recorded for Linux, even when it carries an `x86_64` token and no other. On Windows, `win64` counts as amd64 and `win32` as 32-bit, and a bare `win` token or a `.exe` suffix is enough to name the OS.

:::note Releases with mixed asset types
Some tools publish VS Code extensions (`.vsix`), Linux packages (`.deb`, `.rpm`), NuGet packages (`.nupkg`), Python wheels (`.whl`), Windows installers (`.msi`), or macOS installer packages (`.pkg`) alongside binary archives in the same release. datamitsu automatically excludes these non-executable formats before scoring, so only actual binaries compete for selection. No configuration is needed — the filtering is automatic.
:::

### Node Apps (npm): `devtools pull-node`

Node apps are npm packages managed via pnpm. Use `pull-node` to check for updates on the npm registry.

**Preview available updates:**

```bash
datamitsu devtools pull-node apps/nodeApps.json --update --dry-run
```

The `--update --dry-run` combination fetches the latest versions and shows what would change without writing to the file.

**Apply updates:**

```bash
datamitsu devtools pull-node apps/nodeApps.json --update
```

This queries the npm registry for each configured package, compares versions, and updates the JSON file with new versions and descriptions.

**Regenerate lock files after updating:**

After updating node app versions, regenerate their lock files to ensure reproducible installs:

```bash
datamitsu config lockfile prettier
datamitsu config lockfile eslint
```

Each command outputs brotli-compressed lock file content (with a `br:` prefix) that you paste into the app's `lockFile` field in your configuration.

### UV Apps (Python): `devtools pull-uv`

UV apps are Python packages installed in isolated environments. Use `pull-uv` to check for updates on PyPI.

**Preview available updates:**

```bash
datamitsu devtools pull-uv apps/uvApps.json --update --dry-run
```

**Apply updates:**

```bash
datamitsu devtools pull-uv apps/uvApps.json --update
```

This queries PyPI for each configured package, compares versions, and updates the JSON file.

**Regenerate lock files after updating:**

```bash
datamitsu config lockfile yamllint
```

`pull-uv` ages only the package itself. Its dependencies are resolved here, under the 7-day window uv records in the lock: a regenerated lock carries that window, and an older lock without one keeps installing unchanged. See [Release Age of Transitive Dependencies](../guides/supply-chain-security.md#release-age-of-transitive-dependencies).

### Runtimes: `devtools pull-runtimes`

Runtimes (Bun, Node.js, UV/Python, JVM/Temurin, and Go) need periodic updates too. Use `pull-runtimes` to fetch the latest runtime versions.

**Update all runtimes:**

```bash
datamitsu devtools pull-runtimes runtimes/runtimes.json --update
```

The `--update` flag is required as a safety guard — the command refuses to run without it.

**Update a specific runtime only:**

```bash
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime bun
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime node
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime uv
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime jvm
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime pnpm
```

**Preview changes without writing:**

```bash
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --dry-run
```

The command fetches versions from upstream sources:

- **Bun**: latest eligible release and official archive SHA-256 digests from GitHub
- **Node.js**: latest LTS version from endoflife.date API
- **pnpm**: latest pnpm 12 release old enough for the minimum release age (judged by its npm publish date), with per-platform archive SHA-256 digests from the matching GitHub release
- **Python**: latest stable (non-EOL) version from endoflife.date API
- **Java (Temurin)**: latest major version from Adoptium API, or the previous one while the latest has no build old enough for the minimum release age

It then downloads runtime binaries for all platform tuples, computes SHA-256 hashes, and deduplicates musl entries that are identical to glibc.

#### Bumping the Bun runtime

```bash
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime bun
```

The updater selects the latest Bun GitHub release allowed by the configured minimum release age and records the official SHA-256 digest for each macOS, Linux glibc, Linux musl, and Windows Bun archive on amd64 and arm64. The Bun entry points at the pnpm runtime with `pnpmRuntime: "pnpm"`.

#### Bumping the pnpm runtime

```bash
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime pnpm
```

pnpm is a runtime of its own, shared by the Node and Bun runtimes through `pnpmRuntime`. The updater picks the newest pnpm 12 release whose npm publish date passes the configured minimum release age, then pins the native archive for each macOS, Linux glibc, Linux musl, and Windows platform on amd64 and arm64 with the SHA-256 digests published in the matching pnpm/pnpm GitHub release. A pnpm bump reinstalls Node and Bun apps on their next use without downloading Node or Bun again.

#### Bumping the Node.js runtime

The Node.js runtime is a direct, hash-pinned archive (like the JVM runtime), so bumping it means refreshing the pinned version and the per-platform hashes in `runtimes.json`:

```bash
datamitsu devtools pull-runtimes runtimes/runtimes.json --update --runtime node
```

This resolves the latest Node.js LTS, builds the archive URLs for every os/arch/libc combination, and records a SHA-256 hash for each:

- **glibc, macOS, and Windows** hashes are taken from nodejs.org's clearsigned `SHASUMS256.txt.asc` and GPG-verified against the embedded official Node.js release public keys. An invalid or untrusted signature aborts the pull, giving a strong supply-chain anchor.
- **musl** hashes come from unofficial-builds.nodejs.org's unsigned `SHASUMS256.txt` (Node publishes no signature for musl builds) and are pinned in git — the same trust model as the official `node:alpine` image.

After a Bun, Node.js, or pnpm version bump, regenerate the lock files for the affected Bun or Node apps so they resolve against the new runtime, then commit the refreshed `runtimes.json`:

```bash
datamitsu config lockfile eslint
datamitsu config lockfile prettier
```

#### Bumping the Go runtime

```bash
datamitsu devtools pull-runtimes runtimes.json --update --runtime go
```

The Go SDK archives and their per-file SHA-256 come from go.dev (`https://go.dev/dl/?mode=json`): HTTPS plus published SHA-256, no GPG — the same trust posture as the musl Node path. The pull preserves (or sets) `go.goVersion` in the runtime entry.

## Generating a Docker image: `devtools dockerfile`

If you publish a container image of your wrapper with every tool pre-installed, `devtools dockerfile` generates an optimized multi-stage Dockerfile from your config's tool list — so you never hand-write or hand-tune it.

```bash
datamitsu devtools dockerfile -o docker/Dockerfile
```

**What it generates.** A config-free shared base, then a `config-split` stage, then one build stage per binary app, per managed runtime, and per runtime-managed app (each inheriting its runtime stage). The final stage assembles the populated datamitsu store with `COPY --link`, one layer per app, and carries the full config for the entrypoint.

**Two layers of cache isolation.** Each app is its own `COPY --link` layer, so bumping a single app re-pulls only that layer instead of the whole image (pull-time, for your users). The generator also isolates the **build**: the base never carries the config, and the `config-split` stage slices the config into one minimal per-stage file (via [`devtools split-config`](../reference/cli-commands.md#devtools-split-config)) that each stage loads on its own. So editing one app — or regenerating/reformatting the whole config — re-runs only the cheap split plus the stages whose slice actually changed, instead of reinstalling every tool from scratch. Changing a runtime rebuilds that runtime and every app under it; changing the base datamitsu image rebuilds everything.

Each app slice defines its entire dependency closure and every referenced
runtime, including pnpm. The stage's normal `install <app>` installs that
closure, so verification can execute the app safely. Each app still has its own
stage, including conventionally private names, and the final image copies each
app's own store subtree with `COPY --link`. A dependency edit rebuilds dependent
slices as well as the dependency's stage. Build-only Go and pnpm runtimes remain
out of the final image; run-time interpreters and UV's Python tree remain in it.

If Linux/libc filtering would remove a dependency of an included app, generation
fails with the root and missing dependency named. Unsupported architectures
fail the stage's install with the binary name and target platform, including
with `--no-verify`; no successfully built image can omit that dependency.

**Base image and digest pinning.** The base image is `ghcr.io/datamitsu/datamitsu` at the version of the datamitsu binary you run the command with — _not_ your `package.json`. That tag is resolved to a SHA-256 digest and pinned as `FROM …@sha256:…` so builds are reproducible.

Pinning is best-effort and never fails the command. If the registry is unreachable, you pass `--offline`, or you build against a non-release (`dev`/unstable) datamitsu, the `FROM` line is left unpinned and a warning is written both into the generated file and to stderr:

```bash
datamitsu devtools dockerfile -o docker/Dockerfile --offline
```

:::note
The generated file is **fully overwritten** on every run — there are no managed regions. It is a generated artifact you own: hand-edit it freely, but re-running the command discards those edits. Commit the generated file and protect it with the drift check below.
:::

**Build-time verification (on by default).** Each app stage runs the app's version check right after installing it, so an app that doesn't actually run fails the Docker build instead of shipping a broken image. This is the safe default; pass `--no-verify` to turn it off (for example, to speed up emulated cross-arch builds):

```bash
datamitsu devtools dockerfile -o docker/Dockerfile --no-verify
```

**Alpine variant.** Pass `--alpine` to target the musl base image (`…:<version>-alpine`):

```bash
datamitsu devtools dockerfile -o docker/Dockerfile.alpine --alpine
```

**OCI labels.** Supply your image's labels with repeatable `--label` flags. Keep them in the generate invocation (e.g. a `Taskfile` task) so they survive regeneration:

```bash
datamitsu devtools dockerfile -o docker/Dockerfile \
  --label org.opencontainers.image.title=my-config \
  --label org.opencontainers.image.source=https://github.com/me/my-config
```

**Build args and environment variables.** Declare build-time `ARG`s with repeatable `--arg` flags and runtime `ENV` vars with `--env`. In the final stage all `ARG`s are emitted **before** all `ENV`s, so an `ENV` value can reference an `ARG`. An `--arg` may be a bare `NAME` (its default is supplied by `docker build --build-arg NAME=…`) or `NAME=default`; an `--env` value may contain `=` (only the first separates key from value). Like labels, keep them in the generate invocation so they survive regeneration:

```bash
datamitsu devtools dockerfile -o docker/Dockerfile \
  --arg BUILD_DATE \
  --arg TZ=UTC \
  --env LANG=C.UTF-8
```

This emits, in the final stage:

```dockerfile
ARG BUILD_DATE
ARG TZ="UTC"
ENV LANG="C.UTF-8"
```

**Build-time variables (`--build-arg`).** `--arg`/`--env` only affect the **final** image — they are runtime knobs and do nothing for the build itself. To influence the install stages (for example raise the install timeout for heavy tools), use `--build-arg`. Each one is declared as an `ARG` (overridable via `docker build --build-arg`) and promoted to an `ENV` in a dedicated `dm-build` stage that every install stage derives from, so `datamitsu install` sees it. The final image is built `FROM dm-base` (not `dm-build`), so build args **never leak into the shipped image**:

```bash
datamitsu devtools dockerfile -o docker/Dockerfile \
  --build-arg DATAMITSU_INSTALL_TIMEOUT=1200 \
  --build-arg HTTP_PROXY
```

emits:

```dockerfile
FROM dm-base AS dm-build
ARG DATAMITSU_INSTALL_TIMEOUT="1200"
ENV DATAMITSU_INSTALL_TIMEOUT=$DATAMITSU_INSTALL_TIMEOUT
ARG HTTP_PROXY
ENV HTTP_PROXY=$HTTP_PROXY

FROM dm-build AS rt-go          # install inherits the ENV
RUN datamitsu install --runtime go
```

A bare `--build-arg NAME` (no default) takes its value from `docker build --build-arg NAME=…`. With no `--build-arg` flags the `dm-build` stage is omitted and install stages derive straight from `dm-base`.

:::warning Secrets
Do not pass tokens or other secrets via `--build-arg`: an `ARG` value lingers in the intermediate build layers (visible in the build cache). For credentials use `RUN --mount=type=secret` instead.
:::

**libc filtering and `--force-include`.** The image targets one libc — **musl** when you pass `--alpine`, **glibc** otherwise. Binary apps are filtered to those that ship a binary for that libc on every architecture they declare; a glibc-only binary cannot execute on a musl image, so such apps are dropped from the generated Dockerfile rather than failing the build. Each generation prints the dropped apps:

```text
Warning: excluded 47 app(s) with no musl binary (add via --force-include if universal): actionlint, age, … swag, …
```

Runtime-managed apps (bun/node/uv/jvm/go) are never filtered — their runtime provides the libc.

Many dropped tools are actually **universal**: a statically-linked Go binary recorded as `glibc` (or a static-musl Rust binary recorded as `musl`) runs fine on the other libc, but the registry under-declares it. Triage the warning list and add the genuinely-universal ones back with `--force-include` (keep it in the generate invocation so it survives regeneration):

```bash
datamitsu devtools dockerfile -o docker/Dockerfile.alpine --alpine \
  --force-include jq,shfmt,golangci-lint,hadolint
```

A truly libc-specific tool (e.g. a dynamically-linked glibc binary like `swag`) should stay excluded — install it another way on that variant, or fix its registry entry if a musl build does exist.

**Pulling from a mirror.** To resolve the base-image digest from a registry other than `ghcr.io` (for example a pull-through cache), set `DATAMITSU_OCI_REGISTRY`:

```bash
DATAMITSU_OCI_REGISTRY=mirror.internal datamitsu devtools dockerfile -o docker/Dockerfile
```

### Keeping the generated Dockerfile fresh in CI

Because the output is fully generated, add a drift check that fails when the committed Dockerfile is stale. Run the generator with `--offline` so a re-pushed upstream tag (a moving digest) cannot cause false failures — the check then compares structure and version, not the live digest:

```yaml
- name: Check Dockerfiles are up to date
  run: |
    datamitsu devtools dockerfile -o docker/Dockerfile --offline
    datamitsu devtools dockerfile -o docker/Dockerfile.alpine --alpine --offline
    git diff --exit-code -- docker/Dockerfile docker/Dockerfile.alpine \
      || { echo "Dockerfiles are stale; run the generator and commit."; exit 1; }
```

In your publish workflow, generate with pinning enabled (drop `--offline`) so the pushed image's `FROM` is digest-pinned.

## Testing After Updates

### Verify cross-platform integrity

After updating any tool or runtime versions, run `verify-all` to check integrity across all platforms:

```bash
datamitsu devtools verify-all
```

This command:

1. Downloads and hash-verifies all binary apps for every configured platform
2. Downloads and hash-verifies all managed runtime binaries
3. Installs runtime-managed apps (Bun, Node, UV, JVM, Go) on the current platform
4. Runs version checks to confirm tools execute correctly

**Useful flags:**

```bash
# Skip version checks (faster, hash-only verification)
datamitsu devtools verify-all --no-version-check

# Increase download concurrency
datamitsu devtools verify-all --concurrency 8

# Skip entries that passed on the last run with unchanged config
datamitsu devtools verify-all --skip-passed

# Machine-readable output for CI pipelines
datamitsu devtools verify-all --json

# Skip remote config resolution
datamitsu devtools verify-all --no-remote
```

Results are cached incrementally in a state file. Using `--skip-passed` skips entries whose configuration fingerprint hasn't changed since the last successful verification, which speeds up repeated runs during development.

### Local smoke test

Always test locally before publishing:

```bash
# Re-download everything
datamitsu init

# Run the full check pipeline
datamitsu check

# Verify specific tools
datamitsu exec prettier -- --version
datamitsu exec eslint -- --version
```

### Bumping a tool whose output is parsed

A cached lint pass means the tool's
[`outputParser`](../guides/architecture/parsers.md#extraction-outcomes) read its output
and found nothing. A release that changes the output format can turn every finding into
"nothing" for a parser that no longer recognizes it, and the run then looks clean and is
cached as clean. Each parser the reference configuration wires therefore has a clean and
a finding-bearing recording of its real tool in the datamitsu repository
(`parsers/datamitsu-parsers/fixtures/<parser>/`), asserted by the parser's tests.

When a bump changes the version of such a tool, record both runs again with the new
version and run the parser tests before the bump ships:

```bash
# In the datamitsu repository: rerun the tool over a clean input and over one with
# findings, write stdout, stderr and the exit code into the fixture files, then run
# the tests from parsers/, where rustup picks up the pinned Rust release
(cd parsers && cargo test)
```

`parsers/datamitsu-parsers/fixtures/README.md` lists the arguments each recording uses.
A findings recording that parses to nothing fails the test: the parser needs a fix, in
a module release, before the configuration can rely on the new version.

## Automation

### GitHub Actions: periodic version checks

Set up automated version checking with a scheduled GitHub Actions workflow:

```yaml
name: Check for tool updates

on:
  schedule:
    - cron: "0 9 * * 1" # Every Monday at 9:00 UTC
  workflow_dispatch: # Allow manual triggers

jobs:
  check-updates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup datamitsu
        run: |
          # Install datamitsu (adjust for your setup)
          go build -o datamitsu .

      # Note: pull-releases does not support --dry-run.
      # Use pull-releases --update in the automated update PR workflow instead.

      - name: Check node app updates
        run: ./datamitsu devtools pull-node apps/nodeApps.json --update --dry-run

      - name: Check UV app updates
        run: ./datamitsu devtools pull-uv apps/uvApps.json --update --dry-run

      - name: Check runtime updates
        run: ./datamitsu devtools pull-runtimes runtimes/runtimes.json --update --dry-run
```

### GitHub Actions: automated update PR

For a more hands-off workflow, create a workflow that applies updates and opens a pull request:

```yaml
name: Update tool versions

on:
  schedule:
    - cron: "0 9 1 * *" # First day of each month
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup datamitsu
        run: go build -o datamitsu .

      - name: Update binary apps
        run: ./datamitsu devtools pull-releases apps/binaryApps.json --update

      - name: Update node apps
        run: ./datamitsu devtools pull-node apps/nodeApps.json --update

      - name: Update UV apps
        run: ./datamitsu devtools pull-uv apps/uvApps.json --update

      - name: Update runtimes
        run: ./datamitsu devtools pull-runtimes runtimes/runtimes.json --update

      - name: Verify all platforms
        run: ./datamitsu devtools verify-all

      - name: Create pull request
        uses: peter-evans/create-pull-request@v6
        with:
          title: "chore: update tool versions"
          body: "Automated tool version update. Review changes and verify locally before merging."
          branch: chore/update-tool-versions
          commit-message: "chore: update tool versions"
```

## Best Practices

### Semantic versioning

Follow semantic versioning for your wrapper package releases:

- **Patch** (1.0.x): tool version bumps with no configuration changes
- **Minor** (1.x.0): new tools added, new features in configuration
- **Major** (x.0.0): tools removed, breaking configuration changes, minimum version bumps

### Changelog

Keep a changelog documenting what changed in each release:

- Which tools were updated and to what version
- Any new tools added or removed
- Configuration changes that users need to be aware of
- Minimum datamitsu version changes (`getMinVersion()`)

### Update workflow

A typical update cycle looks like this:

1. Run `devtools pull-*` commands to detect and apply updates
2. Regenerate lock files for any updated Bun, Node, UV, or Go apps
3. Run `devtools verify-all` to check cross-platform integrity
4. Run `datamitsu init && datamitsu check` locally
5. Commit, push, and create a release

### Migration guides

When making breaking changes (removing tools, changing configuration structure), provide a migration guide in your release notes explaining:

- What changed and why
- Step-by-step instructions to update
- The new minimum datamitsu version if changed

### Configuring pnpm Settings for Node Apps

Node apps run `pnpm install` in an isolated directory managed by datamitsu. datamitsu always writes a `pnpm-workspace.yaml` containing secure supply chain defaults before `pnpm install` runs. You can override or extend those defaults by supplying your own `pnpm-workspace.yaml` via `App.files` — datamitsu shallow-merges your keys on top of the baseline.

See the [Supply Chain Security](../guides/supply-chain-security.md) guide for the full list of baseline settings and what each one does.

:::caution Files are written only on initial install
`App.files` (including `pnpm-workspace.yaml`) are read on every install, but the install directory is only rebuilt when the app's config hash changes. If you change `files` after an app is already cached, run `datamitsu store clear` (or delete the app's subdirectory under `.apps/node/`) to force a reinstall.
:::

#### Apps without build scripts (zero config)

No `App.files["pnpm-workspace.yaml"]` is required. datamitsu writes the secure defaults automatically:

```js
const eslint = {
  node: {
    packageName: "eslint",
    binPath: "node_modules/.bin/eslint",
    version: "9.17.0",
    lockFile: "br:...",
  },
};
```

#### Apps that need build scripts (puppeteer, sharp, esbuild, etc.)

pnpm (11 and later) blocks lifecycle scripts by default. If install fails with `ERR_PNPM_IGNORED_BUILDS`, allowlist the package via `allowBuilds`:

```js
const mmdc = {
  files: {
    "pnpm-workspace.yaml": YAML.stringify({
      allowBuilds: { puppeteer: true },
    }),
  },
  node: {
    packageName: "@mermaid-js/mermaid-cli",
    binPath: "node_modules/.bin/mmdc",
    version: "11.15.0",
    lockFile: "br:...",
  },
};
```

The merged result written to the app environment keeps all secure defaults (`strictDepBuilds: true`, `minimumReleaseAge: 10080`, etc.) **plus** the user's `allowBuilds` entry. Only the keys you explicitly set are overridden.

After adding `allowBuilds`, regenerate the lock file so pnpm can record the approved builds:

```bash
pnpm exec datamitsu config lockfile mmdc
```

#### Overriding a security key

User intent wins on every key. Setting `strictDepBuilds: false` disables strict build approval — use only when you understand the risk:

```js
files: {
  "pnpm-workspace.yaml": YAML.stringify({
    strictDepBuilds: false,
  }),
}
```

:::note Bun, Node, and UV apps
For Bun and Node apps, any `package.json` included in `App.files` will be overwritten by the datamitsu core when it writes the managed `package.json`. Both app kinds can use `pnpm-workspace.yaml` for customization — the core merges that file with secure defaults rather than overwriting it.

For UV apps, project-level settings are configured via `pyproject.toml`. However, any `pyproject.toml` included in `App.files` will be overwritten by the datamitsu core when it writes the managed `pyproject.toml`. This customization path is not available for UV apps.
:::

---

## Manage Cache


datamitsu separates ephemeral **cache** state from the global **store** of
downloaded, verified artifacts. Both are children of the base selected by
`DATAMITSU_CACHE_DIR`, `XDG_CACHE_HOME`, or the platform fallback.

## Cache vs Store

| Area      | What it holds                                                                   | Scope                 | Command prefix    |
| --------- | ------------------------------------------------------------------------------- | --------------------- | ----------------- |
| **Cache** | File results, unit verdicts, tool caches, source farms, evaluated config chains | Per repo/config chain | `datamitsu cache` |
| **Store** | Binaries, runtimes, apps, bundles, parsers, remotes, package-manager data       | Global to the user    | `datamitsu store` |

## Cache Structure

Each repository gets an isolated namespace. The same repository directory holds
its source-mode farm, execution state, and tool-owned caches:

```
~/.cache/datamitsu/cache/projects/{hash}/
├── bin/                    # source-mode command farm
├── manifest.json           # farm contents and staleness fingerprint
├── lock                    # advisory farm bake lock
├── toolstate.msgpack       # file entries and unit/repo verdicts
└── cache/                  # directories exposed as {toolCache}
    ├── packages/frontend/
    │   ├── tsc/tsbuildinfo
    │   └── eslint/.eslintcache
    └── services/api/
        └── ruff/.ruff_cache/
```

The `{hash}` is an XXH3-128 hash of the git root path. Within it, tool caches are organized by project path and tool name.

[Machine-level toolchains](machine-level-toolchain.md) have no git root, so they live in a sibling namespace keyed by the config chain instead:

```
~/.cache/datamitsu/cache/configs/{hash}/
├── bin/            # the farm PATH points at
├── manifest.json   # what it contains, and what makes it stale
└── lock            # the advisory bake lock
```

Here `{hash}` is an XXH3-128 hash of the resolved config chain. Project config
evaluation results live separately under
`cache/config-eval/projects/{identity}/{key}.msgpack`; explicit machine config
chains use `cache/config-eval/configs/`.

`datamitsu cache clear` only removes repository namespaces and the relevant
evaluated-config entries. It does not remove `cache/configs/` machine-level
farms. Rebuild one with
`datamitsu source refresh --config <path> --force`.

Tools reference their cache directory using the `{toolCache}` placeholder in their operation arguments or environment variables.

## Store Structure

The global store holds all downloaded artifacts:

```
~/.cache/datamitsu/store/
├── .bin/                    # Binary apps
│   └── lefthook/{hash}/
├── .runtimes/               # Runtime binaries
│   ├── node/{configHash}/
│   ├── pnpm/11.20.0/{hash}/
│   ├── jvm/{hash}/
│   └── go/{hash}/
├── .apps/                   # Runtime-managed app environments
│   ├── uv/yamllint/{hash}/
│   ├── node/eslint/{hash}/
│   ├── jvm/openapi-generator-cli/{hash}/
│   └── go/govulncheck/{hash}/
├── .bundles/                # Managed static content
├── .parsers/                # Downloaded WASM output parsers
├── .remote-configs/         # Cached remote configs
├── .pnpm-store/             # Shared pnpm content-addressable store
└── .uv/python/              # Python installations managed by uv
```

## Viewing Cache Paths

```bash
# Global cache directory
datamitsu cache path

# Current project's cache directory
datamitsu cache path project

# Global store directory
datamitsu store path
```

## Clearing the Cache

Clear per-project tool caches when lint/fix results seem stale:

```bash
# Clear current project's cache
datamitsu cache clear

# Preview what would be deleted
datamitsu cache clear --dry-run

# Clear caches for all projects
datamitsu cache clear --all
```

For the current repository this removes the complete `projects/{hash}` namespace
(source farm, lint/fix state, verdicts, and per-tool caches) plus that
repository's evaluated config chains. `--all` removes all `projects/` namespaces
and the entire `config-eval/` tree. Neither form removes machine-level farms in
`cache/configs/`, downloaded artifacts, or execution traces.

## Clearing the Store

Clear the global store to remove all downloaded binaries and runtimes:

```bash
datamitsu store clear
```

:::warning
This removes the whole global store: binaries, runtimes, app environments,
bundles, parsers, package-manager stores, managed Python installations, and
remote configs. You will need to run `datamitsu init` again to download required
content.
:::

## When to Clear Cache

**Clear the project cache** (`datamitsu cache clear`) when:

- Lint or fix results seem incorrect or stale
- You've changed tool configurations and want a fresh run
- You're debugging tool behavior

**Clear the store** (`datamitsu store clear`) when:

- You want to reclaim disk space
- A binary or runtime download seems corrupted
- You've changed binary URLs or hashes and want a clean state

**You usually don't need to clear anything** because:

- Changing app versions or hashes in your config automatically creates new cache entries
- The old entries stay around but aren't used

## Cache Invalidation

datamitsu automatically invalidates caches when configuration changes:

- **Binary apps**: The store key includes URL, hash, format, and resolved OS/architecture/libc target
- **Runtime apps**: The store key includes the runtime and app configuration, lock content, managed files/archives, and target dimensions
- **Execution state**: The project key includes the datamitsu version, full effective config, and sorted `--tools` selection; file contents and unit guards decide individual hits
- **Remote configs**: The store filename is derived from the URL, but cached bytes are accepted only when their mandatory SHA-256 matches

No manual clearing is needed for version upgrades: update the config and the next
run selects the new content-addressed entry. Superseded store entries are not
removed automatically; `datamitsu store clear` is currently the available
cleanup command.

---

## Use in Alpine Linux


Alpine Linux uses musl libc instead of the more common glibc. Datamitsu automatically detects musl and selects the correct binary variant when available.

## How It Works

### Automatic Libc Detection

When datamitsu starts, it detects the host libc using a multi-stage process:

1. **ldd --version** — parses output for "musl libc" or "GNU libc"
2. **ELF interpreter** — reads the PT_INTERP header from the current binary for `ld-musl` or `ld-linux`
3. **Loader paths** — checks for musl/glibc loader files on disk

The first successful detection wins. If all stages fail, libc is reported as `unknown`.

On non-Linux systems (macOS, Windows, FreeBSD), libc detection is skipped and always returns `unknown`.

The detected libc is available in JavaScript configs via `facts().libc`:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  const libc = facts().libc; // "glibc", "musl", or "unknown"
  // ...
}
globalThis.getConfig = getConfig;
```

### Target-Based Binary Resolution

Datamitsu uses a three-dimensional target model for binary selection: **OS**, **Arch**, and **Libc**.

Each target is represented as a tuple like `linux/amd64/musl` or `darwin/arm64/unknown`.

When selecting a binary for a tool, the resolver scores all available candidates:

| Signal        | Weight | Requirement           |
| ------------- | ------ | --------------------- |
| OS match      | +1000  | Required (0 if wrong) |
| Arch match    | +100   | Required (0 if wrong) |
| Libc exact    | +10    | Preferred             |
| Libc unknown  | +5     | Neutral               |
| Libc mismatch | +1     | May work via compat   |

The highest-scoring candidate is selected. Ties are broken alphabetically for determinism.

### Fallback Behavior

When a musl-specific binary is not available but a glibc variant exists, datamitsu falls back to the glibc binary and emits a warning:

```
WARN: typst: musl binary not found, falling back to glibc variant
```

This fallback may or may not work depending on the specific binary. Statically linked glibc binaries often work on musl, but dynamically linked ones typically fail with errors like `fcntl64: symbol not found`.

To avoid fallback issues, prefer tools that provide musl-specific builds or statically linked binaries.

### Nested Storage Format

Binary definitions use a three-level nested structure: `os → arch → libc → BinaryInfo`.

```javascript
binaries: {
  linux: {
    amd64: {
      glibc: {
        url: "https://example.com/tool_linux_amd64.tar.gz",
        hash: "sha256:abc123...",
        contentType: "tar.gz",
      },
      musl: {
        url: "https://example.com/tool_linux_amd64_musl.tar.gz",
        hash: "sha256:def456...",
        contentType: "tar.gz",
      },
    },
  },
  darwin: {
    arm64: {
      unknown: {
        url: "https://example.com/tool_darwin_arm64.tar.gz",
        hash: "sha256:789abc...",
        contentType: "tar.gz",
      },
    },
  },
}
```

Key rules:

- The libc level is always present, even for non-Linux platforms
- Non-Linux platforms use `unknown` as the libc key
- Linux platforms typically have `glibc` and optionally `musl` variants
- All config sources (JSON and inline TypeScript) use the three-level format directly

### Store Isolation

Store paths include the resolved target, so glibc and musl binaries occupy
separate entries. A tool resolved as `linux/amd64/musl` gets a different store
path than the same tool resolved as `linux/amd64/glibc`, even on the same
machine.

This prevents conflicts when switching between container environments or
testing with different libc variants.

## Managed Runtimes (Bun, Node, UV, JVM)

datamitsu applies two distinct musl-specific mechanisms to managed runtimes:

- **Bun** — the registry pins Bun's official musl archives for amd64 and arm64, selected directly on a musl host.
- **The Node.js archive that datamitsu downloads** — the registry pins musl-linked Node.js archives directly, selected automatically on a musl host (see [Node.js (musl): static archive entries](#nodejs-musl-static-archive-entries)).
- **A runtime's own binary** (`node`, `uv`, `java`) — when the managed config has no musl variant for that executable, datamitsu falls back to the system binary on PATH (see [Automatic Fallback](#automatic-fallback)).

### Node.js (musl): static archive entries

datamitsu acquires Node.js as a direct, hash-pinned archive — it downloads the archive named in the registry, verifies its SHA-256 hash, and extracts it itself (exactly like the JVM runtime downloads a JDK). There is no version-manager binary to shell out to, no `node install` step, and no dynamic mirror logic.

The registry (`runtimes.json`) carries explicit musl entries for Node.js. On Linux they are the `node-v<ver>-linux-{x64,arm64}-musl.tar.xz` archives published by [unofficial-builds.nodejs.org](https://unofficial-builds.nodejs.org/download/release); glibc, macOS, and Windows entries come from `nodejs.org/dist`. Every entry — musl included — is pinned with a SHA-256 hash that datamitsu verifies before extraction.

On a musl host datamitsu selects the `musl` libc entry automatically via libc detection. There is **nothing to configure and no environment variables to set** — musl support works out of the box in managed mode.

**Supported musl architectures:** `amd64` (`x64`) and `arm64` — the only architectures unofficial-builds publishes. Other architectures (arm/armv7l, 386, ppc64le, …) have no musl entry; on those datamitsu falls back to a system `node` on PATH if one is present.

**Integrity does not depend on the mirror.** The hashes are pinned in git and refreshed by maintainers via `devtools pull-runtimes --runtime node`, so an archive is rejected unless it matches the recorded SHA-256 — the mirror being trustworthy at download time is not required.

#### libstdc++ is required on Alpine

musl Node.js from the unofficial mirror is **dynamically linked** against `libstdc++` (and `libgcc`), which the base `alpine` image does not include. Without it `node` fails to start. Install it:

```sh
apk add --no-cache libstdc++
```

`libgcc` is pulled in transitively, so no separate entry is needed. datamitsu's own `*-alpine` Docker image already bundles `libstdc++`, so wrappers building `FROM ghcr.io/datamitsu/datamitsu:<version>-alpine` inherit it with no Dockerfile change.

#### No configuration needed for musl

Musl support requires no setup: the registry already pins the musl archives, and datamitsu selects them automatically on a musl host. There are no mirror or arch environment variables to set.

### Automatic Fallback

datamitsu automatically handles this. When running on a musl system with managed runtimes that only have glibc binaries, datamitsu checks if the corresponding system binary is available on PATH. If found, it automatically switches to system mode instead of downloading an incompatible glibc binary.

The system binaries checked for each runtime:

| Runtime | System binary looked up | Alpine package                          |
| ------- | ----------------------- | --------------------------------------- |
| Node    | `node`                  | Managed musl archive — no apk needed    |
| UV      | `uv`                    | Not in default repos (install manually) |
| JVM     | `java`                  | `openjdk17`                             |

:::note
Node runs in managed mode on Alpine via the static musl archive (the registry pins musl-linked Node.js), so no system fallback or apk package is needed. UV is not available in Alpine's default package repositories — for UV on Alpine, use the [manual system mode override](#manual-system-mode-override) to configure system mode explicitly, or install the `uv` binary from its upstream release.
:::

When a system binary is found, you will see a log message like:

```
INFO: automatic fallback to system mode  runtime=jvm  reason="musl binary unavailable"  system_command=/usr/bin/java
```

If the system binary is not found, datamitsu falls through to the existing glibc fallback behavior (which may fail at runtime with errors like `fcntl64: symbol not found`).

### Manual System Mode Override

If you prefer explicit control, you can still configure runtimes in system mode manually:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    runtimes: {
      ...config.runtimes,
      node: {
        ...config.runtimes.node,
        mode: "system",
      },
      uv: {
        ...config.runtimes.uv,
        mode: "system",
      },
      jvm: {
        ...config.runtimes.jvm,
        mode: "system",
      },
    },
  };
}
globalThis.getConfig = getConfig;
```

Manual system mode configuration takes precedence over automatic fallback since the runtime is already in system mode.

## Dockerfile Example

A typical Alpine-based CI Dockerfile using manual system mode for UV:

```dockerfile
FROM alpine:3.20

RUN apk add --no-cache git go nodejs npm python3 openjdk17

# Build datamitsu
COPY . /workspace
WORKDIR /workspace
RUN go build -o /usr/local/bin/datamitsu

# Initialize - binary apps auto-detect musl, Node uses its managed musl archive,
# JVM auto-fallbacks to system mode
# UV requires manual system mode config (see manual override section above)
RUN datamitsu init
```

Binary apps automatically detect musl and select the appropriate variant. Node runs in managed mode via its static musl archive. For JVM, datamitsu auto-detects the system `java` binary. For UV, configure system mode in your wrapper config (see [manual system mode override](#manual-system-mode-override) above).

:::tip
If you maintain a wrapper package, you can auto-generate an optimized Alpine Dockerfile (digest-pinned base, one cacheable layer per tool) instead of hand-writing the example above:

```bash
datamitsu devtools dockerfile -o docker/Dockerfile.alpine --alpine
```

See [Generating a Docker image](/docs/how-to/maintain-wrapper#generating-a-docker-image-devtools-dockerfile).
:::

## Checking Detection Results

Use the `facts().libc` value in your config to verify detection:

```javascript
// In datamitsu.config.ts
console.log("Detected libc:", facts().libc);
```

The `devtools apps list` command shows which binary variant was resolved for each app on the current system.

## Troubleshooting

### `fcntl64: symbol not found` or similar errors

This means a glibc binary is running on a musl system. For binary apps, check if a musl variant is available for the tool and add it to the config. For managed runtimes, Bun and Node use their pinned musl archives automatically, and the JVM runtime auto-falls back to system `java` if installed (`apk add openjdk17`). For UV, configure system mode manually in your wrapper config since the `uv` binary is not available in Alpine's default repositories. If no musl variant or system binary exists, the tool cannot run on Alpine without a glibc compatibility layer.

### Detection returns `unknown`

If libc detection returns `unknown`, datamitsu cannot determine the libc and will use neutral scoring. This can happen in minimal containers without `ldd` or with statically linked init binaries. The resolver will still select the best available candidate but cannot prefer musl-specific builds.

---

## Use in GitHub Actions


The official [`datamitsu/setup-datamitsu`](https://github.com/datamitsu/setup-datamitsu)
action installs the datamitsu CLI, provisions the managed tools your config
declares, and runs datamitsu — in a single step. It carries no configuration of
its own: it reads the datamitsu config already in your repository.

## Quick Start

```yaml
name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: datamitsu/setup-datamitsu@v0.1.13
```

Those two steps install datamitsu `0.1.13` (replace with the
[latest release](https://github.com/datamitsu/datamitsu/releases/latest)) and
run `datamitsu init` to provision the tools your config declares
(golangci-lint, lefthook, …). By default the action then runs `datamitsu lint`;
override the command with the `args` input (or set `args: ""` to install and
initialize only).

## How It Works

```mermaid
flowchart LR
  A[actions/checkout] --> B[setup-datamitsu]
  B --> C[Download release asset]
  C --> D[Verify SHA-256]
  D --> E[Cache + add to PATH]
  E --> F[datamitsu init]
  F --> G["datamitsu $args (default: lint)"]
```

The release binary is downloaded from datamitsu's GitHub Releases, its SHA-256 is
verified against the hash baked into the action's tag, and the verified binary is
stored in the runner tool cache (reused on later runs) and added to `PATH`.

The `datamitsu init` step runs unless `init: "false"`. The final step runs
`datamitsu $args` — `lint` by default — and is skipped entirely when `args` is
empty, leaving just the CLI on `PATH`.

## Inputs

| Input  | Default | Description                                                                                 |
| ------ | ------- | ------------------------------------------------------------------------------------------- |
| `args` | `lint`  | Arguments passed to `datamitsu` after setup. An empty string installs and initializes only. |
| `init` | `true`  | Run `datamitsu init` after install to provision managed tools.                              |

## Outputs

| Output    | Description                               |
| --------- | ----------------------------------------- |
| `version` | The datamitsu version that was installed. |

## Examples

### Run a different command

```yaml
- uses: actions/checkout@v4
- uses: datamitsu/setup-datamitsu@v0.1.13
  with:
    args: "exec golangci-lint run ./..."
```

### Install only, run datamitsu yourself

```yaml
- uses: actions/checkout@v4
- uses: datamitsu/setup-datamitsu@v0.1.13
  with:
    args: ""
- run: datamitsu check
```

### Set up the CLI without provisioning tools

```yaml
- uses: datamitsu/setup-datamitsu@v0.1.13
  with:
    args: ""
    init: "false"
```

## Versioning and Integrity

Each action tag pins **one** datamitsu version: `@v0.1.13` installs datamitsu
`0.1.13`. The SHA-256 hashes of every release binary are baked into that tag and
verified on download — a missing or mismatched hash fails the run.

:::tip Pin a full version, not a moving tag
Because each tag carries its own baked hashes, pin a full version (`@v0.1.13`) or
a commit SHA — **not** a moving major tag (`@v0`). A moving tag would silently
swap the verified binary and skip update notifications.
:::

Keep the action current with [Dependabot](https://docs.github.com/code-security/dependabot):

```yaml
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
```

Dependabot opens a pull request whenever a new datamitsu version is released, so
upgrading is a one-line change.

:::note Version floor still applies
The datamitsu binary independently enforces the minimum version your config
requires (`getMinVersion()`). If you pin an action version older than your config
demands, datamitsu fails fast with a clear error — so the action and your config
stay consistent.
:::

## See Also

- [Installation](/docs/getting-started/installation) — install datamitsu locally
- [Maintain a wrapper](/docs/how-to/maintain-wrapper) — devtools workflows for wrapper maintainers
- [Use in Alpine Linux](/docs/how-to/use-in-alpine) — musl/libc handling in containers

---

## Use Remote Configs


Remote configs let you share datamitsu configuration across multiple repositories. A team or organization can maintain a central configuration that individual projects inherit and extend.

## Creating a Remote Config

A remote config is a standard datamitsu config file hosted at an HTTPS URL. It exports `getMinVersion()` and `getConfig()` like any local config:

```javascript
// https://config.myorg.com/datamitsu/base.js
function getConfig(config) {
  return {
    ...config,
    apps: {
      ...config.apps,
      // organization-standard tools
    },
    tools: {
      ...config.tools,
      // organization-standard tool definitions
    },
    ignoreRules: [...config.ignoreRules, "vendor/**/*: *"],
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";
```

Host this file on any HTTPS server accessible to your team.

## Using a Remote Config

Reference remote configs by exporting a `getRemoteConfigs()` function from your local config:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

// datamitsu.config.js
function getRemoteConfigs() {
  return [
    {
      url: "https://config.myorg.com/datamitsu/base.js",
      hash: "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;

function getConfig(config) {
  // config already includes remote config changes
  return {
    ...config,
    // project-specific overrides
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";
```

## Hash Verification

Every remote config requires a SHA-256 hash. This is a strict security
requirement: datamitsu refuses to load a remote config without a valid hash.
Write it canonically — `sha256:` followed by 64 lowercase hex characters. A bare
or uppercase value is accepted here and normalized to canonical, because this
pin is routinely copied from a release page or a checksum file; every other
hash pin in `datamitsu.config` accepts the canonical form only.

The publisher should hash the local file **before** uploading it and distribute
that value through a reviewed release or change:

```bash
sha256sum base.js
```

Copy the published value into the `hash` field. Do not download unknown content
merely to discover the value that will later be used to trust the same content.
If you audit the hosted bytes manually, start with the expected hash and verify
the download immediately:

```bash
EXPECTED_SHA256="a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
curl --fail --location --output /tmp/datamitsu-base.js \
  "https://config.myorg.com/datamitsu/base.js"
printf '%s  %s\n' "$EXPECTED_SHA256" /tmp/datamitsu-base.js | sha256sum --check -
```

When the remote config changes, update its reviewed hash in every consuming
project.

## Config Inheritance Chain

Remote configs are resolved depth-first before the referencing config's `getConfig()` runs. Remote configs can themselves reference other remote configs, creating an inheritance chain:

```
Organization base config (remote)
  ↓ getRemoteConfigs()
Team-specific config (remote)
  ↓ getRemoteConfigs()
Project config (local datamitsu.config.js)
```

Each layer receives the accumulated configuration from all previous layers and can extend or override it.

Circular dependencies are detected and produce an error.

## Wrapper Package Pattern

For npm-based monorepos, you can distribute configuration as an npm package:

```javascript
// @myorg/datamitsu-config/index.js
function getRemoteConfigs() {
  return [
    {
      url: "https://config.myorg.com/datamitsu/base.js",
      hash: "sha256:abc123...",
    },
  ];
}
globalThis.getRemoteConfigs = getRemoteConfigs;

function getConfig(config) {
  return {
    ...config,
    // organization-specific overrides on top of the remote base
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";
```

Projects use it via `--before-config`:

```bash
datamitsu check --before-config ./node_modules/@myorg/datamitsu-config/index.js
```

This pattern separates the shared configuration (the npm package) from the remote base config, allowing the remote base to be updated independently.

## Caching

Remote configs are cached locally to avoid network requests on every run:

- Cache location: `{store}/.remote-configs/`
- Cache validity is determined by hash match — if the cached content matches the expected SHA-256 hash, it is used without a network request
- When the hash in your config changes (pointing to a new version), datamitsu fetches the updated content

## Security

Remote config loading includes several security measures:

- SHA-256 hash verification is mandatory -- missing or mismatched hashes cause an error
- HTTPS-to-HTTP redirects are rejected
- Response size is limited to 10 MiB
- Requests have a 30-second timeout

## Skipping Remote Configs

For offline development or testing, skip remote config resolution:

```bash
# Skip remote configs during verify-all
datamitsu devtools verify-all --no-remote
```

## Updating Remote Configs

When a remote config is updated, each consuming project needs to update its hash pin:

1. Compute the new SHA-256 from the local release file
2. Publish that exact file and its hash
3. Update the `hash` field in each project's `getRemoteConfigs()` return value
4. Commit the hash update

This explicit update step is intentional -- it ensures that config changes are reviewed and deployed deliberately, not automatically.

---

## Introduction

# datamitsu

**Your toolchain deserves a home.**

datamitsu is a platform for building reproducible, security-first development tool distributions. It manages binaries, runtimes, and configuration files so teams can standardize their tooling across all projects with a single package.

For a comprehensive overview of why datamitsu exists and what makes it unique, see [About datamitsu](./about.md).

:::caution[Alpha Software]
datamitsu is in alpha. The configuration API is not yet stabilized and may change between versions.
:::

## Key Features

- **Security-first binary management** — SHA-256 hash verification for every binary
- **Programmable JavaScript configuration** — Full programmatic control via the goja runtime
- **Config chaining and inheritance** — Layer configs from base → company → team → project
- **Multi-runtime support** — Bun, Python (UV), Node.js (pnpm), JVM, Go, and native binaries
- **Monorepo-aware** — Per-project isolation for caches and tool execution
- **Docker-optimized** — Pre-cache all tools in a Docker layer for fast CI builds

## Quick Example

Create a `datamitsu.config.ts` at your git root:

```typescript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(prev) {
  return {
    ...prev,
    apps: {
      ...prev.apps,
      "golangci-lint": {
        binary: {
          binaries: {
            linux: {
              amd64: {
                glibc: {
                  url: "https://github.com/golangci/golangci-lint/releases/download/v2.1.0/golangci-lint-2.1.0-linux-amd64.tar.gz",
                  hash: "sha256:<digest>",
                  contentType: "tar.gz",
                  binaryPath: "golangci-lint-2.1.0-linux-amd64/golangci-lint",
                },
              },
            },
          },
        },
      },
    },
  };
}

globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "0.0.1";
```

Then initialize and run:

```bash
# Download all configured tools
datamitsu init

# Run lint checks
datamitsu check
```

## How It Works

datamitsu uses a [two-level architecture](./about.md#the-two-level-architecture): the core binary provides secure tool delivery and a config engine, while wrapper packages (npm/gem/pypi) provide concrete tool versions and opinionated defaults. Teams install one package and get everything configured.

## Next Steps

- [Installation](./getting-started/installation/index.md) — Install datamitsu on your system
- [Quick Start](./getting-started/quick-start.md) — Get up and running in minutes
- [Core Concepts](./getting-started/core-concepts.md) — Understand how datamitsu works

---

:::tip[Want to Learn More?]

- **[About datamitsu](./about.md)** — Understand why datamitsu exists and what makes it unique
- **[Comparison Guide](./reference/comparison.md)** — See how datamitsu compares to mise, moon, Nx, and other tools
- **[Using Wrappers](./guides/using-wrappers.md)** — Learn how to consume config distribution packages
- **[Contributing](./contributing/index.md)** — Help improve datamitsu or build your own wrapper package

:::

---

## CLI Commands


## Global Flags

These flags apply to all commands:

| Flag                      | Description                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `--config <file>`         | Additional configuration file(s) to load and merge (repeatable)                                        |
| `--before-config <file>`  | Configuration file(s) to load before auto-discovery (repeatable; for wrappers/libraries)               |
| `--no-auto-config`        | Disable auto-discovery of datamitsu.config.\{js,mjs,ts\} at git root                                   |
| `--binary-command <name>` | Override the binary command name. Also settable via `DATAMITSU_BINARY_COMMAND`                         |
| `--log-format <format>`   | Status output format: `console` or newline-delimited `jsonl`. Also settable via `DATAMITSU_LOG_FORMAT` |
| `--no-oci`                | Disable OCI bundle store seeding. Also settable via `DATAMITSU_NO_OCI`                                 |
| `--no-parse`              | Show raw tool output instead of parsed findings; parsing still runs. Also via `DATAMITSU_NO_PARSE`     |
| `-v`, `--verbose`         | Enable debug-level logging for this invocation                                                         |

With `--log-format=jsonl`, status and progress go to stderr as typed JSON events,
one per line, and log lines arrive the same way: each is a
[`log` event](#lsp-events) whose `level` is `debug`, `info`, `warn` or `error`,
with the message and its fields in `msg`. Which levels appear follows
`DATAMITSU_LOG_LEVEL` (`warn` by default) and `--verbose` (`debug`), exactly as
in console mode.

## Exit codes

| Code         | Meaning                                                                                                                                                                                                                                                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`          | Success                                                                                                                                                                                                                                                                                                                                                            |
| `1`          | A tool failed — it exited non-zero, or its parsed output held a finding at or above its operation's `failOn` (see [Failing on findings](#failing-on-findings---fail-on)) — or any error without a code of its own                                                                                                                                                  |
| `2`          | Usage: an unknown flag, a flag or `DATAMITSU_*` value the command does not accept (`--widen-to=Repo`, `DATAMITSU_FAIL_FAST=yes`), a missing required flag, flags that cannot be combined, the wrong number of arguments, or a combination refused before anything runs (`--require-coverage` with `--tools`, a report of a narrowed run without `--allow-partial`) |
| `3`          | `llms`: an unknown or ambiguous page                                                                                                                                                                                                                                                                                                                               |
| `4`          | The run did not cover what it was asked to: `--require-coverage` (see [Narrowed runs](#narrowed-runs)) or `--fail-on-skip` (see [Skipped tools](#skipped-tools)); when both fail, both messages are printed                                                                                                                                                        |
| `5`          | A report asked for with `--report` or `DATAMITSU_REPORT` was not written (see [Reports](#reports))                                                                                                                                                                                                                                                                 |
| `130`, `143` | `fix`, `lint` or `check` interrupted by `SIGINT` or `SIGTERM` (see [Keep-going runs](#keep-going-runs))                                                                                                                                                                                                                                                            |

When several apply, a tool failure (`1`) wins over an incomplete run (`4`),
which wins over a report that was not written (`5`); the messages of the ones
that lost are still printed. A usage error is found
before anything runs and combines with nothing. A script that tells "you called
it wrong" from "the code is bad" checks for `2` and `1` apart. An unknown command
(`datamitsu bogus`) and a few checks that other commands make on their own
arguments still exit `1`.

## exec

Execute a managed binary with all environment variables passed through.

```bash
datamitsu exec <appName> [args...]
```

When called without arguments, lists all available tools grouped by type (binary, uv, node, jvm, go, shell).

`exec` hands the app the environment it was started with, unchanged: in a GitHub Actions job a tool run through `exec` sees `GITHUB_ACTIONS` and prints its own annotations. `fix`, `lint` and `check` do not — they strip the variables that switch a tool's output format and set `NO_COLOR=1` (see [Tool Environment](./tool-environment.md)).

An app is installed on demand the first time you `exec` it. If that app declares `links`, its `.datamitsu/` symlinks are created at the same time — this is how a `lazy: true` link-app that `init` deferred gets its managed-config links on first use.

**Examples:**

```bash
# List all available tools
datamitsu exec

# Run golangci-lint
datamitsu exec golangci-lint run ./...

# Run eslint via the managed Node.js runtime
datamitsu exec eslint --fix src/
```

## install

Install one or more managed apps (and optionally runtimes) into the store and leave them **ready**. Where `exec` installs, prepares and then runs an app, `install` materializes its files, runs its declared `prepare` step (see [prepare](./configuration-api.md#one-time-preparation-step-prepare)) and exits — the building block for the per-app stages of a generated Dockerfile (see [devtools dockerfile](#devtools-dockerfile)).

```bash
datamitsu install [app...]
```

| Flag               | Description                                                        |
| ------------------ | ------------------------------------------------------------------ |
| `--runtime <name>` | Install the named runtime(s) only, without any app (repeatable)    |
| `--no-verify`      | Skip the post-install version check (verification runs by default) |

The prepare step always runs before the version check; `--no-verify` skips only the check. By default, each installed app's version command (`--version`, or its configured `versionCheck.args`) is run after installation, so a broken install fails the command instead of producing a broken artifact. Apps whose version check is disabled, and shell apps, are skipped.

**Examples:**

```bash
# Install a single tool
datamitsu install shellcheck

# Install only the node runtime (no app)
datamitsu install --runtime node

# Install and verify each tool actually runs (the default)
datamitsu install eslint prettier

# Install without running the post-install version checks
datamitsu install eslint prettier --no-verify
```

## init

Download binaries, install runtime-managed apps, and run initialization commands.

```bash
datamitsu init
```

Must be run from the git repository root.

| Flag                       | Description                                        |
| -------------------------- | -------------------------------------------------- |
| `--all`                    | Download all binaries (both required and optional) |
| `--skip-download`          | Skip binary downloads                              |
| `--fail-on-download-error` | Stop if any binary download fails                  |
| `--dry-run`                | Show what would be done without making changes     |

Download concurrency is controlled via the `DATAMITSU_CONCURRENCY` env var (default: 3).

**What init does:**

1. Detects project types in the repository
2. Downloads required binaries and runtimes
3. Installs runtime-managed apps (Bun/Node/UV/JVM/Go) that are referenced by tools
4. Creates `.datamitsu/` symlinks for the config files of installed link-apps — an app marked `lazy: true` is deferred and gets its links on first `datamitsu exec` instead
5. Writes `.datamitsu/configs/`: every [ejectable managed config](./configuration-api.md#keeping-configs-out-of-the-repository-ejectable--ejectconfigs) the project has not ejected, removing any that no longer belong there
6. Runs configured init commands (e.g., `lefthook install`)

**Examples:**

```bash
# Standard initialization
datamitsu init

# Download all tools including optional ones
datamitsu init --all

# Preview what would happen
datamitsu init --dry-run
```

## check

Run fix followed by lint in a single process with shared context. If fix fails,
lint is skipped — unless `--fail-fast=false` runs it anyway (see
[Keep-going runs](#keep-going-runs)).

```bash
datamitsu check [files...]
```

| Flag                         | Description                                                                                                                                                                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--explain [mode]`           | Show execution plan without running. Modes: `summary` (default), `detailed`, `json`                                                                                                                                                     |
| `--file-scoped`              | Only process git staged files                                                                                                                                                                                                           |
| `--tools <list>`             | Comma-separated list of tools to run                                                                                                                                                                                                    |
| `--fail-on-skip`             | Exit non-zero if any tool is skipped because its binary is unavailable for this platform (see [Skipped tools](#skipped-tools))                                                                                                          |
| `--widen-to <level>`         | Limit how far work may widen beyond what you asked for: `target`, `unit` or `repo` (see [Narrowed runs](#narrowed-runs))                                                                                                                |
| `--require-coverage <level>` | Exit non-zero unless the run answered completely: `unit` or `repo` (see [Narrowed runs](#narrowed-runs))                                                                                                                                |
| `--fail-fast[=false]`        | Stop at the first failing tool (the default); `=false` runs everything to the end (see [Keep-going runs](#keep-going-runs))                                                                                                             |
| `--fail-on <level>`          | Fail on findings at this level or above in every operation: `error`, `warning`, `info` or `hint`; raises each operation's `failOn`, never lowers it (see [Failing on findings](#failing-on-findings---fail-on))                         |
| `--report <format>=<path>`   | Write a report once the run ends, failed or not; `-` is stdout; repeatable; one that lists findings turns fail-fast off (see [Reports](#reports))                                                                                       |
| `--events <what>`            | Which findings `--log-format jsonl` emits as `diagnostic` events: `diagnostics=reported` (default) or `diagnostics=all` (see [Run events](#run-events))                                                                                 |
| `--allow-partial`            | Write a report that lists findings for a narrowed run instead of refusing the run (see [Reports](#reports))                                                                                                                             |
| `--annotations <mode>`       | Print the run's findings as CI annotations once it ends: `auto` (the default), `github`, `azure`, `teamcity` or `off` (see [GitHub annotations](#github-annotations) and [Azure Pipelines and TeamCity](#azure-pipelines-and-teamcity)) |
| `--output <mode>`            | How the run shows its results: `human` (the default) or `agent`, one line per finding for a program that reads the run (see [Agent output](#agent-output))                                                                              |
| `--baseline <file>`          | Gate only on findings the baseline does not hold: a [`report baseline`](#report-baseline) document or a run's own JSON; a tool that exits non-zero still fails (see [Baselines](#baselines))                                            |

**Examples:**

```bash
# Check entire project
datamitsu check

# Check specific files
datamitsu check src/main.go src/handler.go

# Check only staged files (useful in git hooks)
datamitsu check --file-scoped

# Preview what would run
datamitsu check --explain

# In CI: fail if a tool you rely on has no binary for the runner's platform
datamitsu lint --fail-on-skip

# See every failure at once instead of stopping at the first
datamitsu check --fail-fast=false
```

`check`, `fix` and `lint` start every tool without `GITHUB_ACTIONS`, the AI agent
markers and `FORCE_COLOR`, and with `NO_COLOR=1`, so a tool prints the format its
parser reads whether the run is in CI, under an agent or in a terminal. `CI`
passes through. An operation gets a stripped variable back with
[`inheritEnv`](./configuration-api.md#inheriting-host-variables-inheritenv); the
[Tool Environment](./tool-environment.md) page lists them all.

The run opens with two rounded boxes: the CLI name and version in green, and
the resolved configuration name and version in orange, without a `config`
label. An unnamed configuration displays `datamitsu.config`. The boxes sit
side by side when they fit, stack on narrow terminals, and truncate long
names while retaining the version when space permits. This header appears
once per run; `--explain` and `--output agent` suppress it.

`check` closes with the wall clock of the whole command:

```console
$ datamitsu check
┏━ fix ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┃ golang · typescript
┃
┃ ✓ gofmt          120ms
┃ ✓ prettier       1.10s
┗━ 2 tools · 2 runs · done in 1.10s · cache 80% ━━━━━━━━━━━

┏━ lint ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┃ golang · typescript
┃
┃ ✓ golangci-lint  7.90s
┃ ✓ eslint         3.20s
┗━ 2 tools · 2 runs · done in 7.90s ━━━━━━━━━━━━━━━━━━━━━━━

┗━ check · done in 9.40s · fix 1.10s · lint 7.90s · setup 400ms ━━━
```

`done in` runs from the start of the command to the end of the last
operation. `fix` and `lint` repeat their own footers' times, and `setup` is the
rest: loading the configuration, walking the repository, planning, installing
tools. An operation that did not run is named — `lint not run` after a failed
fix under fail-fast, both when a setup step such as the `.datamitsuignore`
check failed. The line is printed for `check` only, never under `--explain`,
and on failure too; `fix` and `lint` end with their footer.

### Keep-going runs

By default a run stops at the first failing tool: nothing at a later priority
starts, a parallel sibling that is still running is stopped, a tool that runs
once per file stops at the first failing file, and `check` does not run lint
after a failed fix. That is the right answer for a person at a terminal, who
fixes one thing and runs again.

`--fail-fast=false` (or `DATAMITSU_FAIL_FAST=false`) runs everything to the end:

| Level                    | Default (fail-fast)                                  | `--fail-fast=false`                                                                |
| ------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Priority groups          | Stop after the first failing group                   | Every group runs, in order                                                         |
| Overlapping tools        | The ones after the failure do not start              | All run, one after another                                                         |
| Parallel tools           | Waiting ones are cancelled, running ones are stopped | All finish                                                                         |
| Files of a per-file tool | Stop at the first failing file                       | Every file runs; when more than one fails, the frame names each with its exit code |
| `check`'s fix, then lint | Lint is not run after a failed fix                   | Lint runs, and its footer says `lint ran after a failed fix`                       |
| Exit code                | 1 when anything failed                               | 1 when anything failed                                                             |

The flag wins over the variable; `--fail-fast` restores the default when
`DATAMITSU_FAIL_FAST=false` is set. `datamitsu config runtime` reports the
effective value as `failFast`, and where it came from as `failFastSource`
(`default` or `env`). A value of `DATAMITSU_FAIL_FAST` other than `true`,
`false`, `1` or `0` is refused.

In CI, run `datamitsu lint --fail-fast=false`: one run then reports every
failing tool. A [report](#reports) that lists findings turns fail-fast off by itself. When a later operation fails for another reason than an earlier
one — lint cannot install its tools after fix failed — both reasons are
reported. A tool that runs once per file and is interrupted after one of its
files failed stays a failure; the files it did not reach make the run
incomplete. CI runs `lint`, not `fix` or `check`, which change the working
tree.

A formatter that fails at a low priority leaves its files unformatted for the
linters that run after it, so a keep-going run can report findings that
disappear once the formatter passes.

### Failing on findings (`--fail-on`)

A tool fails a run when it exits non-zero, or when its parsed output holds a
finding at or above its operation's
[`failOn`](./configuration-api.md#failing-on-findings-failon) — `error` unless the
configuration sets another. `--fail-on <level>` (or `DATAMITSU_FAIL_ON`) raises
that threshold for every operation of the run, to `warning`, `info` or `hint`; an
operation whose own `failOn` is already stricter keeps it, and nothing lowers a
threshold or turns a non-zero exit into a pass:

```bash
# CI: a warning fails the run too, whatever the tool's exit code
datamitsu lint --fail-on warning
```

The flag wins over the variable. `datamitsu config runtime` reports the
variable as `failOn` (empty when it is not set), and `--explain` shows each
task's threshold: `failOn` in the JSON, a `Fail on:` line when it is not
`error`. A value of either that is not `error`, `warning`, `info` or `hint`
exits 2 before anything runs — a mistyped gate is refused, not ignored.

The threshold gates only output a parser module with the severity contract
(descriptor schema 2) read: its levels are what the tool printed. Under an
older module the exit code alone decides, and a run that asked for a threshold
other than `error` says so once, after its last operation:

```console
WARN failOn ignored for hadolint: parser module predates the severity contract
```

With the default threshold, a tool that exits 0 on a finding its parser reads
as an error fails the run — semgrep without `--error`, trivy without
`--exit-code`. A tool that failed because of the threshold shows exit code 0 in
its frame, with a `Failed on:` line naming the threshold.

### Findings in the terminal

What the terminal shows is what gates: for every tool it prints the findings at
or above the operation's threshold, sorted by level, file, line, column and
rule, and counts the rest.

- A failed tool prints them in its red frame. A tool that failed although none
  of its findings reaches the threshold — one that fails on warnings, such as
  `yamllint --strict` or `eslint --max-warnings 0` — prints every finding, so a
  failure always explains itself; one that failed without findings prints its
  output.
- The findings below the threshold are never dropped: the tool line counts them
  per level, the frame ends with one line saying what it left out, and the
  footer sums them.
- A passed tool prints no frame, except when a threshold other than `error` was
  asked for and its parser module predates the severity contract: its findings
  at or above that threshold then print in a yellow frame, since nothing
  enforced it.

An abridged run, the frame without its directory, command and duration lines:

```console
┃ ✗ eslint        1.20s  (1 failed)  · 5 warnings
  ┌─ eslint [per-project] (run #1) ────────────────────
  │  Exit code: 1
  │
  │  src/a.ts:3:7 error 'x' is assigned a value but never used. [no-unused-vars]
  │  src/b.ts:9:1 error Unexpected var, use let or const instead. [no-var]
  │  + 5 warnings hidden (failOn=error)
  └─────────────────────────────────────────────────────────
┃ ✓ yamllint      310ms  · 2 warnings
┗━ 2 tools · 2 runs · done in 1.20s · 1 failed · 7 warnings hidden
```

`--fail-on hint` shows every finding and fails on any of them. `--no-parse`
prints each framed tool's output instead of findings and counts nothing for it,
and so does a tool run once over many files whose parser names no file for its
findings: a finding that cannot say which file it is about reads worse than the
output it came from. A tool that prints no frame keeps its counters either way.

A tool the run stopped is neither a pass nor a failure, and it is listed rather
than left out:

```console
┃ ✗ eslint        1.2s     (1 failed)
  …
┃ ⊘ tsc [packages/api]  cancelled (fail-fast)
┃ ⊘ custom-check  not started (fail-fast)
┗━ 1 tools · 1 runs · done in 1.2s · 1 failed · 2 cancelled
```

`cancelled` means the tool had started and was stopped; `not started` means it
never ran. `(interrupted)` replaces `(fail-fast)` when the run was stopped by
Ctrl-C or `SIGTERM`: datamitsu then stops every running tool, prints what it
did not finish and exits 130 (SIGINT) or 143 (SIGTERM). A second Ctrl-C ends the
process at once. A signal that arrives while the configuration is still loading,
before the run has started, ends the process at once too, with no report. The `(N failed)` counts never include stopped tools, and a
tool stopped in several places of one kind shares one line with a `×N` count.

A tool that runs once per file stops at its first failing file under fail-fast,
and the files it never reached are named under its failure:

```console
┃ ✗ alpha  12ms  (1 failed)
  …
┃ ⊘ alpha  2 files not run (fail-fast): src/b.txt, src/c.txt
```

The line names up to three files, relative to the repository root, and counts
the rest.

### Agent output

`--output agent` (or `DATAMITSU_OUTPUT=agent`) prints a run for a program that
reads it, such as a coding agent: no banner, frame, colour or progress, and one
line per record on stdout. What the configuration prints while it loads
(`console.log`) goes to stderr, with the warnings.

```console
$ datamitsu check --fail-fast=false --output agent
fix changed 2 files: src/a.ts, src/b.ts
fix: 3 tools · 4 runs · 0 failed · 0 errors 0 warnings · 0 hidden
src/a.ts:3:7: error eslint(no-unused-vars): 'x' is assigned a value but never used.
src/b.ts:9:1: error eslint(no-var): Unexpected var, use let or const instead.
tsc [packages/api] exited 2 without parsable findings
  │  error TS5083: Cannot read file 'tsconfig.base.json'.
knip: skipped (opt-in)
lint: 4 tools · 5 runs · 2 failed · 2 errors 0 warnings · 5 hidden
check · done in 9.40s · fix 1.10s · lint 7.90s · setup 400ms
```

- **A finding** is `path:row:col: <level> <source>(<code>): <message>`, the path
  relative to the repository root, the column as the tool counted it and left
  out when there is none. A line break in anything a record names — a message, a path, a skip reason — is written as the two
  characters `\n`, so a record is always one line. The findings are the ones
  the terminal would show, chosen by the same rule (see
  [Findings in the terminal](#findings-in-the-terminal)), and `--no-parse`
  changes only the human frames.
- **A tool that failed without findings** is one line —
  `<tool> [<dir>] exited <code> without parsable findings`, after the file for a
  tool that runs once per file — followed by the last 20 lines of what it
  printed, each behind `  │  `, masked as a report is. A tool whose parser
  module puts it in the `security` category gets
  `failed (exit <code>); output withheld for a security tool` and no output.
- **What did not run** — a task stopped or never started, the files a tool that
  runs once per file left unchecked, a tool the planner skipped — is one line
  each, as the human block words it.
- **The files a fix changed** are one line before its summary,
  `fix changed <N> files: <path>, <path>` — an agent that holds any of them in
  memory reads them again. When they could not be observed (see
  [Reports](#reports)) the line is `fix changes not observed: <reason>`,
  followed by the files seen before the observation stopped.
- **Each operation ends** with
  `<op>: <tools> tools · <runs> runs · <failed> failed · <E> errors <W> warnings · <H> hidden`,
  `<H>` counting the findings below the threshold, and `· <N> baselined` when a
  [baseline](#baselines) held some, and `check` with its closing
  wall-clock line. The exit code is the run's.

Fail-fast stays the default: add `--fail-fast=false` to see every failure at
once. `--output agent` prints on stdout, so it cannot be combined with
`--log-format jsonl`, which keeps stdout clean, or with a report written to
stdout (`-`); either exits 2, as does any other value. In a GitHub Actions job
the records print inside the
[stop-commands region](#github-annotations) like any other tool text; a record
of a finding in a `.go` file is in the form `actions/setup-go`'s problem matcher
reads, so a job that registers it annotates such a finding twice.

### Run events

With `--log-format=jsonl`, `fix`, `lint` and `check` write their progress to
stderr as typed events, one JSON object per line:

| `type`       | When                                                                                                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hello`      | Opens the stream: `op_id` `stream`, `schema` (`datamitsu.report/1`), `events`, the comma-separated types the stream may carry, and for `fix`, `lint` and `check` `annotations` |
| `phase`      | An operation (`op`: `fix` or `lint`) starts: `status: "start"`                                                                                                                 |
| `tool_run`   | A tool starts in a directory (`status: "start"`) and ends: `done` or `fail` with its findings per level, or `skip` for a stopped tool                                          |
| `chunk`      | A tool finished a unit of its work: `index` of `total`                                                                                                                         |
| `error`      | A tool failed: `tool`, `dir`, `msg`                                                                                                                                            |
| `done`       | The operation ended, with its summary                                                                                                                                          |
| `report`     | A report was written or not: `format`, `path`, `status` and, when it was not, `msg` (see [Reports](#reports)); `github-annotations` for the [annotations](#github-annotations) |
| `diagnostic` | One finding of a tool, once the tool finished: by default those at or above the operation's `failOn`                                                                           |

Every task — one tool in one directory, or one file of a tool that runs once
per file — has an `op_id` of its own: the operation's `op_id` followed by
`:<tool>:<dir>:<seq>`, where `dir` is relative to the repository root (empty for
the root) and `seq` numbers the operation's planned tasks from 1 in plan order,
for example `run-1:eslint:packages/web:3`. A task's `tool_run` start, its `chunk`
events, its `error` and its closing `tool_run` share it, and no other task's
events do.

A `--log-format jsonl` stream opens with a `hello` event, whatever the
command, so a reader can tell a stream without `diagnostic` events from a run
that found nothing. For `fix`, `lint` and `check` it also says whether stdout
carries [GitHub annotations](#github-annotations) beside the stream:
`annotations` is `github` or `off`.

```json
{
  "type": "hello",
  "op_id": "stream",
  "schema": "datamitsu.report/1",
  "events": "hello,phase,download,install,chunk,tool_run,error,done,log,report,diagnostic",
  "annotations": "off"
}
```

A `tool_run` that ends with `done` or `fail` carries the task's findings per
level — `findings_error`, `findings_warning`, `findings_info`, `findings_hint`,
zero included — and `cached`, true when a cache answered for the task. No other
event carries them.

A `diagnostic` event is one finding, emitted once its tool has finished in the
operation — every task of the tool, since a finding's fingerprint depends on
all of the tool's findings — and before the operation's `done`. Its `op_id` is
the task that reported it:

```json
{
  "type": "diagnostic",
  "op_id": "run-1:eslint:packages/web:3",
  "tool": "eslint",
  "dir": "packages/web",
  "file": "packages/web/src/a.ts",
  "row": 3,
  "col": 7,
  "end_row": 3,
  "end_col": 8,
  "severity": "error",
  "code": "no-unused-vars",
  "source": "eslint",
  "msg": "'x' is assigned a value but never used.",
  "fingerprint": "8d08ad593059cec87a6c97ce43655d04b1bee8102810cd99952dd606b26bb618",
  "provenance": "parser",
  "reported": true,
  "gates": true
}
```

`file` is relative to the repository root, rows and columns are 1-based and
`end_col` is exclusive; `fingerprint` is the finding's
[report fingerprint](#reports). Every event of a JSON-L stream is masked as a
report is, `op_id` included, from its first line with the values the
environment names, and once a run has loaded its configuration with its apps'
and operations' values and those its tools were started with; a task's events
still share one `op_id`. By
default only the findings at or above the operation's `failOn` are emitted —
what the terminal shows. `--events diagnostics=all` (or
`DATAMITSU_EVENTS=diagnostics=all`) emits every finding, with `reported` and
`gates` saying which are at the threshold and which failed their tool, and
`baselined: true` on one a [baseline](#baselines) held;
`diagnostics=reported` is the default. Any other value exits 2. The synthetic
finding a report lists for a tool that failed without findings is never an
event.

A stream that could not be written — a closed or full stderr — fails the
command, whichever it is and however it ended otherwise: it exits 1 and says so
on stdout, the one stream left, unless stdout carries the command's own data (a
report written to `-`, the language server's JSON-RPC, `source`'s shell code).

`--verbose` adds datamitsu's debug log lines to the stream as `log` events,
with what a tool printed and the arguments it ran with withheld
(`"<withheld>"`): a stream is what a pipeline publishes. The console keeps
them.

A `tool_run` with `status: "skip"` ends the chain of a tool the run stopped,
and is never a failure. Its `msg` says what happened and why:
`cancelled: fail-fast` or `cancelled: interrupted` closes the `start` of a tool
that was stopped while it ran; `not started: fail-fast` or
`not started: interrupted` is the only event of a tool that never started.

An operation's `done` carries `op`, `status` (`done` or `fail`), `duration_ms`,
`tools` (tools that ran), `runs` (tasks that ran), `failed` (tools with a failed
task), `skipped` (tools the planner left out, see
[Skipped tools](#skipped-tools)) and `cancelled` (tasks the run stopped, present
when there were any). A counter or `duration_ms` that is zero is left out. An
operation whose tools could not be installed ends with a `done` of status
`fail` and no counters.

The stream ends with one more `done`, for the whole command: its `op_id` starts
with `cmd-` where an operation's starts with `run-`, and its `op` is `fix`,
`lint` or `check`. It carries `status`, `success` (whether the command
succeeded), `duration_ms` (the wall clock of the whole command), the sums of the
operations' `tools`, `runs`, `failed` and `skipped`, `cancelled` (always
present, zero included) and `complete`: `true` when every planned operation ran,
no task was cancelled or left unstarted, and no tool that runs once per file
stopped at a failing file with files left to check. `check` whose fix failed under
fail-fast reports `complete: false`. It is emitted for every execution of `fix`,
`lint` and `check` — also when the run could not start, for example because the
configuration does not load — never under `--explain`, for a usage error, or for
a run a signal ended while its configuration was loading, and not for the fix
that `config reconcile` runs after writing its files.

```json
{
  "type": "done",
  "op_id": "cmd-7",
  "op": "check",
  "status": "fail",
  "success": false,
  "duration_ms": 9400,
  "tools": 3,
  "runs": 4,
  "failed": 1,
  "cancelled": 1,
  "complete": false
}
```

### Reports

`--report <format>=<path>` writes a report of the run once its last operation
has ended, whether or not its tools failed — the run that fails is the one a
pipeline needs to read. The flag is repeatable, one per format: `json`, the
run's own document; `markdown`, the same run for a person; `sarif`, the run for
code scanning; `junit`, the run as test results; `codequality`, GitLab's Code
Quality report; `checkstyle`, Checkstyle XML; `rdjsonl`, reviewdog's
diagnostics; `history`, one line of counts appended to a trend file; and
`patch`, the diffs a fix's formatters applied.
The [Reports guide](../guides/reports.md) explains what a
report holds and how far to trust it; [`report render`](#report-render) writes
one again, offline, from a run's own JSON.

```bash
# CI: the whole run as one document, uploaded whatever the outcome
datamitsu lint --report json=out/run.json
```

- The path is required, and relative to the working directory. Missing
  directories are created, and the file is written to a temporary name beside
  it and renamed, so a reader never sees half a report. It gets the
  permissions a file created in its place would — the umask decides — and a
  report it replaces keeps its own.
- `-` writes the report to stdout, for one format per run. stdout then carries
  the report alone: the human output is left out, and stderr carries the
  [run events](#run-events) as it does under `--log-format jsonl`.
- A path that ends in `/` names a directory, for a format that splits a run
  over several files (`sarif`); any other format given one exits 2. Options
  follow the path after `?`: `sarif=out/results.sarif?category=linux`.
- `DATAMITSU_REPORT` is the variable twin, comma-separated:
  `DATAMITSU_REPORT=json=out/run.json`. A `--report` naming the same format
  wins over its entry. `datamitsu config runtime` reports the variable as
  `report`.
- A report that lists findings — every format but `history` and `patch` — turns fail-fast
  off: a run that stopped at the first failing tool could not list every
  finding. Such a report together with `--fail-fast=true`, or with
  `DATAMITSU_FAIL_FAST=true` and no `--fail-fast` flag, exits 2. `history`
  and `patch` leave fail-fast as it is.
- A format named twice, an unknown format or option, a missing path, two
  reports that would write one file — one path twice, a report where another's
  completeness companion goes, or a file inside a split format's directory —
  and a report combined with `--explain` (which runs nothing) exit 2 before
  anything runs.
- A report that cannot be written prints
  `error: report <format>: <path>: <cause>` and makes the run exit 5 — unless a
  tool failed (exit 1) or the run was incomplete (exit 4), which keep their code;
  the line is printed either way. Under `--log-format jsonl` the same fact is a
  `report` event.
- The time a report is stamped with comes from `SOURCE_DATE_EPOCH` when it is
  set, the reproducible-builds convention; durations are always measured.

A report says how much of the repository its findings stand for. Every tool is
judged on three facts, and each one that fails adds a reason to the tool's
`incomplete` list:

| Fact       | Complete when                                                                                                        | Reasons                                                                                                             |
| ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| scope      | the run covered the whole repository — no files named, no subdirectory, no `--file-scoped` — and every task its unit | `narrowed-selection`, `partial-unit`                                                                                |
| execution  | every planned task ran to the end                                                                                    | `cancelled`, `not-started`, `setup-failed`, `platform-skip`                                                         |
| extraction | every output was read into findings by a parser, or a cache replayed a pass its parser read as clean                 | `no-extraction`, `parser-unavailable`, `parse-failed`, `truncated`, `unparsed-cache-hit`, `failed-without-findings` |

A tool whose output no parser read — its own, a format parser, or the fallback
built into datamitsu — is never complete (`no-extraction`, or `parse-failed` when
a parser was declared): its exit code says whether it passed, not what it found.
Nor is a tool whose process exited non-zero while the parser that recognized its
output found nothing in it (`failed-without-findings`). The run is `complete` when
every tool is, every operation ran, and nothing was left out at run level:
`narrowed-selection`, `tools-filter` (with `selection.excludedTools` naming the
tools `--tools` left out — the selected tools' own runs can still be complete),
`not-narrowable` (a tool skipped because it could not be narrowed) and
`operation-skipped`. A tool disabled with `skip: true` is neither.

A report that lists findings is refused for a run narrowed before it starts —
files named, a subdirectory, `--file-scoped` or `--tools` — because it would
read as the findings of the repository: the run exits 2 before anything runs,
and the report is recorded as `refused`. `--allow-partial` (or
`DATAMITSU_ALLOW_PARTIAL=true`) writes it anyway, with every reason in the
document; it never makes a run complete. A report left on its path by an
earlier run is not deleted, so a pipeline that uploads it with `if: always()`
checks the exit code as well.

`json` writes datamitsu's own document, `datamitsu.report/1`: what the run was
asked to cover (`selection`), whether fail-fast was on (`failFast`), the CI job
it ran in (`ci`: `vendor`, empty outside CI, and the `sha`, `ref`, `baseRef` and
`prNumber` the vendor names — see
[`facts().ci`](./configuration-api.md#platform-information)), and for each
operation (`fix`, `lint`; `check` writes one document holding both) whether it
ran and succeeded, the tools the planner skipped and the tasks the run stopped.
Each tool lists its app as configured, its parser module and its threshold, and
one invocation per process: its task, state, exit code, extraction outcome, the
files it answered for and the findings it reported, with paths relative to the
repository root. The files a cache answered appear as one `cached` or
`verdict-hit` invocation of their task. A finding says whether it is at or above
the threshold (`reported`), whether it failed its tool (`gates`) and whether the
terminal shows it (`shown`, see
[Findings in the terminal](#findings-in-the-terminal)), which is what the
annotations, `markdown` and `--output agent` list.

Every finding carries a `fingerprint` that identifies it across runs: SHA-256
over the tool, the rule, the path and the text of the finding's first line, and
its position among the findings the tool reported with the same rule on the
same line. A line inserted above a finding moves its row, not its fingerprint,
and rewording a message changes neither. `fingerprintBasis` says what the
fingerprint rests on: `line`, `row` when the file could not be read, `none` for
a finding without a file. A finding's `location` gives its columns as the tool
counted them, in the `unit` its parser declares, and converted while the file
was on disk into code points (`chars`), UTF-8 bytes (`bytes`) and UTF-16 units
(`utf16`); `precision` is `exact`, `ascii` (no unit declared, but an ASCII
line), or `unknown`, when there was nothing to convert from. A report never holds a command line or
an environment variable, and nothing caches it: every report is written from
the run that produced it.

`sarif` writes SARIF 2.1.0 for GitHub code scanning and the other services
that keep alerts across uploads. It holds one run per tool of the `lint`
operation (`check` writes its lint, a `fix` run its fix), in the category
`datamitsu` — `automationDetails.id` `datamitsu/` — or the one
`?category=<name>` names, and each result carries the finding's fingerprint as
`partialFingerprints.primaryLocationLineHash`. A tool whose completeness is not
established is left out rather than listed, and so is a tool with more than
25 000 results, which GitHub would cut: an upload without a tool leaves that
tool's alerts as they are. Each tool left out gets one `WARN` line on stderr
naming why and is recorded in the `omitted` list of the report's entry in
`exports`. Because it leaves out what is incomplete, `sarif` is written for a
narrowed run instead of being refused — named files, a subdirectory and
`--file-scoped` leave every tool incomplete, `--tools` writes the selected tools
that are complete. Code scanning refuses a SARIF file without a run, so a report
that would hold none is not written: a file an earlier run left at its path, or
the `datamitsu-<n>.sarif` files of its directory, are removed, the export is
`omitted` (a `report` event with that status under `--log-format jsonl`), and a
`WARN` line says so; nothing is written to stdout either. GitHub reads at most twenty runs from one
file: `sarif=<dir>/` writes `datamitsu-1.sarif`, `datamitsu-2.sarif` and so on,
twenty tools each, sorted by name, and removes the `datamitsu-<n>.sarif` files
an earlier run left there that this one did not write; a file or `-` for a run
that plans more than twenty tools exits 2 before anything runs. See
[Code scanning](../guides/reports.md#code-scanning) for the workflow.

`junit` writes JUnit XML: one suite per operation and tool (`<operation>/<tool>`,
its completeness in `properties`), one case per file the tool answered for, and
a `<failure>` only for a file with a finding at or above the operation's
`failOn` that failed its tool — the failure count follows the gate, not the
findings. Findings below the threshold are a case's `<system-out>`. An
invocation that failed without such a finding is one extra case named after its
directory (with the invocation's ID when several share one): a
`<failure type="exit">` listing its findings, or an
`<error type="exit">` with the masked tail of its output when it has none
(never for a `security` tool). Stopped tasks, skipped tools and an operation
that did not run are `<skipped>` cases. See
[Test results](../guides/reports.md#test-results-junit).

`codequality` writes GitLab's Code Quality array: one issue per finding of the
`lint` operation (fix for a `fix` run), with `check_name` `<source>/<rule>`,
the finding's fingerprint, `severity` `major` for an error, `minor` for a
warning and `info` below, `categories` `Security` for a `security` tool and
`Style` otherwise, and a repository-relative `location.path` with `positions`
in characters, or `lines` where the columns could not be converted. A finding
without a file or outside the repository cannot be placed and is left out and
counted. A tool that is not complete is kept. See
[GitLab Code Quality](../guides/reports.md#gitlab-code-quality).

`checkstyle` writes one `<file>` per file and one `<error>` per finding of the
`lint` operation (fix for a `fix` run), with `line`, `column` in characters
where the report could convert it, `severity` `error`, `warning` or `info`,
`message` and `source` `<source>/<rule>`; a finding without a file is under
`<file name="">`. `rdjsonl` writes one reviewdog diagnostic per line: the
message, the path with a range in UTF-8 byte columns (exclusive end, left out
where they could not be converted), severity `ERROR`, `WARNING` or `INFO`, the
source with its app's official URL and the rule with its documentation; a
finding without a file has no location. See
[Checkstyle](../guides/reports.md#checkstyle) and
[reviewdog](../guides/reports.md#reviewdog).

A format that lists findings but has no place to say how complete it is —
`junit`, `codequality`, `checkstyle`, `rdjsonl` — gets a completeness companion
beside its file,
`<path>.completeness.json` (`datamitsu.completeness/1`): whether the report is
complete, the run-level reasons, each tool with its own, the findings the
format could not carry (`omitted`), and the run's exports.
A job checks it before it publishes the report. Each incomplete tool also gets
one `WARN` line on stderr, and the report's entry in `exports` names the
companion (`companion`). A report on stdout has none.

`markdown` writes the same run for a person, as GitHub renders Markdown: what
the run covered and whether it is complete, a table of each operation's tools
(status, runs, files a cache answered, findings per level), the findings the
terminal would show — grouped by level, then by file, as
`path:row:col — source(code): message`, columns in characters and only where
the report could convert them — with a count of those below the threshold, the
tools skipped and the tasks stopped, and each incomplete tool with its reasons.
It carries no tool output: a tool that failed without findings is its
structured message. It lists findings, so it is refused for a narrowed run like
`json`.

`history` appends one line, `datamitsu.history/1`, to the file it names —
creating it and its directories the first time, never replacing it: when the
run started, the build and configuration, the CI job's vendor, commit and ref,
what the run covered (`selection`: `mode`, `fileScoped`, `toolsFiltered`),
whether it was complete and ran fail-fast, and per operation and tool the
processes that ran, the files a cache answered, the invocations that failed,
completeness with its reasons and the findings per level. It holds no finding,
no path and none of the paths the run was given, so a narrowed run writes it
without `--allow-partial`, and it leaves fail-fast alone. The line is appended
in one write. See [History](../guides/reports.md#history).

A `fix` operation records the files its tools changed. A snapshot of the working
tree — `git status --porcelain=v2` over tracked and untracked files, without
optional locks, plus a hash of each file it lists — is taken before the first
group of tools that run together and after every group, a failed or cancelled
one included. Each file whose state moved between two snapshots is a change:
`created`, `modified`, `deleted`, or `reverted` for a file that differed from
the index before and matches it after — a formatter that restored what the
commit holds. A change is listed on the invocation of that group whose files
hold it, and on the operation (`changes`) when none does. `changesObserved` says
whether the changes were observed and `changesScope` what that covers: ignored
files and the contents of submodules and nested repositories are not observed,
and a rename is a deletion and a creation. When they were not observed,
`changesReason` says why — `no-fix-task` for `lint` and a fix that planned
nothing, `not-run`, `not-executed` when the tools could not be set up,
`snapshot-failed` (with `changesDetail`) when git is missing, the root is not a
repository, or a status failed — and no list stands for "nothing changed";
changes seen before a snapshot failed are kept. Snapshots are taken only when
the run records anything: a report, a JSON-L stream, annotations or agent
output.

`patch` writes the unified diffs the formatters that write their result on
stdout applied, captured while both versions existed, in the order they were
applied: a file two formatters changed one after the other has two hunks, the
first formatter's first, and `git apply` or `patch -p1` takes the file — a
name that holds a control character, a quote or a backslash is quoted as git
quotes it. A tool
that writes its files itself leaves no patch; its changes carry `patch: false`.
Patches hold source text, so they are captured only when `--report patch=` is
asked for, and the run's `json` then holds them too, masked like everything
else, which lets `report render --format patch` write them again. Like
`history`, `patch` lists no finding: a narrowed run writes it, and it leaves
fail-fast alone.

A tool that exits non-zero without a finding its parser could read is listed
with one `synthetic` finding of level `error` and no location, whose message
says so — `tsc exited 2 without parsable findings` — rather than as a clean
tool. The message carries none of the tool's output. The document keeps the last
4 KiB of a failed invocation's output as `outputTail`, without its colour codes.
For a tool whose parser module puts it in the `security` category, the output is
never kept: its synthetic finding reads
`gitleaks failed (exit 1); output withheld for a security tool`, and there is no
`outputTail`.

Before a report is written, the value of every variable of the environment,
and of every app's and operation's `env`, whose name contains `TOKEN`,
`SECRET`, `PASSWORD` or `CREDENTIAL`, or ends in `_KEY` (in any letter case),
and that is at least 8 characters long, is replaced by `***` wherever it occurs
in the document. This catches what the environment names; a secret a tool
prints that no variable holds is not caught, which is why a security tool's
output is withheld altogether.

### Baselines

`lint --baseline <file>` and `check --baseline <file>` gate only on findings the
baseline does not hold. The file is a [`report baseline`](#report-baseline)
document or a run's own JSON, whose findings are taken as one; it is read
before anything runs, and one that cannot be read, of another schema, or of
fingerprints of another version exits 2.

```bash
datamitsu lint --baseline .datamitsu-baseline.json
```

A finding whose fingerprint the baseline holds is marked while its process is
judged, before the threshold decides — at most as many findings of a rule on a
line as the baseline holds fingerprints of, whichever processes report them:
it is neither reported nor gates, so it
fails nothing, and under fail-fast cancels nothing. The terminal counts it —
`· 2 baselined` on the tool's line and in the footer — instead of printing it;
the own JSON marks it `baselined`, SARIF puts it in the result's
`properties.baselined`, JUnit lists it in `<system-out>` marked `(baselined)`,
and Markdown and `--output agent` count it.

The exit code of a tool is untouched: a tool that exits non-zero still fails the
run, and its frame shows the baselined findings it failed on, marked
`(baselined)`. Most linters exit 1 on the findings they print, so a baseline
makes a run fail only on new findings when the tool exits 0 and the gate
decides: give the tool its exit-zero flag — `--exit-zero`, `--exit-code 0` —
and let `failOn` gate. See [Baselines](../guides/reports.md#baselines).

### GitHub annotations

In a GitHub Actions job `fix`, `lint` and `check` print the run's findings as
workflow commands once the last operation has ended — `::error file=…,line=…::`
— which GitHub shows as annotations in the Checks tab and on the lines a pull
request changed, with no token and no extra step:

```text
::error file=src/a.ts,line=3,col=7,endColumn=8,title=eslint(no-unused-vars)::'x' is assigned a value but never used.
::error title=tsc::tsc exited 2 without parsable findings
```

`--annotations` (or `DATAMITSU_ANNOTATIONS`) chooses when:

| Mode       | Prints                                                                                                                                                                                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auto`     | the annotations of the CI the run is in — GitHub's in a GitHub Actions job (`GITHUB_ACTIONS=true`, not Gitea or Forgejo), Azure Pipelines' under `TF_BUILD`, TeamCity's under `TEAMCITY_VERSION` — unless stdout carries a document or `--log-format jsonl` is on; the default |
| `github`   | GitHub's, wherever the run is, under `--log-format jsonl` too: stdout is not the event stream's channel                                                                                                                                                                        |
| `azure`    | Azure Pipelines' logging commands, wherever the run is (see [Azure Pipelines and TeamCity](#azure-pipelines-and-teamcity))                                                                                                                                                     |
| `teamcity` | TeamCity's service messages, wherever the run is                                                                                                                                                                                                                               |
| `off`      | never                                                                                                                                                                                                                                                                          |

An explicit mode together with a report written to stdout (`-`) or with
`--explain=json` exits 2: the commands would land in the document. Any other
value, from the flag or the variable, exits 2 as well. Nothing is printed when
no task ran — a plan that matched nothing, a run refused before it started.
The annotations are recorded as an export of the [report](#reports),
`github-annotations`, `azure-annotations` or `teamcity-annotations`, `written`
or `omitted` with the reason, and under `--log-format jsonl` as a `report`
event; the stream's `hello` says the mode the run settled on.

The annotations are what the terminal shows (see
[Findings in the terminal](#findings-in-the-terminal)): each tool's findings at
or above its `failOn`, or all of them for a tool that failed on findings below
it, plus one error without a file for a tool that failed without a finding its
parser could read. A finding reported twice — by `fix` and by `lint`, or by two
processes of one tool — is annotated once. The path is relative to the
repository root, whatever directory the workflow checked the repository out
into; a finding outside the repository names no file. Columns are given in
characters, and only on a one-line finding whose columns could be converted
(see the report's `precision`). A message is escaped and cut at 4096 bytes.

GitHub keeps the first ten annotations of each type — error, warning, notice —
a step prints, so datamitsu chooses which ten: findings in the files the change
touched come first, then one finding of every other file before a second of any,
then findings without a file. When anything did not fit, a notice takes the
first notice slot and says how many were left out and where they are:
`datamitsu: 15 more findings in the step summary and in out/run.json` names the
step summary when it was written and every report written to a file that lists
findings. The files a change touched come from git: on a
`pull_request`, the merge commit the checkout holds against its first parent,
the base branch's tip (with `actions/checkout`'s default depth of 1 that parent
is not fetched: set `fetch-depth: 2`); on a `push`, the commit the push started
from, named by the event (fetched only with `fetch-depth: 0`). When the change
cannot be read, one `info` line says why, and the order is the same without the
priority. Several datamitsu commands in one step share one budget of ten.

In a GitHub Actions job the run also appends its [`markdown`](#reports) report
to the step summary, the Markdown page of the job's run that
`GITHUB_STEP_SUMMARY` names, unless `--annotations off` — whatever stdout
carries, since the summary is a file, and under `--log-format jsonl` too. It
lists every finding the annotations could have shown. GitHub takes 1 MiB of
summary from a step, whoever wrote it, so the run writes what fits in what the
file has left and ends with a line saying how many findings it cut and, when the run wrote its `json` report to a file, that every finding is there. A summary
that cannot be written — the variable is unset, the file cannot be opened, or
it is full — is one warning (a `log` event under `--log-format jsonl`), never a
failure; nothing is written when no task ran. Gitea and Forgejo have no step
summary.

Everything the run prints between its first results block and the annotations
is one `::stop-commands::` region with a random token, so no line a tool printed
— raw output, a parsed message — can be read as a workflow command; the
annotations follow its end. Every line of tool text in a frame is indented
behind its border. The problem matchers `actions/setup-go` and
`actions/setup-node` register read every line whatever the region, and the
indentation keeps `tsc`'s and `eslint-stylish`'s from matching; two remain:
`go`'s pattern accepts any text before a path, so raw output in Go's
`file:line:col: message` form still matches — with the border in the file name,
which GitHub drops, keeping an error annotation without a location — and so does
`eslint-compact`'s, for output in ESLint's compact format. Such a line appears
only when a tool's output is shown raw: it has no parser, `--no-parse` is on, or
it failed without findings.

### Azure Pipelines and TeamCity

Under `TF_BUILD` the run logs its findings as the issues of the Azure Pipelines
task, once the last operation has ended:

```text
##vso[task.logissue type=error;sourcepath=src/a.ts;linenumber=3;columnnumber=7;code=eslint(no-unused-vars)]'x' is assigned a value but never used.
##vso[task.logissue type=error;code=tsc]tsc exited 2 without parsable findings
```

The findings are those GitHub would get — what the terminal shows, each once,
and the failures without a finding — with the path relative to the repository
root and the column in characters on a one-line finding whose columns could be
converted. The agent has two issue types, `error` and `warning`, so `info` and
`hint` findings are not logged, and keeps ten of each type per task: datamitsu
orders each type as it does for GitHub — the files the pull request touched
first, then one finding of every other file before a second of any — and when
anything did not fit, ends with one plain line, `datamitsu: 4 more findings in
out/run.json`. The touched files are those that differ between HEAD and its
merge base with `origin/<target branch>` (`SYSTEM_PULLREQUEST_TARGETBRANCH`);
when that ref is not fetched, or the build is not a pull request, one `info`
line says so. A property value and the message are escaped as the agent
unescapes them: `%` as `%AZP25`, `;` as `%3B`, a carriage return as `%0D`, a
line feed as `%0A`, `]` as `%5D`.

The agent runs a `##vso[` command wherever it appears in a line, not only at its
start, on stdout and stderr, and has no way to suspend that. Under `TF_BUILD` —
whatever `--annotations` says — and in `azure` mode, every line the run prints
that holds tool output or a repository path — raw output, a parsed message, a
command line, a directory, a file name, a progress label, an agent record or
tail, a JSON-L event, a `--verbose` log line, an `--explain` plan, a GitHub
annotation printed there — has `##vso[` rewritten to `##vso [`, so no tool and no
file name can set a variable, upload a file or fail the task through
datamitsu's output. That alters a line of raw output by one space. A report
written to stdout — by the run or by `report render` — is a document that has to
keep its meaning: a JSON format spells the bracket `\u005b` and an XML format
`&#91;`, which read back as the same text, and Markdown and `patch` get the
space.

Under `TEAMCITY_VERSION` the run reports its findings as TeamCity inspections:
an `inspectionType` once per tool and rule (`id` `<tool>/<rule>`, the rule's
documentation as its description when the tool names one), an `inspection` per
finding with the file, the line and a `SEVERITY` of `ERROR`, `WARNING`, `INFO`
or `WEAK WARNING` for the four levels, and a `buildProblem` for a tool that
failed without a finding, whose `identity` is the tool's name in Java identifier
characters, at most 60. TeamCity keeps every inspection, so nothing is left out,
except a finding without a file, which an inspection cannot hold: one plain line
counts those. Values are escaped as TeamCity reads them: `|` as `||`, `'` as
`|'`, `[` and `]` as `|[` and `|]`, line breaks as `|n` and `|r`, and other
control characters and the Unicode line separators as `|0xNNNN`.

TeamCity reads a service message anywhere in a line too. Everything the run
prints between its first results block and the inspections is wrapped in
`##teamcity[disableServiceMessages]` … `##teamcity[enableServiceMessages]`, and
the inspections follow the second line; under `TEAMCITY_VERSION` and in
`teamcity` mode every line that holds tool output or a repository path —
inside the region and out, the event stream included — has `##teamcity[`
rewritten to `##teamcity [`, so neither a tool nor a file name can turn the
reading back on. A run killed before it prints its inspections — a second
interrupt — leaves the reading suspended for the rest of the build step.

Tools still see `TF_BUILD` and `TEAMCITY_VERSION` (see
[Tool Environment](./tool-environment.md)); a tool that prints logging commands
or service messages of its own when it sees them has them broken like any other
line. The recipes are in the [Reports guide](../guides/reports.md#azure-pipelines-and-teamcity).

### Skipped tools

:::info
A tool is reported as **skipped** (not run, not failed) for one of three reasons:

- **Disabled in config** — the tool sets `skip: true` (optionally with a `skipReason`).
- **No binary for this platform** — the tool's binary has no build for the current
  OS/architecture/libc. This is a soft skip: the run still succeeds.
- **Cannot narrow** — a narrowed invocation selected less than the operation's
  declared granularity and the widening policy does not permit expanding it.

Skipped tools appear as `⊘ <tool> skipped (<reason>)` lines and a `· N skipped`
count in the summary footer, and as a `skipped` array in `--explain=json`.

`--fail-on-skip` makes the run exit 4 **only** for platform skips (a tool you
expected to run had no binary), the code of a run that did not look at
everything. Intentional `skip: true` and narrowing skips never fail that flag;
use `--require-coverage` to enforce complete narrowed runs.
:::

### Narrowed runs

Naming files, or running from a subdirectory, asks for less than the whole
repository. Most tools follow: a formatter given one file formats that file.
Some cannot. `syncpack` compares versions **across** `package.json` files, so a
one-file answer is not a smaller answer, it is a wrong one.

datamitsu decides this per operation, from the tool's
[granularity](configuration-api.md#granularity). A narrowable tool runs on what
you asked for. One whose verdict covers the whole repository is reported as
skipped:

```console
$ cd packages/api
$ datamitsu fix ./swagger.json
✓ oxfmt                packages/api/swagger.json
⊘ syncpack             skipped (whole-repository verdict — cannot narrow)
```

Before this behaviour existed those tools were dropped silently — absent from the
report, from `--explain`, from everything. If you were relying on that silence,
the tools have not changed; only the reporting has.

**`--widen-to`** overrides how far the core may go beyond your request, in either
direction — you typed it for this one run, so it wins over the project's policy:

```bash
# Only what I named. Anything needing more is reported, not run.
datamitsu fix ./swagger.json --widen-to=target

# Run the whole-repository tools anyway.
datamitsu fix ./swagger.json --widen-to=repo
```

The policy governs unit-scoped tools too, not only whole-repository ones. A tool
whose command line carries no path — `go fmt ./...`, `golangci-lint run`, and most
formatters that find their own files — reads its entire project whatever you
named, so naming one file runs it over that file's project and no other. Under
`target` it is reported rather than run, because a whole project is more than what
you named. Tools that take a `{files}` list are already narrowed by that list and
are unaffected.

Set the project default in config with
[`execution.widenTo`](configuration-api.md#executionwidento).

**`--require-coverage`** turns an incomplete answer into a failure, for CI:

```bash
# Every unit the run touched was fully analysed.
datamitsu check --require-coverage=unit

# ...and the run covered the repository at all.
datamitsu check --require-coverage=repo
```

`unit` fails if a tool could not be narrowed, if a task covered only part of its
unit, or if the host lacked a binary. `repo` adds that the run must have targeted
the whole repository — without that clause, `check --require-coverage pkg/x.ts`
would pass having checked one package of nine.

A tool you disabled with `skip: true` never counts against coverage: a repository
that opts a tool out has given its answer, not an incomplete one.

It works under `--explain` too, since coverage is decided while planning — a CI
gate that costs one plan and downloads nothing. It cannot be combined with
`--tools`, which would make the assertion cover only the selected subset.

## fix

Run fix operations on files.

```bash
datamitsu fix [files...]
```

| Flag                         | Description                                                                                                                                                                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--explain [mode]`           | Show execution plan without running. Modes: `summary` (default), `detailed`, `json`                                                                                                                                                     |
| `--file-scoped`              | Only process git staged files                                                                                                                                                                                                           |
| `--tools <list>`             | Comma-separated list of tools to run                                                                                                                                                                                                    |
| `--fail-on-skip`             | Exit non-zero if any tool is skipped because its binary is unavailable for this platform (see [Skipped tools](#skipped-tools))                                                                                                          |
| `--widen-to <level>`         | Limit how far work may widen beyond what you asked for: `target`, `unit` or `repo` (see [Narrowed runs](#narrowed-runs))                                                                                                                |
| `--require-coverage <level>` | Exit non-zero unless the run answered completely: `unit` or `repo` (see [Narrowed runs](#narrowed-runs))                                                                                                                                |
| `--fail-fast[=false]`        | Stop at the first failing tool (the default); `=false` runs everything to the end (see [Keep-going runs](#keep-going-runs))                                                                                                             |
| `--fail-on <level>`          | Fail on findings at this level or above in every operation: `error`, `warning`, `info` or `hint`; raises each operation's `failOn`, never lowers it (see [Failing on findings](#failing-on-findings---fail-on))                         |
| `--report <format>=<path>`   | Write a report once the run ends, failed or not; `-` is stdout; repeatable; one that lists findings turns fail-fast off (see [Reports](#reports))                                                                                       |
| `--events <what>`            | Which findings `--log-format jsonl` emits as `diagnostic` events: `diagnostics=reported` (default) or `diagnostics=all` (see [Run events](#run-events))                                                                                 |
| `--allow-partial`            | Write a report that lists findings for a narrowed run instead of refusing the run (see [Reports](#reports))                                                                                                                             |
| `--annotations <mode>`       | Print the run's findings as CI annotations once it ends: `auto` (the default), `github`, `azure`, `teamcity` or `off` (see [GitHub annotations](#github-annotations) and [Azure Pipelines and TeamCity](#azure-pipelines-and-teamcity)) |
| `--output <mode>`            | How the run shows its results: `human` (the default) or `agent`, one line per finding for a program that reads the run (see [Agent output](#agent-output))                                                                              |

**Examples:**

```bash
# Fix entire project
datamitsu fix

# Fix specific files
datamitsu fix src/main.go

# Fix only with specific tools
datamitsu fix --tools prettier,eslint
```

## lint

Run lint operations on files.

```bash
datamitsu lint [files...]
```

| Flag                         | Description                                                                                                                                                                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--explain [mode]`           | Show execution plan without running. Modes: `summary` (default), `detailed`, `json`                                                                                                                                                     |
| `--file-scoped`              | Only process git staged files                                                                                                                                                                                                           |
| `--tools <list>`             | Comma-separated list of tools to run                                                                                                                                                                                                    |
| `--fail-on-skip`             | Exit non-zero if any tool is skipped because its binary is unavailable for this platform (see [Skipped tools](#skipped-tools))                                                                                                          |
| `--widen-to <level>`         | Limit how far work may widen beyond what you asked for: `target`, `unit` or `repo` (see [Narrowed runs](#narrowed-runs))                                                                                                                |
| `--require-coverage <level>` | Exit non-zero unless the run answered completely: `unit` or `repo` (see [Narrowed runs](#narrowed-runs))                                                                                                                                |
| `--fail-fast[=false]`        | Stop at the first failing tool (the default); `=false` runs everything to the end (see [Keep-going runs](#keep-going-runs))                                                                                                             |
| `--fail-on <level>`          | Fail on findings at this level or above in every operation: `error`, `warning`, `info` or `hint`; raises each operation's `failOn`, never lowers it (see [Failing on findings](#failing-on-findings---fail-on))                         |
| `--report <format>=<path>`   | Write a report once the run ends, failed or not; `-` is stdout; repeatable; one that lists findings turns fail-fast off (see [Reports](#reports))                                                                                       |
| `--events <what>`            | Which findings `--log-format jsonl` emits as `diagnostic` events: `diagnostics=reported` (default) or `diagnostics=all` (see [Run events](#run-events))                                                                                 |
| `--allow-partial`            | Write a report that lists findings for a narrowed run instead of refusing the run (see [Reports](#reports))                                                                                                                             |
| `--annotations <mode>`       | Print the run's findings as CI annotations once it ends: `auto` (the default), `github`, `azure`, `teamcity` or `off` (see [GitHub annotations](#github-annotations) and [Azure Pipelines and TeamCity](#azure-pipelines-and-teamcity)) |
| `--output <mode>`            | How the run shows its results: `human` (the default) or `agent`, one line per finding for a program that reads the run (see [Agent output](#agent-output))                                                                              |
| `--baseline <file>`          | Gate only on findings the baseline does not hold: a [`report baseline`](#report-baseline) document or a run's own JSON; a tool that exits non-zero still fails (see [Baselines](#baselines))                                            |

**Examples:**

```bash
# Lint entire project
datamitsu lint

# Lint specific files
datamitsu lint src/main.go

# Show detailed execution plan
datamitsu lint --explain detailed
```

## inspect

Explore the resolved configuration in a browser or export a portable HTML artifact.

```bash
datamitsu inspect                         # Local server on loopback port 7744
datamitsu inspect --port 0                # Choose an available port
datamitsu inspect --output atlas.html     # Export a self-contained HTML file
datamitsu inspect --output - > atlas.html # Write HTML to stdout
datamitsu inspect --theme theme.json      # Apply color overrides
datamitsu inspect --print-theme           # Print the theme that would be applied
```

`--output` (`-o`) and `--port` are mutually exclusive, and so is `--print-theme` with
either of them. The inspector loads the usual configuration chain and serves a fixed
snapshot until restarted. Exported HTML works offline and on static hosts, with
light/dark themes and hash-based links to views, filters, and selections.

`--theme` merges a JSON file of color overrides onto the built-in theme, token by
token and mode by mode; an export bakes the result in. An unknown key or a value that
is not a color is an error naming the full key path, and colors that fall below WCAG
AA contrast against their surface produce a warning, not an error. `--print-theme`
writes the merged theme — the complete built-in one when no `--theme` is given. See
[Config Inspector](../guides/config-inspector.md) for navigation, artifact contents,
theming, and publishing examples.

## report

Work with the reports `fix`, `lint` and `check` write with
[`--report`](#reports). None of these commands runs a tool.

### report render

Render a run's own JSON document (`datamitsu.report/1`) into a report format,
offline:

```bash
datamitsu report render --input <run.json> --format <format> [--output <path>|-]
```

| Flag                | Description                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--input <path>`    | The own JSON document a run wrote with `--report json=<path>` (required)                                                                        |
| `--format <format>` | The format to write: `json`, `markdown`, `sarif`, `junit`, `codequality`, `checkstyle` or `rdjsonl`; a format's options follow a `?` (required) |
| `--output <path>`   | Where to write it; `-`, the default, is stdout. Written atomically, like `--report`                                                             |
| `--allow-partial`   | Render a format that lists findings for a document of a narrowed run                                                                            |

The renderers and the completeness rule are the run's own: a document of a
narrowed run is refused (exit 2) for a format that lists findings unless
`--allow-partial`, and a document without its completeness fields is read as
incomplete, never as complete — as is a tool an earlier build called complete
although one of its processes failed while its parser found nothing
(`failed-without-findings`). The document holds everything a renderer needs,
so rendering works on another machine and after the checkout changed; `json`
reproduces the document byte for byte, and every other format the file the run
wrote, its completeness companion included, which is written beside
`--output` and never on stdout. An `--output` that ends in `/` is a directory,
for `sarif`; a document with more tools than one SARIF file holds is refused
(exit 2) for a file or stdout. A document of another schema, or one
that cannot be read, exits 1; an output that cannot be written exits 5.

```bash
# Print a run's report again
datamitsu report render --input out/run.json --format json

# The same run for a person
datamitsu report render --input out/run.json --format markdown --output out/run.md

# For code scanning, split into files of twenty tools
datamitsu report render --input out/run.json --format sarif --output sarif/
```

`history` renders too: it appends the document's line to `--output`.

### report baseline

Write the fingerprints of every finding a run reported as a baseline,
`datamitsu.baseline/1`, which [`lint --baseline`](#baselines) and
`check --baseline` read:

```bash
datamitsu report baseline <run.json> [--output <path>|-]
```

| Flag              | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `--output <path>` | Where to write the baseline; `-`, the default, is stdout. Written atomically |

The baseline holds the fingerprint version (`fingerprint`: `dmfp1`), when it
was made (`createdAt`, from `SOURCE_DATE_EPOCH` when set), the build and
configuration of the run it was made from, that run's start, commit and ref,
whether it was complete with the reasons of the run and its tools (`source`),
and the sorted fingerprints of every finding of every operation, whatever its
level; a tool that failed without findings adds none. A document of
fingerprints of another version exits 2. A run that was not
complete is taken with one `WARN` line: its baseline holds fewer fingerprints,
which only suppresses fewer findings. A document that cannot be read, or of
another schema, exits 1; an output that cannot be written exits 5.

```bash
datamitsu lint --report json=out/run.json
datamitsu report baseline out/run.json --output .datamitsu-baseline.json
```

### report diff

Compare the findings of two runs' own JSON documents by fingerprint, tool by
tool:

```bash
datamitsu report diff <before.json> <after.json> [--format json|markdown] [--output <path>|-]
```

| Flag                | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `--format <format>` | `json` (the default), `datamitsu.diff/1`, or `markdown` for a person |
| `--output <path>`   | Where to write it; `-`, the default, is stdout. Written atomically   |

Each document contributes the operation a report lists — `lint`, or `fix` for a
fix-only run. A finding is:

| Class        | When                                                                                                |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `new`        | only the second run holds it                                                                        |
| `unchanged`  | both hold it, on the same row                                                                       |
| `moved`      | both hold it, on another row (`beforeRow` names the first run's)                                    |
| `fixed`      | only the first run holds it, and the second run covered the whole repository with the tool complete |
| `unknown`    | only the first run holds it, and the second did not look everywhere: the tool's reasons say why     |
| `unobserved` | every finding of a tool only one run holds (`status`: `before-only` or `after-only`)                |

The document counts each class per tool and in `summary`, and lists every
finding with its fingerprint, level, rule, message, path and row. For two
complete runs the counts are symmetric: what one direction calls `new` the other
calls `fixed`. The command exits 0 whatever it finds; a document that cannot be
read, or of another schema, exits 1, an unknown `--format` 2, and an output that
cannot be written 5.

```bash
datamitsu report diff main.json branch.json --format markdown
```

## config

Configuration management commands.

### config reconcile

Reconcile project-owned configuration files declared under `managedConfigs`
for the detected project types, then run `datamitsu fix`.

```bash
datamitsu config reconcile [flags]
```

| Flag               | Description                                                                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run`        | Preview reconciliation without writing files or running `datamitsu fix`                                                                                                    |
| `--skip-fix`       | Reconcile managed files without running the post-reconciliation `datamitsu fix`                                                                                            |
| `--opt-in-tools`   | Also reconcile an all-disabled `.datamitsuignore` so tools are opt-in (enable them by removing names from the list)                                                        |
| `--tools`          | Comma-separated list of tools to scope reconciliation to (only their managed config files are considered)                                                                  |
| `--no-verify-hash` | Skip [`expectChainHash`](./configuration-api.md#pinning-the-upstream-chain-expectchainhash) verification even when a pinned managed config drifted from its upstream chain |

With no flags, the command creates, replaces, patches, links, or removes the
managed files and then runs `datamitsu fix`. Use `--dry-run` to inspect the plan
without either action, or `--skip-fix` when the files should be reconciled but
formatters should not run. There are deliberately no `--apply` or `--fix`
switches: writing and the post-reconciliation fix are the default workflow.
There is also no general `--force` flag; the one narrow safety-check bypass is
`--no-verify-hash`.

:::warning `init` and `config reconcile` are different operations

After editing `datamitsu.config.*`, run `datamitsu init` to provision apps,
runtimes, bundles, `.datamitsu` links, and init commands. Run
`datamitsu config reconcile` only when you explicitly intend to rewrite
project-owned files declared under `managedConfigs`.

:::

With `--tools`, reconciliation is scoped to the named tools: it considers only
the config files associated with them (via each managed config entry's
[`tools`](./configuration-api.md#managed-configs-managedconfigs) field)
and leaves everything else untouched — other tools' configs and unassociated
infrastructure files (`.gitignore`, `lefthook.yaml`, `pnpm-workspace.yaml`, …)
are skipped. The default post-reconciliation fix is scoped to the same tools;
pass `--skip-fix` to omit it. This is the recommended way to iterate on a single
tool's config without rewriting your whole project. Unknown tool names fail
fast before anything is written; a selected tool that owns no config file is
reported and skipped (not an error).

With `--opt-in-tools`, reconciliation also writes a
`.datamitsuignore` at the git root that disables **every** configured tool via a
single `**/*: <tool names>` rule. You then enable tools one at a time by removing
their names from that list. The file is written before the default fix so that
fix already respects the opt-in state. Reconciliation refuses to overwrite an
existing `.datamitsuignore`; `--dry-run` previews the file without writing it.
See [Generating an all-disabled file](./ignore-rules.md#generating-an-all-disabled-file).

An [ejectable](./configuration-api.md#keeping-configs-out-of-the-repository-ejectable--ejectconfigs)
config the project has not ejected lives in `.datamitsu/configs/`, not in the
repository: reconciliation removes its repository copy — and writes
`.datamitsu/configs/` so the post-reconciliation fix finds it — but only when the
copy holds nothing the configuration would not render again. A copy with changes
of the project's own is never deleted; reconciliation refuses before writing
anything and names the file, to be kept by adding its tool to `ejectConfigs` or
deleted by hand.

Any config file that pins [`expectChainHash`](./configuration-api.md#pinning-the-upstream-chain-expectchainhash)
is verified before reconciliation writes anything: if its upstream chain drifted from the
pinned hash, reconciliation aborts with a report (the expected/actual hash and the full
incoming content) and **no files are written**. Review the change against your
overrides, update the pin, and re-run — or explicitly pass `--no-verify-hash`
to write regardless. The check also runs during `--dry-run`.

**Examples:**

```bash
# Preview managed config changes without writing or fixing
datamitsu config reconcile --dry-run

# Reconcile managed files, then run fix (default)
datamitsu config reconcile

# Reconcile managed files without running fix
datamitsu config reconcile --skip-fix

# Reconcile configs and start with all tools disabled (opt-in model)
datamitsu config reconcile --opt-in-tools

# Regenerate only golangci-lint's config (e.g. .golangci.yml); nothing else is touched
datamitsu config reconcile --tools golangci-lint

# Preview a tool-scoped reconciliation without writing or fixing
datamitsu config reconcile --tools golangci-lint --dry-run

# Scope to several tools at once
datamitsu config reconcile --tools golangci-lint,prettier
```

`--force` regenerates managed files from the Datamitsu configuration layers,
ignoring their existing on-disk settings. Overrides declared in the project's
Datamitsu layer still apply. It also permits removal of customized repository
copies of configs that are internally managed. `--tools` still limits the files,
and `--dry-run` previews the reset without writing. Hash verification remains
enabled; `--no-verify-hash` is a separate choice.

```bash
datamitsu config reconcile --force --tools sqruff --dry-run
datamitsu config reconcile --force --tools sqruff --skip-fix
```

### config show

Display the current configuration as JSON.

```bash
datamitsu config show
```

### config types

Display the TypeScript type definitions file (`config.d.ts`).

```bash
datamitsu config types
```

### config runtime

Display the full effective runtime configuration snapshot as JSON — env-resolved execution limits, the per-app install timeout, and the minimum release age. This is the introspection/debug surface: it reflects what the program runs with right now, including environment overrides. It is **not** the surface injected into the config JS VM (config JS receives only the minimal allowlisted `datamitsuConfigInputs`).

```bash
datamitsu config runtime
```

**Examples:**

```bash
# Inspect the full effective runtime config
datamitsu config runtime

# Mechanically verify a single value (and that env overrides apply)
datamitsu config runtime | jq .minimumReleaseAgeMinutes
DATAMITSU_INSTALL_TIMEOUT=1200 datamitsu config runtime | jq .installTimeoutSeconds  # -> 1200

# The parse caps: bytes read from each output stream, findings kept per process
datamitsu config runtime | jq '{maxParseInputBytes, maxFindingsPerProcess}'
```

`fix`, `lint` and `check` refuse a `DATAMITSU_MAX_PARSE_INPUT_BYTES` or
`DATAMITSU_MAX_FINDINGS_PER_PROCESS` that is not a positive integer with exit 2;
`config runtime` reports the default in its place. See
[parse caps](../guides/architecture/parsers.md#parse-caps).

### config chain-hash

Print the XXH3-128 chain hash that `datamitsu config reconcile` verifies for managed config files — the hash of the content entering each file's root (topmost) config layer. Copy it into a `managedConfigs` entry's [`expectChainHash`](./configuration-api.md#pinning-the-upstream-chain-expectchainhash) to pin the upstream baseline your overrides were written against, without having to trigger a drift error to read it.

```bash
datamitsu config chain-hash [file...]
```

The value is the input to the **topmost** layer, so declare your own entry for the file first (a placeholder `expectChainHash` is enough), then read the real hash here. With no arguments every managed config file is listed as `file  hash`; with exactly one file only its hash is printed, ready to paste into a pin — `expectChainHash` accepts only the canonical `xxh3:<32 lowercase hex>` form.

**Examples:**

```bash
# List the chain hash of every managed config file
datamitsu config chain-hash

# Print just one file's hash (capture it into a variable / your config)
datamitsu config chain-hash eslint.config.mjs
pin=$(datamitsu config chain-hash eslint.config.mjs)
```

### config lockfile

Generate lock file content for a runtime-managed app (Bun/Node/UV/Go).

```bash
datamitsu config lockfile [appName]
```

Without arguments, lists all apps that use lock files. With an app name, creates
the package-manager lock data from scratch and outputs it as a brotli-compressed,
base64-encoded JSON string ready to paste into configuration. The command uses a
special config-load path that permits the selected app's initially missing
`lockFile`; every normal config load requires lock files for Bun, Node, UV, and Go
apps.

Transitive dependencies are subject to the minimum release age: pnpm resolves
Bun and Node apps with `minimumReleaseAge`, uv resolves UV apps with
`--exclude-newer P7D` and records the window in the lock, and a Go app fails
when any resolved module is younger than the effective minimum release age
(`DATAMITSU_MIN_RELEASE_AGE=0` skips that check). See
[Transitive dependencies](/docs/guides/supply-chain-security#transitive-dependencies).

**Examples:**

```bash
# List apps that support lock files
datamitsu config lockfile

# Generate lock file for a Bun or Node app
datamitsu config lockfile eslint

# Generate the go.mod + go.sum lock payload for a Go app
datamitsu config lockfile govulncheck
```

## devtools

Developer utility commands for maintaining datamitsu configurations.

### devtools pull-releases

Update binary configurations from release providers. Requires a file argument specifying the path to the binary apps JSON file. If the file doesn't exist, an empty appstate structure is created automatically. Fetches repository descriptions from the source API and stores them in the output JSON.

```bash
datamitsu devtools pull-releases <file>
datamitsu devtools pull-releases config/src/binaryApps.json
datamitsu devtools pull-releases config/src/binaryApps.json --update
```

| Flag                  | Description                                                                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--update`            | Fetch latest release tags before updating                                                                                                                                                                                  |
| `--verify-extraction` | Verify that each downloaded asset extracts to an executable (ELF, Mach-O, PE or a `#!` script)                                                                                                                             |
| `--min-age <minutes>` | Minimum release age before a version is eligible (`-1` = global default of `10080`, `0` = disable, positive = custom). See [Minimum Release Age](/docs/guides/supply-chain-security#minimum-release-age-version-selection) |

By default, the command scans releases for all platform combinations using OS/Arch/Libc target tuples. For Linux, both glibc and musl variants are detected separately; an asset whose name says `alpine` or `musl` counts as a Linux build even without `linux` in it, so `tool-alpine` lands on `linux/amd64/musl`. The output JSON uses a nested three-level storage structure:

```json
{
  "binaries": {
    "linux": {
      "amd64": {
        "glibc": { "url": "...", "hash": "...", "contentType": "tar.gz" },
        "musl": { "url": "...", "hash": "...", "contentType": "tar.gz" }
      }
    },
    "darwin": {
      "arm64": {
        "unknown": { "url": "...", "hash": "...", "contentType": "tar.gz" }
      }
    }
  }
}
```

Add an optional top-level `platforms` array to the input manifest to restrict detection:

```json
{
  "sources": { "github": { "type": "github", "url": "https://github.com" } },
  "platforms": ["darwin/arm64", "linux/amd64/musl"],
  "apps": {},
  "binaries": {}
}
```

Accepted identifiers are `darwin/amd64`, `darwin/arm64`, `windows/amd64`,
`windows/arm64`, `freebsd/amd64`, `freebsd/arm64`, `openbsd/amd64`,
`openbsd/arm64`, `linux/amd64/glibc`, `linux/amd64/musl`,
`linux/arm64/glibc` and `linux/arm64/musl`. Values are case-sensitive and exact:
there are no aliases or whitespace normalization. `linux/amd64` is not accepted.
An empty array, `null`, an invalid type or an unknown identifier fails before
filtering or GitHub requests. Repeated identifiers are processed once.

When present, the array removes every unselected platform from existing binary
entries before pulling releases, including entries without an `apps` record.
This deletion is saved even if a subsequent pull fails. Only selected platforms
are detected and, with `--verify-extraction`, downloaded and verified. A selected
platform without a compatible asset is reported and omitted. The list filters
available platforms; it does not require every app to publish every selected
platform. An app fails if none of its selected platforms has a usable asset.
A missing SHA-256 digest or failed verification still fails the app without
saving a partial new entry. Explicit selections keep separate glibc and musl
entries even when they share an asset.

The sorted, unique selection participates in `configHash`: changing the set
reruns detection at the same tag; reordering it does not. Removing `platforms`
restores default-all detection at the same tag. Without the field, existing
all-platform behavior and libc deduplication are preserved.

Non-Linux platforms use `unknown` as the libc key. Without an explicit selection, a missing musl variant is simply omitted.

Before scoring, the detector filters out three categories of assets: checksum files (`.sha256`, `.md5`, `.sha512`, etc.), attestations published beside an asset (`.proof`, `.sig`, `.asc`, `.minisig`, `.pem`, `.crt`, `.sigstore.json`, `.intoto.jsonl`, `.sbom`, `.spdx.json`, `.cdx.json`) and non-executable package formats and installers (`.vsix`, `.deb`, `.rpm`, `.nupkg`, `.whl`, `.msi`, `.msix`, `.appx`, `.pkg`, `.dmg`, and a name in which `setup` or `installer` stands as a word of its own, such as `Harper_2.11.0_x64-setup.exe` — unless the app's own name says so). This prevents IDE extensions, package-manager bundles, a desktop app's installer or a signature file from outscoring — or standing in for — actual binaries when releases mix them.

When a release holds several programs — harper publishes `harper-cli-*`, `harper-ls-*` and the `Harper` desktop app together — the asset whose name carries the app's name as whole tokens (case and separators aside) outranks the others of the same platform, whatever their format. An asset that names the requested libc still ranks above it: a `tool-alpine-*` build is the musl build even when only `tool-cli-linux-*` carries the app's name.

The manifest has no schema version. Every app selects a named source and a
repository path:

```json
{
  "sources": {
    "github": { "type": "github", "url": "https://github.com" },
    "codeberg": { "type": "forgejo", "url": "https://codeberg.org" },
    "gitea": { "type": "gitea", "url": "https://gitea.com" },
    "gitlab": { "type": "gitlab", "url": "https://gitlab.com" }
  },
  "apps": {
    "tool": { "source": "github", "repository": "owner/tool", "tag": "v1.0.0" }
  },
  "binaries": {}
}
```

The repository and tag above are illustrative. Use the actual tag your source
publishes. `repository` accepts nested GitLab namespaces. Supported `type` values
are exactly `github`, `gitlab`, `gitea` and `forgejo`; Codeberg is a Forgejo
instance, not a separate provider. `url` is the instance URL, including a
self-hosted subpath when needed. Optional `apiUrl` overrides the derived API
root (`/api/v3` for GitHub Enterprise, `/api/v4` for GitLab, `/api/v1` for Gitea
and Forgejo; public GitHub uses `https://api.github.com`). Source URLs require
HTTPS; local loopback instances also accept HTTP.

An optional source `tokenEnv` names a third-party token environment variable.
No token value is saved. It authorizes discovery API requests independently of
artifact downloads. The optional `downloadAuth` field controls downloads:

| Value            | Behavior                                                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auto` (default) | Resolve access separately for each asset from provider metadata and its endpoint. Public downloads have no auth. Restricted downloads require `tokenEnv`. Unknown access is an error with instructions to select an explicit policy. |
| `required`       | Require `tokenEnv` and authorize downloads on the configured instance. External origins remain anonymous. This uses the provider's token scheme; it does not configure reverse-proxy Basic auth or SSO.                              |
| `none`           | Never attach download credentials. Reject endpoints known to require auth; explicitly permit unknown endpoints anonymously. Discovery still uses `tokenEnv`.                                                                         |

For example, a source can specify `"downloadAuth": "none"` alongside a
`tokenEnv` used only for metadata. Different aliases of one instance can choose
different policies; app-level overrides are not supported.

GitHub reads explicit repository `private` metadata. Published public native
assets retain `browser_download_url`; private assets and drafts use the API
asset URL with an octet-stream Accept header. Gitea and Forgejo native release
attachments use repository visibility and draft status, retaining their browser
download URL with a Bearer token when restricted. Successful repository metadata
with known visibility is cached for the current client; absent visibility is
never silently treated as public.

GitLab reads `visibility` (`public`, `internal`, or `private`). It prefers the
original release link target over the permanent redirect URL. Generic-package
URLs for the same project use `package_registry_access_level`: `public` permits
anonymous download, `private` requires auth, `enabled` follows project visibility,
and `disabled` is an error. Missing package policy requires an explicit
`downloadAuth`. Restricted permanent release URLs use the token-capable release
API download route. Arbitrary same-origin links, including links to other
projects, require an explicit policy. External links never inherit repository
credentials, even when the project is private or the mode is `required`.
See the [GitLab package registry access rules](https://docs.gitlab.com/user/packages/package_registry/)
and [project API access levels](https://docs.gitlab.com/api/projects/).

Installation, checksum downloads, and `--verify-extraction` consume the same
resolved download auth. Missing required tokens fail before the request.
Cross-origin redirects drop credentials. There is no anonymous-to-authenticated
fallback after HTTP errors. SHA-256 verification remains mandatory in every mode.

After upgrading from the initial multi-source implementation, run
`pull-releases` again with the existing tags. The generation fingerprint
invalidates old entries for all providers once, replacing public download auth
and GitHub API asset URLs with anonymous download URLs. Changing `downloadAuth`
also invalidates generated entries.

**Integrity:** GitHub API digests are used directly. GitLab generic-package
links obtain SHA-256 from package-file metadata for the same project. A source
without a published digest must use explicit per-app `hashes` (asset filename
to SHA-256), or `checksums` (checksum asset filename to the checksum file's own
SHA-256). Only candidate files for selected platforms resolve digests. Checksum
files are downloaded only with their own validated SHA-256 pin; a binary is
never downloaded to manufacture its expected hash. GNU SHA-256 lists and BSD
`SHA256 (filename) = hash` records are supported. Conflicting records are errors.

Per-app pins apply by asset filename. When a new release needs those pins to
resolve its digests, update them from independently trusted upstream metadata
before using `--update`. With `--verify-extraction`, a stale matching pin fails verification and keeps
the previous app entry. Without that flag, a manual `hashes` pin cannot be
checked against the binary during pulling: the new tag and expected hash are
recorded, and installation still refuses a mismatching download. Checksum-file
pins are always verified when fetched. Pins are never refreshed by trusting
unverified downloaded bytes. Native
API digests permit automatic updates without maintaining per-app pins.

**Breaking migration:** rename your registry file to `binaryApps.json`, add
`sources`, and replace each app's `owner`/`repo` with `source`/`repository`.
Replace `pull-github` with `pull-releases` in scripts. The old command and old
manifest shape are not accepted. Unknown fields, sources and repository shapes
fail before pruning or network requests. `configHash` includes the source
profile, repository, tag, integrity pins and sorted unique platform selection.
Generated entries record their resolved provider, instance, repository and tag.

**Examples:**

```bash
# Detect binaries for the tags the file already pins (apps added or re-pinned by hand)
datamitsu devtools pull-releases config/src/binaryApps.json

# Update to latest releases
datamitsu devtools pull-releases config/src/binaryApps.json --update

# Update and verify that archives extract correctly
datamitsu devtools pull-releases config/src/binaryApps.json --update --verify-extraction
```

**Failures, retries and the exit code:**

Every app is attempted; one that fails does not stop the others. A request that fails for a transient reason — a network error, a timeout, a 5xx, a rate limit that names a short wait — is made up to four times with backoff, and each retry is printed with the app's request, the attempt and the reason. A 404, a release whose assets carry no digest, or a rate limit with no wait in sight is not retried. The run ends with a report naming every failed app, the stage it failed at (`metadata`, `latest release`, `release <tag>`, `binaries for <tag>`, `verify <platform>`) and the error, plus a hint when the cause is a GitHub rate limit, and exits with status 1 when any app failed.

With `--verify-extraction`, the download of each asset retries the same way. A platform whose asset turns out to be at fault — a hash mismatch, an archive that does not extract, a file that is not an executable — falls back to the next-ranked asset; a download that fails does not, since it says nothing about the asset, and a platform that still cannot be verified fails the app: its previous entry is kept, the report names the platform and the asset (`verify linux/amd64/glibc`), and the run exits with status 1.

The file is saved after each app that succeeds, and each save replaces the file whole. Every entry in it is therefore either the previous state of an app that failed or was not reached, or the complete new state of one that succeeded; a failed app never gets a partial new entry. The deletion of platforms excluded by `platforms` is applied and saved before any app pull, including pulls that fail. A save that fails stops the run, since nothing after it could be recorded either.

:::tip See also
For a complete workflow including CI automation, see [Maintaining Wrapper Packages — Binary Apps](/docs/how-to/maintain-wrapper#binary-apps-devtools-pull-releases).
:::

### devtools pull-node

Pull latest npm package versions from the npm registry. Requires a file argument specifying the path to the node apps JSON file. Descriptions are always fetched from the registry. If the file doesn't exist, an empty `{}` JSON file is created automatically.

```bash
datamitsu devtools pull-node <file>
datamitsu devtools pull-node config/src/nodeApps.json
datamitsu devtools pull-node config/src/nodeApps.json --update
```

| Flag                  | Description                                                                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--update`            | Update versions in the JSON file with latest from npm                                                                                                                                                                      |
| `--dry-run`           | Show results without writing to file                                                                                                                                                                                       |
| `--min-age <minutes>` | Minimum release age before a version is eligible (`-1` = global default of `10080`, `0` = disable, positive = custom). See [Minimum Release Age](/docs/guides/supply-chain-security#minimum-release-age-version-selection) |

**Examples:**

```bash
# Preview available npm updates without modifying files
datamitsu devtools pull-node config/src/nodeApps.json --dry-run

# Apply updates from npm registry
datamitsu devtools pull-node config/src/nodeApps.json --update

# After updating, regenerate lock files for affected apps
datamitsu config lockfile prettier
datamitsu config lockfile eslint
```

Registry requests that fail for a transient reason are made up to four times, each retry printed. With `--update`, a package whose entry changes is saved before the next one is looked up, so a later failure or an interrupted run keeps everything already pulled. A package that still fails keeps its previous entry; the run lists every failed package after the summary and exits with status 1. Without `--update` (or with `--dry-run`) the file is not written.

:::tip See also
For the full node app update workflow including lock file regeneration, see [Maintaining Wrapper Packages — Node Apps](/docs/how-to/maintain-wrapper#node-apps-npm-devtools-pull-node).
:::

### devtools pull-uv

Pull latest Python package versions from PyPI. Requires a file argument specifying the path to the UV apps JSON file. Descriptions are always fetched from the registry. If the file doesn't exist, an empty `{}` JSON file is created automatically.

```bash
datamitsu devtools pull-uv <file>
datamitsu devtools pull-uv config/src/uvApps.json
datamitsu devtools pull-uv config/src/uvApps.json --update
```

| Flag                  | Description                                                                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--update`            | Update versions in the JSON file with latest from PyPI                                                                                                                                                                     |
| `--dry-run`           | Show results without writing to file                                                                                                                                                                                       |
| `--min-age <minutes>` | Minimum release age before a version is eligible (`-1` = global default of `10080`, `0` = disable, positive = custom). See [Minimum Release Age](/docs/guides/supply-chain-security#minimum-release-age-version-selection) |

**Examples:**

```bash
# Preview available PyPI updates without modifying files
datamitsu devtools pull-uv config/src/uvApps.json --dry-run

# Apply updates from PyPI
datamitsu devtools pull-uv config/src/uvApps.json --update

# After updating, regenerate lock files for affected apps
datamitsu config lockfile yamllint
```

Registry requests that fail for a transient reason are made up to four times, each retry printed. With `--update`, a package whose entry changes is saved before the next one is looked up, so a later failure or an interrupted run keeps everything already pulled. A package that still fails keeps its previous entry; the run lists every failed package after the summary and exits with status 1. Without `--update` (or with `--dry-run`) the file is not written.

:::tip See also
For the full UV app update workflow including lock file regeneration, see [Maintaining Wrapper Packages — UV Apps](/docs/how-to/maintain-wrapper#uv-apps-python-devtools-pull-uv).
:::

### devtools pull-runtimes

Pull runtime configurations (Bun, Node, UV, JVM, Go, pnpm) with latest versions from upstream releases. Fetches latest releases from upstream, computes SHA-256 hashes, and writes the result to `<file>`.

```bash
datamitsu devtools pull-runtimes --update <file>
```

| Flag                  | Description                                                                                                                                                                                                                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--update`            | Required. Fetch latest versions from upstream before updating                                                                                                                                                                                                                                                               |
| `--dry-run`           | Show what would be updated without writing files                                                                                                                                                                                                                                                                            |
| `--runtime <name>`    | Update only the specified runtime (`bun`, `node`, `uv`, `jvm`, `go`, or `pnpm`)                                                                                                                                                                                                                                             |
| `--min-age <minutes>` | Minimum release age before a version is eligible (`-1` = global default of `10080`, `0` = disable, positive = custom). Applies to specific-version sources (GitHub releases, npm pnpm), not major-version-line lookups. See [Minimum Release Age](/docs/guides/supply-chain-security#minimum-release-age-version-selection) |

The command detects binaries for all platform combinations (OS/Arch/Libc). For Linux, both glibc and musl variants are detected when upstream provides separate binaries. If a musl binary is identical to the glibc variant (same URL and hash), the musl entry is deduplicated.

**Version sources:**

- **bun**: latest eligible Bun GitHub release; official archives and their SHA-256 digests from GitHub release metadata
- **node**: latest Node.js LTS resolved automatically; archives + SHA-256 from nodejs.org/dist (glibc/darwin/windows, GPG-verified via SHASUMS256.txt.asc) and unofficial-builds.nodejs.org (musl)
- **pnpm**: newest pnpm 12 release old enough for the minimum release age (judged by its npm publish date), with per-platform archive SHA-256 digests from the matching pnpm/pnpm GitHub release; the Node and Bun entries reference it with `pnpmRuntime: "pnpm"`
- **UV**: Python stable from endoflife.date, UV binary from GitHub
- **JVM**: Java version from Adoptium API, Temurin JDK from GitHub; when the newest feature release has no build old enough for the minimum release age yet, the previous feature release
- **go**: latest stable Go release + per-file SHA-256 from go.dev (`https://go.dev/dl/?mode=json`); HTTPS with published SHA-256, no GPG (the git-pinned hash is the integrity anchor, same trust model as the musl Node path)

**Examples:**

```bash
# Update all runtimes
datamitsu devtools pull-runtimes --update config/src/runtimes.json

# Update only Bun runtime
datamitsu devtools pull-runtimes --update --runtime bun config/src/runtimes.json

# Update only UV runtime
datamitsu devtools pull-runtimes --update --runtime uv config/src/runtimes.json

# Update only Go runtime
datamitsu devtools pull-runtimes --update --runtime go config/src/runtimes.json

# Update only the pnpm runtime shared by Node and Bun
datamitsu devtools pull-runtimes --update --runtime pnpm config/src/runtimes.json

# Preview changes without writing
datamitsu devtools pull-runtimes --update --dry-run config/src/runtimes.json
```

Upstream requests that fail for a transient reason are made up to four times, each retry printed. Every runtime is attempted, pnpm first and then the rest in alphabetical order, and a runtime whose entry changes is saved before the next one starts, so a later failure or an interrupted run keeps everything already pulled. A runtime that fails keeps its previous entry — so does a Node or Bun entry that would name a pnpm runtime the file does not define — and the run lists every failed runtime with its error and exits with status 1. A save that fails stops the run.

:::tip See also
For the full runtime update workflow and CI automation, see [Maintaining Wrapper Packages — Runtimes](/docs/how-to/maintain-wrapper#runtimes-devtools-pull-runtimes).
:::

### devtools dockerfile

Generate an optimized, digest-pinned multi-stage Dockerfile from the loaded config. Emits a config-free base, a `config-split` stage, then one build stage per binary app, per managed runtime, and per runtime-managed app (each inheriting its runtime stage), then assembles the populated store with `COPY --link` — one cacheable layer per app, so bumping one app re-pulls only its layer. The base never carries the config and each stage loads only its own slice (see [devtools split-config](#devtools-split-config)), so editing or regenerating the config rebuilds only the stages whose slice actually changed instead of every tool.

```bash
datamitsu devtools dockerfile -o docker/Dockerfile
```

| Flag                     | Description                                                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `-o, --output <path>`    | **Required.** Output Dockerfile path including filename, fully overwritten on each run                         |
| `--alpine`               | Target the Alpine (musl) base image variant (`<version>-alpine`)                                               |
| `--offline`              | Skip base-image digest resolution; emit an unpinned `FROM` with a warning                                      |
| `--no-verify`            | Do not run apps' version checks in their build stages (verification is on by default)                          |
| `--config-js <path>`     | Pre-built config file COPYed into the image (default `datamitsu.config.js`)                                    |
| `--repo <repo>`          | Override the base image repository (default: the repo this datamitsu build was published under)                |
| `--label <key=value>`    | OCI label for the final image (repeatable)                                                                     |
| `--arg <name[=val]>`     | Build `ARG` declared before `ENV` in the final stage; bare name or name=default (repeatable)                   |
| `--build-arg <n[=v]>`    | Build-time `ARG`→`ENV` in a `dm-build` stage so install stages inherit it; not in the final image (repeatable) |
| `--env <key=value>`      | `ENV` var baked into the final image (repeatable)                                                              |
| `--force-include <apps>` | Keep binary apps that lack a binary for the target libc (comma-separated, repeatable)                          |
| `--emit-oci-map <path>`  | Also write the layer→subtree map JSON consumed by the OCI bundle annotation post-process                       |

**libc filtering.** The generated image targets one libc — **musl** with `--alpine`, **glibc** otherwise — and binary apps are filtered to those that ship a binary for it on every arch they declare. A glibc-only binary can't execute on a musl image (and vice versa), so incompatible apps are dropped from the Dockerfile and listed in a warning. Runtime-managed apps (bun/node/uv/jvm/go) are unaffected — their runtime carries the libc. Statically-linked tools that run on any libc but are under-declared in the registry (e.g. a static Go binary recorded as glibc-only) can be added back with `--force-include name1,name2`.

The base image **repository and tag are baked into the datamitsu binary at release time**, so the `FROM` points at the exact image this build came from — including across release channels, where the stable image (`datamitsu/datamitsu:<version>`) and the unstable image (`datamitsu/datamitsu-unstable:<unstable-tag>`) live in different repositories under different tags. The registry host defaults to `ghcr.io` (override with `DATAMITSU_OCI_REGISTRY`); `--repo` overrides the repository for mirrors or forks. The tag is resolved to a SHA-256 digest and pinned as `FROM …@sha256:…`. Pinning is best-effort and never fails the command: `--offline`, an unreachable registry, or a non-release (`dev`/unstable) build leave the `FROM` unpinned with a warning. The output file is fully overwritten (no managed regions).

**Examples:**

```bash
# Generate the glibc and Alpine variants
datamitsu devtools dockerfile -o docker/Dockerfile
datamitsu devtools dockerfile -o docker/Dockerfile.alpine --alpine

# Offline (no digest pinning) — useful for CI drift checks
datamitsu devtools dockerfile -o docker/Dockerfile --offline

# Resolve the base digest from a mirror registry
DATAMITSU_OCI_REGISTRY=mirror.internal datamitsu devtools dockerfile -o docker/Dockerfile
```

:::tip See also
For the full image-publishing workflow and CI drift guard, see [Maintaining Wrapper Packages — Generating a Docker image](/docs/how-to/maintain-wrapper#generating-a-docker-image-devtools-dockerfile).
:::

### devtools split-config

Write one minimal config slice per app and per runtime into a directory. Each slice is a self-contained config defining exactly one stage's target — an app with its transitive dependencies and all referenced runtimes (including pnpm), or a runtime with its pnpm reference — that `install --config` can load on its own.

```bash
datamitsu devtools split-config -o ./slices
```

| Flag                 | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `-o, --output <dir>` | **Required.** Output directory for the config slices |

This is the build-cache primitive behind [devtools dockerfile](#devtools-dockerfile): the generated Dockerfile runs it in the `config-split` stage so every other stage loads only its own slice. Editing an app changes its slice and those of its dependents, invalidating their build caches instead of busting the whole image. You rarely run it directly; it is documented because it appears in the generated Dockerfile. The config is read from the usual sources (`--config` / `--before-config` / auto-discovery).

### devtools verify-all

Cross-platform config integrity checker. Downloads and hash-verifies binary apps and managed runtimes for all configured platforms. Every single file it extracts (all but `extractDir` archives) must be an executable: an ELF, Mach-O or PE file, or a script starting with `#!`.

```bash
datamitsu devtools verify-all
```

| Flag                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `--no-version-check` | Skip version command execution and comparison                       |
| `--concurrency <n>`  | Concurrent download workers (default: `DATAMITSU_CONCURRENCY` or 3) |
| `--json`             | Output machine-readable JSON                                        |
| `--skip-passed`      | Skip checks whose config is unchanged and passed last run           |
| `--no-remote`        | Skip loading remote configs                                         |

### devtools pack-inline-archive

Pack a directory into a brotli-compressed tar archive for use in inline archive configs.

```bash
datamitsu devtools pack-inline-archive <directory>
```

Output is written to stdout in `tar.br:` format. Archives are deterministic.

### devtools apps list

List all configured apps with their type, version, description, and install status. For binary apps, the resolved target (including libc variant) is determined by the current host's target detection. This helps verify which binary variant would be selected on the current system.

```bash
datamitsu devtools apps list
```

### devtools apps inspect

Show install path and file tree for an installed app. For binary apps, the inspect output reflects the resolved target for the current host, including any libc fallback that may have occurred during resolution.

```bash
datamitsu devtools apps inspect <name>
```

### devtools apps path

Print the install directory path for an app.

```bash
datamitsu devtools apps path <name>
```

### devtools bundles list

List all configured bundles with name, version, and install status.

```bash
datamitsu devtools bundles list
```

### devtools bundles inspect

Show install path and file tree for a bundle (collapses heavy directories).

```bash
datamitsu devtools bundles inspect <name>
```

### devtools bundles path

Print the install directory path for a bundle.

```bash
datamitsu devtools bundles path <name>
```

### devtools parsers

Inspect the WASM output-parser modules declared in the [`parsers`](./configuration-api.md#output-parsers-parsers)
config and the tools they can parse. Each module self-describes (via its WASM
`describe` export) which tools it parses, how to invoke each, its upstream URL, and
its build-injected version — so this is the source of truth, not the config.

`list` aggregates every configured parser into a **deduplicated** catalog (a module
declared by N tools is described once); `inspect` shows the full detail for one
tool. A module built with descriptor schema 2 or later also says, per tool, which
level words the tool prints (`levels`, `none` when it prints none), the unit it
counts columns in where that was measured (`columns`), and whether it is a
security scanner (`category`); an older module shows none of these lines, which
is how to tell which contract a pinned module carries (see
[levels](../guides/architecture/parsers.md#levels)). A module built with
descriptor schema 3 also lists its format parsers and the `fallback` sniffer,
each marked `format` ([format parsers](../guides/architecture/parsers.md#format-parsers)).
A module older than schema 3 is named once on stderr with a `note:` line, as
`datamitsu config show` names one already in the store
([older modules](../guides/architecture/parsers.md#older-modules)).
Both accept:

- `--json` — machine-readable output, for driving configs or build pipelines.
- `--wasm <path>` — describe a local `.wasm` file directly, with no config or
  network access (handy in CI and release tooling).
- `--embedded` — describe the fallback parser module built into this binary
  (format parsers and the `fallback` sniffer only), with no config or network
  access ([the embedded fallback](../guides/architecture/parsers.md#the-embedded-fallback)).

```bash
# Human-readable catalog of all tools the configured parsers can parse
datamitsu devtools parsers list

# Machine-readable catalog (tools is [] when none are configured)
datamitsu devtools parsers list --json

# Full detail for one tool
datamitsu devtools parsers inspect hadolint

# Describe a locally built module without any config
datamitsu devtools parsers list --wasm ./parsers/target/wasm32-unknown-unknown/release/datamitsu_parsers.wasm
```

`run` pipes a tool's raw output (from stdin) through its parser and prints the
module's answer as JSON — `abi`, whether it `recognized` the output, the `format`
it read, and the structured `diagnostics` — the quickest way to develop or debug a
parser against real output. A module that answers with a bare array (ABI 1) is
shown in the same shape, with `recognized` inferred as the core infers it. It reads
stdout from stdin; pass `--stderr-file` / `--exit-code` for parsers that use them,
and `--wasm <path>` to use a local module instead of a configured one.

```bash
# Run eslint through datamitsu, then parse its JSON into diagnostics
datamitsu exec eslint -- --format json file.js \
  | datamitsu devtools parsers run eslint --wasm ./datamitsu_parsers.wasm --exit-code 1

# Run a format parser of the fallback built into this binary
datamitsu exec shellcheck -- -f checkstyle script.sh \
  | datamitsu devtools parsers run checkstyle-xml --embedded --exit-code 1
```

`sniff [<file>|-]` runs the sniffer of the built-in fallback over a captured output
(a file, or stdin with `-` or no argument) and prints the standard format it
recognized and the findings it read, or `no standard format recognized`. It is how
to check which format key a tool's flag produces before declaring it as
`outputParser.parser`. `--stderr-file` and `--exit-code` pass the tool's other
stream and exit code; `--json` prints the whole answer.

```bash
ruff check --output-format sarif src > out.sarif
datamitsu devtools parsers sniff out.sarif
# format: sarif (1 finding)
#   src/a.py:1:8 error [F401] `os` imported but unused
```

`prefetch` downloads and SHA-256 verifies the configured parser modules into the
store, without compiling or running anything. Each module lands at its
content-addressed store path, so it can be `COPY`ed into an OCI-bundle layer (the
generated Dockerfile's parser stages do exactly this) and found offline later. A
module already on disk whose bytes still match the declared SHA-256 is a no-op —
and one whose bytes do not is discarded and fetched again, whatever put it
there.

```bash
# Fetch every module declared in the parsers config
datamitsu devtools parsers prefetch

# Fetch only a subset
datamitsu devtools parsers prefetch datamitsu-parsers
```

### devtools tools

Inspect the tools declared in the config — the fix/lint units datamitsu plans and
runs. `list` shows each tool's operations, project types, the app it runs, and its
output parser; `inspect` shows full per-operation detail. Both accept `--json`.

```bash
# All configured tools: name [operations] (projectTypes) → parser
datamitsu devtools tools list

# Machine-readable
datamitsu devtools tools list --json

# Full detail for one tool (per-operation app/scope/globs/args)
datamitsu devtools tools inspect eslint
```

### Troubleshooting devtools commands

**File not found errors:**

If the JSON file argument doesn't exist, `pull-releases`, `pull-node`, and `pull-uv` create an empty file automatically. However, `pull-runtimes` requires the `--update` flag to write — running without it produces an error.

**GitHub API rate limits:**

Without a token the GitHub API allows 60 requests an hour, and a registry pull of a few dozen apps uses more. A rate limit that asks for a short wait (a `Retry-After` header, or a reset within two minutes) is waited out and retried; one that resets later is reported at once, with the reset time, and the run goes on with the next app and exits non-zero. Set the `GITHUB_TOKEN` environment variable to authenticate and raise the limit:

```bash
export GITHUB_TOKEN=ghp_your_token_here
datamitsu devtools pull-releases config/src/binaryApps.json --update
```

**Hash mismatches:**

If `verify-all` reports a hash mismatch, investigate the changed upstream
artifact before changing the expected hash. For release manifests, update manual
`hashes` or `checksums` pins only from independently trusted upstream metadata.
For a re-released tag using native API digests, clear the affected generated
entry's `configHash` to force discovery while preserving its archive-path history.
An unchanged tag and config hash skip discovery; `--update` alone does not
refresh manual pins. Then pull and verify again:

```bash
datamitsu devtools pull-releases config/src/binaryApps.json --verify-extraction
datamitsu devtools verify-all
```

**Network errors:**

Release and package devtools require network access to their configured forge, npm or PyPI. If you're behind a proxy, ensure `HTTPS_PROXY` is set. For intermittent failures, retry the command — downloads are idempotent.

## cache

Manage the per-project cache for linting and fixing operations.

### cache clear

Clear cache data.

```bash
datamitsu cache clear
```

| Flag        | Description                                             |
| ----------- | ------------------------------------------------------- |
| `--all`     | Clear all project caches (not just the current project) |
| `--dry-run` | Show what would be deleted without deleting             |

:::warning This removes project source-mode farms

A project's [source-mode](../guides/source-mode.md) farm and manifest live in the
same per-project cache directory, so `cache clear` deletes them along with the
lint/fix caches. Every shell already activated for that project then reports exit
127 for every declared tool — the shim deliberately does not re-bake a farm that
is not there. Run `datamitsu source refresh` (or re-activate) afterwards, and use
`--dry-run` first to see what would go.

[Machine-level farms](../how-to/machine-level-toolchain.md) created with
`datamitsu source --config <path>` live in a separate `configs/` namespace and are
**not** removed by `cache clear`, not even with `--all`. Rebuild one deliberately
with `datamitsu source refresh --config <path> --force`.

:::

`cache clear` also drops this project's [cached config
evaluations](../guides/architecture/startup.md#the-config-evaluation-cache)
(`{cache}/config-eval/projects/{hash}`); `--all` drops the whole `config-eval`
tree, including the machine-level `--config` chains whose farms survive. Clearing
them costs one re-evaluation and nothing else.

### cache path

Print the absolute path to the global cache directory.

```bash
datamitsu cache path
```

### cache path project

Print the absolute path to the current project's cache directory.

```bash
datamitsu cache path project
```

## store

Manage the global binary and runtime store.

### store path

Print the absolute path to the global store directory.

```bash
datamitsu store path
```

### store clear

Remove the entire global store directory, including binaries, runtimes, app
environments, bundles, parsers, package-manager data, managed Python
installations, and remote configs.

```bash
datamitsu store clear
```

:::warning
This removes all downloaded and installed managed content. You will need to run
`datamitsu init` again (and re-run lazy apps on demand) afterward.
:::

### store seed

Pull the [OCI bundle](/docs/guides/oci-bundles) declared by the config's top-level `oci` key into the global store — no docker/podman required. Without arguments the **whole** bundle is pulled (airgap seeding); with `--apps` only the layers of the named tools plus their runtime dependencies are pulled.

```bash
# Full pull from the config's oci declaration
datamitsu store seed

# Selective pull
datamitsu store seed --apps golangci-lint,prettier

# Explicit digest-pinned reference (overrides the config)
datamitsu store seed ghcr.io/owner/tool-store@sha256:0123…cdef
```

| Flag            | Description                                                                       |
| --------------- | --------------------------------------------------------------------------------- |
| `--apps <list>` | Seed only the layers of these apps and their runtime dependencies (repeatable)    |
| `--resolve-tag` | Allow a `:<tag>` reference: resolve it to a digest first and print it for pinning |

Every manifest body and blob is verified against its SHA-256 descriptor before extraction; seeded single-file binaries and JVM jars are additionally re-hashed against the published hashes from the config. A repeated full pull is a no-op (zero network requests).

Blob downloads have no overall timeout — only an attempt that delivers zero bytes for 2 minutes is aborted and retried, so large layers on slow links finish instead of being cut off mid-stream. The `store` commands also work without a usable git context (no `git` binary, `dubious ownership` in containers): a broken project repo only skips the project-level config with a warning.

### store status

Show what the declared bundle contains for this platform and which configured apps it covers versus which still require the network.

```bash
datamitsu store status
datamitsu store status --json
```

### store refs

List every artifact the effective config fetches from outside the machine: OCI references (the bundle and any registry-sourced parser modules) first, then the hash-pinned https downloads. It answers "what do I have to mirror?" and touches no network, so it runs inside a firewall.

```bash
# Everything this config pulls from anywhere
datamitsu store refs

# Just the registry side — the input to a mirroring loop
datamitsu store refs --oci-only | xargs -n1 -I{} crane copy {} harbor.corp/dm/{}

# Every artifact with its mandatory hash and platform
datamitsu store refs --json | jq '.https[] | select(.kind == "app-binary")'
```

| Flag         | Description                                                           |
| ------------ | --------------------------------------------------------------------- |
| `--json`     | Emit the references as JSON, including each artifact's mandatory hash |
| `--oci-only` | List only OCI references, omitting the hash-pinned https downloads    |

The output is sorted and byte-stable, so it is safe to pipe or diff between
config revisions. Managed runtime binaries declared by the effective config,
including the native pnpm archives of the pnpm runtime, are included. Package-manager dependencies
fetched later by pnpm, UV, or Go are not
individual entries; their exact versions and integrity data live in each app's
mandatory lock file.

### store import

Seed the store from a local [OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) directory (as produced by `crane pull --format=oci`, `oras copy --to-oci-layout`, or `skopeo copy`) — fully offline bundle transfer. Blobs are verified against the digest chain exactly like a registry pull.

```bash
datamitsu store import ./bundle-layout
datamitsu store import ./bundle-layout --digest sha256:0123…cdef
```

## version

Print the version number.

```bash
datamitsu version
```

## completion

Generate a shell-completion script for Bash, Zsh, Fish, or PowerShell.

```bash
datamitsu completion bash
datamitsu completion zsh
datamitsu completion fish
datamitsu completion powershell
```

The command writes the script to stdout. Run
`datamitsu completion <shell> --help` for the installation instructions for
that shell.

## llms

Print this documentation as plain markdown, for feeding to an AI agent.

The docs are compiled into the binary, so they always match the version you are
running and are served without network access. Content goes to stdout and
diagnostics to stderr, so the output pipes straight into a model's context.

With no arguments it prints an index of every page, where each entry is the exact
argument that fetches it — an agent can read the index and choose its next call
without knowing anything about the site's URLs.

```bash
# Index of every available page
datamitsu llms

# One page, by its documentation path
datamitsu llms about
datamitsu llms contributing/brand-guidelines

# A unique page name may be abbreviated
datamitsu llms brand-guidelines

# A directory's own page is addressed by the directory
datamitsu llms getting-started/installation

# A URL copied from the website works too
datamitsu llms https://datamitsu.com/docs/guides/architecture/caching.md
```

Flags:

| Flag     | Description                                            |
| -------- | ------------------------------------------------------ |
| `--list` | List every page slug, one per line                     |
| `--json` | Emit JSON instead of markdown                          |
| `--web`  | Print the standard `llms.txt` index, with website URLs |

```bash
# Machine-readable page list, with titles and descriptions
datamitsu llms --list --json

# Provenance of the embedded snapshot
datamitsu llms --json | jq .pageSetHash

# One page as JSON, body included
datamitsu llms about --json
```

Exit codes: `0` on success, `2` for a usage error, `3` for an unknown or
ambiguous page. An unknown page suggests the nearest matches on stderr and
leaves stdout empty, so a failed fetch never pollutes a pipe.

## lsp

Run a Language Server Protocol server on stdin/stdout, so an editor can format
files through datamitsu's configured tools.

```bash
datamitsu lsp
```

This is normally launched by an editor rather than by hand — see the
[VS Code extension](../getting-started/installation/vscode.md) for the packaged
integration.

The server answers document formatting and nothing else. It serves one
repository, which it takes from the editor at `initialize` (see
[lsp root](#lsp-root)), and it picks up a changed configuration by itself, with
no restart (see [lsp configuration reload](#lsp-configuration-reload)).

A format request runs the project's fix tools on the real file, in place, so a
format also saves the file. A buffer with unsaved changes is written to disk
first, and the response holds the edits from that buffer to the fixed result.
That write goes through a temporary file, with the original's permissions,
renamed over the original, so it never leaves a truncated file behind, and it
replaces the file a symlink points to, not the symlink. A buffer that already
matches the file on disk gets an empty edit list: the fix is only on disk, and
the client has to reload the file. VS Code does so by itself. In Neovim, run
`:edit` after formatting; until then the buffer still shows the text from
before the format.

stdout carries only JSON-RPC. stderr carries only [JSON-L events](#lsp-events),
whatever `--log-format` says: status, progress, and log lines alike. `--verbose`
sets the log level to `debug`, so datamitsu's `info` and `debug` lines join the
stream as `log` events, never as plain text.

### lsp root

One server serves one repository for its whole life. At `initialize` it starts
from the first of these that the editor sends:

1. the first entry of `workspaceFolders`;
2. `rootUri`;
3. `rootPath`;
4. none of them: the directory the server was started in.

From there it resolves the repository root the way the CLI does — the git root,
climbing out of a submodule to its topmost superproject — changes into that
root, and loads the configuration there. The `initialize` result names the root
in `capabilities.experimental.datamitsu.root` (see the
[echo](#lsp-initialization-options)). Relative `--config` and `--before-config`
paths are resolved once, against the directory the server was started in,
before it changes directory.

File URIs are percent-decoded, and on Windows `file:///C:/x` is read as `C:\x`.
The root and every document path are compared after resolving symlinks, so a
workspace opened through a symlink formats like any other. A document outside
the served repository is not formatted: the server answers with an empty edit
list before planning or installing anything, and logs one `info` notice per
document per session.

The first workspace folder decides the repository, and every folder inside that
repository is served with it. For each other folder whose repository differs,
the server logs one `info` notice saying it does not format that folder. The
server does not advertise workspace-folder support, so an editor does not add
folders to a running server: one that wants several repositories formatted
starts one server for each.

Neither a missing repository nor a configuration that does not load stops the
server or fails `initialize`. `initialize` succeeds, one `log` event at level
`error` names the cause, and the session serves nothing: a format request gets
an empty edit list rather than an error, so the editor does not raise one on
every save, and the `error` is repeated once per distinct cause rather than on
every request. Once the configuration is fixed, the next format request loads
it.

### lsp configuration reload

The server picks up a changed configuration by itself. At the start of every
format request — before planning, because formatting the config file itself
changes it — it compares the contents of the configuration's inputs with what
it read at the last load:

- every file of the configuration chain: the discovered `datamitsu.config.*`,
  the configs it layers on (a shared config package in `node_modules`
  included), and any `--config` or `--before-config` file;
- the checkout's `HEAD` (`.git/HEAD`, or a linked worktree's own), so a branch
  switch counts;
- `pnpm-lock.yaml` at the root, so an install that bumps a shared config
  package counts;
- every auto-config file name at the root, present or not, so a second
  `datamitsu.config.*` appearing counts.

A server started with `--no-auto-config` discovers no config at the root, so it
compares only the files of its `--config` chain.

It compares content, not modification times, so an edit within the same second
counts, and a file reached through a symlink is compared by what it points to.
A file that appears or disappears counts as a change too. When nothing changed,
the request proceeds. When something did, the server loads the configuration
again:

- **It loads.** The server replaces everything it built from the old
  configuration — tools, planner, execution cache (the old cache is flushed
  first) — and resolves the
  [`initializationOptions`](#lsp-initialization-options) the editor sent at
  `initialize` again, so a `format.tools` entry for a tool the new configuration
  adds now applies. It logs `configuration reloaded` at `info`, followed by the
  policy line, and logs the option warnings again.
- **It fails.** Saving a half-edited config is the normal case. The session
  keeps the configuration that last loaded, logs one `warn` saying the
  configuration changed but failed to load, with the cause, and keeps
  formatting with the previous configuration. The same content is not loaded or
  reported again on the next save; only a further change is.
- **No session yet**, because the configuration did not load at `initialize`: a
  successful load starts one.

A reload writes nothing: it does not run `datamitsu init`. When the new
configuration changes an
[ejectable config](configuration-api.md#keeping-configs-out-of-the-repository-ejectable--ejectconfigs)
— what it renders to, or whether the project ejects it — a format that would run
a tool reading that config fails the managed-config preflight until the files
match the configuration again. The error names the command to run:
`datamitsu init` for a changed render. A tool the new configuration adds is
installed by the first format that needs it, like any other. The repository the
server serves, its command-line flags and its environment stay as they were
when it started.

### lsp format policy

A format request plans `fix` for the saved file, then decides for each operation
whether it runs from the editor. The first matching rule wins; the reason is what
the server logs for a tool it leaves out:

| Rule                                                 | Result                                 | Logged reason                                                         |
| ---------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
| The operation has `lsp: false`                       | Left out                               | `lsp: false in config`                                                |
| `format.tools[name]` is `false`                      | Left out                               | `disabled by format.tools`                                            |
| Granularity `repo`                                   | Left out, whatever `format.tools` says | `repository-wide, never on save`                                      |
| Granularity `unit`, a project without the saved file | Left out                               | Not logged                                                            |
| Granularity `unit`, no `globs`, no opt-in            | Left out                               | `declares no globs, so it cannot tell which files it formats`         |
| Granularity `unit`, level below `unit`               | Left out                               | `project-wide, editor policy is target` or `project policy is target` |
| Granularity `unit`, otherwise                        | Runs over the saved file's project     | —                                                                     |
| Granularity `file`                                   | Runs on the saved file                 | —                                                                     |

A `unit` operation that declares no `globs` is planned for every file of its
project, so it would claim every save there, whatever the file's type: saving a
TypeScript file that lives in a Go module would run a glob-less
`golangci-lint fmt` over the whole module. It is left out unless
`format.tools[name]` is `true`. An author fixes it at the source by adding
`globs` (such as `["**/*.go"]`), so only the files it formats bring it in. A tool
whose result for one file does not depend on its neighbours can also take
`{files}` and declare `granularity: "file"`, so a save runs it on the saved file
alone.

The level of a `unit` operation is the project's
[`execution.widenTo.fix`](configuration-api.md#executionwidento) when
`format.tools[name]` is `true`, and otherwise the narrower of that and
`format.widenTo`. An opt-in therefore lifts the session's `target`, never the
project's. `lsp: true` on an operation is the same as leaving it unset. A tool
the policy leaves out is never downloaded.

`format.timeoutMs` is a watchdog, not a deadline. The plan runs one
[priority group](../guides/architecture/execution.md#two-layer-execution-model)
at a time, and once the limit has elapsed no further group starts. The first
group always runs, a running tool is never interrupted, and downloads and
installs happen before the clock starts. When it fires, a warning names the file,
how many groups ran, and the tools that did not; the response still reflects
what is on disk. A cancel, unlike the watchdog, can stop a format before its
first group: see [lsp cancellation](#lsp-cancellation).

### lsp cancellation

The server keeps reading messages while a format runs, so it sees a
`$/cancelRequest` at once. Requests still run one at a time, in the order they
arrived. Document changes that arrive during a format are applied as they come
in, and a format request works on the text the document had when the request
arrived.

A cancelled request is always answered with `RequestCancelled` (`-32800`), never
with an error an editor would show. A request still waiting its turn never runs.
A running format stops at its next checkpoint: at the start, after planning,
after the managed-config preflight, after its tools are installed, before the
unsaved buffer is written, and before each priority group, the first one
included. A cancel never interrupts a running tool: killing a formatter that
rewrites a file in place can leave that file truncated. It does not abort a
download or install already under way either — the next save needs that tool
anyway — so the request stops once it is done.

What a cancelled format leaves on disk depends on when the cancel arrived:

| The cancel arrives                                  | The file on disk                                                   |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| Before the unsaved buffer is written                | Unchanged; the unsaved text stays in the editor only               |
| After the buffer is written, before the first group | The unsaved text, unformatted                                      |
| While a priority group runs                         | Fixed by that group and every group before it; no later group runs |

Each `tool_run` that started still gets its closing event, since the tool ran to
completion. One `info` notice names the file and, once a tool group has run, how
many ran and the tools that did not; a cancel before the first group only says
that no tool ran. `done` closes the request with `status: "fail"`,
`success: false` and `msg: "cancelled"`. The results of the tools that ran are
cached as usual.

Stopping the server uses the same checkpoints:

- **`shutdown`** — the running format stops at its next checkpoint, every
  format request still waiting is answered `RequestCancelled`, and any other
  request still waiting is handled as usual, so a queued `initialize` still
  initializes. `shutdown` is answered once nothing runs. Requests after it are
  answered `InvalidRequest` (`-32600`). `exit` ends the process: status `0`
  after `shutdown`, `1` without it.
- **stdin closes, or its framing breaks** (a header without a valid
  `Content-Length`, for example) — the running format stops at its next
  checkpoint, waiting requests are dropped without a reply, the execution cache
  is flushed, and the server exits. A message whose body is not valid JSON is
  not a framing error: it is answered with a parse error, and the server keeps
  serving.
- **`SIGTERM` or an interrupt** — the first one does the same as stdin closing.
  A second one stops the running tool as well and exits at once, which can leave
  a file that tool was rewriting incomplete.

On Unix the server ignores `SIGPIPE`, so an editor that goes away in the middle
of a format cannot kill the server through a closed stdout or stderr.

### lsp initialization options

The server reads `initializationOptions` at `initialize` and keeps them: a
[configuration reload](#lsp-configuration-reload) resolves them again against
the new configuration.

```ts
interface DatamitsuInitializationOptions {
  format?: {
    widenTo?: "target" | "unit";
    timeoutMs?: number; // non-negative integer; 0 disables the watchdog
    tools?: Record<string, boolean>; // keyed by tool name in the config's `tools`
  };
}
```

Each key is resolved on its own, highest first: `initializationOptions`, then the
environment, then the default.

| Key                | Values                                  | Environment variable              | Default |
| ------------------ | --------------------------------------- | --------------------------------- | ------- |
| `format.widenTo`   | `target` or `unit`                      | `DATAMITSU_LSP_FORMAT_WIDEN_TO`   | `unit`  |
| `format.timeoutMs` | Milliseconds, integer `>= 0`; `0` = off | `DATAMITSU_LSP_FORMAT_TIMEOUT_MS` | `15000` |
| `format.tools`     | Tool name to `true` or `false`          | —                                 | `{}`    |

- **`widenTo`** — `repo` is refused: a repository-wide fix never runs on save.
  The environment variable set to `repo` or to an unknown value means `unit`.
- **`timeoutMs`** — a negative or unparsable environment value means `15000`.
- **`tools`** — `false` keeps a tool out. `true` runs a project-wide tool under
  `widenTo: "target"`, or one that declares no `globs`, but never beyond the
  project's `execution.widenTo.fix`, never for a repository-wide tool, and never
  against `lsp: false`.

A bad option never fails `initialize`. A value of the wrong type, a `widenTo`
of `repo`, a negative or fractional `timeoutMs`, a non-boolean `tools` entry, a
`tools` entry naming no configured tool, or an unknown key inside `format` is
ignored with a warning: a rejected `widenTo` or `timeoutMs` falls back to the
environment or the default, and a rejected `tools` entry has no effect. A
`tools` entry naming a tool the configuration does not have yet applies once a
reload adds that tool; the warnings are logged again with each reload. Unknown
top-level keys are ignored silently.

The `initialize` result echoes the policy the session runs with and the
repository it serves, under `capabilities.experimental`. `tools` holds the
entries the server accepted, and `root` is the
[resolved repository root](#lsp-root), absent when the server found none:

```json
{
  "capabilities": {
    "experimental": {
      "datamitsu": {
        "format": { "widenTo": "unit", "timeoutMs": 15000, "tools": {} },
        "root": "/work/example"
      }
    }
  }
}
```

The echo is not repeated after a reload; the policy line the reload logs is the
current one.

In Neovim 0.11 or later, `init_options` is sent as `initializationOptions`:

```lua
vim.lsp.config("datamitsu", {
  cmd = { "datamitsu", "lsp" },
  root_markers = { "datamitsu.config.ts", "datamitsu.config.mjs", "datamitsu.config.js" },
  init_options = {
    format = { widenTo = "target", timeoutMs = 5000, tools = { eslint = false } },
  },
})
vim.lsp.enable("datamitsu")
```

Neovim sends the directory `root_markers` finds as the workspace folder, and the
server serves that directory's repository, wherever Neovim itself was started.
When no marker is found, Neovim sends no folder, and the server falls back to
the directory it was started in.

### lsp events

Every stderr line is one JSON object carrying `type` and `op_id`, with
`--verbose` or without. The stream opens with a `hello` event, as a `--log-format jsonl`
stream does (see [Run events](#run-events)). The language server never emits
`diagnostic` events: an editor gets findings through `publishDiagnostics`. It
emits:

| `type`                | Meaning                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `log`                 | A human-readable notice in `msg`, with `level` `debug`, `info`, `warn` or `error`                                  |
| `phase`               | `op: "format"`, `status: "start"`: opens each format request the server starts running; no `phase` event closes it |
| `download`, `install` | Tool provisioning progress                                                                                         |
| `tool_run`            | A tool task starting and ending: `tool`, `dir` (relative to the git root), `success`, `duration_ms`                |
| `error`               | A tool task that failed: `tool`, `dir`, `msg`                                                                      |
| `done`                | Closes the request's phase, under its `op_id`, failed and cancelled requests included: `status` `done` or `fail`   |

`done` also carries `op: "format"`, `success`, `duration_ms`, `tools`, `runs`,
`failed` and `skipped`. `tools` counts the distinct tools that ran and `failed`
the distinct tools with a failed task; `runs` counts the tasks that ran and
`skipped` the tasks the policy, the watchdog or a cancel left out. One tool failing in two
projects therefore gives `runs: 2` and `failed: 1`. A counter or `duration_ms`
that is zero is left out of the line rather than written as `0`: read a missing
one as zero. A `tool_run` op id is the format request's op id followed by
`:<tool>:<dir>:<seq>`, `seq` numbering the tasks of one priority group from 1,
so a consumer can attribute every task to its request. Every
task that starts also gets its closing `tool_run`, in a cancelled request too. A
cancelled request's `done` has `status: "fail"`, `success: false` and
`msg: "cancelled"`: there is no separate status for it.

`log` events carry the session's own notices:

- **At `initialize`:** one `info` with the effective policy
  (`format policy: widenTo=unit timeoutMs=15000 tools={}`), naming the keys that
  came from `initializationOptions`; one `warn` per rejected option; one `info`
  for each other workspace folder in a different repository; and an `error` when
  there is no repository or the configuration does not load.
- **Per format request:** one `info` listing the tools the policy left out and
  why, when there are any. A `warn` also marks a save the watchdog stopped, and
  an `info` a cancelled one. A document outside the served repository gets one
  `info`, once per session. With no session, the `error` from `initialize` is
  repeated, once per distinct cause.
- **On a configuration change:** `configuration reloaded` at `info`, followed by
  the policy line, with the option warnings logged again; or one `warn` when the
  changed configuration fails to load.

Once per session, and once more after each reload, a cache on disk that the
session will not write is reported too. Written by a different `datamitsu`
version — the editor runs another binary than the CLI — it is an `info`: the two
simply do not share cache entries. Written for a different configuration — for
example by a run with `--tools`, or while a changed configuration fails to load
in the session — it is a `warn`. Formatting works in both cases; it just does
not warm the cache.

Log lines from the rest of datamitsu — config loading, tool provisioning — are
`log` events too, each with its own op id, at its own level: `warn` and `error`
by default, `debug` and `info` as well with `--verbose` or a lower
`DATAMITSU_LOG_LEVEL`. `msg` carries the line's message followed by its fields.

## source

Put the project's declared toolchain on `PATH` for the current shell, so every
tool runs as an ordinary command at the version this repository pins.

```bash
# bash / zsh
eval "$(datamitsu source bash)"
eval "$(datamitsu source zsh)"

# fish
datamitsu source fish | source
```

Activation downloads nothing — a tool is fetched the first time it is actually
run. Switching branches needs no re-activation: the next tool invocation notices
the config changed and re-resolves itself.

`source` requires a project. Run inside a repository whose git root holds a
`datamitsu.config.{js,mjs,ts}`, or name one explicitly with the global
`--config` flag; outside a project it exits non-zero and writes nothing to
stdout.

stdout carries shell code and nothing else, so the output is always safe to
`eval`. Warnings — tools not downloaded yet, system binaries this shadows — go
to stderr.

`--no-auto-config` without a `--config` is refused: activating the built-in
default config would bake a handful of built-in apps into the farm this root's
real config owns. `--before-config` and `--no-auto-config` also bypass the
manifest fast path and re-resolve the config, and a farm baked with them is not
reused by a later plain `datamitsu source` — a manifest baked from a different
config chain would otherwise activate a toolchain the plain invocation never
asked for.

If the farm cannot be re-baked at all — a config that does not evaluate on this
branch, a remote config unreachable offline — activation warns on stderr,
activates the farm already on disk and **exits 0**. Emitting nothing would exit 0
with a shell that was never activated, and every declared tool would then fall
through `PATH` to whatever the system has. `source refresh` is the repair command
and inverts this: a failed bake exits non-zero, leaving the previous farm in
place, so a CI step can trust `refresh`'s exit code but not `source`'s.

### source --config: a machine-level toolchain

```bash
# outside any repository, e.g. from a shell rc file
datamitsu source fish --config ~/.config/datamitsu/datamitsu.config.ts | source
eval "$(datamitsu source bash --config ~/.config/datamitsu/datamitsu.config.ts)"
```

With the global `--config` flag the toolchain comes from a config you name rather
than from a project, so `source` works outside any git repository. `status` and
`refresh` take the same flag and act on the same farm.

Such a farm's origin is `explicit-config`, and it differs from a project farm in
two ways:

|           | `git-root`                       | `explicit-config`                                             |
| --------- | -------------------------------- | ------------------------------------------------------------- |
| identity  | the git root                     | XXH3-128 of the resolved config chain                         |
| farm path | `{cache}/cache/projects/{hash}/` | `{cache}/cache/configs/{hash}/`                               |
| watch set | config chain + `.git/HEAD`       | the config chain                                              |
| shim      | re-resolves from cwd's git root  | revalidates its own recorded chain, never walks up for `.git` |

The chain is resolved to absolute paths with symlinks followed before hashing, so
a relative, an absolute and a symlinked spelling of the same file are one farm.
Order is significant, and `--before-config` files are part of the chain rather
than a modifier of it.

An explicit-config activation never merges a discovered config, even when it runs
inside a repository: the chain is exactly what was named, and every re-bake the
shim spawns carries `--no-auto-config` for the same reason. Unlike the other
config flags, `--config` does **not** bypass the manifest fast path — a config
farm's manifest lives at the path the chain itself hashes to, so the only
manifest such an invocation can find is one baked from those very files.

**The trust boundary:** an explicit-config farm never evaluates a project's
config. A shell activated against a machine-level config that `cd`s into an
untrusted clone keeps running the machine-level tools; entering a repository's
toolchain still requires running `datamitsu source` there. This is a security
property, not an omission — a config is evaluated JavaScript.

Both farms can be active at once. Layering is `PATH` order and nothing else: the
project farm sits ahead of the config farm, so the project's pin wins, and a name
only the machine-level config declares stays reachable from inside the project.

Activation exports `DATAMITSU_FARM` and `DATAMITSU_FARM_CONFIG`, and deliberately
no `DATAMITSU_ROOT` — there is no git root, and an empty one would read as "the
repository could not be determined".

See [Machine-Level Toolchain](../how-to/machine-level-toolchain.md) for the
full walkthrough.

### source status

```bash
datamitsu source status
datamitsu source status --json
datamitsu source status --config ~/.config/datamitsu/datamitsu.config.ts
```

Reports the farm for the current project: its origin, its root and directory, whether the
baked manifest still matches the working tree, every tool the farm provides with
how it is materialized (`shim`) and whether it has been downloaded
yet, every declared name that was refused **with the reason**, and every system
binary the farm shadows with the absolute path it was found at.

Names are never silently dropped, which is what makes this the first command to
run when a tool is missing or resolves to the wrong version: a refused name is
listed with its reason, so it can never be confused with a name that was never
declared.

`--json` emits the same information as a single document and writes no human
text to stdout; warnings still go to stderr. `origin` is always present; a
`git-root` farm reports `root`, an `explicit-config` farm reports `configPaths`
and prints `config:` lines in place of `root:`.

`status` resolves and reports. It never downloads and never re-bakes the farm.

### source refresh

```bash
datamitsu source refresh
datamitsu source refresh --force
datamitsu source refresh --config ~/.config/datamitsu/datamitsu.config.ts --force
```

Re-resolves the project's declared apps and rewrites the farm the current shell's
`PATH` points at. With `--config` it acts on that chain's machine-level farm
instead.

Nothing normally needs this. A tool invocation notices on its own that the config
changed and re-bakes before running, which is what makes branch switching
invisible. `refresh` exists for the case that detection cannot see: the staleness
check watches the config chain's files and `.git/HEAD`, so a config that branches
on an environment variable outside datamitsu's own namespace — reachable through
`facts().env` — changes what it produces without changing anything the check
compares. `--force` re-bakes unconditionally and is the escape hatch for exactly
that.

Without `--force`, a farm that already matches the tree is left alone and the
command exits 0.

Refresh resolves and materializes; it downloads nothing. A tool that has not been
fetched yet stays a shim entry and installs on its first real use.

The summary goes to stderr and stdout stays empty, so `refresh` is safe to call
from the same shell function that runs an activation through `eval`.

## Environment Variables

| Variable                             | Description                                                                                                                                    | Default                                             |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `DATAMITSU_CACHE_DIR`                | Custom base directory; ephemeral data goes in `{base}/cache`, downloaded artifacts in `{base}/store`                                           | `$XDG_CACHE_HOME/datamitsu` or `~/.cache/datamitsu` |
| `DATAMITSU_CONCURRENCY`              | Number of concurrent download workers                                                                                                          | `3`                                                 |
| `DATAMITSU_INSTALL_TIMEOUT`          | Per-app install timeout in seconds (`0` = disabled)                                                                                            | `600`                                               |
| `DATAMITSU_MIN_RELEASE_AGE`          | Minimum release age in minutes for `pull-*` and the Go lock-file check (`0` = disabled)                                                        | `10080`                                             |
| `DATAMITSU_MAX_CMD_LENGTH`           | Maximum command-line length before a list-taking operation is split into chunks                                                                | `32000`                                             |
| `DATAMITSU_MAX_ERROR_CMD_DISPLAY`    | Maximum command length shown in an error before truncation                                                                                     | `120`                                               |
| `DATAMITSU_MAX_PARALLEL_WORKERS`     | Maximum parallel tool execution workers                                                                                                        | `max(4, floor(NumCPU * 0.75))`, capped at 16        |
| `DATAMITSU_UNIT_CACHE_TTL`           | Minutes a cached unit-level verdict stays trusted; `0` disables verdict caching                                                                | `1440` (24h)                                        |
| `DATAMITSU_FAIL_FAST`                | Stop `fix`, `lint` and `check` at the first failing tool (`true`/`1`) or run everything (`false`/`0`)                                          | `true`                                              |
| `DATAMITSU_FAIL_ON`                  | Raise every operation's `failOn` for `fix`, `lint` and `check` to `error`, `warning`, `info` or `hint`; never lowers one (twin of `--fail-on`) | -                                                   |
| `DATAMITSU_REPORT`                   | Reports `fix`, `lint` and `check` write, as comma-separated `format=path` pairs (twin of `--report`; see [Reports](#reports))                  | -                                                   |
| `DATAMITSU_ALLOW_PARTIAL`            | Write a report that lists findings for a narrowed run (`true`/`1`) instead of refusing it (twin of `--allow-partial`)                          | `false`                                             |
| `DATAMITSU_EVENTS`                   | Which findings the JSON-L stream of `fix`, `lint` and `check` emits: `diagnostics=reported` or `diagnostics=all` (twin of `--events`)          | `diagnostics=reported`                              |
| `DATAMITSU_ANNOTATIONS`              | Whether `fix`, `lint` and `check` print CI annotations: `auto`, `github`, `azure`, `teamcity` or `off` (twin of `--annotations`)               | `auto`                                              |
| `DATAMITSU_OUTPUT`                   | How `fix`, `lint` and `check` show their results: `human` or `agent` (twin of `--output`)                                                      | `human`                                             |
| `DATAMITSU_CONFIG_CACHE`             | Serve evaluated config chains from disk (`0`/`false`/`off`/`no` disables it)                                                                   | `1`                                                 |
| `DATAMITSU_LSP_FORMAT_WIDEN_TO`      | How far editor format-on-save may widen: `target` or `unit`                                                                                    | `unit`                                              |
| `DATAMITSU_LSP_FORMAT_TIMEOUT_MS`    | Format-on-save watchdog in ms: no further tool group starts once it has elapsed (`0` = disabled)                                               | `15000`                                             |
| `DATAMITSU_LOG_LEVEL`                | Log level (`debug`, `info`, `warn`, `error`)                                                                                                   | `warn`                                              |
| `DATAMITSU_LOG_FORMAT`               | Status output format (`console`, or newline-delimited `jsonl` with log lines as `log` events)                                                  | `console`                                           |
| `DATAMITSU_TIMINGS`                  | Enable detailed planner/runner timings (`1` = enabled)                                                                                         | `0`                                                 |
| `DATAMITSU_STARTUP_TIMINGS`          | Report per-phase startup/config-load durations to stderr (`1` = enabled)                                                                       | `0`                                                 |
| `DATAMITSU_TRACE`                    | Record a full execution trace and print its summary (`1` = enabled)                                                                            | `0`                                                 |
| `DATAMITSU_TRACE_DIR`                | Directory for execution trace files                                                                                                            | `{cache}/traces`                                    |
| `DATAMITSU_FORCE_GIT_SUBPROCESS`     | Resolve the git root by forking `git` instead of walking the filesystem (`1` = enabled)                                                        | `0`                                                 |
| `DATAMITSU_BINARY_COMMAND`           | Override binary command path                                                                                                                   | -                                                   |
| `DATAMITSU_NO_SPONSOR`               | Suppress sponsor messages (any non-empty value)                                                                                                | -                                                   |
| `DATAMITSU_OFFLINE`                  | Refuse all network access (any non-empty value; requires a pre-seeded store)                                                                   | -                                                   |
| `DATAMITSU_NO_OCI`                   | Disable OCI bundle store **seeding** (any non-empty value; twin of `--no-oci`)                                                                 | -                                                   |
| `DATAMITSU_NO_PARSE`                 | Show tools' raw output instead of parsed findings; parsing still runs (twin of `--no-parse`)                                                   | -                                                   |
| `DATAMITSU_MAX_PARSE_INPUT_BYTES`    | Bytes of each output stream of one tool process a parser reads; a longer stream is cut and the process is `truncated`                          | `8388608` (8 MiB)                                   |
| `DATAMITSU_MAX_FINDINGS_PER_PROCESS` | Findings kept from one tool process's output; the rest are dropped and the process is `truncated`                                              | `10000`                                             |
| `DATAMITSU_LIBC`                     | Override host libc detection (`glibc` or `musl`); affects store paths and OCI bundle selection                                                 | auto-detected                                       |
| `DATAMITSU_OCI_REGISTRY`             | Registry host for base-image digest resolution in `devtools dockerfile`                                                                        | `ghcr.io`                                           |
| `DATAMITSU_PARSERS_DIR`              | Override directory for downloaded WASM output-parser modules                                                                                   | `{store}/.parsers`                                  |
| `DATAMITSU_ROOT`                     | Git root of the source-mode farm activated in this shell (exported by `datamitsu source`)                                                      | -                                                   |
| `DATAMITSU_FARM`                     | Farm directory activated in this shell (exported by `datamitsu source`)                                                                        | -                                                   |
| `DATAMITSU_FARM_CONFIG`              | Config chain of the farm activated in this shell (exported by `datamitsu source --config`)                                                     | -                                                   |
| `NO_COLOR`                           | Disable color output                                                                                                                           | -                                                   |
| `FORCE_COLOR`                        | Force color output                                                                                                                             | -                                                   |

`DATAMITSU_ROOT` and `DATAMITSU_FARM` are written by `datamitsu source`. Neither
is used to resolve a tool — the shim discovers the repository root from the
working directory, so a tool run in another repository resolves against that
repository, not against the one the shell was activated in. `DATAMITSU_ROOT` is
purely informational; `DATAMITSU_FARM` is read in one place, to recognize that an
invocation arrived through a farm directory when the computed cache path and the
activated one spell the same directory differently (a `DATAMITSU_CACHE_DIR` or
`HOME` that resolves differently in this process). Without it a genuine tool
invocation could be mistaken for a renamed `datamitsu` binary and handed to the
CLI. `DATAMITSU_FARM_CONFIG` is written only by an `explicit-config` activation,
which exports no `DATAMITSU_ROOT` because it has no git root; it records the
config chain the farm was baked from, joined with the platform's list separator,
and is informational in the same way. All three are excluded from the farm's
staleness fingerprint, so exporting them cannot make a farm look stale.
`DATAMITSU_FAIL_FAST`, `DATAMITSU_FAIL_ON`, `DATAMITSU_REPORT`,
`DATAMITSU_ALLOW_PARTIAL`, `DATAMITSU_EVENTS`, `DATAMITSU_ANNOTATIONS` and `DATAMITSU_OUTPUT` are excluded too: they change how far one run goes and what it prints or writes, never what a
farm contains, so setting one for one command does not re-bake the farm.

`DATAMITSU_FORCE_GIT_SUBPROCESS` applies to the config loader's memoized git-root
lookup, which is where the pure-Go walk runs; the command handlers use a separate
resolver that always forks `git`. See
[Startup and Config Load](../guides/architecture/startup.md).

:::note `--no-oci` is not a network switch
`--no-oci` / `DATAMITSU_NO_OCI` turns off OCI bundle **store seeding** — an
accelerator that degrades gracefully to fetching each artifact individually. It
does **not** disable a parser that declares an `oci` source: that is not an
accelerator but the only route to those bytes, so disabling it would leave no
way to get the module at all.

`DATAMITSU_OFFLINE` is the hard gate. It refuses every network operation,
including a registry-sourced parser, and expects a pre-seeded store.
:::

---

## Comparison with Similar Tools


**TL;DR:**
Others run tools. **datamitsu defines what those tools are.**

- mise → runtime versions
- moon / Nx → task orchestration
- datamitsu → **toolchain distribution**

The only tool here that can package and distribute a complete, configured toolchain.

## Different Layer, Different Problem

```
WHAT gets run
↑
datamitsu (toolchain definition & distribution)

------------------------------

WHEN / HOW it runs
mise (versions)
moon / Nx (execution)
```

**Others run tools. datamitsu defines what those tools are.**

- **mise:** "Switch to Node 18 in this directory" (runtime flexibility)
- **moon/Nx:** "Run these tasks in the right order" (build optimization)
- **datamitsu:** "Everyone uses ESLint 8.57 with this config" (toolchain standardization)

## The Missing Layer for Toolchain Distribution

datamitsu occupies a category that didn't exist: **toolchain distribution as code.**

**What this means:**

- You build a package (`@company/dev-standards`)
- That package bundles tools + managed config rules
- Teams install it like any dependency (`npm install @company/dev-standards`)
- Everything is configured automatically

**This is not a feature. This is the category.**

No other tool here can:

- package a full toolchain
- distribute it via npm/gem/pypi
- apply it across projects automatically

### The Only Tool That Packages Toolchains

mise can't do this. moon can't do this. Nx can't do this.

**datamitsu is the only tool in this comparison that can:**

1. Bundle tools + configs into a package
2. Distribute that package via npm/gem/pypi
3. Have teams install it like any dependency
4. Auto-configure everything on installation

This isn't a feature. It's the entire point.

**Result:** You build your toolchain once, distribute it everywhere. Teams consume it via familiar package managers (npm/gem/pypi). Updates propagate via version bumps.

## Quick Reference: Tool Categories

| Tool          | Layer    | What It Does                            |
| ------------- | -------- | --------------------------------------- |
| **datamitsu** | WHAT     | Distributes toolchains as packages      |
| **mise**      | WHEN/HOW | Switches runtime versions per-directory |
| **moon**      | WHEN/HOW | Orchestrates monorepo builds            |
| **Nx/Turbo**  | WHEN/HOW | Optimizes JavaScript build caching      |

## mise: Runtime Flexibility vs Toolchain Standardization

[mise](https://mise.jdx.dev/) manages tool versions on a per-directory basis. It's great at runtime flexibility.

**mise solves a different problem entirely.**

- **mise:** "I need Node 18 here, Node 20 there" (per-developer flexibility)
- **datamitsu:** "Everyone uses these exact tools with these configs" (team standardization)

**Can You Use Both?**

Yes. They operate at different layers:

- **mise manages runtime versions** (Node 18 in this directory, Node 20 in that directory)
- **datamitsu delivers configured tools** (ESLint with company rules)

Example:

```bash
mise use node@20              # mise handles version
datamitsu check               # datamitsu provides tools
```

**When to use datamitsu instead of mise:**

- You need to **distribute tools as packages** (npm/gem/pypi)
- **Security and hash verification** are mandatory (CI/CD, compliance)
- You're **building config packages** for company-wide standards

**When to use mise instead of datamitsu:**

- You need **per-directory runtime versions** for individual developers
- You want a **personal, per-developer toolchain** that follows you across unrelated repositories

**Both activate a shell — at different layers:**

Shell activation is not a reason to pick one over the other. [`datamitsu source`](/docs/guides/source-mode) puts the **project's pinned, hash-verified, config-distributed toolchain** on `PATH`; `mise activate` puts **per-developer runtime versions** on `PATH`. They answer different questions and compose:

```bash
mise use node@20                  # which Node runtime this directory gets
eval "$(datamitsu source bash)"    # the team's pinned tools, as ordinary commands
tofu plan                          # the version this repository pins
```

The mechanisms differ where it matters. `mise activate` installs a prompt hook, so a version change is picked up when a prompt renders. datamitsu's activation revalidates on every tool invocation instead, which is what makes `git checkout v2 && tofu plan` — one line, no prompt in between — run v2's version. And a name the project declares but cannot resolve exits 127 rather than falling through to a system binary.

## moon: Build Orchestration vs Tool Delivery

[moon](https://moonrepo.dev/moon) orchestrates builds in large monorepos. It's great at build optimization.

**moon operates at a different layer.**

- **moon:** "Build these packages in dependency order, cache artifacts" (build optimization)
- **datamitsu:** "Deliver these verified tools with these configs" (tool delivery)

**Can You Use Both?**

Yes. They operate at different layers:

- **datamitsu delivers the tools** (golangci-lint, prettier, eslint)
- **moon orchestrates running those tools** (dependency order, caching)

Example monorepo setup:

```bash
datamitsu init       # Download all linters
moon run :lint       # Run linting in optimal order
```

**When to use datamitsu instead of moon:**

- Your primary need is **tool delivery**, not build orchestration
- You want to **distribute standardized configs** as packages
- You're **building config packages** for company-wide use

**When to use moon instead of datamitsu:**

- You have a **large monorepo** with complex build dependencies
- **Optimizing CI/CD build times** is the primary goal

## Nx/Turborepo: JavaScript Build Systems

[Nx](https://nx.dev/) and [Turborepo](https://turbo.build/) are JavaScript monorepo build systems. They're great at optimizing builds.

**Nx/Turbo focus on a different concern.**

- **Nx/Turbo:** "Run tasks in the right order with caching" (build optimization)
- **datamitsu:** "Deliver ESLint/Prettier/etc. with company configs" (tool delivery)

**Can You Use Both?**

Yes. They complement each other:

- **datamitsu delivers and configures tools** (ESLint, Prettier, TypeScript)
- **Nx/Turbo optimizes running those tools** (caching, parallelization)

Example:

```json
// Nx project.json uses datamitsu
{
  "targets": {
    "lint": {
      "executor": "nx:run-commands",
      "command": "datamitsu lint"
    }
  }
}
```

**When to use datamitsu instead of Nx/Turbo:**

- You need **multi-language support** (Go, Rust, Python, JVM, Node.js)
- You want to **build config packages** to distribute via npm/gem/pypi

**When to use Nx/Turbo instead of datamitsu:**

- You have a **JavaScript/TypeScript monorepo**
- **Build speed optimization** is the primary goal

## What datamitsu IS

datamitsu is **not** a task runner, runtime manager, or build system.

datamitsu **is** the missing layer for toolchain distribution:

### Security-First by Design

Every binary downloaded from the internet must have a SHA-256 hash. No exceptions. No bypassing. Hash verification happens before extraction.

### JavaScript-Based Configuration with Inheritance

Layer configurations from base → company → team → project:

```javascript
// Wrapper provides base
export const baseConfig = {...}

// Project overrides
export function getConfig(prev) {
  // Disable tool for this project
  delete prev.apps['some-linter']
  return prev
}
```

### Docker CI/CD Optimization

Pre-cache all tools in a Docker layer:

```dockerfile
RUN npm install -g @company/datamitsu-config
RUN datamitsu init --all
# Layer cached — only changed tools re-download
```

## Frequently Asked Questions

### "Why not just use mise?"

**Answer:** mise manages tool versions for individual developers. datamitsu distributes standardized configs for entire teams. **Different problems.** Use both together.

### "Why not just use moon?"

**Answer:** moon orchestrates builds in large monorepos. datamitsu delivers and configures linting/tooling. **Different layers.** Use moon to orchestrate, datamitsu to deliver.

### "How is this different from Nx/Turborepo?"

**Answer:** Nx and Turborepo are build system orchestrators. datamitsu is a tool delivery platform. **They can work together:** Nx runs tasks, datamitsu provides tools.

### "Can I use datamitsu WITH mise/moon/Nx?"

**Answer:** **Yes!** They solve different problems:

- **datamitsu:** Delivers verified tools + configs
- **mise:** Switches runtime versions
- **moon/Nx/Turbo:** Orchestrates builds

They're complementary, not competitive.

## Real-World Combination Example

Here's how a team might use datamitsu with other tools:

```bash
# Developer setup
mise use node@20                    # mise manages Node version
npm install @company/dev-standards  # datamitsu wrapper installed

# Initialize tools
datamitsu init                      # Download all linters/formatters

# Reconcile project config, then run fix
datamitsu config reconcile

# Development
moon run :lint                      # moon orchestrates linting task
                                    # which uses datamitsu-provided tools
```

**Result:**

- **mise** ensures developers use Node 20
- **datamitsu** provides ESLint, Prettier, golangci-lint with company configs
- **moon** runs linting across monorepo projects efficiently

Each tool does what it does best.

## Learn More

- [About datamitsu](../about.md) — Why datamitsu exists and what makes it unique
- [Creating Wrappers](../contributing/creating-wrappers.md) — Build your own config distribution
- [Using Wrappers](../guides/using-wrappers.md) — Consume wrapper packages
- [Core Concepts](../getting-started/core-concepts.md) — Understand the architecture

---

## Configuration API


datamitsu uses JavaScript configuration files powered by the [goja](https://github.com/dop251/goja) JavaScript runtime. Configuration is defined in `datamitsu.config.js`, `datamitsu.config.mjs`, or `datamitsu.config.ts` at your git repository root.

## Required Exports

Every config file must export:

- **`getMinVersion()`** — Returns a semver string specifying the minimum datamitsu version required. Checked before `getConfig()` is called. Configs without this function fail to load.
- **`getConfig(config)`** — Receives the previous layer's config and returns a new `Config` object.
- **`version`** — Required top-level configuration release label, validated after all layers resolve. It must be nonempty, one line, at most 80 characters, with no leading or trailing whitespace. It may be a package release version or a static label such as `core`; semver is not required. It is inherited as a scalar and may be overridden by later layers. It is independent of `getMinVersion()`, which names the minimum compatible datamitsu core version.
- **`getRemoteConfigs()`** _(optional)_ — Returns remote parent configs to load before this config.
- **`getBeforeConfigs()`** _(optional)_ — Returns local config files to load as under-layers, the config-declared equivalent of the `--before-config` flag. Honoured **only** in the auto-discovered git-root config, and **not evaluated** when a `--before-config` flag is passed (the flag wins).

```typescript
function getMinVersion(): string;
function getConfig(config: Config): Config;
function getRemoteConfigs(): Array<{ url: string; hash: string }>;
function getBeforeConfigs(): Array<{ path: string }>;
```

The special version `"dev"` (used when running from source) is treated as `v0.0.0`.

## Config Structure

The `getConfig()` function returns a `Config` object:

```typescript
interface Config {
  version: string;
  name?: string;
  apps?: BinManager.MapOfApps;
  runtimes?: BinManager.MapOfRuntimes;
  bundles?: Record<string, Bundle>;
  tools?: MapOfTools;
  parsers?: Record<string, Parser>;
  lsp?: Record<string, LspProxy | LspDerived>;
  projectTypes?: MapOfProjectTypes;
  managedConfigs?: MapOfManagedConfigs;
  ejectConfigs?: string[];
  initCommands?: MapOfInitCommands;
  ignoreRules?: string[];
  sharedStorage?: Record<string, string>;
  execution?: {
    widenTo?: Partial<Record<"fix" | "lint", "target" | "unit" | "repo">>;
  };
  oci?: OCIReference;
}
```

## Config Loading Order

Configuration is loaded in layers, each receiving the previous result as input:

```text

default (embedded config.js)
↓ [getRemoteConfigs() resolved depth-first, if exported]
--before-config flags (for wrappers/libraries)
↓ [getRemoteConfigs() resolved depth-first]
declared before-configs (auto config's getBeforeConfigs(), only when no --before-config flag)
↓ [getRemoteConfigs() resolved depth-first]
auto (datamitsu.config.{js,mjs,ts} at git root)
↓ [getRemoteConfigs() resolved depth-first]
--config flags (for CI/testing overrides)
↓
final Config

```

- Each source must export `getMinVersion()` — version is checked before `getConfig()` runs (fail-fast)
- Each source can export `getRemoteConfigs()` returning `Array<{url: string, hash: string}>` for recursive parent resolution. The `hash` is a SHA-256 digest — canonical form recommended; a bare or uppercase value is accepted and normalized there
- The auto git-root config can export `getBeforeConfigs()` returning `Array<{path: string}>` to load local files as under-layers (parity with `--before-config`). It is honoured only at the git-root layer and skipped entirely when a `--before-config` flag is present; relative paths resolve against the git-root config's directory, no hash is required (local files are not downloads)
- `ignoreRules` use append semantics across config layers
- Circular remote config dependencies are detected and produce an error

## Configuration Version (`version`)

Every resolved configuration requires a top-level version label. It must be
nonempty, one line, at most 80 characters, with no leading or trailing
whitespace. A package release version is suitable, but semver is not required:
a static label such as `core` is also valid. The embedded default supplies
`core`; a layer that discards the input config must supply its own value.

The field is inherited as a normal scalar and later layers may override it;
the loader validates only the final resolved value. This identifies the
configuration release, not a core compatibility declaration: `getMinVersion()`
independently returns the semver minimum datamitsu core version each source
requires. Existing configs without a version fail to load.

## Name (`name`)

How the configuration names itself wherever one is displayed — the inspector header, an exported
snapshot, a listing. It chains as a scalar: the last layer that sets it wins.

```javascript
export function getConfig(input) {
  return { ...input, name: "@acme/datamitsu-config" };
}
```

When no layer sets it, the name is `datamitsu.config`. A name is one line of at most 80 characters;
a blank string is a config error rather than a silent fallback, so a layer cannot half-clear it.
The field is display metadata: it never affects what is installed or executed.

## Apps (`apps`)

Apps define the tools datamitsu manages. The app kind is determined by which sub-object is present (`binary`, `bun`, `uv`, `node`, `jvm`, `go`, or `shell`).

### App Kinds

| Kind     | Sub-object | Description                                       |
| -------- | ---------- | ------------------------------------------------- |
| `binary` | `binary`   | Self-managed binaries downloaded from URLs        |
| `bun`    | `bun`      | npm packages installed and executed with Bun      |
| `uv`     | `uv`       | Python packages installed via managed UV runtime  |
| `node`   | `node`     | npm packages installed via managed Node.js + pnpm |
| `jvm`    | `jvm`      | Java applications executed via managed JDK        |
| `go`     | `go`       | Go tools built from source via managed Go SDK     |
| `shell`  | `shell`    | Shell commands with custom environment            |

### App Names

A key in `apps` must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`. That means no
path separators, no leading `-`, not `.` or `..`, and not a Windows reserved
device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`). Two names
differing only by case — `Git` and `git` — are rejected as a collision, because a
case-insensitive filesystem would collapse them into one file.

The rule exists because an app name is not just a lookup key: it becomes a file
name in the store and, under [source mode](../guides/source-mode.md), a file name
in a directory placed on `PATH`.

This is a hard validation error on every command, not a warning and not
source-mode-specific: a config using a name outside this set fails to load.

### Common App Fields

All app kinds share metadata, environment, and version-check fields. The common
schema also exposes managed-content fields, but config validation accepts
`files`, `links`, and `archives` only on Bun, UV, Node, and Go apps (for a Go
app they carry the module source — the [source-blob form](#go-apps)).

```typescript
interface AppCommon {
  description?: string; // Human-readable text shown in app listings
  required?: boolean; // Whether the app is required for init
  lazy?: boolean; // Defer installation and link creation until first exec
  dependsOn?: AppDependency[]; // Apps that must be available when this app runs
  officialUrl?: string; // Where a person reads about this app (never fetched)
  files?: Record<string, string>; // Bun/UV/Node/Go only: filename → static content
  links?: Record<string, string>; // Bun/UV/Node/Go only: linkName → relativePath
  archives?: Record<string, ArchiveSpec>; // Bun/UV/Node/Go only: name → archive
  env?: Record<string, string>; // Install-time and run-time environment
  runtimeEnv?: Record<string, string>; // Execution-only environment (all app kinds)
  versionCheck?: {
    disabled?: boolean; // Skip version check in verify-all
    args?: string[]; // Override default ["--version"] args
  };
}
```

`lazy: true` keeps a user-invoked app out of `datamitsu init`; its environment
and `.datamitsu/` links are created on the first `datamitsu exec`. Apps consumed
by tools, hooks, or managed config files must remain eager (omit `lazy` or set
it to `false`). A selected app's dependencies are still installed even when
they are `lazy: true` or not `required`.

#### Where to read about an app (`officialUrl`)

`officialUrl` is a link for people: the app's documentation, its repository, its
package page. Nothing downloads it, runs it, or verifies it, and it takes no part
in an install. It must be an absolute `http` or `https` URL; validation checks
the shape and nothing else, because the URL is never fetched.

It inherits like any other scalar — a child layer overrides it, and removing it
uses the config's existing undefined semantics.

Leave it out and datamitsu derives one at config resolution from what the app
already declares. A derived link is reported as `officialUrl` alongside
`officialUrlDerived: true`, so `datamitsu config show`, the inspector dataset and
the inspector's app panel can tell a maintainer's choice from an address worked
out from a download URL:

| Declaration                                           | Derived link                           |
| ----------------------------------------------------- | -------------------------------------- |
| `binary` whose download URLs are on one forge         | that repository's page                 |
| `node` or `bun` with a package name                   | `https://www.npmjs.com/package/<name>` |
| `uv` with a package name                              | `https://pypi.org/project/<name>/`     |
| `go` with a module path                               | `https://pkg.go.dev/<module>`          |
| `jvm` with a Maven Central JAR URL                    | that artifact's Maven Central page     |
| `jvm` with a forge-hosted JAR URL                     | that repository's page                 |
| `shell`, or anything the rules above do not recognize | none                                   |

The forges whose release paths name a repository unambiguously are `github.com`,
`gitlab.com`, `codeberg.org` and `gitea.com`. A binary whose platforms point at
different repositories derives nothing: there is no single page to send a reader
to. There is no network lookup and no guessing — a shape the rules do not
recognize yields no link rather than one that might be wrong.

Set the field to point somewhere better than the default:

```javascript
apps: {
  eslint: {
    node: { packageName: "eslint", version: "9.0.0", binPath: "node_modules/.bin/eslint" },
    // Without this, the derived link is the npm page.
    officialUrl: "https://eslint.org/docs/latest/",
  },
}
```

#### App dependencies (`dependsOn`)

`dependsOn` names other apps that must be installed before this app runs.
Each entry is an app name or an object that also names the role under which
this app refers to the dependency in `${APP_BIN:<alias>}` bindings; the alias
defaults to the app name and must be unique among this app's direct
dependencies (case-insensitive).

```typescript
type AppDependency = string | { app: string; as?: string };
```

```javascript
const apps = {
  "doc-lint": {
    binary: docLintBinary,
    // "shellcheck" binds as "shellcheck"; jsonschema binds as "validator"
    dependsOn: ["shellcheck", { app: "jsonschema", as: "validator" }],
    runtimeEnv: { VALIDATOR_BIN: "${APP_BIN:validator}" },
  },
};
```

Provisioning expands selected roots to their transitive dependency closure,
installs dependencies before dependents, and deduplicates shared dependencies.
This applies to `init`, `install`, `exec`, planner tools (`check`, `lint`, `fix`),
LSP tools, and OCI seeding (`store seed --apps`). Init still selects its normal
roots; a dependency need not have `required: true` and cannot opt out with `lazy`.

Every name must exist in `apps`. Self-references, duplicate names in one list,
and cycles are validation errors; cycle errors show the dependency chain.
Aliases follow the app-name pattern (`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`), and
one edge per target app keeps the alias unambiguous. Shell apps may declare
dependencies but cannot be dependency targets, because core cannot install a
host PATH command.

A dependency is a run-time availability contract. Neither `dependsOn` nor
`runtimeEnv` changes the app's install identity: changing either does not
reinstall otherwise unchanged app contents. Execution caches include the full
config, so these changes still invalidate cached tool results.

**Dependencies on `PATH`.** When an app runs, every native binary app in its
`dependsOn` closure is on `PATH` under its app name, ahead of the inherited
`PATH` and behind the directories a runtime owns (a managed node's `bin/`), so
a dependency can never displace the app's own interpreter. A tool that looks a
helper up by name therefore finds the pinned one:

```javascript
const apps = {
  // a Dockerfile linter that runs ShellCheck by looking up `shellcheck` on PATH
  "dockerfile-lint": { binary: dockerfileLintBinary, dependsOn: ["shellcheck"] },
  shellcheck: { binary: shellcheckBinary },
};
```

The store names each binary by its config hash, so datamitsu links them under
their app names in a directory of their own
(`{store}/.dependency-path/<hash>/`), with `.exe` appended on Windows. The
directory is named after the exact set of links it holds, so a dependency bump
produces a new directory rather than rewriting one a running process uses.

- The **whole closure** is linked, not only direct dependencies: a dependency
  invoked by name runs straight from the store, without a directory of its own,
  so it would otherwise miss its own helpers.
- Only **native binary** apps are linked, the same targets `${APP_BIN:…}`
  accepts. A runtime-managed app needs a command and arguments that a `PATH`
  entry cannot carry, and a shell app already resolves through the inherited
  `PATH`.
- A dependency called by name runs with the calling app's environment; its own
  `env` and `runtimeEnv` apply only when datamitsu runs it directly.
- A tool operation's own `env` is applied last and can still override `PATH`.
- On Windows the entries are symbolic links where the account may create them
  (Developer Mode or elevation) and hard links otherwise.
- In source mode the directory is a health path of the app's shim: if it is
  missing (for example after `datamitsu store clear`), the shim repairs it
  through an install instead of running a tool that cannot find its helpers.
  A repair adds the missing entries in place and never replaces the directory,
  since a running tool may still be using it.

#### Custom environment variables (`env`)

The optional `env` field applies to **every** app kind (binary, bun, uv, node,
jvm, go, shell). It is injected both at **install time** (for the bun/uv/node/go
dependency-install phase) and at **run time** (every app type).

Values support placeholder expansion, performed in Go and never written into the
committed config:

- `${STORE}` → the shared datamitsu store path (cleaned by `datamitsu store clear`).
- `${APP_DIR}` → this app's install directory (per-app, config-hashed).
- `${APP_BIN:<name>}` is available only in `runtimeEnv`, as described below.

**Precedence:** any key the runtime itself sets for the app wins. A user
config can never relocate the pnpm store, uv cache, `GOPATH`, etc. Variables
merely inherited from the calling environment are not protected: an `env` or
`runtimeEnv` key replaces the inherited value.

`PATH` is rejected in both `env` and `runtimeEnv`, in any letter case. Values
are not expanded against the inherited environment, so a `PATH` entry would
replace the inherited `PATH` wholesale. To put a binary on `PATH`, list it in
`dependsOn` (see above).

```javascript
const apps = {
  slidev: {
    node: {
      packageName: "@slidev/cli",
      // ...
    },
    // Redirect playwright to download browsers into the datamitsu store
    env: { PLAYWRIGHT_BROWSERS_PATH: "${STORE}/.playwright/browsers" },
  },
};
```

> **Migration (alpha breaking change):** `env` was previously a field on
> `AppConfigShell` (`shell.env`). It has moved to the top-level `env` field
> shared by all app kinds. Move any `shell: { env: {...} }` up one level to
> `env: {...}` on the app.

#### Execution-only environment (`runtimeEnv`)

Use `runtimeEnv` for values needed when the app executes, including version
checks, shims, `exec`, planner tools, and LSP tools. Installers never receive it.
As with `env`, keys the runtime sets for the app win, inherited values do not,
and `PATH` is rejected. A key present in both `env` and `runtimeEnv` on the same
app is a validation error.

Values support `${STORE}` and `${APP_DIR}`, plus `${APP_BIN:<alias>}`: the exact
executable path of a binary, uv or go app — the kinds with a single executable
entry point. The target must be in this app's **direct** `dependsOn` list
(by name or alias). A transitive edge alone is insufficient. Runtime apps
(node, bun, jvm) and shell apps are rejected as binding targets: they need a
launcher that does not exist yet.

When the app declares a `prepare` step, `runtimeEnv` also supports
`${APP_PREPARED}`: the app's prepared-state directory
(`{store}/.prepared/<app>/<key>/out`), the same tree the step filled. Subpaths
are allowed (`${APP_PREPARED}/browsers`). Using it without a declared step, or
in `env` (which installers see), is a validation error.

```javascript
runtimeEnv: {
  UPSTREAM: "${APP_BIN:dm-internal-lefthook-upstream}",
  DATA_DIR: "${APP_DIR}/data",
}
```

Bindings remain symbolic in the evaluated-config cache. Resolution computes
paths without downloading, installing, or spawning a process; an unresolved
binary or an unsupported platform is an error. `${APP_DIR}` keeps its existing
best-effort behavior when an app has no managed install directory.

Empty or unterminated `${APP_BIN:...}` bindings and unknown colon forms such as
`${FOO:bar}` are validation errors in `runtimeEnv` values. `${APP_BIN` in app
`env` values is rejected with a message directing you to `runtimeEnv`. Other
config data and environment keys are not APP_BIN expansion sites; documentation
or file contents can contain the literal syntax.

See [Wrapping a private binary](../how-to/maintain-wrapper.md#wrapping-a-private-binary)
for a complete binding example and the source-farm repair contract.

#### One-time preparation step (`prepare`)

`prepare` declares a step that runs **once**, after the app and its whole
`dependsOn` closure are installed, to fill the app's prepared state: data the
app would otherwise download lazily at first run — a schema catalog, a browser,
a compiled artifact. Run time exposes the result as `${APP_PREPARED}`.

```typescript
interface AppPrepare {
  args: string[]; // required, may be empty
  env?: Record<string, string>;
  binPath?: string; // another executable of this app's own install
  network: boolean; // required
  path?: "declared" | "inherit"; // default "declared"
}
```

The step is the app's own executable run directly, without a shell. The
prepared state lives in `{store}/.prepared/<app>/<key>/out`, keyed by the app
identity, its dependency closure, and the step description — a new dependency
version or a changed argument list prepares a new state, and identical
configurations share one. The state is project-independent: it is shared by
every project of the user and ships in OCI bundles.

**Placeholders.** `args` and `env` accept `${APP_PREPARED}` (the directory the
step fills), `${APP_DIR}`, and `${APP_BIN:<alias>}` (a direct dependency).
`${STORE}` and every project-bound tool placeholder (`{root}`, `{cwd}`,
`{file}`, `{files}`, `{target}`, `{toolCache}`) are validation errors: the
prepared state cannot depend on a project. Everything the step needs must be
spelled out explicitly — the inherited environment is available for proxies
and credentials, but it is not part of the key, so a step that reads a
behavior-changing variable from it may produce different states on different
machines. Neutralize such variables with explicit arguments.

**Network and offline.** `network` is required. Under `DATAMITSU_OFFLINE`, an
unprepared step that needs the network is refused before the process starts.

**PATH.** `path: "declared"` (default) limits the step to the runtime's own
directories and the binaries of its dependency closure — nothing from the host.
Use `"inherit"` when the step genuinely needs host utilities; the choice is
part of the key.

**Isolation.** `PATH`, `TMPDIR`, `TEMP`, `TMP`, `XDG_CACHE_HOME`,
`XDG_DATA_HOME` and `XDG_STATE_HOME` are rejected in `prepare.env`: datamitsu
points them at throwaway directories inside the step layout. `XDG_CONFIG_HOME`
and `HOME` stay available — tools read registry credentials through them.

**Version requirement.** A config layer using `prepare`, object
`dependsOn` edges or `${APP_PREPARED}` must raise its `getMinVersion()`:
an older core silently drops the field and hands the app a literal
`${APP_PREPARED}`. Datamitsu warns when it sees the construction without the
matching minimum version.

### Binary Apps

Binary apps download platform-specific executables with hash verification.

```javascript
const apps = {
  "golangci-lint": {
    binary: {
      version: "2.1.0",
      binaries: {
        linux: {
          amd64: {
            glibc: {
              url: "https://github.com/golangci/golangci-lint/releases/download/v2.1.0/golangci-lint-2.1.0-linux-amd64.tar.gz",
              hash: "sha256:abc123...", // canonical SHA-256 digest (mandatory)
              contentType: "tar.gz",
              binaryPath: "golangci-lint-2.1.0-linux-amd64/golangci-lint",
            },
          },
        },
        darwin: {
          arm64: {
            unknown: {
              url: "https://github.com/golangci/golangci-lint/releases/download/v2.1.0/golangci-lint-2.1.0-darwin-arm64.tar.gz",
              hash: "sha256:def456...",
              contentType: "tar.gz",
              binaryPath: "golangci-lint-2.1.0-darwin-arm64/golangci-lint",
            },
          },
        },
      },
    },
  },
};
```

**Binary-specific fields:**

```typescript
interface AppConfigBinary {
  version?: string;
  binaries: Partial<
    Record<OsType, Partial<Record<ArchType, Partial<Record<LibcType, BinaryOsArchInfo>>>>>
  >;
}

interface BinaryOsArchInfo {
  url: string;
  hash: string; // Canonical SHA-256 digest "sha256:<64 lowercase hex>" (mandatory)
  contentType: BinContentType;
  binaryPath?: string; // Path to binary within archive; with extractDir, the command inside the directory (required)
  extractDir?: boolean; // Extract entire archive to directory and run binaryPath inside it (tar or zip only)
}
```

The `binaries` map uses a three-level nested structure: `os → arch → libc → BinaryOsArchInfo`. Linux platforms use `"glibc"` or `"musl"` as the libc key; non-Linux platforms use `"unknown"`.

**Supported platforms:** `darwin/amd64/unknown`, `darwin/arm64/unknown`, `linux/amd64/glibc`, `linux/amd64/musl`, `linux/arm64/glibc`, `linux/arm64/musl`, `freebsd/amd64/unknown`, `openbsd/amd64/unknown`, `windows/amd64/unknown`, `windows/arm64/unknown`

**Supported archive types:** `tar.gz`, `tar.xz`, `tar.bz2`, `tar.zst`, `tar`, `zip`, `gz`, `bz2`, `xz`, `zst`, `binary`

**How `binaryPath` selects an archive entry:** an entry whose path equals `binaryPath` wins, then one whose path ends in `/<binaryPath>`, then one with the same file name. Among entries that match equally well, an executable entry beats a plain file, and an entry in a `bin/` directory beats one elsewhere; only then does archive order decide. A bare `binaryPath: "buf"` therefore extracts `buf/bin/buf`, not `buf/etc/bash_completion.d/buf`. Prefer the full path all the same: it leaves nothing to choose.

### UV Apps (Python)

UV apps install Python packages in isolated environments using the managed UV runtime.

```javascript
const apps = {
  yamllint: {
    uv: {
      packageName: "yamllint",
      version: "1.35.1",
      requiresPython: ">=3.12", // optional, defaults to ">=3.12"
      lockFile: "br:...", // brotli-compressed lock file (required)
      runtime: "uv-default", // optional runtime override
    },
  },
};
```

**UV-specific fields:**

```typescript
interface AppConfigUV {
  packageName: string;
  version: string;
  requiresPython?: string; // Defaults to ">=3.12"
  lockFile: string; // Brotli-compressed with "br:" prefix (required)
  runtime?: string; // Runtime name override
}
```

### Bun Apps

Bun apps install npm packages with pnpm and execute their JavaScript entrypoint with the managed Bun runtime. pnpm runs as a native binary and its lifecycle scripts reach Bun through a `node` alias, so a Bun app does not require a Node runtime for installation.

```javascript
const apps = {
  eslint: {
    bun: {
      packageName: "eslint",
      version: "10.9.0",
      binPath: "node_modules/eslint/bin/eslint.js",
      dependencies: {
        typescript: "6.0.2",
      },
      lockFile: "br:...", // brotli-compressed pnpm-lock.yaml (required)
      runtime: "bun-default", // optional runtime override
    },
  },
};
```

```typescript
interface AppConfigBun {
  binPath: string; // JavaScript entrypoint; node_modules/.bin shims are rejected
  packageName: string;
  version: string;
  lockFile: string; // pnpm-lock.yaml, optionally compressed with "br:" (required)
  dependencies?: Record<string, string>;
  runtime?: string; // Runtime name override
}
```

Installs run the pinned native `pnpm install --frozen-lockfile` with the same hardened `pnpm-workspace.yaml` policy as Node apps. Execution uses `bun run --bun --no-install <binPath>` so Node-shebang commands stay on the selected Bun runtime and Bun cannot fetch dependencies on first run.

### Node Apps (Node.js/npm)

Node apps install npm packages using the managed Node.js runtime and pnpm.

```javascript
const apps = {
  eslint: {
    node: {
      packageName: "eslint",
      version: "9.27.0",
      binPath: "node_modules/.bin/eslint",
      dependencies: {
        "typescript-eslint": "^8.32.0",
        "@eslint/js": "^9.27.0",
      },
      lockFile: "br:...", // brotli-compressed lock file (required)
      runtime: "node-default", // optional runtime override
    },
    links: {
      "eslint-config": "dist/eslint.config.js",
    },
  },
};
```

**Node-specific fields:**

```typescript
interface AppConfigNode {
  binPath: string; // Path to binary (e.g., "node_modules/.bin/eslint")
  packageName: string;
  version: string;
  lockFile: string; // Brotli-compressed with "br:" prefix (required)
  dependencies?: Record<string, string>;
  runtime?: string; // Runtime name override
}
```

### JVM Apps (Java)

JVM apps download JAR files and execute them via a managed JDK.

```javascript
const apps = {
  "openapi-generator-cli": {
    jvm: {
      version: "7.12.0",
      jarUrl:
        "https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.12.0/openapi-generator-cli-7.12.0.jar",
      jarHash: "sha256:abc123...", // canonical SHA-256 digest (mandatory)
      runtime: "jvm-default",
    },
  },
};
```

**JVM-specific fields:**

```typescript
interface AppConfigJVM {
  version: string;
  jarUrl: string;
  jarHash: string; // Canonical SHA-256 digest "sha256:<64 lowercase hex>" (mandatory)
  mainClass?: string; // When set, uses java -cp instead of java -jar
  runtime?: string; // Runtime name override
}
```

### Go Apps

Go apps build a command-line tool from source using the managed Go SDK. The lock file carries both `go.mod` and `go.sum` so the build is reproducible and hash-verified.

```javascript
const apps = {
  govulncheck: {
    go: {
      packageName: "golang.org/x/vuln/cmd/govulncheck",
      version: "v1.3.0",
      lockFile: "br:...", // brotli-compressed lock file (required)
      runtime: "go-default", // optional runtime override
    },
  },
};
```

**Go-specific fields:**

```typescript
interface AppConfigGo {
  packageName: string; // Go import path, e.g. "golang.org/x/vuln/cmd/govulncheck"
  version: string; // Module version query, e.g. "v1.3.0"
  lockFile: string; // Brotli-compressed JSON {"mod","sum"} with "br:" prefix (required)
  runtime?: string; // Runtime name override
}
```

The tool is built with `go build -trimpath -mod=readonly` in an isolated, hardened environment. See the [Supply Chain Security](../guides/supply-chain-security.md#go-go-apps) guide for the full defense model.

**Shipping your own program as a source blob.** A Go app may carry its module source in `files`/`archives` (the same inline/external [archive form](#archives) other app kinds use). The source is staged into the app directory before the build, the lock file's `go.mod`/`go.sum` overwrite any files of the same name, and `packageName` points at the package **inside** the shipped module:

```javascript
const apps = {
  "my-gen": {
    go: {
      packageName: "example.com/mygen/cmd/mygen", // package inside the shipped module
      version: "v0.1.0",
      lockFile: "br:...", // go.mod + go.sum of the shipped module itself
    },
    archives: { main: { inline: "tar.br:..." } }, // the module source
  },
};
```

The lock file must describe the shipped module (generate it with `datamitsu config lockfile`, which stages the source and runs `go mod tidy` against **its** `go.mod`), so the build compiles the blob, never a remote package that happens to share the name. The archive content folds into the app's install identity — new source means a new install path. A module on the standard library alone legitimately has an **empty `go.sum`**; a module that imports something without a checksum entry still fails the `-mod=readonly` build.

### Shell Apps

Shell apps wrap system commands. Set environment variables through the shared
top-level [`env` field](#custom-environment-variables-env).

```javascript
const apps = {
  "my-script": {
    shell: {
      name: "bash",
      args: ["-c", "echo hello"],
    },
    env: { MY_VAR: "value" },
  },
};
```

**Shell-specific fields:**

```typescript
interface AppConfigShell {
  name: string; // Command name
  args?: string[]; // Default arguments
}
```

## Bundles (`bundles`)

Bundles store static content (files, archives) in a hash-keyed directory in the
global store and expose it through `.datamitsu/` symlinks. Unlike apps, bundles
are not executable.

```typescript
interface Bundle {
  version?: string;
  files?: Record<string, string>;
  archives?: Record<string, ArchiveSpec>;
  links?: Record<string, string>;
}
```

| Field      | Type                          | Description                                             |
| ---------- | ----------------------------- | ------------------------------------------------------- |
| `version`  | `string`                      | Version identifier (changes trigger cache invalidation) |
| `files`    | `Record<string, string>`      | Filename to content mapping                             |
| `archives` | `Record<string, ArchiveSpec>` | Named archives (inline or external)                     |
| `links`    | `Record<string, string>`      | Link name to relative path in install dir               |

A bundle must have at least `files` or `archives`. Link names must be unique across both apps and bundles.

Link values can point to files or directories within the install dir. Use `"."` to link to the entire bundle directory.

**Example:**

```javascript
const bundles = {
  "agent-skills": {
    version: "1.0",
    files: {
      "agents.md": "# Agent instructions...",
      "skills/search.md": "# Search skill...",
    },
    links: {
      "agent-skills-dir": ".", // link to entire bundle directory
      "agents-md": "agents.md", // link to a single file
    },
  },
};
```

Install path: `{store}/.bundles/{name}/{hash}/`

See [Managed Content (Bundles)](../guides/managed-content.md) for a full guide.

## Runtimes (`runtimes`)

Runtimes define how language-specific package managers are provisioned.

```typescript
interface RuntimeConfig {
  kind: "bun" | "node" | "uv" | "jvm" | "go" | "pnpm";
  mode: "managed" | "system";
  managed?: RuntimeConfigManaged; // Required for managed mode
  system?: RuntimeConfigSystem; // For system mode
  bun?: RuntimeConfigBun; // Required when kind is "bun"
  node?: RuntimeConfigNode; // Required when kind is "node"
  uv?: RuntimeConfigUV; // When kind is "uv"
  jvm?: RuntimeConfigJVM; // Required when kind is "jvm"
  go?: RuntimeConfigGo; // Required when kind is "go"
  pnpm?: RuntimeConfigPNPM; // Required when kind is "pnpm" (managed mode)
}
```

### Managed Mode

In managed mode, datamitsu downloads the runtime binary itself:

```javascript
const runtimes = {
  "node-default": {
    kind: "node",
    mode: "managed",
    managed: {
      binaries: {
        linux: {
          amd64: {
            glibc: {
              url: "https://nodejs.org/dist/v26.2.0/node-v26.2.0-linux-x64.tar.xz",
              hash: "sha256:abc123...", // canonical SHA-256 digest (mandatory)
              contentType: "tar.xz",
              binaryPath: "node-v26.2.0-linux-x64/bin/node",
              extractDir: true,
            },
          },
        },
        // ... other platforms
      },
    },
    node: {
      nodeVersion: "26.2.0",
      pnpmRuntime: "pnpm", // the runtime below installs this runtime's apps
    },
  },
  pnpm: {
    kind: "pnpm",
    mode: "managed",
    managed: {
      binaries: {
        linux: {
          amd64: {
            glibc: {
              url: "https://github.com/pnpm/pnpm/releases/download/v12.4.1/pnpm-linux-x64.tar.gz",
              hash: "sha256:def456...", // canonical SHA-256 digest (mandatory)
              contentType: "tar.gz",
              binaryPath: "pnpm",
              extractDir: true,
            },
          },
        },
        // ... other platforms
      },
    },
    pnpm: {
      pnpmVersion: "12.4.1",
    },
  },
};
```

### System Mode

In system mode, the runtime uses the system-installed version:

```javascript
const runtimes = {
  "uv-system": {
    kind: "uv",
    mode: "system",
    system: {
      command: "uv",
      systemVersion: "1.0", // Bump to invalidate cache
    },
    uv: {
      pythonVersion: "3.12",
    },
  },
};
```

### Runtime Kind Configuration

**Bun Runtime:**

```typescript
interface RuntimeConfigBun {
  bunVersion: string; // e.g., "1.4.1"
  pnpmRuntime: string; // name of a runtime of kind "pnpm" (required)
}
```

**Node Runtime:**

```typescript
interface RuntimeConfigNode {
  nodeVersion: string; // e.g., "26.2.0"
  pnpmRuntime: string; // name of a runtime of kind "pnpm" (required)
}
```

**pnpm Runtime:**

```typescript
interface RuntimeConfigPNPM {
  pnpmVersion: string; // e.g., "12.4.1" (optional in system mode)
}
```

pnpm 12 ships no JavaScript implementation, so pnpm is a runtime of its own: its per-platform native archives live in the pnpm runtime's `managed.binaries`, with the same shape and validation rules as any managed runtime, and `datamitsu devtools pull-runtimes` fills them from the pnpm GitHub release. Node and Bun runtimes name it with `pnpmRuntime`, which must reference a runtime of kind `pnpm`; an app cannot select a pnpm runtime as its own. The earlier `pnpmVersion` and `pnpmHash` fields on Node and Bun runtimes were removed: a runtime that still pins pnpm that way fails to load (it has no `pnpmRuntime`) until it is regenerated.

**UV Runtime:**

```typescript
interface RuntimeConfigUV {
  pythonVersion?: string; // e.g., "3.14.3"
}
```

**JVM Runtime:**

```typescript
interface RuntimeConfigJVM {
  javaVersion: string; // e.g., "25"
}
```

**Go Runtime:**

```typescript
interface RuntimeConfigGo {
  goVersion: string; // Go SDK version to build with, e.g., "1.26.3"
}
```

## Tools (`tools`)

Tools define fix and lint operations that datamitsu executes.

```typescript
interface Tool {
  name: string;
  operations: Partial<Record<"fix" | "lint", ToolOperation>>;
  outputParser?: { module: string; parser: string }; // module = parsers entry; parser = dispatch key
  projectTypes?: string[]; // Restrict to specific project types
  skip?: boolean; // Report as skipped and never run (instead of omitting the tool)
  skipReason?: string; // Human-readable reason shown in the skipped report
}

interface ToolOperation {
  app: string; // App name from apps
  args: string[]; // Supports template placeholders ({file}, {files}, {root}, {cwd}, {toolCache}, {managedConfig:<key>})
  globs?: string[]; // File patterns (doublestar syntax; `!` negation not supported). Omit to match all discovered files.
  excludeGlobs?: string[]; // Patterns removed from the matched set (doublestar syntax)
  scope: "repository" | "per-project" | "per-file";
  arity?: "many" | "one" | "dir" | "none"; // argv path shape; inferred, assert-only
  granularity?: "file" | "unit" | "repo"; // smallest complete input set; inferred
  priority?: number; // Execution order (lower = first, default: 0)
  cache?: boolean; // Disable file/unit caching, or opt a repo verdict in
  invalidateOn?: string[]; // Additional unit/repo verdict inputs
  env?: Record<string, string>; // Extra environment variables; values support {root}, {cwd}, {toolCache}, {managedConfig:<key>}
  inheritEnv?: string[]; // Host variables handed to the tool with the host's value, even stripped ones
  failOn?: "error" | "warning" | "info" | "hint"; // Lowest finding level that fails the run (default: "error")
  input?: "file" | "stdin"; // How file content reaches the tool (default: "file")
  output?: "inplace" | "stdout"; // How the result is captured (default: "inplace")
  lsp?: boolean; // false keeps the operation out of the language server (format on save)
}
```

**Example:**

```javascript
const toolsConfig = {
  prettier: {
    name: "prettier",
    operations: {
      fix: {
        app: "prettier",
        args: ["--write", "{files}"],
        globs: ["**/*.{js,ts,jsx,tsx,json,md,yaml,yml}"],
        scope: "per-project",
      },
      lint: {
        app: "prettier",
        args: ["--check", "{files}"],
        globs: ["**/*.{js,ts,jsx,tsx,json,md,yaml,yml}"],
        scope: "per-project",
      },
    },
    projectTypes: ["typescript", "javascript"],
  },
};
```

### Scope Types

| Scope         | Description                         | Working Directory |
| ------------- | ----------------------------------- | ----------------- |
| `repository`  | Runs once for the entire repository | Git root          |
| `per-project` | Runs once per detected project      | Project root      |
| `per-file`    | Runs once per matched file          | Project root      |

See [Template Placeholders](./template-placeholders.md) for the `{file}`, `{files}`, `{target}`, `{root}`, `{cwd}`, and `{toolCache}` placeholders available in `args` (and `{root}`, `{cwd}`, `{toolCache}` in `env`). Unknown placeholders fail config loading rather than being passed through to the tool.

`scope` says where the process starts. Two other properties say what it needs and
what it can be given, and both are inferred — a tool usually declares neither.

### Granularity

`granularity` is the smallest set of files on which an operation's verdict is
complete. It decides whether datamitsu may honour a narrowed request, and whether
a result can be cached per file.

| Value  | Meaning                                   | Example            |
| ------ | ----------------------------------------- | ------------------ |
| `file` | Any subset of files is a complete input   | prettier, shfmt    |
| `unit` | Valid only over a whole project or module | tsc, golangci-lint |
| `repo` | Valid only over the whole repository      | syncpack, knip     |

Inferred when omitted:

```
scope: "per-file"                              -> file
scope: "repository" with {file} or {files}     -> file
scope: "repository" otherwise                  -> repo
scope: "per-project"                           -> unit
```

Note the last line: a per-project operation is `unit` **regardless of its
arguments**. A type checker and a formatter can carry byte-identical `args` while
one's answer depends on its siblings and the other's does not, and no inspection
of the command line can tell them apart. The default therefore errs towards
`unit`, where being wrong costs a cache entry rather than a wrong answer.

Declaring `granularity: "file"` is a speed decision — it puts the operation back
on the per-file cache — and is only correct when a file's result cannot depend on
its neighbours. datamitsu rejects it when the file list never reaches the tool,
since such an operation cannot have a per-file verdict at all.

An explicitly declared `granularity: "unit"` on a per-project operation with
`{file}` or `{files}` requests the complete eligible file set owned by that
project. A source selection widens to that set when the policy allows it;
`--widen-to=target` reports the operation as not narrowable. Nested projects
keep their own input sets and configurations. The complete input vector is
part of the unit verdict identity, so changing project ownership cannot reuse
a pass for a different set of source files. Inferred unit granularity retains
the existing narrowed-argv behavior; declare the full-input contract explicitly
for analyses whose findings depend on callers and sibling modules.

Declaring `unit` or `repo` is otherwise safe: it can only cause more work. The
one rejected combination is `scope: "repository"` with `granularity: "unit"` — a
repository-scoped operation starts one process at the git root and is never split
per unit, so its verdict covers the repository whatever it declares. Use
`scope: "per-project"` for a unit-complete verdict.

### Caching

Caching follows the operation's granularity:

| Granularity | Default                       | What a successful entry means                         |
| ----------- | ----------------------------- | ----------------------------------------------------- |
| `file`      | Enabled unless `cache: false` | This tool passed for this exact file content          |
| `unit`      | Enabled unless `cache: false` | This tool passed for every member and guard in a unit |
| `repo`      | Disabled unless `cache: true` | This tool passed for the whole tracked repository     |

A unit or repository verdict is stored only after a successful run with
complete coverage. Its input hash includes every member of the unit plus
ancestor marker/config/lock files, existing absolute file arguments, and paths
listed in `invalidateOn`. The hash also includes inherited environment variables
whose names match the toolchain-oriented allowlist documented in
[Caching Strategy](../guides/architecture/caching.md#unit-verdicts-and-the-content-hash-memo).
Each `invalidateOn` path is resolved against the unit and every ancestor up to
the git root, so a nested package can name an inherited root-level configuration
file.

`invalidateOn` does not participate in file-granularity cache entries. If one
file's result can change because a shared config changes, declare
`granularity: "unit"` and list that config instead of claiming file independence.
File entries fold in the values of the variables an operation names in
[`inheritEnv`](#inheriting-host-variables-inheritenv), and nothing else from the
inherited process environment; name such a variable there, use unit granularity
or `cache: false` when its value affects the result.
Unit and repository verdicts expire after `DATAMITSU_UNIT_CACHE_TTL` minutes
(`1440` by default; `0` disables them).

See [Caching Strategy](../guides/architecture/caching.md) for the complete key,
coverage, and persistence model.

### Arity

`arity` is the shape of paths the command line accepts.

| Value  | Meaning                      | Placeholder |
| ------ | ---------------------------- | ----------- |
| `many` | An arbitrary list of paths   | `{files}`   |
| `one`  | Exactly one path per process | `{file}`    |
| `dir`  | One directory, no file list  | `{target}`  |
| `none` | No path on the command line  | —           |

It is inferred exactly from the placeholders, so declaring it is an **assertion**,
not an override: a declared value that disagrees with the arguments is a config
error. That is what makes it worth writing. `yq -i` given two files splices the
second into the first and exits 0, so `arity: "one"` on a `yq` operation turns a
one-token edit from silent data loss into a config error.

#### Replacing `batch`

Arity replaces the old `batch` flag, which no longer exists. The key is simply
ignored if left in a config, so check the mapping below rather than assuming a
config carries over unchanged: `batch: false` on an operation carrying `{files}`
used to mean one process per file, where arity reads it as one process taking the
whole list.

| Was               | Now                                    |
| ----------------- | -------------------------------------- |
| `batch: true`     | `{files}` in `args` (arity `many`)     |
| `batch: false`    | `{file}` in `args` (arity `one`)       |
| no file in `args` | nothing to change (arity `none`/`dir`) |

### `execution.widenTo`

How far datamitsu may widen work beyond what you asked for, per operation.

```js
export const getConfig = (config) => ({
  ...config,
  execution: {
    widenTo: {
      fix: "target", // only ever touch the files I name
      lint: "unit",
    },
  },
});
```

| Value    | Meaning                                                |
| -------- | ------------------------------------------------------ |
| `target` | Only what was named; anything needing more is reported |
| `unit`   | May widen to the project containing the target         |
| `repo`   | May widen to the whole repository                      |

Default `unit` for both operations. Under it, `datamitsu fix ./one.ts` may run a
project-wide tool over that project — including one that rewrites files you did
not name, if it takes no file arguments. Set `fix: "target"` if that blast radius
is not what you want. `--widen-to` overrides it for a single run, in either
direction. The narrow-only rule applies to the editor's session policy instead —
`datamitsu.format.widenTo` in VS Code, `format.widenTo` in the language server's
[`initializationOptions`](./cli-commands.md#lsp-initialization-options), or
`DATAMITSU_LSP_FORMAT_WIDEN_TO`: that one is ambient and applies to every save,
so an editor must not be able to out-scope the project. Not even a per-tool
opt-in (`format.tools`) runs a tool beyond the project's `fix` level.

### Keeping an operation out of the editor (`lsp`)

`lsp: false` is the author's veto on running an operation from the language
server. The editor never runs it — not on save, not on "Format Document" — whatever
the editor's settings say, including a `format.tools` opt-in for that tool.
`lsp: true` is the same as leaving the field unset: the editor's session policy
decides, as described in
[What runs on save](../getting-started/installation/vscode.md#what-runs-on-save).

```javascript
const toolsConfig = {
  "go-mod-tidy": {
    name: "go-mod-tidy",
    operations: {
      fix: {
        app: "go",
        args: ["mod", "tidy"],
        scope: "per-project",
        lsp: false, // rewrites go.sum and may reach the network: not on every save
      },
    },
    projectTypes: ["golang"],
  },
};
```

A project-wide operation without `globs`, like this one, is
[already left out of the editor](../getting-started/installation/vscode.md#project-wide-tools-without-globs)
unless a user opts it in with `format.tools`; `lsp: false` takes that choice
away.

Only fix operations run in the editor today; the field is accepted on any
operation. It is unrelated to the top-level [`lsp`](#lsp-servers-lsp--reserved)
record, which declares language servers.

### Operation environment (`env`)

`env` sets fixed values for one operation. They are layered over the app's own
`env`, which is layered over the environment datamitsu was started with, so the
operation's value wins. Values support `{root}`, `{cwd}`, `{toolCache}` and
`{managedConfig:<key>}`.

Tools run by `fix`, `lint` and `check` do not see `GITHUB_ACTIONS`, the AI agent
markers or `FORCE_COLOR`: several tools switch their output format on them, and
datamitsu reads that output with a parser. They do see `CI` and every other CI
variable, and they always get `NO_COLOR=1`, which `env` cannot set, in any letter
case. Return a stripped variable with `inheritEnv`. The full list, with what
each variable changes, is the generated
[Tool Environment](./tool-environment.md) page. `datamitsu exec` strips nothing.

#### Inheriting host variables (`inheritEnv`)

`inheritEnv` names host environment variables the tool is handed with the
host's value, even the ones datamitsu strips — the value is read when the task
starts, never written in the config. A variable the host sets to the empty
string is handed as empty, and one the host does not set adds nothing. `env` is
layered after it, so a fixed value in `env` wins over an inherited one. A name
datamitsu does not strip is accepted too.

```javascript
lint: {
  app: "my-reporter", // writes GitHub annotations on purpose, and has no parser
  args: ["check"],
  scope: "repository",
  inheritEnv: ["GITHUB_ACTIONS"],
},
```

The values are part of the operation's cache identity, for its per-file entries
and its unit verdicts alike: the configuration names the variables but never
holds their values, so a run under another value runs the tool again instead of
replaying a result recorded under the old one.

The field is per operation, because a tool's lint and fix can need different
things. Each name must be an uppercase variable name (`^[A-Z_][A-Z0-9_]*$`),
listed once; `NO_COLOR`, `PATH` (which would compete with the `PATH` the runtime
sets) and every `DATAMITSU_*` name are rejected.

### Failing on findings (`failOn`)

`failOn` is the lowest level of finding that fails an operation: `"error"` (the
default), `"warning"`, `"info"` or `"hint"`. It adds failures to the tool's own
exit code and never removes one: a tool that exits non-zero fails at any
threshold, and a tool that exits 0 fails when its parsed output holds a finding
at or above `failOn`. It applies to `fix` and `lint` alike — a fixer that leaves a
finding above the threshold behind has not fixed it.

```javascript
lint: {
  app: "yamllint",
  args: ["-f", "parsable", "{files}"],
  scope: "repository",
  failOn: "warning", // a warning fails the run, even when yamllint exits 0
},
```

What gates is what the terminal shows: a run prints the findings at or above the
operation's threshold and counts the rest (see
[findings in the terminal](./cli-commands.md#findings-in-the-terminal)).
[`--fail-on`](./cli-commands.md#failing-on-findings---fail-on) and
`DATAMITSU_FAIL_ON` raise every operation's threshold for one run; they never
lower one.

A finding's level comes from its [parser](../guides/architecture/parsers.md#levels):
the level the tool printed, or — for a finding the tool printed no level for —
error when the tool failed and warning when it passed. A threshold is therefore
only meaningful with a parser module whose levels come from what the tool
printed: descriptor schema 2 or later, which
[`devtools parsers list`](./cli-commands.md#devtools-parsers) shows as a `levels`
line. With an older module the exit code alone decides, and a run whose threshold
is not the default warns once, naming the tools:
`failOn ignored for <tool>: parser module predates the severity contract`.

`failOn` is part of no cache identity: a pass is recorded only for output with no
finding of any level, which holds at every threshold.

### Skipping a tool (`skip` / `skipReason`)

Set `skip: true` to keep a tool in the config but report it as **skipped** rather
than running it. This is preferable to conditionally omitting the tool: an omitted
tool is invisible, whereas a skipped one is shown in the run summary (`⊘ <tool>
skipped (<reason>)`), the footer's `· N skipped` count, and the `--explain=json`
`skipped` array. Use `skipReason` to explain why.

A tool is **also** skipped automatically when its binary has no build for the
current OS/architecture/libc — a soft skip that no longer fails the run. See
[`--fail-on-skip`](./cli-commands.md#skipped-tools) to harden CI against that case.

```javascript
// BAD: conditionally omitting the tool — datamitsu never reports it was left out
const toolsConfig = {
  ...(facts().env.CI && { trufflehog: { name: "trufflehog", operations: { lint } } }),
};

// GOOD: keep the tool, mark it skipped with a reason
const toolsConfig = {
  trufflehog: {
    name: "trufflehog",
    skip: !facts().env.CI,
    skipReason: "runs in CI only",
    operations: { lint: { app: "trufflehog", scope: "repository" } },
  },
};
```

### Output Parser (`outputParser`)

A tool may reference a WASM [output parser](#output-parsers-parsers) to turn its
raw text output into structured results. The reference is an object with two
parts: **`module`** — the `parsers` entry to load (a specific WASM artifact, so
different versions are different entries) — and **`parser`** — the parser inside
that module to run (a name from `datamitsu devtools parsers list`). `module` must
name an existing `parsers` entry; a dangling reference is a config error.

```javascript
const toolsConfig = {
  hadolint: {
    name: "hadolint",
    outputParser: { module: "core", parser: "hadolint" },
    operations: { lint: { app: "hadolint", args: ["{file}"], scope: "per-file" } },
  },
  eslint: {
    name: "eslint",
    outputParser: { module: "core", parser: "eslint" },
    operations: {
      lint: { app: "eslint", args: ["--format", "json", "{file}"], scope: "per-file" },
    },
  },
};
```

Keeping `module` and `parser` separate is what makes multiple module versions
work: declare `parsers: { core: {…v2}, core_legacy: {…v1} }` and point each tool's
`outputParser.module` at the version it needs.

`embedded` is reserved: it is the fallback parser module built into datamitsu
([the embedded fallback](../guides/architecture/parsers.md#the-embedded-fallback)),
so a `parsers` entry cannot take the name and `outputParser.module` cannot name
it; either fails the configuration load.

`parser` also accepts a **format key**, for a tool that has no parser of its own
but prints a standard format on request. Pass the tool the flag that selects the
format and name the format:

| `parser`             | Example flag                                          |
| -------------------- | ----------------------------------------------------- |
| `sarif`              | `ruff check --output-format sarif`, `semgrep --sarif` |
| `checkstyle-xml`     | `shellcheck -f checkstyle`, `hadolint -f checkstyle`  |
| `gcc`                | `typos --format brief`, `shellcheck -f gcc`           |
| `codeclimate`        | `ruff check --output-format gitlab`                   |
| `github-annotations` | `ruff check --output-format github`                   |
| `junit-xml`          | `golangci-lint run --output.junit-xml.path=stdout`    |

```javascript
const toolsConfig = {
  ruff: {
    name: "ruff",
    outputParser: { module: "core", parser: "sarif" },
    operations: {
      lint: {
        app: "ruff",
        args: ["check", "--output-format", "sarif", "{files}"],
        scope: "per-project",
      },
    },
  },
};
```

A tool's own format is usually richer than a standard one, and its parser reads
it without a conversion in between: prefer a tool's parser when the module has
one, a format key when the tool prints a standard shape, and know that the line
formats (`gcc`, `msvc`, `github-annotations`, `azure-logissue`) carry only a
file, a line, a column, a level and the text. The
[parser catalog](./parser-catalog.md#format-parsers) lists every format key, and
[format parsers](../guides/architecture/parsers.md#format-parsers) says what each
recognizes. A module older than the one that introduced them does not know the
keys: `datamitsu devtools parsers list` shows what the pinned module carries.

See [WASM Output Parsers](../guides/architecture/parsers.md) for the architecture.

### Formatting input/output modes (`input` / `output`)

By default a tool receives file paths as arguments (`input: "file"`) and either
mutates files in place or has its combined stdout+stderr captured for reporting
(`output: "inplace"`). A **formatter** that reads from standard input and writes
the formatted document to standard output uses the stdin → stdout → diff contract
instead:

| Field    | Values                    | Default     | Meaning                                                                |
| -------- | ------------------------- | ----------- | ---------------------------------------------------------------------- |
| `input`  | `"file"` \| `"stdin"`     | `"file"`    | `"stdin"` pipes the target file's content to the tool's standard input |
| `output` | `"inplace"` \| `"stdout"` | `"inplace"` | `"stdout"` captures stdout (kept apart from stderr) as the new content |

When `output: "stdout"`, datamitsu treats the tool's stdout as the full new file
text, computes a **minimal line-based diff** against the original, and applies
only the changed lines — no change yields no edits. This keeps the formatter
sandboxed from the filesystem and produces precise edits (reusable as LSP
`TextEdit` ranges later). Use it with `scope: "per-file"`.

```javascript
// BAD: a stdin-only formatter forced through the in-place vehicle — it never
// receives the file and its formatted output is swallowed into the report.
const toolsConfig = {
  shfmt: {
    name: "shfmt",
    operations: {
      fix: { app: "shfmt", args: ["{file}"], scope: "per-file" },
    },
  },
};

// GOOD: feed content on stdin, capture stdout, let the core diff + apply.
const toolsConfig = {
  shfmt: {
    name: "shfmt",
    operations: {
      fix: {
        app: "shfmt",
        args: [], // tool reads stdin, writes stdout
        scope: "per-file",
        input: "stdin",
        output: "stdout",
      },
    },
  },
};
```

See [Formatting pipeline](../guides/tooling-system.md#formatting-stdin--stdout--diff)
for the end-to-end flow.

## Project Types (`projectTypes`)

Project types define markers used to detect project boundaries in the repository.

```javascript
const projectTypes = {
  typescript: {
    markers: ["package.json", "tsconfig.json"],
  },
  golang: {
    markers: ["go.mod"],
  },
  python: {
    markers: ["pyproject.toml", "setup.py"],
  },
};
```

## Managed Configs (`managedConfigs`)

Managed config entries define project-owned files that `datamitsu config reconcile`
writes before running `datamitsu fix`. Use `datamitsu config reconcile --dry-run`
to preview without either action.

```typescript
interface ManagedConfig {
  content?: (context: ConfigContext) => string;
  deleteOnly?: boolean; // Only delete, don't create
  ejectable?: boolean; // Live in .datamitsu/configs/ until a project ejects the tool
  expectChainHash?: string; // Pin the upstream-chain hash; abort reconciliation on drift
  linkTarget?: string; // Create symlink instead of writing content
  otherFileNameList?: string[]; // Conflicting files to delete
  projectTypes?: string[]; // Restrict to project types
  scope?: "project" | "git-root"; // Where to create: "project" (default) or "git-root" (once at root)
  tools?: string[]; // Tool name(s) this config belongs to; enables `config reconcile --tools` scoping
}
```

The optional `tools` field associates a config file with one or more tools (by
name, matching keys in [`tools`](#tools-tools)). `datamitsu config reconcile --tools <names>`
then regenerates only the config files whose `tools` intersect the selected set —
every other config, including unassociated infrastructure files, is left
untouched. Omit `tools` for files not tied to a single tool (`.gitignore`,
`lefthook.yaml`); those are skipped whenever `--tools` is passed. A name that is
not a configured tool is a load error: declare a tool that should not run with
[`skip: true`](#skipping-a-tool-skip--skipreason) instead of removing it.

### Keeping configs out of the repository (`ejectable` / `ejectConfigs`)

An entry marked `ejectable` does not have to live in the repository. Until a
project asks for it, datamitsu renders it into `.datamitsu/configs/<key>` —
git-ignored, written by `datamitsu init` — and the tool reads it from there:

```javascript
// shared config
tools: {
  gitleaks: {
    name: "gitleaks",
    operations: {
      lint: { app: "gitleaks", args: ["dir", "--config", "{managedConfig:.gitleaks.toml}", "{target}"], scope: "repository" },
    },
  },
},
managedConfigs: {
  ".gitleaks.toml": { scope: "git-root", tools: ["gitleaks"], ejectable: true, content: (ctx) => "..." },
},
```

```javascript
// project config: keep gitleaks' config in the repository to edit it
return { ...input, ejectConfigs: ["gitleaks"] };
```

- **`{managedConfig:<key>}`** is resolved once the whole chain is known, so a
  shared layer never needs to know whether a later layer ejects the file. It
  becomes `{root}/<key>` (`{cwd}/<key>` for a project-scoped entry) when the file
  is in the repository and `{root}/.datamitsu/configs/<key>` when it is not. The
  key must exist and must list the tool in its `tools`. It works for every
  managed config, ejectable or not.
- **`ejectable`** requires `content`, a non-empty `tools` and `scope: "git-root"`,
  and cannot be combined with `linkTarget` or `deleteOnly`. Declare it only for a
  file nothing but the tool needs: the tool must receive the path explicitly, and
  an editor extension, CI action, `datamitsu exec` or another tool that discovers
  the file by name will not find it.
- **`ejectConfigs`** names tools, not files; every ejectable entry whose `tools`
  include a named tool moves into the repository. Each name must be a configured
  tool that owns at least one ejectable entry. Duplicates are an error. A name
  that is not a configured tool only warns — the project layer usually pins a
  shared configuration, and an older or newer release of it may not define the
  tool yet or any more, which must not stop every datamitsu command in the
  repository. A configured name that owns no ejectable entry is an error.
- **Rendering.** An internal render has no `originalContent` and an empty project
  context; `context.placement` is `"internal"`. Build a path that the file itself
  resolves (a JavaScript import, a file-relative `extends`) from
  `datamitsuDirFromOutput`, and one the tool resolves against its working
  directory (gitleaks' `extend.path`) from `datamitsuDir`. A `content` that
  throws or renders nothing for an ejectable entry fails the config load.
- **Moving back.** When an entry stops being ejected, `datamitsu config reconcile`
  deletes the repository copy — and any `otherFileNameList` file — only if it
  holds nothing the configuration would not render again: re-rendering it from
  its own content must equal rendering it from nothing, so formatting does not
  count and a key the project added does. Otherwise reconciliation refuses before
  writing anything and names the file.
- **Preflight.** `lint`, `fix`, `check` and the language server refuse to run a
  tool whose ejectable config is missing, stale, or — for an internal entry —
  also present in the repository, where the tool would silently ignore it. Each
  message names the command that fixes it (`datamitsu init` or
  `datamitsu config reconcile --tools <tool>`).
- `expectChainHash` is verified only for entries in the repository.

### Pinning the upstream chain (`expectChainHash`)

Config files are generated by layering: a shared config (and any
`getRemoteConfigs()` / `getBeforeConfigs()` layers) runs first, and **your** root
config — the one at the git root, or an explicit `--config` — runs last on top.
When you override a generated config in your root layer, those overrides assume a
particular upstream baseline. If the shared config later changes that baseline, a
plain `datamitsu config reconcile` would re-derive the file and could silently drop your
overrides.

`expectChainHash` guards against exactly that. Set it on a root-layer entry to
pin the XXH3-128 hash of the **content entering your layer** — the output of the
whole upstream chain, _before_ your layer transforms it:

```javascript
const managedConfigs = {
  "eslint.config.mjs": {
    // Pin the upstream baseline this override was written against.
    expectChainHash: "xxh3:0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    content: (context) => {
      /* your overrides on top of the shared config */
    },
  },
};
```

On every `datamitsu config reconcile` dry-run or normal run, the hash is
recomputed and compared. When it matches, reconciliation proceeds normally.
When the upstream chain has **drifted**, reconciliation aborts **before writing anything** and prints the new hash
plus the full incoming content, so you can review the change against your
overrides, update the pin, and re-run. Key properties:

- **Opt-in, per file.** Files without `expectChainHash` behave exactly as before.
  To attach a pin, the file must have an entry in your root config (an entry with
  only `expectChainHash` and no `content` is valid).
- **Root layer only.** A pin is honoured solely on the topmost (root) layer;
  pins on intermediate layers are ignored.
- **Byte-for-byte.** The incoming content is hashed verbatim with no
  normalization — any change (upstream _or_ a handler that folds in your on-disk
  file) moves the hash. Format: `"xxh3:<32 lowercase hex>"` — the only accepted
  form; a bare 32-hex value is rejected at config load.
- **Bypass.** Pass `datamitsu config reconcile --no-verify-hash` to skip the check and write
  regardless of drift.

To obtain the value the first time, declare the entry with a placeholder pin and
read the real hash with [`datamitsu config chain-hash <file>`](./cli-commands.md#config-chain-hash)
(it prints exactly what the gate checks, no error needed):

```bash
pin=$(datamitsu config chain-hash eslint.config.mjs)  # -> xxh3:…
```

The `content` function receives a context object:

```typescript
interface ConfigContext {
  cwdPath: string; // Current working directory
  rootPath: string; // Git repository root
  datamitsuDir: string; // Relative path from cwdPath to .datamitsu/
  datamitsuDirFromOutput?: string; // Relative path from outputDir to .datamitsu/
  outputPath?: string; // Absolute path the result is written to
  outputDir?: string; // Directory of outputPath
  placement: "repo" | "internal"; // Repository file, or .datamitsu/configs/ render
  isRoot: boolean; // Is cwdPath the git root?
  projectTypes: string[]; // Detected project types
  projectLocations: Array<{ type: string; path: string }>; // Git-root-relative markers
  existingContent?: string; // Previous layer's generated content (if any)
  existingPath?: string; // Current file path (if exists)
  originalContent?: string; // Unmodified content from disk
}
```

**Example:**

```javascript
const managedConfigs = {
  "eslint.config.js": {
    projectTypes: ["typescript", "javascript"],
    tools: ["eslint"], // scope `config reconcile --tools eslint` to this file
    content: (context) => {
      const configPath = tools.Path.forImport(
        tools.Path.join(context.datamitsuDir, "eslint.config.js"),
      );
      return `import config from "${configPath}";\nexport default config;\n`;
    },
    otherFileNameList: [".eslintrc", ".eslintrc.json", ".eslintrc.yml"],
  },
};
```

## Init Commands (`initCommands`)

Init commands run shell commands during `datamitsu init`.

```typescript
interface InitCommand {
  command: string; // App name from apps
  args: string[]; // Command arguments
  projectTypes?: string[]; // Restrict to project types
  description?: string; // Human-readable description
  when?: string; // Run only if this root-relative file or directory exists
}
```

`when` is resolved from the git root. A missing path skips the command; any
other stat result leaves it eligible to run. Commands are filtered by
`projectTypes`, then executed in stable name order.

**Example:**

```javascript
const initCommands = {
  lefthook: {
    command: "lefthook",
    args: ["install"],
  },
};
```

## Archives

Apps can bundle directory trees via inline or external archives.

```typescript
interface ArchiveSpec {
  inline?: string; // Brotli-compressed tar: "tar.br:..." prefix
  url?: string; // External archive URL
  format?: string; // Required for external: "tar", "tar.gz", etc.
  hash?: string; // Canonical SHA-256 digest "sha256:<64 lowercase hex>" — required for external archives
}
```

**Extraction order:** Archives extracted first (sorted alphabetically), then `files` written (files overwrite archive contents). Package manager runs after both.

Archives are supported on UV apps, node apps, Go apps (the [source-blob form](#go-apps)), and bundles.

## Ignore Rules

The `ignoreRules` field accepts `.datamitsuignore`-syntax rules:

```javascript
const config = {
  ignoreRules: ["vendor/**/*: *", "**/*.generated.go: golangci-lint"],
};
```

See [Ignore Rules](./ignore-rules.md) for the full syntax reference.

## Shared Storage (`sharedStorage`)

A `map[string]string` field that flows through the config chain as ordinary JS input. Use it to pass arbitrary data between config layers that doesn't fit the typed config structure.

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

// Setting values in a config layer
function getConfig(input) {
  return {
    ...input,
    sharedStorage: {
      ...input.sharedStorage,
      "llms-txt": "# Project documentation...",
      "feature-flag": "true",
    },
  };
}
globalThis.getConfig = getConfig;

// Reading values in a downstream config layer
function getConfig(input) {
  const llmsTxt = input.sharedStorage?.["llms-txt"];
  // Use the value...
  return { ...input };
}
globalThis.getConfig = getConfig;
```

See [Managed Content - Shared Storage](../guides/managed-content.md#shared-storage) for usage examples.

The default configuration publishes these keys:

| Key                              | Value                                                                                                                                                                      |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datamitsu-agent-prompt`         | Markdown guide for agents in a repository that uses datamitsu ([Agent Prompts](../contributing/creating-wrappers.md#agent-prompts))                                        |
| `datamitsu-config-author-prompt` | Markdown guide for agents writing a datamitsu configuration; opt-in ([Agent Prompts](../contributing/creating-wrappers.md#agent-prompts))                                  |
| `pnpm-workspace-defaults`        | YAML of the recommended pnpm workspace security settings ([Supply Chain Security](../guides/supply-chain-security.md#reusing-defaults-in-project-repos-via-sharedstorage)) |

## OCI Bundle (`oci`)

Pins the [OCI bundle](/docs/guides/oci-bundles) that seeds the tool store: the registry repository plus the mandatory SHA-256 digest.

```typescript
interface OCIReference {
  ref: string; // full reference incl. registry host, e.g. "ghcr.io/owner/tool-store"
  digest: string; // "sha256:" + 64 lowercase hex characters — mandatory
  signer?: {
    identity: string; // sigstore certificate identity (e.g. a workflow ref)
    issuer: string; // OIDC issuer URL
  }; // rejected at config load — see below
}
```

```javascript
function getConfig(input) {
  return {
    ...input,
    oci: {
      ref: "ghcr.io/owner/tool-store",
      digest: "sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b",
    },
  };
}
```

Rules:

- `ref` must include the registry host as its first segment — there is no default host and no docker.io shorthand. Tags and digests inside `ref` are rejected; content is pinned exclusively by `digest`.
- `oci` chains through the layers **as a scalar**: the last layer that set or spread it wins, and the effective config holds at most one declaration. A layer that rebuilds its output without `{...input}` silently drops the inherited value (a debug log flags this); reset explicitly with `oci: undefined` or `oci: null`.
- `signer` is **rejected at config load**: `oci: signer is set but signature verification is not implemented in this build; remove signer (the pinned digest still verifies the bundle bytes)`. This build has no sigstore dependency and verifies no signatures at all, so a config that pins a signer would assert a guarantee the binary does not deliver. The field is reserved so the eventual implementation reuses one vocabulary across bundles and [parsers](#registry-source-oci). Previously a set `signer` loaded and failed later, at seed time; it now fails at load.

See the [OCI Bundles guide](/docs/guides/oci-bundles) for the trust model and the seeding lifecycle.

## Output Parsers (`parsers`)

Parsers are Rust→WASM modules that extract structured results from a tool's raw
text output. A `parsers` entry is a **hash-pinned data artifact** — modeled on
`ArchiveSpec`/`Bundle`, _not_ on an app: there is no runtime and no lockfile,
because it is data, not a process. It is fetched, SHA-256 verified,
content-addressed in the store, and loaded into a sandboxed WASM runtime
(wazero).

```typescript
interface Parser {
  hash: string; // Canonical SHA-256 digest "sha256:<64 lowercase hex>" — mandatory for every source
  url?: string; // URL of the .wasm module
  oci?: ParserOCI; // registry-sourced module
  // Exactly one of `url` or `oci`. No `version` field — see note below.
}
```

| Field  | Type        | Description                                                                            |
| ------ | ----------- | -------------------------------------------------------------------------------------- |
| `hash` | `string`    | Canonical SHA-256 digest, `sha256:<64 lowercase hex>` — **mandatory** for every source |
| `url`  | `string`    | URL of the `.wasm` module. Exactly one of `url` or `oci`                               |
| `oci`  | `ParserOCI` | Module pulled from an OCI registry. Exactly one of `url` or `oci`                      |

The entity is intentionally **source + hash only**. A module reports its own
build-injected version (and the tools it parses) through its WASM `describe`
export, surfaced by [`datamitsu devtools parsers list`](./cli-commands.md#devtools-parsers).
The module is the single source of truth, so there is no `version` field to drift
from reality.

A tool opts into a parser via [`tool.outputParser`](#output-parser-outputparser).
The same parser referenced by several tools is downloaded once.

```javascript
function getConfig(input) {
  return {
    ...input,
    parsers: {
      echo: {
        url: "https://github.com/owner/repo/releases/download/v1.2.3/datamitsu_parsers_1.2.3.wasm",
        hash: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      },
    },
  };
}
```

The SHA-256 `hash` is **mandatory** for every source per the
[security policy](#security-requirements) — an empty or malformed hash is a
config error, not a warning (`parser "echo": hash is required (SHA-256)` and
`parser "echo": hash must be a canonical SHA-256 digest (sha256:<64 lowercase hex>)`).

The module is delivered through two channels. As a versioned asset on the GitHub
Release (`datamitsu_parsers_<version>.wasm`): take the `url` from that release
asset and the `hash` from the release's signed `checksums.txt`. Or as an OCI
artifact in a registry: take `oci.ref` and `oci.digest` from the published
artifact, with the same `hash` — see [Registry source (`oci`)](#registry-source-oci)
below. See [WASM Output Parsers](../guides/architecture/parsers.md) for the trust
model.

```javascript
// BAD: missing hash — refused at config load
parsers: {
  echo: { url: "https://example.com/datamitsu_parsers.wasm" },
}

// GOOD: mandatory SHA-256 hash from the release's signed checksums.txt
parsers: {
  echo: {
    url: "https://example.com/datamitsu_parsers.wasm",
    hash: "sha256:0123…cdef", // sha256:<64 lowercase hex>
  },
}
```

### One source per entry (`url` or `oci`)

An entry declares **exactly one** source. Both, or neither, is a config error at
load:

- neither — `parser "echo": exactly one of url or oci is required`
- both — `parser "echo": url and oci are mutually exclusive (declare one source; use a config layer to override)`

This is deliberately not a fallback chain. An air-gapped organization has to be
able to prove there is no `github.com` egress left, which a "try the registry,
then the URL" declaration would quietly undo. Switching an entry to a registry is
what config layers are for: a downstream layer replaces the entry with the `oci`
form instead of adding a second source to it.

```javascript
// BAD: two sources in one entry — refused at config load
parsers: {
  echo: {
    url: "https://example.com/datamitsu_parsers.wasm",
    oci: { ref: "ghcr.io/datamitsu/datamitsu-parsers", digest: "sha256:89ab…4567" },
    hash: "sha256:0123…cdef",
  },
}

// GOOD: a downstream layer replaces the entry, keeping the same hash
function getConfig(input) {
  return {
    ...input,
    parsers: {
      ...input.parsers,
      echo: {
        oci: { ref: "ghcr.io/datamitsu/datamitsu-parsers", digest: "sha256:89ab…4567" },
        hash: input.parsers.echo.hash,
      },
    },
  };
}
```

### Registry source (`oci`)

`oci` pulls the module from an OCI registry instead of over HTTPS, so an
organization that mirrors one registry gets diagnostics parsing along with
everything else. It mirrors the [OCI bundle](#oci-bundle-oci) reference
vocabulary — same grammar, same digest form, same `signer` rejection.

```typescript
interface ParserOCI {
  ref: string; // full reference incl. registry host, e.g. "ghcr.io/datamitsu/datamitsu-parsers"
  digest: string; // "sha256:" + 64 lowercase hex characters — mandatory
  signer?: {
    identity: string; // sigstore certificate identity (e.g. a workflow ref)
    issuer: string; // OIDC issuer URL
  }; // rejected at config load — see below
}
```

| Field    | Type        | Description                                                                                                         |
| -------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `ref`    | `string`    | Full repository reference including the registry host. Tags and digests inside the ref are rejected — **mandatory** |
| `digest` | `string`    | Artifact manifest digest, `"sha256:"` + 64 lowercase hex — **mandatory**                                            |
| `signer` | `OCISigner` | **Rejected at config load** — this build verifies no signatures                                                     |

```javascript
function getConfig(input) {
  return {
    ...input,
    parsers: {
      echo: {
        oci: {
          ref: "ghcr.io/datamitsu/datamitsu-parsers",
          digest: "sha256:89abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567",
        },
        hash: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      },
    },
  };
}
```

Rules:

- `ref` must include the registry host as its first segment — there is no default
  host and no docker.io shorthand. A ref without a host is rejected with
  `oci.ref … must include the registry host as its first segment (e.g. ghcr.io/owner/repo)`,
  and a tag or a digest inside the ref with
  `oci.ref … is not a valid repository reference (expected host[:port]/path, lowercase, no tag and no digest)`.
- Content is pinned exclusively by `digest`, which is mandatory:
  `oci.digest is required (sha256:<64 hex>)`, or
  `oci.digest … must be "sha256:" followed by 64 lowercase hex characters` when it
  is malformed.
- `hash` stays mandatory and does double duty: it is **also** the expected layer
  blob digest — the layer's digest is the same `sha256:`-prefixed value, so the
  registry digest chain and the config hash are the same number. A manifest
  that points at other content is rejected before one payload byte is requested,
  and the same `hash` is checked again on the downloaded stream and once more on
  the file on disk.
- `signer` is rejected at load, on this surface and on the bundle's:
  `oci.signer is set but signature verification is not implemented in this build`.
  datamitsu verifies no signatures at all; the mandatory `hash` is what guarantees
  the bytes.

Because the store key under `{store}/.parsers/{name}/` is derived from `hash`
alone, an entry resolves to **one** store directory however the module arrived — a release URL, a registry, or a
layer of an OCI bundle — which is what makes a bundle-seeded and a registry-pulled
module interchangeable. A module already on disk is re-hashed against the declared
`hash` before use and discarded when it does not match, whatever put it there.

[`--no-oci` / `DATAMITSU_NO_OCI`](./cli-commands.md#environment-variables) disables OCI
_bundle_ seeding, an accelerator; it does **not** disable a declared parser `oci`
source, which is the only route to those bytes. `DATAMITSU_OFFLINE` is the single
hard network gate. [`datamitsu store refs`](./cli-commands.md#store-refs) lists
every artifact the effective config pins, so a mirror can be filled without
guessing.

## LSP Servers (`lsp`) — reserved

:::info Reserved surface
`lsp` is a **declaration-only** entity reserved for a later phase. The types load
and are structurally validated today, but there is **no runtime behavior** in
this release. Declaring `lsp` entries does nothing yet.
:::

Each entry is one of two discriminated shapes:

```typescript
// Wrap a standalone language-server app, scoped by project types.
interface LspProxy {
  type: "proxy";
  app: string; // app name (in `apps`) providing the server
  projectTypes: string[]; // must be non-empty
  order?: number; // precedence; ties break alphabetically by entry name
}

// Reuse an existing tool's projectTypes/globs and its outputParser.
interface LspDerived {
  type: "derived";
  tool: string; // tool name (in `tools`) — must exist
  order?: number; // precedence; ties break alphabetically by entry name
}
```

Structural validation today: `type` must be `"proxy"` or `"derived"`; a `proxy`
requires `app` plus a non-empty `projectTypes`; a `derived` requires a `tool`
that exists in `tools`. The optional `order` controls precedence, with **ties
broken alphabetically by entry name** (the same `sort.Strings`-by-name convention
the planner uses).

```javascript
function getConfig(input) {
  return {
    ...input,
    lsp: {
      "go-lsp": { type: "proxy", app: "gopls", projectTypes: ["golang"] },
      hadolint: { type: "derived", tool: "hadolint" },
    },
  };
}
```

## JavaScript APIs

The following APIs are available in configuration files.

### Engine Globals

Two frozen plain-object globals are injected by the Go engine:

```javascript
// Recommended pnpm workspace security settings. These are publication
// defaults, not inputs that vary with the current invocation.
const workspacePolicy = pnpmWorkspaceDefaults;

// The deliberately small set of runtime values config JS may branch on.
const minimumAge = datamitsuConfigInputs.minimumReleaseAgeMinutes;
```

`datamitsuConfigInputs` currently exposes only `minimumReleaseAgeMinutes`. The
full `datamitsu config runtime` snapshot is intentionally CLI-only and is not
injected into the VM. Keeping this allowlist small makes every observable input
explicit in config-evaluation cache keys.

### Format Utilities

```javascript
// YAML
YAML.parse(text);
YAML.stringify(value);

// TOML
TOML.parse(text);
TOML.stringify(value);

// INI
INI.parse(text);
INI.stringify(sections);
INI.toRecord(sections);
```

### Path Utilities

```javascript
// Join path segments
tools.Path.join("src", "components", "Button.tsx");

// Get absolute path
tools.Path.abs("relative/path");

// Get relative path (basePath defaults to git root)
tools.Path.rel(targetPath, basePath);

// Convert to ES module import path (ensures ./ or ../ prefix)
tools.Path.forImport(tools.Path.join(context.datamitsuDir, "eslint.config.js"));
// → "./.datamitsu/eslint.config.js"
```

### Config Link Utilities

```javascript
// Get relative path from a file to a managed config link
tools.Config.linkPath("eslint", "eslint-config", fromPath);
```

### Ignore Utilities

```javascript
// Parse .gitignore-style content
const groups = tools.Ignore.parse(content);

// Stringify back with optional group ordering
const output = tools.Ignore.stringify(groups, groupOrder);
```

### Platform Information

```javascript
const info = facts();
// info.os       → "linux", "darwin", "windows", etc.
// info.arch     → "amd64", "arm64"
// info.libc     → "glibc", "musl", "unknown" (Linux-only detection)
// info.isInGitRepo → true/false
// info.isMonorepo  → true/false
// info.env      → process environment, except observation-only datamitsu variables
// info.ci       → { vendor, isCI, isPR, sha, ref, baseRef, prNumber }
```

`facts().env` omits `DATAMITSU_TRACE`, `DATAMITSU_TRACE_DIR`, and
`DATAMITSU_CONFIG_CACHE`: they only observe execution or control evaluation
caching and cannot change what config produces. The config-evaluation key hashes
the same remaining environment, so a result cannot be reused across distinct
values the config was allowed to observe.

`facts().ci` says which continuous-integration system runs the job, read from
the variables each vendor sets for its own jobs, and the identifiers of the
change it builds:

| Field      | Value                                                                                                                                               |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vendor`   | `github`, `gitlab`, `azure`, `teamcity`, `buildkite`, `bitbucket`, `jenkins`, `circleci`, `gitea`; `generic` when only `CI` is set; `""` outside CI |
| `isCI`     | `true` under any of them — a vendor's own marker, or `CI` set to anything but `false` or `0`                                                        |
| `isPR`     | `true` when the job builds a pull or merge request                                                                                                  |
| `sha`      | the commit the job builds — on a GitHub pull request, the merge commit                                                                              |
| `ref`      | the ref the job builds, as the vendor names it                                                                                                      |
| `baseRef`  | the branch a pull or merge request targets, when the vendor says                                                                                    |
| `prNumber` | the pull or merge request number, when the vendor says                                                                                              |

Gitea and Forgejo set `GITHUB_ACTIONS=true` as well, and read as `gitea`: they
support neither GitHub's annotations nor its step summary. `facts().ci` is read
from the same environment as `facts().env`, so the config-evaluation key already
tells two of its values apart. Prefer it to `facts().env.CI`, which misses
Azure Pipelines and TeamCity, whose jobs do not set `CI`:

```javascript
const toolsConfig = {
  trufflehog: {
    name: "trufflehog",
    skip: !facts().ci.isCI,
    skipReason: "runs in CI only",
    operations: { lint: { app: "trufflehog", scope: "repository" } },
  },
};
```

## Security Requirements

All content downloaded from the internet must have a SHA-256 hash specified, as a
canonical digest — `sha256:<64 lowercase hex>`; a bare 64-hex pin no longer loads:

- Binary apps: `hash` field on each platform entry
- Managed Bun, Node, pnpm, UV/Python, JVM, and Go runtimes: `hash` on every downloaded platform entry
- JVM apps: `jarHash` field
- External archives: `hash` field
- Remote configs: `hash` on every `getRemoteConfigs()` entry — the one lenient pin: a bare or uppercase-hex value is accepted there and normalized to canonical, because it is copied from a release page or checksum file
- Output parsers: `hash` field on each `parsers` entry, whichever source it declares
- OCI-sourced parsers: `oci.digest` on the entry, **plus** the same mandatory `hash` — which the artifact's single layer must carry as its blob digest
- OCI store bundles: mandatory `oci.digest`; unpacked artifacts are re-verified against their individual SHA-256 pins

Bun, Node, UV, and Go apps also require lock files. These locks pin transitive package
content and are installed in frozen/read-only modes. Missing or empty hashes and
missing lock files are configuration errors, never warnings or hash-less
fallbacks.

### Authenticated binary downloads

A binary platform entry may carry `auth` with `tokenEnv`, `origin`, `header`
(`Authorization` or `PRIVATE-TOKEN`), optional `scheme` (`Bearer` or `token`
for Authorization) and optional `accept: "application/octet-stream"`.
`origin` contains only scheme and host. Credentials are read through the named
environment variable at download time, never serialized, and stripped when a
redirect changes origin. SHA-256 remains mandatory. `pull-releases` generates
these references from source profiles; public downloads need no `auth`.

---

## Ignore Rules


datamitsu supports `.datamitsuignore` files to disable specific tools for matching file patterns. These files work similarly to `.gitignore` but target tool execution rather than version control.

## File Location

Place `.datamitsuignore` files anywhere in your repository. Rules apply to files in the same directory and all subdirectories. Multiple files at different levels of the directory tree are combined, with deeper rules taking precedence.

```
repo/
├── .datamitsuignore          # Rules for entire repo
├── src/
│   └── .datamitsuignore      # Additional rules for src/
└── vendor/
    └── .datamitsuignore      # Rules for vendor/
```

## Syntax

Each line follows the format:

```
{glob}: {tool1}, {tool2}
```

| Component    | Required | Description                                                  |
| ------------ | -------- | ------------------------------------------------------------ |
| `!` prefix   | No       | Inversion operator — re-enables tools for matching files     |
| Glob pattern | Yes      | File matching pattern (supports `**` for recursive matching) |
| `:`          | Yes      | Separator between pattern and tool list                      |
| Tool list    | Yes      | Comma-separated tool names to disable                        |

### Comments and Blank Lines

```bash
# This is a comment
# Blank lines are ignored

**/*.md: prettier
```

### Disabling Specific Tools

Disable one or more tools for files matching a pattern:

```bash
# Disable prettier for markdown files
**/*.md: prettier

# Disable multiple tools for generated files
**/*.generated.go: golangci-lint, gofmt

# Disable eslint for test fixtures
tests/fixtures/**/*: eslint
```

### Wildcard Tool Name

Use `*` to disable all tools for matching files:

```bash
# Disable all tools for vendor directory
vendor/**/*: *

# Disable all tools for build output
dist/**/*: *
```

### Inversion (Re-enabling)

Use the `!` prefix to re-enable tools that were disabled by a broader rule:

```bash
# Disable eslint for all markdown
**/*.md: eslint

# But re-enable it for docs
!docs/**/*.md: eslint
```

The `!` prefix with `*` clears the entire disabled set for matching files:

```bash
# Disable all tools for vendor
vendor/**/*: *

# But re-enable everything for our vendored patches
!vendor/patches/**/*: *
```

## Rule Application Order

Rules are applied from the root directory toward the file's directory:

1. Root-level `.datamitsuignore` rules apply first
2. Subdirectory rules apply on top, in depth order
3. Within the same directory, rules apply in file order (top to bottom)
4. Positive rules add tools to the disabled set
5. Negative (`!`) rules remove tools from the disabled set

This means deeper rules override shallower ones, and later rules in the same file override earlier ones.

### Example

```
repo/.datamitsuignore:
  **/*.md: eslint, prettier

repo/docs/.datamitsuignore:
  !**/*.md: eslint
```

Results:

- `README.md` — eslint disabled, prettier disabled (root rule applies)
- `docs/guide.md` — eslint enabled (docs rule re-enables), prettier disabled (root rule still applies)
- `src/main.js` — no tools disabled (pattern doesn't match)

## Config-Defined Ignore Rules

In addition to `.datamitsuignore` files, you can define ignore rules in your configuration:

```javascript
/// <reference path=".datamitsu/datamitsu.config.d.ts" />

function getConfig(config) {
  return {
    ...config,
    ignoreRules: ["vendor/**/*: *", "**/*.generated.go: golangci-lint"],
  };
}
```

Config-defined rules are merged with file-based rules. Rules from earlier config layers are prepended to later layers (append semantics).

## Per-Project Scope

For tools with `scope: "per-project"`, ignore rules are evaluated by checking if the tool would be disabled for a synthetic file in that project directory. This means:

- Extension-specific patterns like `**/*.md: eslint` do not disable `eslint` for an entire project
- Catch-all patterns like `**/*: eslint` or `vendor/**/*: *` do disable tools for entire projects

A catch-all rule fully disables a per-project tool even when it is the tool's
**only** project (or when no project of the tool's type is detected). The tool is
omitted from the plan entirely rather than resurrected with the full file list —
this is what makes the [opt-in model](#generating-an-all-disabled-file) reliable.

## Generating an all-disabled file

For incremental adoption, you can start with **every tool disabled** and enable
them one at a time. Preview the generated file without writing or running fix:

```bash
datamitsu config reconcile --opt-in-tools --dry-run
```

Then write it as part of the normal reconciliation:

```bash
datamitsu config reconcile --opt-in-tools
```

As part of reconciliation, this writes a `.datamitsuignore` at your git root
that disables all configured tools via a single catch-all rule. The default
post-reconciliation fix then respects that opt-in state:

```bash
# Generated by `datamitsu config reconcile --opt-in-tools`.
# All configured tools are disabled by default (opt-in model).
# Enable a tool by removing it from the list below (or add "!**/*: <tool>").
**/*: eslint, golangci-lint, hadolint, prettier, shellcheck
```

Enable a tool by **removing its name** from the list. The generated file
enumerates each tool name explicitly (rather than `**/*: *`) because re-enabling a
single tool over a `*`-disable does not work — a `!**/*: <tool>` line only clears
that tool's key, leaving the wildcard disable in place.

The file is written in canonical form, so it stays stable under
`datamitsu fix`. Reconciliation refuses to overwrite an existing
`.datamitsuignore` so your manual selections are never lost. Add `--dry-run` to
preview the file without writing it.

## Glob Pattern Reference

datamitsu uses [doublestar](https://github.com/bmatcuk/doublestar) for glob matching:

| Pattern     | Matches                                     |
| ----------- | ------------------------------------------- |
| `*`         | Any characters within a single path segment |
| `**`        | Zero or more path segments                  |
| `?`         | Any single character                        |
| `[abc]`     | Any character in the set                    |
| `[a-z]`     | Any character in the range                  |
| `{foo,bar}` | Either `foo` or `bar`                       |

### Common Patterns

```bash
# All files with a specific extension
**/*.md: prettier

# All files in a specific directory
vendor/**/*: *

# Files at a specific depth
src/*: eslint

# Multiple extensions
**/*.{js,ts,jsx,tsx}: eslint

# Specific filename anywhere
**/Makefile: prettier
```

## Formatting

datamitsu enforces a canonical format for `.datamitsuignore` files. Running `datamitsu fix` normalizes formatting automatically:

- Canonical format: `{!}{glob}: {tool1}, {tool2}`
- Single space after colon
- Single space after each comma
- Leading blank lines removed
- Consecutive blank lines collapsed
- Trailing newline preserved

## Linting

`datamitsu lint` validates `.datamitsuignore` files and reports:

- Parse errors (missing colon, empty pattern, empty tool list) — causes failure
- Formatting deviations from canonical form — warning
- Unknown tool names not in your configuration — warning

---

## JavaScript API


The `@datamitsu/datamitsu` npm package provides a programmatic API for integrating datamitsu into scripts, build pipelines, and code generation workflows.

## Installation

<Tabs>
  <TabItem value="pnpm" label="pnpm" default>

    ```bash
    pnpm add @datamitsu/datamitsu
    ```

  </TabItem>
  <TabItem value="npm" label="npm">

    ```bash
    npm install @datamitsu/datamitsu
    ```

  </TabItem>
  <TabItem value="yarn" label="yarn">

    ```bash
    yarn add @datamitsu/datamitsu
    ```

  </TabItem>
  <TabItem value="bun" label="bun">

    ```bash
    bun add @datamitsu/datamitsu
    ```

  </TabItem>
  <TabItem value="deno" label="deno">

    ```bash
    deno add npm:@datamitsu/datamitsu
    ```

  </TabItem>
</Tabs>

The package requires Node.js 22.12+ and uses ES modules.

## Quick Start

```javascript

// Get the installed version
const v = await version();
console.log(v.version); // "1.2.3"

// Run fix on specific files
const result = await fix({ files: ["src/app.ts"] });
console.log(result.success); // true

// Get a structured execution plan
const plan = await fix({ explain: "json" });
if (plan.success) {
  console.log(plan.plan.groups); // PlanJSON structure
}
```

A default export is also available:

```javascript

await datamitsu.fix({ files: ["src/app.ts"] });
await datamitsu.lint({ explain: "json" });
const tools = await datamitsu.exec();
```

## Output Modes

All commands that produce output support two modes controlled by the `stdio` option:

- **`"pipe"`** (default) - Captures stdout/stderr and returns them in the result object. Use this when you need to process or parse the output programmatically.
- **`"inherit"`** - Streams output directly to the parent process terminal. Use this for interactive CLI wrappers or when you want real-time output.

```javascript
// Capture output for processing
const result = await fix({ stdio: "pipe" });

// Stream output to terminal
await fix({ stdio: "inherit" });
```

## Commands

### fix()

Auto-fix files using configured tools.

```typescript
function fix(options?: FixOptions): Promise<FixResult>;
```

**Options:**

| Option         | Type                                                 | Default         | Description                                       |
| -------------- | ---------------------------------------------------- | --------------- | ------------------------------------------------- |
| `files`        | `string[]`                                           | `[]`            | Target files to fix                               |
| `explain`      | `false \| true \| "summary" \| "detailed" \| "json"` | `false`         | Output format. `"json"` returns parsed `PlanJSON` |
| `fileScoped`   | `boolean`                                            | `false`         | Apply file-scoped fixes only                      |
| `tools`        | `string[]`                                           | `[]`            | Limit to specific tools                           |
| `cwd`          | `string`                                             | `process.cwd()` | Working directory                                 |
| `config`       | `string[]`                                           | `[]`            | Additional config file paths                      |
| `beforeConfig` | `string[]`                                           | `[]`            | Config files loaded before auto-discovery         |
| `noAutoConfig` | `boolean`                                            | `false`         | Disable auto-discovery of config at git root      |
| `stdio`        | `"pipe" \| "inherit"`                                | `"pipe"`        | Output handling mode                              |

**Result:**

The return type depends on the `explain` option and whether the command succeeds:

```typescript
// On failure
{ success: false; error: string; exitCode?: number; raw: SpawnRaw }

// On success without explain
{ success: true; exitCode: number; raw: SpawnRaw }

// On success with explain (text modes)
{ success: true; output: string; raw: SpawnRaw }

// On success with explain="json"
{ success: true; plan: PlanJSON; raw: SpawnRaw }
```

**Examples:**

```javascript

// Fix all files
const result = await fix();

// Fix specific files
await fix({ files: ["src/app.ts", "src/utils.ts"] });

// Get execution plan as JSON
const plan = await fix({ explain: "json" });
if (plan.success) {
  for (const group of plan.plan.groups) {
    for (const pg of group.parallelGroups) {
      for (const task of pg.tasks) {
        console.log(`${task.toolName}: ${task.fileCount} files`);
      }
    }
  }
}

// Fix with specific tools only
await fix({ tools: ["prettier", "eslint"], files: ["src/app.ts"] });

// Use custom config
await fix({ config: ["/path/to/custom.config.js"] });
```

---

### lint()

Validate files without making changes.

```typescript
function lint(options?: LintOptions): Promise<LintResult>;
```

**Options:** Same as [`fix()`](#fix) (`LintOptions` has the same fields as `FixOptions`).

**Result:** Same structure as [`fix()`](#fix).

**Examples:**

```javascript

// Lint all files
const result = await lint();
if (!result.success) {
  console.error("Lint failed:", result.error);
  process.exit(1);
}

// Get detailed lint plan
const plan = await lint({ explain: "json" });
```

---

### check()

Run fix then lint in a single process with shared context. Fails on fix error without continuing to lint.

```typescript
function check(options?: CheckOptions): Promise<CheckResult>;
```

**Options:** Same as [`fix()`](#fix) (`CheckOptions` has the same fields as `FixOptions`).

**Result:** Same structure as [`fix()`](#fix).

**Examples:**

```javascript

// Run full check (fix + lint)
const result = await check();
if (!result.success) {
  console.error("Check failed:", result.error);
}

// Check specific files with plan output
const plan = await check({ explain: "json", files: ["src/app.ts"] });
```

---

### exec()

Execute a managed binary or list available tools.

```typescript
function exec(appName?: string, options?: ExecOptions): Promise<ExecResult>;
```

**Options:**

| Option         | Type                  | Default         | Description                                  |
| -------------- | --------------------- | --------------- | -------------------------------------------- |
| `args`         | `string[]`            | `[]`            | Arguments to pass to the app                 |
| `cwd`          | `string`              | `process.cwd()` | Working directory                            |
| `config`       | `string[]`            | `[]`            | Additional config file paths                 |
| `beforeConfig` | `string[]`            | `[]`            | Config files loaded before auto-discovery    |
| `noAutoConfig` | `boolean`             | `false`         | Disable auto-discovery of config at git root |
| `stdio`        | `"pipe" \| "inherit"` | `"pipe"`        | Output handling mode                         |

**Result:**

```typescript
// On failure
{ success: false; error: string; exitCode?: number; raw: SpawnRaw }

// List tools (no appName)
{ success: true; tools: ToolInfo[]; raw: SpawnRaw }

// Execute app (with appName)
{ success: true; stdout: string; stderr: string; exitCode: number; raw: SpawnRaw }
```

**Examples:**

```javascript

// List all available tools
const list = await exec();
if (list.success) {
  for (const tool of list.tools) {
    console.log(`${tool.name} [${tool.type}] - ${tool.details}`);
  }
}

// Execute a managed binary
const result = await exec("golangci-lint", {
  args: ["run", "./..."],
});

// Stream output from a managed binary
await exec("prettier", {
  args: ["--write", "src/**/*.ts"],
  stdio: "inherit",
});
```

#### ToolInfo

Returned when calling `exec()` without an app name:

```typescript
interface ToolInfo {
  name: string; // Tool name (e.g., "golangci-lint")
  type: string; // Tool type: "binary" | "uv" | "node" | "jvm" | "go" | "shell"
  details: string; // Description or version info
}
```

#### parseToolList()

A utility function for manually parsing tool list output:

```typescript
function parseToolList(output: string): ToolInfo[];
```

```javascript

// Parse raw output from `datamitsu exec`
const tools = parseToolList(rawOutput);
```

---

### cache

Object with three methods for cache management.

#### cache.clear()

Clear the project cache.

```typescript
function cache.clear(options?: CacheClearOptions): Promise<CacheClearResult>;
```

**Options:**

| Option   | Type      | Default         | Description                                    |
| -------- | --------- | --------------- | ---------------------------------------------- |
| `all`    | `boolean` | `false`         | Clear all project caches, not just current     |
| `dryRun` | `boolean` | `false`         | Preview what would be cleared without clearing |
| `cwd`    | `string`  | `process.cwd()` | Working directory                              |

**Result:**

```typescript
// On failure
{
  success: false;
  error: string;
  exitCode: number;
  raw: SpawnRaw;
}

// On success
{
  success: true;
  message: string;
  raw: SpawnRaw;
}
```

**Examples:**

```javascript

// Clear current project cache
await cache.clear();

// Clear all caches
await cache.clear({ all: true });

// Dry run
const preview = await cache.clear({ dryRun: true });
console.log(preview.message);
```

#### cache.path()

Get the global cache directory path.

```typescript
function cache.path(): Promise<CachePathResult>;
```

**Result:**

```typescript
// On failure
{
  success: false;
  error: string;
  exitCode: number;
  raw: SpawnRaw;
}

// On success
{
  success: true;
  path: string;
  raw: SpawnRaw;
}
```

**Example:**

```javascript
const result = await cache.path();
if (result.success) {
  console.log(result.path); // e.g., "/home/user/.cache/datamitsu/cache"
}
```

#### cache.pathProject()

Get the current project's cache directory path.

```typescript
function cache.pathProject(options?: { cwd?: string }): Promise<CachePathResult>;
```

**Example:**

```javascript
const result = await cache.pathProject();
if (result.success) {
  console.log(result.path); // e.g., "/home/user/.cache/datamitsu/cache/projects/abc123"
}
```

---

### version()

Get the installed datamitsu version.

```typescript
function version(): Promise<VersionResult>;
```

**Result:**

```typescript
// On failure
{
  success: false;
  error: string;
  exitCode: number;
  raw: SpawnRaw;
}

// On success
{
  success: true;
  version: string;
  raw: SpawnRaw;
}
```

**Example:**

```javascript

const result = await version();
if (result.success) {
  console.log(`datamitsu v${result.version}`);
}
```

## Types Reference

### PlanJSON

Returned by fix/lint/check when using `explain: "json"`. Represents the full execution plan.

```typescript
interface PlanJSON {
  operation: string; // "fix", "lint", or "check"
  rootPath: string; // Git repository root
  cwdPath: string; // Current working directory
  groups: GroupJSON[]; // Ordered execution groups
  skipped: SkippedToolJSON[]; // Tools that will not run; empty when none
}

interface SkippedToolJSON {
  toolName: string; // Tool identifier
  operation: string; // "fix" or "lint"
  reason: "config" | "unsupported-platform" | "not-narrowable";
  detail?: string; // Configured skipReason, or the unsupported platform
}

interface GroupJSON {
  priority: number; // Execution priority
  parallelGroups: ParallelGroupJSON[]; // Groups within this priority
}

interface ParallelGroupJSON {
  canRunInParallel: boolean; // Whether tasks can run concurrently
  tasks: TaskJSON[]; // Tasks in this parallel group
}

interface TaskJSON {
  toolName: string; // Tool identifier
  app: string; // Binary/application name
  args: string[]; // Command arguments
  scope: string; // Execution scope
  arity: "many" | "one" | "dir" | "none"; // argv path shape (inferred)
  granularity: "file" | "unit" | "repo"; // smallest complete input set (inferred)
  coverage: "complete" | "partial"; // whether the task answers for its whole unit
  workingDir: string; // Task working directory
  globs?: string[]; // File glob patterns (omitted when empty)
  excludeGlobs?: string[]; // Patterns removed from the matched set (omitted when empty)
  files: string[]; // Matched file paths
  fileCount: number; // Number of matched files
}
```

### SpawnRaw

Available on all results via the `raw` field, providing access to the underlying process output:

```typescript
interface SpawnRaw {
  stdout: string; // Standard output
  stderr: string; // Standard error
  exitCode: number; // Process exit code
  failed: boolean; // Whether the process failed
}
```

## Error Handling

The API uses an explicit `success` flag pattern instead of exceptions:

- **Spawn errors** (binary not found, permission denied) throw exceptions
- **Tool errors** (non-zero exit code) return `{ success: false, error, exitCode }`

```javascript

try {
  const result = await fix({ files: ["src/app.ts"] });

  if (!result.success) {
    // Tool reported an error (e.g., lint violations)
    console.error("Fix failed:", result.error);
    console.error("Exit code:", result.exitCode);
    // Raw output available for debugging
    console.error("stderr:", result.raw.stderr);
    process.exit(1);
  }

  // Success
  console.log("Fixed successfully");
} catch (err) {
  // Binary not found or spawn error
  console.error("Could not run datamitsu:", err.message);
  process.exit(1);
}
```

## Use Cases

### Code Generation + Fix

```javascript

// Generate code
const code = generateTypeScriptCode();
await writeFile("src/generated.ts", code);

// Auto-fix formatting and lint issues
const result = await fix({ files: ["src/generated.ts"] });
if (!result.success) {
  console.error("Could not fix generated file:", result.error);
}
```

### CI Lint Check

```javascript

const result = await lint();
if (!result.success) {
  console.error(result.error);
  process.exit(1);
}
```

### Build Script Integration

```javascript

const v = await version();
console.log(`Running datamitsu v${v.version}`);

const result = await check({ stdio: "inherit" });
process.exit(result.success ? 0 : 1);
```

---

## Parser Catalog

:::info Auto-generated
This page is generated from the WASM parser module's `describe` output by
`packaging/parsers-catalog.ts`, run from `task build:parsers`. Do not edit by hand.
:::

datamitsu ships a single signed Rust → WASM module (`datamitsu-parsers`) that turns these **97 tools**' raw output into structured diagnostics. Wire one to a tool with [`outputParser`](./configuration-api.md#output-parser-outputparser) — the **Parser** name below is its `parser` field.

**Levels** are the level words the tool prints, which the parser maps onto error, warning, info and hint; `none` means the tool prints no level ([how the core resolves a finding without one](../guides/architecture/parsers.md#levels)). **Columns** is the unit the tool counts columns in, where it was measured. **Category** marks a security scanner.

| Parser                 | Modes | Levels                                                                           | Columns | Category | Description                                                                                                                                                                                                                                                                   | Upstream                                                                             |
| ---------------------- | ----- | -------------------------------------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `actionlint`           | lint  | none                                                                             | utf-8   | —        | Actionlint is a static checker for GitHub Actions workflow files.                                                                                                                                                                                                             | [link](https://github.com/rhysd/actionlint)                                          |
| `alex`                 | lint  | `error`, `warning`, `info`                                                       | —       | —        | Catch insensitive, inconsiderate writing.                                                                                                                                                                                                                                     | [link](https://github.com/get-alex/alex)                                             |
| `ansiblelint`          | lint  | `major`, `minor`                                                                 | —       | —        | Linter for Ansible playbooks, roles and collections.                                                                                                                                                                                                                          | [link](https://github.com/ansible-community/ansible-lint)                            |
| `bean_check`           | lint  | none                                                                             | —       | —        | Beancount: text-based double-entry accounting tool                                                                                                                                                                                                                            | [link](https://github.com/beancount/beancount)                                       |
| `bslint`               | lint  | `error`, `warning`, `info`, `hint`                                               | —       | —        | A brighterscript CLI tool to lint your code without compiling your project.                                                                                                                                                                                                   | [link](https://github.com/rokucommunity/bslint)                                      |
| `buf`                  | lint  | none                                                                             | —       | —        | A new way of working with Protocol Buffers.                                                                                                                                                                                                                                   | [link](https://github.com/bufbuild/buf)                                              |
| `buildifier`           | lint  | `warnings`                                                                       | —       | —        | buildifier is a tool for formatting and linting bazel BUILD, WORKSPACE, and .bzl files.                                                                                                                                                                                       | [link](https://github.com/bazelbuild/buildtools/tree/master/buildifier)              |
| `cfn_lint`             | lint  | `E`, `W`, `I`                                                                    | —       | —        | Validate AWS CloudFormation yaml/json templates against the AWS CloudFormation Resource Specification                                                                                                                                                                         | [link](https://github.com/aws-cloudformation/cfn-lint)                               |
| `checkmake`            | lint  | none                                                                             | —       | —        | `make` linter.                                                                                                                                                                                                                                                                | [link](https://github.com/mrtazz/checkmake)                                          |
| `checkstyle`           | lint  | `error`, `warning`, `note`                                                       | —       | —        | Checkstyle is a tool for checking Java source code for adherence to a Code Standard or set of validation rules (best practices).                                                                                                                                              | [link](https://checkstyle.org)                                                       |
| `clazy`                | lint  | `error`, `fatal error`, `warning`, `note`, `remark`                              | —       | —        | Qt-oriented static code analyzer based on the Clang framework                                                                                                                                                                                                                 | [link](https://github.com/KDE/clazy)                                                 |
| `clj_kondo`            | lint  | `error`, `Exception`, `warning`, `info`                                          | —       | —        | A linter for clojure code that sparks joy                                                                                                                                                                                                                                     | [link](https://github.com/clj-kondo/clj-kondo)                                       |
| `cmake_lint`           | lint  | `E`, `W`, `C`, `R`, `I`                                                          | —       | —        | Check cmake listfiles for style violations, common mistakes, and anti-patterns.                                                                                                                                                                                               | [link](https://github.com/cheshirekow/cmake_format)                                  |
| `codespell`            | lint  | none                                                                             | —       | —        | Codespell finds common misspellings in text files.                                                                                                                                                                                                                            | [link](https://github.com/codespell-project/codespell)                               |
| `commitlint`           | lint  | `1`, `2`                                                                         | —       | —        | commitlint checks if your commit messages meet the conventional commit format.                                                                                                                                                                                                | [link](https://commitlint.js.org)                                                    |
| `cppcheck`             | lint  | `error`, `warning`, `performance`, `note`, `portability`, `information`, `style` | —       | —        | A tool for fast static analysis of C/C++ code.                                                                                                                                                                                                                                | [link](https://github.com/danmar/cppcheck)                                           |
| `credo`                | lint  | `higher`, `high`, `normal`, `low`, `ignore`                                      | —       | —        | Static analysis of `elixir` files for enforcing code consistency.                                                                                                                                                                                                             | [link](https://hexdocs.pm/credo)                                                     |
| `cspell`               | lint  | none                                                                             | utf-16  | —        | A spell checker for code.                                                                                                                                                                                                                                                     | [link](https://cspell.org)                                                           |
| `cue_fmt`              | lint  | none                                                                             | —       | —        | Reports formatting/vet errors in .cue files.                                                                                                                                                                                                                                  | [link](https://github.com/cue-lang/cue)                                              |
| `dclint`               | lint  | `error`, `warning`                                                               | —       | —        | A command-line tool for validating and enforcing best practices in Docker Compose files.                                                                                                                                                                                      | [link](https://github.com/zavoloklom/docker-compose-linter)                          |
| `deadnix`              | lint  | none                                                                             | —       | —        | Scan Nix files for dead code.                                                                                                                                                                                                                                                 | [link](https://github.com/astro/deadnix)                                             |
| `djlint`               | lint  | none                                                                             | —       | —        | ✨ 📜 🪄 ✨ HTML Template Linter and Formatter.                                                                                                                                                                                                                               | [link](https://github.com/Riverside-Healthcare/djLint)                               |
| `dotenv_linter`        | lint  | none                                                                             | —       | —        | Lightning-fast linter for .env files.                                                                                                                                                                                                                                         | [link](https://github.com/dotenv-linter/dotenv-linter)                               |
| `droast`               | lint  | `ERROR`, `WARN`, `WARNING`, `INFO`, `x`, `!`                                     | —       | —        | An opinionated Dockerfile linter with governed suppressions, build-context and ShellCheck awareness.                                                                                                                                                                          | [link](https://github.com/immanuwell/dockerfile-roast)                               |
| `editorconfig_checker` | lint  | none                                                                             | —       | —        | A tool to verify that your files are in harmony with your `.editorconfig`.                                                                                                                                                                                                    | [link](https://github.com/editorconfig-checker/editorconfig-checker)                 |
| `erb_lint`             | lint  | none                                                                             | —       | —        | Lint your ERB or HTML files                                                                                                                                                                                                                                                   | [link](https://github.com/Shopify/erb-lint)                                          |
| `eslint`               | lint  | `2`, `1`                                                                         | utf-16  | —        | Pluggable linter for JavaScript and TypeScript.                                                                                                                                                                                                                               | [link](https://eslint.org)                                                           |
| `fish`                 | lint  | none                                                                             | —       | —        | Basic linting is available for fish scripts using `fish --no-execute`.                                                                                                                                                                                                        | [link](https://github.com/fish-shell/fish-shell)                                     |
| `gccdiag`              | lint  | `fatal error`, `error`, `warning`, `note`, `info`                                | —       | —        | gccdiag is a wrapper for any C/C++ compiler (gcc, avr-gcc, arm-none-eabi-gcc, etc) that automatically uses the correct compiler arguments for a file in your project by parsing the `compile_commands.json` file at the root of your project.                                 | [link](https://gitlab.com/andrejr/gccdiag)                                           |
| `gdlint`               | lint  | `Error`                                                                          | —       | —        | A linter that performs a static analysis on gdscript code according to some predefined configuration.                                                                                                                                                                         | [link](https://github.com/Scony/godot-gdscript-toolkit)                              |
| `gitleaks`             | lint  | none                                                                             | —       | security | Gitleaks is a SAST tool for detecting and preventing hardcoded secrets like passwords, API keys, and tokens in git repos.                                                                                                                                                     | [link](https://github.com/gitleaks/gitleaks)                                         |
| `gitlint`              | lint  | none                                                                             | —       | —        | Linter for Git commit messages.                                                                                                                                                                                                                                               | [link](https://jorisroovers.com/gitlint/)                                            |
| `glslc`                | lint  | `error`, `warning`                                                               | —       | —        | Shader to SPIR-V compiler.                                                                                                                                                                                                                                                    | [link](https://github.com/google/shaderc)                                            |
| `golangci_lint`        | lint  | `error`, `warning`, `info`                                                       | utf-8   | —        | A Go linter aggregator.                                                                                                                                                                                                                                                       | [link](https://golangci-lint.run/)                                                   |
| `hadolint`             | lint  | `error`, `warning`, `info`, `style`                                              | —       | —        | A smarter Dockerfile linter that helps you build best-practice Docker images.                                                                                                                                                                                                 | [link](https://github.com/hadolint/hadolint)                                         |
| `haml_lint`            | lint  | `error`, `warning`                                                               | —       | —        | Tool for writing clean and consistent HAML.                                                                                                                                                                                                                                   | [link](https://github.com/sds/haml-lint)                                             |
| `harper_cli`           | lint  | none                                                                             | utf-32  | —        | A grammar and style checker.                                                                                                                                                                                                                                                  | [link](https://writewithharper.com)                                                  |
| `knip`                 | lint  | none                                                                             | —       | —        | Find unused files, dependencies and exports in JavaScript and TypeScript projects.                                                                                                                                                                                            | [link](https://knip.dev)                                                             |
| `ktfmt`                | lint  | `error`                                                                          | utf-16  | —        | Kotlin formatting differences and syntax errors from ktfmt's dry run.                                                                                                                                                                                                         | [link](https://github.com/facebook/ktfmt)                                            |
| `ktlint`               | lint  | `errors`                                                                         | utf-16  | —        | An anti-bikeshedding Kotlin linter with built-in formatter.                                                                                                                                                                                                                   | [link](https://ktlint.github.io/)                                                    |
| `kube_linter`          | lint  | none                                                                             | —       | —        | KubeLinter is a static analysis tool that checks Kubernetes YAML files and Helm charts to ensure the applications represented in them adhere to best practices.                                                                                                               | [link](https://github.com/stackrox/kube-linter)                                      |
| `ltrs`                 | lint  | none                                                                             | —       | —        | LanguageTool-Rust (LTRS) is both an executable and a Rust library that aims to provide correct and safe bindings for the LanguageTool API.                                                                                                                                    | [link](https://github.com/jeertmans/languagetool-rust)                               |
| `markdownlint`         | lint  | `error`, `warning`                                                               | —       | —        | Markdown style and syntax checker.                                                                                                                                                                                                                                            | [link](https://github.com/DavidAnson/markdownlint)                                   |
| `markdownlint_cli2`    | lint  | `error`, `warning`                                                               | —       | —        | A fast, flexible, configuration-based command-line interface for linting Markdown/CommonMark files with the markdownlint library                                                                                                                                              | [link](https://github.com/DavidAnson/markdownlint-cli2)                              |
| `markuplint`           | lint  | `error`, `warning`, `info`                                                       | —       | —        | A linter for all markup developers.                                                                                                                                                                                                                                           | [link](https://github.com/markuplint/markuplint)                                     |
| `mdl`                  | lint  | none                                                                             | —       | —        | A tool to check Markdown files and flag style issues.                                                                                                                                                                                                                         | [link](https://github.com/markdownlint/markdownlint)                                 |
| `mlint`                | lint  | none                                                                             | —       | —        | Linter for MATLAB files                                                                                                                                                                                                                                                       | [link](https://www.mathworks.com/help/matlab/ref/mlint.html)                         |
| `mypy`                 | lint  | `error`, `warning`, `note`                                                       | —       | —        | Mypy is an optional static type checker for Python that aims to combine the benefits of dynamic (or "duck") typing and static typing.                                                                                                                                         | [link](https://github.com/python/mypy)                                               |
| `npm_groovy_lint`      | lint  | `error`, `warning`, `info`                                                       | —       | —        | Lint, format and auto-fix Groovy, Jenkinsfile, and Gradle files.                                                                                                                                                                                                              | [link](https://github.com/nvuillam/npm-groovy-lint)                                  |
| `opacheck`             | lint  | `errors`                                                                         | —       | —        | Check Rego source files for parse and compilation errors.                                                                                                                                                                                                                     | [link](https://www.openpolicyagent.org/docs/latest/cli/#opa-check)                   |
| `opentofu_validate`    | lint  | `error`, `warning`                                                               | —       | —        | OpenTofu `validate` is a subcommand of OpenTofu to validate configuration files in a directory, referring only to the configuration and not accessing any remote services such as remote state, provider APIs, etc.                                                           | [link](https://opentofu.org/docs/cli/commands/validate)                              |
| `perlimports`          | lint  | none                                                                             | —       | —        | A command line utility for cleaning up imports in your Perl code                                                                                                                                                                                                              | [link](https://metacpan.org/dist/App-perlimports/view/script/perlimports)            |
| `phpcs`                | lint  | `ERROR`, `WARNING`                                                               | —       | —        | PHP_CodeSniffer is a script that tokenizes PHP, JavaScript and CSS files to detect violations of a defined coding standard.                                                                                                                                                   | [link](https://github.com/squizlabs/PHP_CodeSniffer)                                 |
| `phpmd`                | lint  | `1`, `2`, `3`, `4`, `5`                                                          | —       | —        | Runs PHP Mess Detector against PHP files.                                                                                                                                                                                                                                     | [link](https://github.com/phpmd/phpmd/)                                              |
| `phpstan`              | lint  | none                                                                             | —       | —        | PHP static analysis tool.                                                                                                                                                                                                                                                     | [link](https://github.com/phpstan/phpstan)                                           |
| `pmd`                  | lint  | `1`, `2`, `3`, `4`, `5`                                                          | —       | —        | An extensible cross-language static code analyzer.                                                                                                                                                                                                                            | [link](https://pmd.github.io)                                                        |
| `proselint`            | lint  | none                                                                             | —       | —        | An English prose linter.                                                                                                                                                                                                                                                      | [link](https://github.com/amperser/proselint)                                        |
| `protolint`            | lint  | `error`, `warning`, `note`                                                       | utf-32  | —        | A pluggable linter and fixer to enforce Protocol Buffer style and conventions.                                                                                                                                                                                                | [link](https://github.com/yoheimuta/protolint)                                       |
| `puppet_lint`          | lint  | `error`, `warning`                                                               | —       | —        | Check that your Puppet manifest conforms to the style guide.                                                                                                                                                                                                                  | [link](http://puppet-lint.com/)                                                      |
| `pydoclint`            | lint  | none                                                                             | —       | —        | Pydoclint is a Python docstring linter to check whether a docstring's sections (arguments, returns, raises, ...) match the function signature or function implementation. To see all violation codes go to [pydoclint](https://jsh9.github.io/pydoclint/violation_codes.html) | [link](https://github.com/jsh9/pydoclint)                                            |
| `pylint`               | lint  | `fatal`, `error`, `warning`, `convention`, `refactor`, `info`                    | —       | —        | Pylint is a Python static code analysis tool which looks for programming errors, helps enforcing a coding standard, sniffs for code smells and offers simple refactoring suggestions.                                                                                         | [link](https://github.com/PyCQA/pylint)                                              |
| `qmllint`              | lint  | `Error`, `Warning`                                                               | —       | —        | qmllint is a tool shipped with Qt that verifies the syntactic validity of QML files. It also warns about some QML anti-patterns.                                                                                                                                              | [link](https://doc-snapshots.qt.io/qt6-dev/qtquick-tools-and-utilities.html#qmllint) |
| `reek`                 | lint  | none                                                                             | —       | —        | Code smell detector for Ruby                                                                                                                                                                                                                                                  | [link](https://github.com/troessner/reek)                                            |
| `regal`                | lint  | `error`, `warning`                                                               | —       | —        | Regal is a linter for Rego, with the goal of making your Rego magnificent!.                                                                                                                                                                                                   | [link](https://docs.styra.com/regal)                                                 |
| `revive`               | lint  | `error`, `warning`                                                               | —       | —        | Fast, configurable, extensible, flexible, and beautiful linter for Go.                                                                                                                                                                                                        | [link](https://revive.run/)                                                          |
| `rpmspec`              | lint  | `error`, `warning`                                                               | —       | —        | Command line tool to parse RPM spec files.                                                                                                                                                                                                                                    | [link](https://rpm.org/)                                                             |
| `rstcheck`             | lint  | `SEVERE`, `ERROR`, `WARNING`, `INFO`                                             | —       | —        | Checks syntax of reStructuredText and code blocks nested within it.                                                                                                                                                                                                           | [link](https://github.com/myint/rstcheck)                                            |
| `rubocop`              | lint  | `fatal`, `error`, `warning`, `convention`, `info`, `refactor`                    | —       | —        | The Ruby Linter/Formatter that Serves and Protects.                                                                                                                                                                                                                           | [link](https://rubocop.org/)                                                         |
| `saltlint`             | lint  | `VERY_HIGH`, `HIGH`, `MEDIUM`, `LOW`, `VERY_LOW`, `INFO`                         | —       | —        | A command-line utility that checks for best practices in SaltStack.                                                                                                                                                                                                           | [link](https://github.com/warpnet/salt-lint)                                         |
| `selene`               | lint  | `Error`, `Warning`                                                               | —       | —        | Command line tool designed to help write correct and idiomatic Lua code.                                                                                                                                                                                                      | [link](https://kampfkarren.github.io/selene/)                                        |
| `semgrep`              | lint  | `ERROR`, `WARNING`, `INFO`, `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`                  | —       | security | Semgrep is a fast, open-source, static analysis tool for finding bugs and enforcing code standards at editor, commit, and CI time.                                                                                                                                            | [link](https://semgrep.dev/)                                                         |
| `solhint`              | lint  | `Error`, `Warning`                                                               | —       | —        | An open source project for linting Solidity code. It provides both security and style guide validations.                                                                                                                                                                      | [link](https://protofire.github.io/solhint/)                                         |
| `spectral`             | lint  | `0`, `1`, `2`, `3`                                                               | —       | —        | A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI v3.1, v3.0, and v2.0.                                                                                                                                                      | [link](https://github.com/stoplightio/spectral)                                      |
| `sqlfluff`             | lint  | `failure`, `warning`, `notice`                                                   | —       | —        | A SQL linter and auto-formatter for Humans                                                                                                                                                                                                                                    | [link](https://github.com/sqlfluff/sqlfluff)                                         |
| `sqruff`               | lint  | `error`, `warning`, `notice`, `Error`, `Warning`, `Information`, `Hint`          | utf-32  | —        | A high-speed SQL linter written in Rust.                                                                                                                                                                                                                                      | [link](https://github.com/quarylabs/sqruff)                                          |
| `staticcheck`          | lint  | `error`, `warning`                                                               | —       | —        | Advanced Go linter.                                                                                                                                                                                                                                                           | [link](https://staticcheck.io/)                                                      |
| `statix`               | lint  | `E`, `W`, `I`                                                                    | —       | —        | Lints and suggestions for the Nix programming language.                                                                                                                                                                                                                       | [link](https://github.com/nerdypepper/statix)                                        |
| `stylint`              | lint  | `error`, `warning`                                                               | —       | —        | A linter for the Stylus CSS preprocessor.                                                                                                                                                                                                                                     | [link](https://github.com/SimenB/stylint)                                            |
| `swiftlint`            | lint  | `Error`, `Warning`                                                               | —       | —        | A tool to enforce Swift style and conventions.                                                                                                                                                                                                                                | [link](https://github.com/realm/SwiftLint)                                           |
| `teal`                 | lint  | `error`, `errors`, `syntax error`, `syntax errors`, `warning`, `warnings`        | —       | —        | The compiler for Teal, a typed dialect of Lua.                                                                                                                                                                                                                                | [link](https://github.com/teal-language/tl)                                          |
| `terraform_validate`   | lint  | `error`, `warning`                                                               | —       | —        | Terraform validate is is a subcommand of terraform to validate configuration files in a directory                                                                                                                                                                             | [link](https://github.com/hashicorp/terraform)                                       |
| `terragrunt_validate`  | lint  | `error`, `warning`                                                               | —       | —        | Terragrunt validate is is a subcommand of terragrunt to validate configuration files in a directory                                                                                                                                                                           | [link](https://terragrunt.gruntwork.io/docs/reference/cli-options/#validate-inputs)  |
| `textidote`            | lint  | none                                                                             | —       | —        | Spelling, grammar and style checking on LaTeX documents.                                                                                                                                                                                                                      | [link](https://github.com/sylvainhalle/textidote)                                    |
| `textlint`             | lint  | `1`, `2`, `3`                                                                    | —       | —        | The pluggable linting tool for text and Markdown.                                                                                                                                                                                                                             | [link](https://github.com/textlint/textlint)                                         |
| `tfsec`                | lint  | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`                                              | —       | security | Security scanner for Terraform code                                                                                                                                                                                                                                           | [link](https://github.com/aquasecurity/tfsec)                                        |
| `tidy`                 | lint  | `Error`, `Warning`, `Info`                                                       | —       | —        | Tidy corrects and cleans up HTML and XML documents by fixing markup errors and upgrading legacy code to modern standards.                                                                                                                                                     | [link](https://www.html-tidy.org/)                                                   |
| `trivy`                | lint  | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`                                              | —       | security | Find misconfigurations and vulnerabilities                                                                                                                                                                                                                                    | [link](https://github.com/aquasecurity/trivy)                                        |
| `tsc`                  | lint  | `error`, `warning`                                                               | utf-16  | —        | TypeScript compiler type diagnostics (also covers tsgo).                                                                                                                                                                                                                      | [link](https://www.typescriptlang.org)                                               |
| `twigcs`               | lint  | `1`, `2`, `3`                                                                    | —       | —        | Runs Twigcs against Twig files.                                                                                                                                                                                                                                               | [link](https://github.com/friendsoftwig/twigcs)                                      |
| `ty`                   | lint  | `error`, `warning`, `info`                                                       | utf-32  | —        | Python type diagnostics from ty's concise reporter.                                                                                                                                                                                                                           | [link](https://docs.astral.sh/ty/)                                                   |
| `vacuum`               | lint  | `error`, `warn`, `info`, `hint`, `warning`, `notice`                             | utf-32  | —        | The world’s fastest and most scalable OpenAPI linter.                                                                                                                                                                                                                         | [link](https://quobix.com/vacuum)                                                    |
| `vale`                 | lint  | `error`, `warning`, `suggestion`                                                 | utf-32  | —        | Syntax-aware linter for prose built with speed and extensibility in mind.                                                                                                                                                                                                     | [link](https://vale.sh/)                                                             |
| `verilator`            | lint  | `Error`, `Warning`                                                               | —       | —        | Verilog and SystemVerilog linter power by Verilator                                                                                                                                                                                                                           | [link](https://www.veripool.org/verilator/)                                          |
| `vint`                 | lint  | `error`, `warning`, `style_problem`                                              | —       | —        | Linter for Vimscript.                                                                                                                                                                                                                                                         | [link](https://github.com/Vimjas/vint)                                               |
| `write_good`           | lint  | none                                                                             | —       | —        | English prose linter.                                                                                                                                                                                                                                                         | [link](https://github.com/btford/write-good)                                         |
| `yamllint`             | lint  | `error`, `warning`                                                               | utf-32  | —        | A linter for YAML files.                                                                                                                                                                                                                                                      | [link](https://github.com/adrienverge/yamllint)                                      |
| `zsh`                  | lint  | `parse error`                                                                    | —       | —        | Uses zsh's own -n option to evaluate, but not execute, zsh scripts. Effectively, this acts somewhat like a linter, although it only really checks for serious errors - and will likely only show the first error.                                                             | [link](https://www.zsh.org/)                                                         |

## Format parsers

Many tools print a standard format on request. These parsers read one such shape whatever tool printed it, under the same `outputParser.parser` field; `fallback` tries them all in turn and answers with the first that recognizes the output ([format parsers](../guides/architecture/parsers.md#format-parsers)). A format counts columns in whatever unit the tool that printed it does, so none declares one.

| Parser               | Levels                                                                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                    | Specification                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `azure-logissue`     | `error`, `warning`                                                                                                                    | Azure Pipelines logging commands `##vso[task.logissue type=…;sourcepath=…;linenumber=…;columnnumber=…;code=…]message`, as `ruff check --output-format azure` prints them. Recognized when a line matches.                                                                                                                                                                                      | [link](https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands)                       |
| `checkstyle-xml`     | `error`, `warning`, `info`                                                                                                            | Checkstyle XML, as linters print it on request: `shellcheck -f checkstyle`, `hadolint -f checkstyle`, `tflint -f checkstyle`, `oxlint --format checkstyle`, `phpcs --report=checkstyle`. Recognized by a `\<checkstyle>` root, files or not.                                                                                                                                                   | [link](https://checkstyle.org)                                                                                  |
| `codeclimate`        | `blocker`, `critical`, `major`, `minor`, `info`                                                                                       | Code Climate issues, as GitLab Code Quality reads them: `ruff check --output-format gitlab`, `golangci-lint run --output.code-climate.path=stdout`. Recognized by a JSON array whose every element carries `check_name` and `location.path`.                                                                                                                                                   | [link](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md)                              |
| `eslint-json`        | `2`, `1`                                                                                                                              | ESLint's JSON report, `eslint --format json`, and any linter that prints its result array. Recognized by an array whose every element carries `filePath` and a `messages` array, findings or not.                                                                                                                                                                                              | [link](https://eslint.org/docs/latest/use/formatters/#json)                                                     |
| `fallback`           | `error`, `fatal error`, `blocker`, `critical`, `major`, `2`, `warning`, `minor`, `1`, `note`, `notice`, `info`, `information`, `hint` | Tries every format parser — sarif, codeclimate, eslint-json, json, checkstyle-xml, junit-xml, github-annotations, azure-logissue, msvc, gcc — in that order and answers with the first that recognizes the output, named by its format. The core runs the build of it embedded in the binary when a tool's output has no parser that recognized it; `devtools parsers sniff` shows its choice. | —                                                                                                               |
| `gcc`                | `fatal error`, `error`, `warning`, `note`, `info`                                                                                     | The compiler line `path:line:col: level: message` (and `path:line: message`), as gcc and clang print it and as linters print it on request: `typos --format brief`, `shellcheck -f gcc`, `golangci-lint run --output.text.path=stdout`. A trailing `[rule]` or `(rule)` becomes the code. Recognized when a line matches.                                                                      | [link](https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html)                           |
| `github-annotations` | `error`, `warning`, `notice`                                                                                                          | GitHub workflow commands `::error file=…,line=…,col=…,endLine=…,endColumn=…,title=…::message`, as `ruff check --output-format github` and `yamllint -f github` print them; `title` becomes the code. Recognized when a line matches.                                                                                                                                                           | [link](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands)                    |
| `json`               | `error`, `warning`, `info`, `information`, `hint`                                                                                     | The plain JSON array none-ls reads by default: objects with `message`, `line`, `column`, `endLine`, `endColumn`, `ruleId`, `level` and `file`. Recognized by an array whose every element carries `message` and `line`.                                                                                                                                                                        | —                                                                                                               |
| `junit-xml`          | `error`, `warning`, `info`                                                                                                            | JUnit XML, as `golangci-lint run --output.junit-xml.path=stdout` and test runners print it: one finding per `failure` or `error` of a test case, whose name is the code. Recognized by a `\<testsuites>` or `\<testsuite>` root, failures or not.                                                                                                                                              | —                                                                                                               |
| `msvc`               | `fatal error`, `error`, `warning`                                                                                                     | The MSVC line `path(line,col): error CODE: message`, as MSVC and `tsc --pretty false` print it. Recognized when a line matches.                                                                                                                                                                                                                                                                | [link](https://learn.microsoft.com/en-us/cpp/build/formatting-the-output-of-a-custom-build-step-or-build-event) |
| `sarif`              | `error`, `warning`, `note`                                                                                                            | SARIF 2.1.0, the static-analysis interchange format: `ruff check --output-format sarif`, `semgrep --sarif`, `checkstyle -f sarif`, `trivy fs --format sarif`. Recognized by a JSON object with `version` and a `runs` array, findings or not.                                                                                                                                                  | [link](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)                                        |

---

## Template Placeholders


Tool operation **arguments** (`args`) and **environment-variable values** (`env`) support template placeholders that datamitsu resolves before executing the tool. These let you reference file paths, project directories, and cache locations dynamically.

## Available Placeholders

| Placeholder     | Resolves To                                  | `args` | `env` | Typical Use Case                  |
| --------------- | -------------------------------------------- | :----: | :---: | --------------------------------- |
| `{file}`        | Single file path (per-file scope)            |   ✅   |  ❌   | `"{file}"`                        |
| `{files}`       | Separate arguments per file                  |   ✅   |  ❌   | `"{files}"`                       |
| `{root}`        | Git repository root                          |   ✅   |  ✅   | `"{root}/.config"`                |
| `{cwd}`         | Per-project working directory                |   ✅   |  ✅   | `"{cwd}/src"`                     |
| `{toolCache}`   | Per-project, per-tool cache directory        |   ✅   |  ✅   | `"{toolCache}/tsbuildinfo"`       |
| `{target}`      | The single directory a scanner scans         |   ✅   |  ❌   | `"{target}"`                      |
| `{bin:<alias>}` | Executable of the operation app's dependency |   ✅   |  ✅   | `"{bin:validator} check {files}"` |

`{file}`, `{files}` and `{target}` are argument concepts and are **not**
available in `env` values (an environment variable holds a single string, not an
argument list). The path placeholders `{root}`, `{cwd}` and `{toolCache}` work in
both `args` and `env`.

`{bin:<alias>}` names a direct `dependsOn` edge of the operation's app
(by alias — `{ app: "jsonschema", as: "validator" }` binds as
`{bin:validator}`) and resolves to the dependency's exact executable:
binary, uv and go targets today. It is validated at load time against the
app's edges, and expansion is read-only: no install, no prepare step.

:::warning Unknown placeholders are a hard error
datamitsu validates every `{placeholder}` in tool `args` and `env` at config-load
time. If you use a token that datamitsu does not substitute (a typo like
`{toolcache}`, an unsupported name like `{cache}`, or an `args`-only placeholder
such as `{file}` inside `env`), config loading **fails immediately** with a clear
message naming the tool, operation, and offending token — datamitsu never passes an
unsubstituted placeholder through to the tool. Shell brace groups (`{js,ts}`) and
Go templates (`{{.Path}}`) are not treated as placeholders and are left untouched.
:::

## `{file}`

Expands to the path of a single file. Used in tools with `scope: "per-file"`.

**As entire argument** — expands to a single argument:

```javascript
args: ["{file}"];
// File: "src/main.js"
// Result: ["src/main.js"]
```

**Embedded in a string** — replaced inline:

```javascript
args: ["--input={file}"];
// File: "src/main.js"
// Result: ["--input=src/main.js"]
```

## `{files}`

Expands to one argument per file. Using it is what makes an operation's [arity](configuration-api.md#arity) `many`: one process for the whole list, chunked only when the command line would overflow.

**As entire argument** — expands to multiple separate arguments:

```javascript
args: ["--check", "{files}"];
// Files: ["src/main.js", "src/util.js"]
// Result: ["--check", "src/main.js", "src/util.js"]
```

**Embedded in a string** — files are joined with spaces:

```javascript
args: ["--files={files}"];
// Files: ["src/main.js", "src/util.js"]
// Result: ["--files=src/main.js src/util.js"]
```

## `{root}`

Expands to the git repository root path. Always resolves to the same value regardless of which project is being processed.

```javascript
args: ["--config", "{root}/.config/tool.yml"];
// Root: "/home/user/repo"
// Result: ["--config", "/home/user/repo/.config/tool.yml"]
```

Use `{root}` to reference shared configuration files or resources at the repository level.

## `{cwd}`

Expands to the per-project working directory. For `scope: "per-project"` tools, this is the detected project root. Falls back to the git root when the project path is empty (e.g., repository-scope tools).

```javascript
args: ["--project", "{cwd}/tsconfig.json"];
// Per-project (packages/frontend): "/home/user/repo/packages/frontend/tsconfig.json"
// Repository scope: "/home/user/repo/tsconfig.json"
```

Use `{cwd}` to reference project-specific files within a monorepo.

## `{toolCache}`

Expands to an isolated, per-project, per-tool cache directory. The path is computed using an XXH3-128 hash of the git root to ensure uniqueness.

```
~/.cache/datamitsu/cache/projects/{xxh3_128(gitRoot)}/cache/{relativeProjectPath}/{toolName}/
```

```javascript
args: ["--cache-dir", "{toolCache}"];
// Tool: "eslint", Project: "packages/frontend"
// Result: ["--cache-dir", "~/.cache/datamitsu/cache/projects/a1b2c3/cache/packages/frontend/eslint/"]
```

Each tool and each project gets its own cache directory, preventing conflicts in monorepos.

If the cache path computation fails, the literal string `{toolCache}` is preserved unchanged.

## Usage in environment values

The path placeholders also expand in `env` values, which is the correct way to
point a tool at its datamitsu-managed cache:

```javascript
const toolsConfig = {
  "golangci-lint": {
    name: "golangci-lint",
    operations: {
      lint: {
        app: "golangci-lint",
        args: ["run", "--allow-parallel-runners"],
        scope: "per-project",
        env: {
          // Resolves to an absolute, per-project cache path.
          GOLANGCI_LINT_CACHE: "{toolCache}",
        },
      },
    },
    projectTypes: ["golang-package"],
  },
};
```

## Usage in Tool Configuration

Placeholders are used in the `args` field of tool operations:

```javascript
const toolsConfig = {
  prettier: {
    name: "prettier",
    operations: {
      fix: {
        app: "prettier",
        args: ["--write", "--cache", "--cache-location", "{toolCache}", "{files}"],
        globs: ["**/*.{js,ts,json,md}"],
        scope: "per-project",
      },
      lint: {
        app: "prettier",
        args: ["--check", "{files}"],
        globs: ["**/*.{js,ts,json,md}"],
        scope: "per-project",
      },
    },
  },
  "golangci-lint": {
    name: "golangci-lint",
    operations: {
      lint: {
        app: "golangci-lint",
        args: ["run", "--config", "{root}/.golangci.yml", "{cwd}/..."],
        globs: ["**/*.go"],
        scope: "repository",
      },
    },
  },
};
```

## `{target}`

Marks the one directory a tool walks itself, as opposed to a list of files you
hand it. Scanners want this: `gitleaks dir`, `trivy fs`, `osv-scanner` all take a
path and do their own traversal.

```js
args: ["dir", "--redact", "--config", "{root}/.gitleaks.toml", "{target}"];
```

It exists because `{root}` is ambiguous. In `--config {root}/.gitleaks.toml` the
root is a path the tool _reads_; in `dir {root}` it is the thing it _scans_, and
nothing in the argument list distinguishes them. `{target}` says which one you
mean, and that is what lets datamitsu infer the operation's [arity](configuration-api.md#arity)
exactly rather than guessing.

Handing a directory-scanning tool `{files}` instead is a silent mistake, not a
loud one. `gitleaks dir` accepts exactly one path and, given more, discards them
all and scans the working directory — same exit code, no warning, and your glob
and ignore rules never reached it.

`{target}` and `{file}`/`{files}` are mutually exclusive: a directory argument
and a file list are different shapes, and declaring both is a config error.

## Expansion Order

Placeholders are resolved in this order:

1. `{files}` — expands to multiple arguments or inline
2. `{file}` — expands to single argument or inline
3. `{root}` — string replacement
4. `{cwd}` — string replacement
5. `{toolCache}` — computed and replaced

Multiple placeholders can appear in a single argument. All are resolved in the order above.

## App environment placeholders

App `env` and `runtimeEnv` use a separate syntax from tool operation templates:

| Placeholder          | App `env` |  App `runtimeEnv`   | `prepare` args/env | Resolves to                                              |
| -------------------- | :-------: | :-----------------: | :----------------: | -------------------------------------------------------- |
| `${STORE}`           |    Yes    |         Yes         |         No         | Shared store directory                                   |
| `${APP_DIR}`         |    Yes    |         Yes         |        Yes         | This app's install directory, when resolvable            |
| `${APP_BIN:<alias>}` |    No     |         Yes         |        Yes         | Exact executable of a direct dependency (binary, uv, go) |
| `${APP_PREPARED}`    |    No     | Yes, with `prepare` |        Yes         | The app's prepared-state directory                       |

`runtimeEnv` applies only to execution and never enters installer environments
or install hashes. The `${APP_BIN}` target must be listed in the same app's
direct `dependsOn` — by name or by the edge's alias (`{ app: "jsonschema",
as: "validator" }` binds as `${APP_BIN:validator}`); binary, uv and go apps
resolve today, node/bun/jvm need a launcher that does not exist yet, and
shell apps are not installable targets. Missing or platform-unsupported
targets produce an error without fetching them. Malformed bindings and
unknown colon forms in `runtimeEnv` values are errors.

`${APP_PREPARED}` names the directory a declared `prepare` step fills
(`{store}/.prepared/<app>/<key>/out`); subpaths are allowed. It is rejected
without a declared step and in app `env` (installers see `env`, and the state
does not exist at install time).

Inside a `prepare` step, every other placeholder is an error: the prepared
state is shared by every project, so project-bound forms (`${STORE}`,
`{root}`, `{cwd}`, `{file}`, `{files}`, `{target}`, `{toolCache}`) cannot
enter it.

App `env` rejects `${APP_BIN` and `${APP_PREPARED` values; other config data
and environment keys remain literal for these purposes.

See [App environments](./configuration-api.md#execution-only-environment-runtimeenv)
and [Wrapping a private binary](../how-to/maintain-wrapper.md#wrapping-a-private-binary).

---

## Tool Environment

:::info Auto-generated
This page is generated from `internal/toolenv` by `task gen:toolenv-doc`. Do not edit by hand.
:::

Tools read their environment to decide what to print. Under `GITHUB_ACTIONS` several linters switch to GitHub workflow commands, under an AI agent's marker oxlint switches to a one-line format, and `FORCE_COLOR` colours output even into a pipe. datamitsu reads a tool's output with its [output parser](./configuration-api.md#output-parser-outputparser), and a parser that meets a format it does not expect reads the run as clean. So `datamitsu fix`, `lint` and `check` start every tool, in the language server's format lane too, with the environment datamitsu was started with minus the variables below, and with `NO_COLOR=1`.

`datamitsu exec` changes nothing: it hands its app the environment it was started with, so a tool run through `exec` in a GitHub Actions job still prints its own annotations.

## Order

1. The environment datamitsu was started with, without the removed variables.
2. The variables the operation names in [`inheritEnv`](./configuration-api.md#inheriting-host-variables-inheritenv), with the host's values.
3. The app's `env`, then the operation's [`env`](./configuration-api.md#operation-environment-env); a later value wins.
4. `NO_COLOR=1`, which nothing overrides.

## Removed

| Variable                    | Why                                                                                                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GITHUB_ACTIONS`            | Set in every GitHub Actions job. editorconfig-checker, oxlint, sqruff, pinact and yamllint (without `-f`) switch to `::error` workflow commands, which a parser reading their usual format takes for clean output. |
| `AI_AGENT`                  | Names the AI agent running the session; oxlint switches to its one-line agent output format.                                                                                                                       |
| `AGENT`                     | Generic AI agent session marker, removed before the next agent-aware tool starts reading it.                                                                                                                       |
| `CLAUDECODE`                | Set by Claude Code; oxlint switches to its one-line agent output format.                                                                                                                                           |
| `CLAUDE_CODE`               | Claude Code marker; oxlint switches to its one-line agent output format.                                                                                                                                           |
| `CLAUDE_CODE_CHILD_SESSION` | Claude Code session marker, removed with the others.                                                                                                                                                               |
| `GEMINI_CLI`                | Set by Gemini CLI; oxlint switches to its one-line agent output format.                                                                                                                                            |
| `CURSOR_AGENT`              | Set by the Cursor agent; oxlint switches to its one-line agent output format.                                                                                                                                      |
| `OPENCODE`                  | Set by OpenCode; oxlint switches to its one-line agent output format.                                                                                                                                              |
| `AUGMENT_AGENT`             | Augment agent session marker, removed with the others.                                                                                                                                                             |
| `FORCE_COLOR`               | Forces ANSI colour into a pipe; Node's colour detection reads it before `NO_COLOR`. Removed from the host environment, and datamitsu no longer adds it.                                                            |
| `CLICOLOR_FORCE`            | Forces ANSI colour into a pipe. Removed from the host environment, and datamitsu no longer adds it.                                                                                                                |
| `CODEX_*`                   | OpenAI Codex CLI (`CODEX_SANDBOX`, `CODEX_THREAD_ID`); oxlint switches to its one-line agent output format.                                                                                                        |
| `COPILOT_*`                 | GitHub Copilot CLI (`COPILOT_CLI`); oxlint switches to its one-line agent output format.                                                                                                                           |
| `JUNIE_*`                   | JetBrains Junie (`JUNIE_DATA`, `JUNIE_SHIM_PATH`); oxlint switches to its one-line agent output format.                                                                                                            |

A tool that needs one of them names it in its operation's `inheritEnv` and gets the host's value, or gets a fixed value through `env`.

## Set

`NO_COLOR=1` is set for every tool, after every other layer; neither `env` nor `inheritEnv` can name it. A tool that colours its output anyway is still parsed: the parser reads the output without its ANSI sequences, and the failure frame shows what the tool printed. The cost is that the output of a failing tool without a parser has no colour, even in a terminal.

## Kept on purpose

| Variable           | Why                                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CI`               | Tools branch on it for good reasons, such as knip's plugins and tools that look up a pull request's base; without it a run in CI would look local to them.            |
| `GITHUB_*`         | Every one but `GITHUB_ACTIONS`: tokens (gitleaks, zizmor and trufflehog read `GITHUB_TOKEN`), the workspace, and the refs a tool reads to find a pull request's base. |
| `GITLAB_CI`        | GitLab CI; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                                       |
| `CI_*`             | GitLab CI; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                                       |
| `TF_BUILD`         | Azure Pipelines; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                                 |
| `TEAMCITY_VERSION` | TeamCity; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                                        |
| `BUILDKITE*`       | Buildkite; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                                       |
| `BITBUCKET_*`      | Bitbucket Pipelines; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                             |
| `JENKINS_URL`      | Jenkins; no tool is known to change its output format on it, and a tool may read it for other things, such as a build's base.                                         |
| `REPL_ID`          | Set for every process on Replit, people included, so it is not an agent marker, although oxlint reads it as one.                                                      |
| `CURSOR_TRACE_ID`  | Set in every Cursor terminal, people included, so it is not an agent marker.                                                                                          |
| `TERM`             | The terminal type; colour is decided by `NO_COLOR`.                                                                                                                   |
| `PATH`             | oxlint reads a `.pi/agent` segment in it as an agent marker; no stripping can address that.                                                                           |
| `EDITOR`           | oxlint reads `devin` in it as an agent marker; datamitsu leaves the user's editor alone.                                                                              |
| `TERM_PROGRAM`     | oxlint reads `kiro` in it as an agent marker; datamitsu leaves it alone.                                                                                              |