Skip to content

Usage Guide

How to install, configure, and use @shibanet0/datamitsu-config in your projects.

Installation

Choose one of three installation methods based on your use case:

Install the package as a dev dependency:

pnpm add -D @shibanet0/datamitsu-config

After installation, the postinstall script automatically builds the config. You can then initialize datamitsu in your project:

pnpm dm init

Use the package-local wrapper to run the exact core this configuration was tested with. The package pins Datamitsu 0.6.0 and its matching parser module; a separately installed global binary does not inherit that pin. An older core cannot provide the verified Python provisioning and named-runtime execution this configuration uses.

To bypass a shell alias that routes dm to a global binary, invoke the wrapper directly:

node node_modules/@shibanet0/datamitsu-config/bin/datamitsu.js init

This installs managed tool binaries. To initialize configuration files, run:

pnpm dm config reconcile

This creates all necessary configuration files for the managed tools in your project.

Managed root package.json files initialize tools from prepare with datamitsu init --quiet. The package manager adds local binaries to the lifecycle's PATH. An unchanged repeat suppresses routine output; managed-state changes, warnings, and errors remain visible. Workspace members keep their own lifecycle scripts. Lefthook initialization remains non-quiet so hook runs retain their normal diagnostics.

The managed JVM is JDK 27, available on macOS arm64, Linux amd64/arm64 and Windows amd64. Intel Macs no longer have a managed JVM for ktfmt, ktlint or openapi-generator.

The default Python is 3.15.2. Apps whose locked native dependencies lack Python 3.15 wheels explicitly select the separate uv-python314 runtime (Python 3.14.8). Both runtimes use uv 0.13.6 and explicit SHA-256-pinned Python catalogs; managed installs continue to prohibit source builds.

Reconciliation installs Codex skills in .agents/skills/<name>/SKILL.md, with YAML name and description metadata. Codex discovers them automatically; invoke one with $backlog, $cleanup-agents-md, $scaffold-stack, $setup-tsconfig, $conventional-commit-message, $conventional-changelog or $release-pipelines. The commit-message skill follows Conventional Commit conventions; the changelog skill uses the consumer's configured release tooling and project conventions. The release-pipelines skill audits or standardizes GitHub Actions release workflows with a default no-publication Verify mode and explicit Prerelease publication. It lets incomplete build or signing stages resume with verified inputs while keeping completed release artifacts immutable during publication recovery. It validates signed deliverables after finalization, separates publisher trust from product source, and guards mutable release channels against older runs replacing newer releases. Invoking it does not authorize creating tags, running remote workflows or publishing. It removes the previous managed .codex/prompts/<name>.md files while preserving unrelated custom prompts. Claude Code skills remain in .claude/skills/.

The shared script policy and scaffold skill use test for the complete main unit/integration suite. E2E (test:e2e) and visual checks (test:snapshots) run separately by default; a project may explicitly include them in test. Ordinary text and inline snapshots remain in their unit/integration suites. test:fast budgets the whole selected command, not individual test durations.

Turbo owns dependencies between workspace packages; Taskfile orchestrates steps inside a package without building sibling packages again. Standard script names remain the default for everyday work; documented extensions and tool-required names are allowed for distinct operations, with prerequisites and side effects made explicit.

Shared agent instructions default to English for documentation, code comments, and commit messages, without setting the language of conversation with the user. ASD-STE100 principles guide the writing style: prefer short sentences, familiar words, active voice, and direct instructions where appropriate. Accuracy and completeness take priority over simplicity; preserve precise technical terms, conditions, normative requirements, exact identifiers, and syntax. An explicit request for another language or style overrides this default. Formal ASD-STE100 compliance is not required.

For existing pnpm-workspace.yaml files, reconciliation also migrates the legacy trustPolicy.allowDowngrade list to trustPolicyExclude:

# Before
trustPolicy:
  allowDowngrade:
    - semver@6.3.1
# After
trustPolicy: no-downgrade
trustPolicyExclude:
  - semver@6.3.1

