@ariestools/toolchain

@ariestools/toolchain

Unified TypeScript toolchain for XY Labs — build, lint, test, deploy with auto-detected package manager and React support

Install

Using npm:

npm install {{name}}

Using yarn:

yarn add {{name}}

Using pnpm:

pnpm add {{name}}

Using bun:

bun add {{name}}

Create a new repo (xy repo init)

Scaffold a toolchain-ready repo. Omit the template to answer setup questions (monorepo, React, package manager, skills tier).

# Interactive (recommended for new projects)
npx --package=@ariestools/toolchain xy repo init

# Explicit template + name (non-interactive defaults)
pnpm xy repo init cli my-cli --pm pnpm --skills-tier xy

# Single-package React tooling
pnpm xy repo init cli my-app --no-monorepo --react --skills-tier xl1

Useful flags:

Flag	Meaning
--pm	pnpm (default) / yarn / npm / bun
--monorepo / --no-monorepo	Workspace layout vs single package
--react / --no-react	eslint-config-react-flat + tsconfig-react vs flat
--skills-tier	none / xy / xyo / xl1 — install matching agent skills
--skills-optional	With xl1, also install xl1-scaffold / xl1-build
--skip-install / --skip-git	Skip post-scaffold steps
-y / --yes	Accept wizard defaults (project name still required)

Security (xy secure)

xy secure is an overview: it runs both audits, prints one summary line each, and points at the subcommands for detail.

pnpm xy secure                 # summary of both
pnpm xy secure deps            # direct dependency age + weekly downloads
pnpm xy secure dependabot      # GitHub Dependabot security alerts

xy secure deps is the dependency-hygiene audit (age, download volume) — it does not look at CVEs.

xy secure dependabot reads GitHub's Dependabot alerts through the gh CLI, so it needs gh installed and authenticated; the standard repo scope is enough. Alerts are enabled per repository, and a repo with the feature switched off is reported as such rather than treated as an error.

Flag	Behavior
--org <name>	Report every repository in a GitHub org instead of the current repo
--scope	all (default) / runtime / development
--relationship	all (default) / direct / transitive
--state	open (default) / fixed / dismissed / all
--summary	Summary line and counts only, no per-alert table
--rules	List the dependabot rules and their effective levels

Findings map onto the rule system, one rule per severity plus a check that alerts are switched on at all. Because alerts are overwhelmingly transitive lockfile findings, nothing fails a build by default — critical and high warn, medium and low are off. Raise them to gate:

const config: XyConfig = {
  commands: {
    dependabot: {
      rules: {
        'dependabot.critical': 'error',
        'dependabot.medium': 'warn',
      },
    },
  },
}

Console output caps at 50 alerts with a count of what was held back; --json always carries every finding.

Enforcing that alerts are on

Alerts are only useful where the feature is switched on, so xy repo lint carries a companion policy rule:

pnpm xy repo lint            # warns: Dependabot alerts are disabled for this repository
pnpm xy repo lint --fix      # turns them on

repo.dependabot-enabled warns by default and is fixable. The fix needs admin on the repository; without it the rule reports the finding as still open rather than claiming a fix it did not make. The check costs one gh subprocess and stays silent when gh is missing, unauthenticated, or the remote is not GitHub — an environment it cannot ask about is not a repository finding.

Rules (xy --rules)

Every rule the toolchain enforces has a namespaced id, a level (error / warn / off), and a config entry at commands.<command>.rules["<id>"] in xy.config.ts. To list them:

# every xy-native rule, grouped by command
pnpm xy --rules

# machine-readable
pnpm xy --rules --json

Add --rules to any individual command to see just that command's rules and the levels currently in effect for this repo:

pnpm xy deplint --rules
pnpm xy publint --rules
pnpm xy repo lint --rules
pnpm xy clean --rules

The Level column shows the default; when a repo overrides it, the effective level follows in parentheses (warn (error)). Fix marks rules that --fix can resolve.

pnpm xy --rules deliberately omits the ~600 upstream ESLint rules — list those separately with pnpm xy lint --rules. It also omits the aggregate xy check and xy fix views, which re-list rules already shown under their owning command; pnpm xy check --rules and pnpm xy fix --rules show what those commands run.

Rule levels accept several config forms:

const config: XyConfig = {
  commands: {
    repoLint: {
      rules: {
        'repo.spec-layout': 'off',
        'repo.pnpm-no-overrides': 'error',
        'repo.engines-lts': { enabled: false },
      },
    },
  },
}

An unknown rule id is a hard error rather than a silent no-op, so a typo surfaces immediately.

Extending package-compile / package-build / package-recompile

To add steps to a per-package build phase, override the matching script in your package's package.json and chain to the toolchain default via the matching -only bin:

{
  "scripts": {
    "package-compile": "package-compile-only && tsx scripts/generate-types.ts"
  }
}

Do not call pnpm package-compile / yarn package-compile / pnpm run package-compile from the override — those re-enter the same npm script and recurse infinitely. The -only bin variants exist precisely so your override can invoke the toolchain default once and add work around it.

Available -only variants: package-compile-only, package-build-only, package-recompile-only.

Copying opaque monolith entries

Monolith packages can copy already-built runtime files into exact public output paths without a package-local post-processing script. Configure compile.monolith.copyEntries as platform → output path → source:

import type { XyConfig } from '@ariestools/toolchain'

const config: XyConfig = {
  compile: {
    mode: 'monolith',
    monolith: {
      copyEntries: {
        neutral: {
          'hash/worker/subtleHash-bundle.mjs':
            '@xyo-network/sdk-protocol-core/hash/worker/subtleHash-bundle.mjs',
        },
      },
      modules: [
        {
          name: 'hash',
          export: true,
          reexport: '@xyo-network/sdk-protocol-core/hash',
        },
      ],
      platforms: ['neutral'],
    },
  },
}

export default config

The example copies the dependency export byte-for-byte to dist/neutral/hash/worker/subtleHash-bundle.mjs. The output key is also the subpath suggested by xy publint --fix, so the corresponding package export is ./hash/worker/subtleHash-bundle.mjs.

Sources may be package export specifiers, paths relative to the compiling package, or absolute paths. Copying runs only during emit, after normal monolith compilation; --validate-only does not resolve or copy the configured sources. Destinations must remain inside their configured dist/<platform> directory.

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Credits

Made with 🔥 and ❄️ by XY Labs