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:
Method 1: npm/pnpm Package (Recommended)¶
Install the package as a dev dependency:
After installation, the postinstall script automatically builds the config. You can then initialize datamitsu in your project:
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:
This installs managed tool binaries. To initialize configuration files, run:
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:
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-configflag (allows project config to override) - Stable registry (
ghcr.io/shibanet0/datamitsu-config): latest/latest-alpine— latest stable releasestable/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:
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:
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:
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:
For example, to run ESLint:
To list all available tools:
Configuration¶
TypeScript¶
This package includes reusable tsconfig presets. Extend them in your tsconfig.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-scopedon 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 configurationcspell.json— cspell dictionary and settingsknip.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;
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.ymlextends.datamitsu/alint-managed.yml. Redefine a rule by itsid(for examples0-js-ts-file-names) to narrow it. The managed filename rules reject Git-tracked.key,.p12and.pfxfiles, including files force-added despite.gitignore. Ignored, untracked local keys do not trigger this rule. It checks names, not contents..crtand.pemfilenames remain allowed because they can hold public certificates. Keepallow_out_of_root: true: the managed file is linked from outside the repository..ls-lint.ymllayers over.datamitsu/ls-lint-managed.yml.ignoreadds exclusions, and a literal path such asapps/web/src/generatedis free. Redefining.dirreplaces the base rule, so includeregex:\.[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:
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:
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:
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:
The dm binary is provided by this package. Verify it exists:
Tool binary not found¶
If a specific tool fails to run, reinitialize to download its binary:
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:
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.