Existing trustPolicyExclude entries are retained and duplicates are removed when merging the lists. Package selectors keep their versions and ranges. Repeating reconciliation preserves the result; modern scalar trustPolicy values are left intact. Malformed exclusion lists stop reconciliation with an error.

The managed workspace config also adds allowBuilds.esbuild: false when no value exists, including when allowBuilds is absent. An explicit esbuild value is preserved, as are all other package selectors in allowBuilds.

Reconciliation also brings the file up to pnpm 12, which fails every command on a workspace setting it does not recognize. The settings pnpm 12 removed — confirmModulesPurge, ignoreDepScripts, ignorePatchFailures, managePackageManagerVersions, packageManagerStrict, packageManagerStrictVersion and useNodeVersion — are dropped, allowNonAppliedPatches becomes allowUnusedPatches with its value, and auditLevel gives way to audit.level. Everything else under audit, such as the audit.ignore list, is kept.

pnpm 12 records the packageManager version in pnpm-lock.yaml. The managed package.json pins the pnpm version this package ships with, so a reconciliation that moves it leaves the lockfile out of date, and pnpm install --frozen-lockfile fails in CI. Run pnpm install after reconciling and commit pnpm-lock.yaml together with package.json.

The managed .config/wt.toml cache-copy hook uses the launcher recorded by datamitsu init (facts().binaryCommand). It keeps the new worktree as the destination and adds the base worktree's node_modules/.bin to the hook's PATH. Package-manager commands can therefore find the base installation before the new worktree has installed dependencies, without a global datamitsu command. WorkTrunk escapes the source path, including spaces and apostrophes. This does not install dependencies for other project hooks or bootstrap custom scripts that themselves require files under the new worktree's node_modules.

Existing string, table, and pipeline post-start hooks are preserved. A string hook becomes a named command in a table and runs alongside cache copy. In a pipeline, an existing cache-copy step is updated in place; otherwise cache copy joins the last step. It can run concurrently with dependency installation without waiting for a long-running server. An empty pipeline receives a cache-only step.

When to use:

  • Standard development workflow
  • Projects using npm/pnpm for dependency management
  • When you need the npm package ecosystem integration

Method 2: Docker Images

Pre-built Docker images with all tools pre-installed for fast, consistent CI/CD.

Stable releases (Debian default):

# Pull latest stable
docker pull ghcr.io/shibanet0/datamitsu-config:latest

# Pull specific version (recommended for CI)
docker pull ghcr.io/shibanet0/datamitsu-config:0.0.4

Stable releases (Alpine, smaller image):

# Latest stable Alpine
docker pull ghcr.io/shibanet0/datamitsu-config:latest-alpine

# Specific version Alpine
docker pull ghcr.io/shibanet0/datamitsu-config:0.0.4-alpine

Unstable builds (bleeding edge):

# Latest unstable (Debian)
docker pull ghcr.io/shibanet0/datamitsu-config-unstable:unstable

# Latest unstable (Alpine)
docker pull ghcr.io/shibanet0/datamitsu-config-unstable:unstable-alpine

The PR workflow builds and runs an offline smoke test for both image variants on native amd64 and arm64 runners, so source-built Go tools do not compile under QEMU.

Docker image features:

  • All tools pre-installed (via datamitsu init --all) — faster startup
  • Multi-platform support: linux/amd64, linux/arm64
  • Base configuration via --before-config flag (allows project config to override)
  • Stable registry (ghcr.io/shibanet0/datamitsu-config):
  • latest / latest-alpine — latest stable release
  • stable / stable-alpine — same as latest
  • Semver versions: 0.0.4, 0.0.4-alpine
  • Unstable registry (ghcr.io/shibanet0/datamitsu-config-unstable):
  • unstable / unstable-alpine — latest unstable build
  • Date-tagged: unstable-YYYYMMDD-SHA, unstable-YYYYMMDD-SHA-alpine

Usage examples:

# Run all checks in current directory
docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/shibanet0/datamitsu-config:latest check

# Run with Alpine (smaller image)
docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/shibanet0/datamitsu-config:latest-alpine check

# Run specific tool
docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/shibanet0/datamitsu-config:latest exec eslint -- src/

# Use in CI with version pinning (CI=true: see "CI/CD integration" below)
docker run --rm -e CI=true -v "$(pwd):/workspace" \
  ghcr.io/shibanet0/datamitsu-config:0.0.4 check

# Override with local project config (config merging)
docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/shibanet0/datamitsu-config:latest \
  --config /workspace/datamitsu.config.js check

When to use:

  • CI/CD environments without Node.js dependency management
  • Consistent tooling across different environments and platforms
  • Fast CI runs (tools are pre-installed, no download time)
  • Multi-platform builds (amd64, arm64)

Container configuration merging:

The Docker images use the --before-config flag in the ENTRYPOINT, which loads the container's config as a base layer. This allows your project's datamitsu.config.js to override or extend the base configuration when you pass --config /workspace/datamitsu.config.js.

Container registries:

Method 3: Remote Config

Reference this config as a remote base configuration in your project. datamitsu supports remote configs for centralized configuration management.

Remote configs do not replace the executable running them. Use the core version pinned by the corresponding configuration package. A configuration using an unstable core can require features that are not yet available in stable releases.

Create datamitsu.config.js in your project:

function getRemoteConfigs() {
  return [
    {
      url: "https://github.com/shibanet0/datamitsu-config/releases/download/v0.0.4/datamitsu.config.js",
      hash: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", // SHA-256 hash
    },
  ];
}

function getConfig(config) {
  // config contains merged configuration from remote
  return {
    ...config,
    // Add project-specific overrides here
  };
}

globalThis.getRemoteConfigs = getRemoteConfigs;
globalThis.getConfig = getConfig;
globalThis.getMinVersion = () => "1.0.0";

Get the SHA-256 hash for verification:

Every remote config requires a SHA-256 hash for security. Get it from the releases page or compute it:

VERSION=v0.0.4
curl -sL "https://github.com/shibanet0/datamitsu-config/releases/download/${VERSION}/datamitsu.config.js" | sha256sum

Then use datamitsu normally:

datamitsu init
datamitsu check

When to use:

  • Projects that don't use npm/pnpm
  • Centralized configuration across multiple repositories
  • Teams wanting to inherit a base configuration and customize per-project
  • CI/CD environments with datamitsu already available

How it works:

  • Remote config is fetched and verified against SHA-256 hash
  • Configuration is cached locally in {store}/.remote-configs/
  • Your local getConfig() receives the merged config from remote
  • You can override or extend the remote configuration locally

Security features:

  • SHA-256 hash verification is mandatory
  • HTTPS-to-HTTP redirects are rejected
  • 30-second timeout and 10 MiB size limit

Important:

  • Pin to a specific version (not latest) since the hash changes with each release
  • Update the hash in your config when upgrading to a new version
  • See remote configs guide for advanced usage (inheritance chains, wrapper packages)

Browse all releases with SHA-256 hashes at GitHub Releases.

Basic Usage

Running checks

Run all configured linters and formatters in one pass:

pnpm dm check

This executes fixers (formatters, auto-fixes) followed by linters (type checking, ESLint, etc.). It should complete with no errors on a clean codebase.

Named runtimes

List the configured runtimes without installing or starting an interpreter:

pnpm dm runtime list
pnpm dm runtime list --json

The human table includes RUNNABLE and REASON, distinguishing interpreter support from installation status and explaining why pnpm cannot run directly.

Run an interpreter by its exact configured name. The -- separator is required; everything after it belongs to the interpreter:

pnpm dm runtime run node -- script.js "with space"
pnpm dm runtime run bun -- script.ts "with space"
pnpm dm runtime run uv-python314 -- -c 'import sys; print(sys.version)'
pnpm dm runtime run go -- run ./cmd/tool
pnpm dm runtime run jvm -- -jar tool.jar

uv and uv-python314 run their pinned CPython directly, not uv run. They do not sync a project, run pip, or install script dependencies. Bun runs directly with implicit package installation disabled, while preserving project bunfig and .env loading. pnpm appears in the inventory but is not a direct runtime run target. Add --dry-run before the runtime name to inspect a JSON execution plan without provisioning or execution.

A normal run installs missing managed components automatically and preserves the calling directory, arguments, streams and exit status. Runtime-owned caches are separate for each runtime name and identity; HOME is unchanged. With DATAMITSU_OFFLINE=1, an installed interpreter still runs, while a missing one fails instead of falling back to a host interpreter.

Upgrading from the earlier shared-cache layout rebuilds managed app environments. Old store entries remain until an explicit store clear; cache clear does not remove runtime data. Clearing the store is not required for this upgrade and can disrupt tools already running from it.

golangci-lint is built from its locked Go module using the configured Go runtime, rather than downloaded as a prebuilt executable. Its compiler must be at least as new as the Go version it analyzes: the standard importer embedded in an older compiler may not decode newer export data. Keep the managed Go runtime aligned with the projects you lint; disabling gocritic is not the compatibility fix.

Go linter migration

The shared baseline enables exhaustruct_v5, which checks struct field initialization. Reconciliation replaces legacy exhaustruct references in enabled/disabled linter lists and exclusion rules. Its old include, exclude and allow-empty-rx settings become enforce-patterns, ignore-patterns and allow-empty-patterns.

A nonempty legacy include list enables explicit-mode to preserve opt-in checking; an empty list keeps implicit checking. Explicit v5 settings take precedence, and arrays replace migrated arrays. Repeating reconciliation preserves the result. The baseline already uses the supported gomodguard_v2 and wsl_v5 names.

Running a specific tool

Execute any managed tool directly:

pnpm dm exec <tool-name> -- [tool-args]

For example, to run ESLint:

pnpm dm exec eslint -- src/

To list all available tools:

pnpm dm exec

Configuration

TypeScript

This package includes reusable tsconfig presets. Extend them in your tsconfig.json:

{
  "extends": "@shibanet0/datamitsu-config/tsconfig/base.json"
}

Available presets:

Preset Use Case
base.json Any TypeScript project
library.json Standalone libraries
react-library.json Standalone React libraries
service.json Backend services (Node.js)
service-worker.json Backend services (Cloudflare Workers)
shared-library.json Libraries in a monorepo
shared-react-library.json React libraries in a monorepo
nextjs.json Next.js applications
infra-pulumi.json Pulumi / Infrastructure-as-Code

Git Hooks

datamitsu integrates with lefthook for git hooks. After pnpm dm init, hooks are configured automatically:

  • pre-commit — runs dm check --file-scoped on staged files, regenerates docs, and runs tests (sequentially)
  • commit-msg — validates commit messages with commitlint (Conventional Commits)
  • post-checkout — reinstalls dependencies and reinitializes datamitsu

Commit messages use <type>[optional scope][optional !]: <description>, with a space after the colon and a lowercase type. Descriptions may start with an uppercase letter and preserve acronyms or identifier spelling. Commitlint does not impose a header-length limit. Keep one concise summary in the header and put details and rationale in the body.

Customizing Tool Behavior

Individual tools (ESLint, Prettier, cspell, etc.) can be customized through their standard config files. datamitsu respects these files when present in your project root:

  • eslint.config.mjs — ESLint configuration
  • .prettierrc / prettier.config.mjs — Prettier configuration
  • cspell.json — cspell dictionary and settings
  • knip.config.js — Knip unused code configuration

Configs that only their tool reads — gitleaks, yamlfmt, yamllint, hadolint and a few more — are not written into your repository: dm init keeps them in .datamitsu/configs/. To change one, name its tool in your datamitsu.config.* and reconcile it into the repository:

function getConfig(config) {
  return { ...config, ejectConfigs: ["gitleaks"] };
}

globalThis.getConfig = getConfig;
pnpm dm config reconcile --tools gitleaks

Naming checks are opt-in and split between two tools: alint checks file names, ls-lint checks directory names. Enable either with tools["alint"].skip: false or tools["ls-lint"].skip: false, then run pnpm dm init and pnpm dm config reconcile so both the managed base in .datamitsu/ and your own file exist.

  • .alint.yml extends .datamitsu/alint-managed.yml. Redefine a rule by its id (for example s0-js-ts-file-names) to narrow it. The managed filename rules reject Git-tracked .key, .p12 and .pfx files, including files force-added despite .gitignore. Ignored, untracked local keys do not trigger this rule. It checks names, not contents. .crt and .pem filenames remain allowed because they can hold public certificates. Keep allow_out_of_root: true: the managed file is linked from outside the repository.
  • .ls-lint.yml layers over .datamitsu/ls-lint-managed.yml. ignore adds exclusions, and a literal path such as apps/web/src/generated is free. Redefining .dir replaces the base rule, so include regex:\.[a-z0-9_-]+ to keep dot-directories valid.

Adopting Knip on an existing codebase

Everything here works on a new project with no configuration. The exception is Knip, and only because it reports debt that predates it: on a codebase that has never run it, unused files and exports arrive by the hundred, and the gate is red from day one.

adopted phases that in. Everything outside the list is switched off, so the gate stays green while the debt is still there:

export default defineConfig(undefined, { adopted: ["correctness"] });

correctness reports defects rather than debt — imports that do not resolve, dependencies used but never declared — and stays small at any age. Widen it one group at a time (dependencies, files, exports) until the option can go. Once most of a group passes, prefer ignoreIssues over dropping the group again, so new code stays covered:

export default defineConfig({
  ignoreIssues: { "packages/legacy/**": ["exports", "files"] },
});

Overrides extend the shared configuration rather than replacing it. To replace something instead, pass a function — it receives the base configuration and returns the final one.

Common Workflows

Setting up a new project

# Install the package
pnpm add -D @shibanet0/datamitsu-config

# Install tool binaries
pnpm dm init

# Initialize configuration files
pnpm dm config reconcile

# Run all checks to verify the configuration
pnpm dm check

Adding to an existing project

# Install
pnpm add -D @shibanet0/datamitsu-config

# Install tool binaries
pnpm dm init

# Initialize configuration files
pnpm dm config reconcile

# Check for issues — expect some on first run
pnpm dm check

# Fix issues iteratively, or auto-fix what can be auto-fixed
pnpm dm check

CI/CD integration

In CI pipelines, run checks after install:

Method 1: npm/pnpm (traditional):

# GitHub Actions example
- run: pnpm install
- run: pnpm dm init # needed if postinstall was skipped (e.g. --ignore-scripts)
- run: pnpm dm check

datamitsu handles binary installation during pnpm dm init, which runs automatically as part of postinstall. In CI environments that use --ignore-scripts, run pnpm dm init explicitly.

Method 2: Docker (faster, no dependencies):

# GitHub Actions example with Docker
- name: Run datamitsu checks
  run: |
    docker run --rm -e CI=true -v "${{ github.workspace }}:/workspace" \
      ghcr.io/shibanet0/datamitsu-config:0.0.4 check

-e CI=true is not optional. Some tools run only in CI — their status in the tools reference reads "runs in CI only" — and they recognize CI by the CI variable, which docker run does not forward from the runner. Without it they are skipped, in CI as well as locally.

Docker advantages in CI:

  • No npm install or binary download time (tools pre-installed in image)
  • Consistent environment across all CI runs
  • Faster cold starts
  • No Node.js version management needed

Troubleshooting

Bootstrap problem: missing datamitsu.config.js

If you see an error like "no such file or directory: datamitsu.config.js", the config file needs to be built first. This happens after a fresh clone or if the file was deleted.

Run the bootstrap command:

./node_modules/.bin/datamitsu --no-auto-config exec task -- build:datamitsu-config

This builds the config from source, moves it to the project root, and runs pnpm dm init.

pnpm dm command not found

Ensure the package is installed as a dev dependency:

pnpm add -D @shibanet0/datamitsu-config

The dm binary is provided by this package. Verify it exists:

pnpm dm --help

Tool binary not found

If a specific tool fails to run, reinitialize to download its binary:

pnpm dm init

Checks failing on first run

This is expected when adding datamitsu to an existing project. Run pnpm dm check repeatedly — many issues are auto-fixed on each pass. For remaining issues, review the output and fix manually.

Further Reading

  • Apps — full list of managed apps with versions and links
  • datamitsu documentation — comprehensive docs for the datamitsu tool manager

Lefthook configuration formatting

pnpm dm check sorts Lefthook configuration files with lefthook-sort, which runs on the managed Bun runtime. Datamitsu provisions Bun automatically; a system Bun installation is unnecessary. To sort a configuration explicitly:

pnpm dm exec lefthook-sort -- lefthook.yaml

The sorter preserves comments and orders hooks by lifecycle and commands by priority. Configuration validation runs separately through lefthook validate.

JavaScript and TypeScript tool runtimes

pnpm dm check runs ESLint, oxlint, and oxfmt on the pinned Bun runtime. Datamitsu installs Bun and each tool's locked dependencies automatically. The same runtime is used when these managed apps run from Git hooks.

With the pinned Bun 1.4.1, ESLint can report a shifted column for TypeScript syntax errors: export const broken = ; is reported at column 16 instead of 22. The error message and failure status are preserved.

Svelte

.svelte needs nothing configured. oxfmt formats components in every project, and oxlint reads the <script> block; ESLint adds eslint-plugin-svelte as soon as svelte (or @sveltejs/kit) is in the project's package.json, because its rules only mean something where components exist. stylelint lints the <style> block too, so a Svelte project gets CSS checks without naming anything either.

The svelte compiler all of them need ships with the managed tools rather than being resolved from the project.

Kotlin

pnpm dm check formats .kt and .kts files with ktfmt and checks Kotlin naming and idioms with ktlint. Both use the managed JVM; no Gradle plugin or application compilation is needed.

The managed .editorconfig supplies shared indent and line width settings, preserves project overrides, and keeps lint rules separate from layout. See the Kotlin configuration reference for the exact rule decisions, Compose support, IDE settings and parser requirements.

Helm charts

Chart.yaml identifies each Helm chart, including charts in a monorepo. Reconciliation creates each chart's .helmfmt; it does not create .datamitsuignore files.

pnpm dm check formats .yaml, .yml, .tpl and .gotmpl files under each chart's templates/ with helmfmt. YAML-suffixed template files also reach repository-scoped yamlfmt, yamllint and the YAML key sorter. Datamitsu 0.6.0 has no dynamic chart-scoped YAML exclusion in the root configuration API, so these tools may fail on Go template syntax or rewrite a template. Do not use a global templates/** exclusion because it would also skip unrelated directories. Chart.yaml, values.yaml and other ordinary YAML remain on the YAML tool path.

The generated .helmfmt takes its indentation from the shared formatter settings and preserves project overrides. Managed checks read the chart's configuration, not the developer's home-directory .helmfmt. helmfmt aligns template directives; it does not reformat the surrounding YAML. Helm's existing helm lint remains the chart-level validator.

The managed config leaves printf indentation alone: moving an output-producing call to template depth can move its value out of a YAML block scalar. Native defaults also leave include, tpl, template and toYaml indentation alone. Keep those defaults unless the chart explicitly needs otherwise; project overrides are retained.

helmfmt recognizes .gotmpl, but Helm rejects that extension inside a chart. Use .tpl for chart helpers; formatter support does not make a file a valid Helm template.

Native helmfmt 0.7.0 requires a templates/ directory, even for a valid chart with no templates. It also formats directives rather than rendered manifests. Run helm template for the values combinations your chart supports; helm lint alone does not exercise every conditional branch.

There is a separate YAML limitation: yamlfmt 0.21.0 can require a second formatting pass for comments in an unmodified helm create chart's values.yaml. The first check then fails its formatting check. This is not suppressed by the Helm integration.