diff --git a/.changeset/readme-structure.md b/.changeset/readme-structure.md new file mode 100644 index 0000000..2f29006 --- /dev/null +++ b/.changeset/readme-structure.md @@ -0,0 +1,17 @@ +--- +"@rrlab/cli": patch +"@rrlab/astro-plugin": patch +"@rrlab/biome-plugin": patch +"@rrlab/oxc-plugin": patch +"@rrlab/ts-plugin": patch +"@rrlab/tsdown-plugin": patch +"@rrlab/vitest-plugin": patch +"@rrlab/biome-config": patch +"@rrlab/ts-config": patch +"@rrlab/tsdown-config": patch +"@variablelab/vland": patch +"@variablelab/clibuddy": patch +"@variablelab/loggy": patch +--- + +The README follows the Variable Lab README structure, and the tarball now includes the MIT `LICENSE`. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 8e60cf9..e06b527 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,26 @@ -# DX +# dx -Monorepo to hold tools made for DX. +The monorepo of run-run and vland. -## Packages +## Projects +-  [run-run](run-run/cli): One way to run the scripts in a repo. [Project page](https://lab.variable.land/run-run). +-  [vland](vland/cli): Starts a project in Variable Land. [Project page](https://lab.variable.land/vland). -| Name | Description | Documentation | -| --------- | ----------------------------------------------------- | -------------------------------------------------------------------------- | -| `vland` | CLI to init a new project in Variable Land | [vland](./vland/cli/README.md) ([CLI reference](./vland/cli/CLI.md)) | -| `run-run` | CLI + plugin ecosystem for scripts in Variable Land | [run-run](./run-run/cli/README.md) ([CLI reference](./run-run/cli/CLI.md)) | -| `shared` | Internal utilities shared across both CLIs | [clibuddy](./shared/clibuddy/README.md), [loggy](./shared/loggy/README.md) | +## Repository -The `run-run` ecosystem ships as opt-in pieces: the `@rrlab/cli` kernel + its official plugins (`@rrlab/-plugin`, listed in the [`@rrlab/cli` README](./run-run/cli/README.md#plugins)) + their shared config presets (`@rrlab/-config`). See [`run-run/CLAUDE.md`](./run-run/CLAUDE.md) for the architecture. +- [`run-run/`](run-run): run-run. The CLI is in `cli/`, a plugin per tool in `*-plugin/` and the presets in `*-config/`. The [run-run README](run-run/cli/README.md#plugins) lists the plugins. +- [`vland/`](vland): vland. The CLI is in `cli/`, and the templates it starts a project from are in `templates/`. +- [`shared/`](shared): `@variablelab/clibuddy` and `@variablelab/loggy`, internal to the two CLIs. +## Contributing -## Usage +The [contributing guide](docs/contributing.md) covers issues, pull requests and releases, and the [development guide](docs/development.md) covers setting up the repo and running its checks. -To get started with any package, navigate to the respective package directory and follow the installation and usage instructions in its README. +## License -## Development +[MIT](LICENSE). -### Requirements - -To use this monorepo, you need to have the following tools installed: - -- [Node.js](https://nodejs.org) >= 24.0.0 -- [pnpm](https://pnpm.io) >= 10.0.0 -- [mise](https://mise.jdx.dev) >= 2025.3.3 (optional) - -### Setup - -1. Clone the repository: - - ```bash - git clone git@github.com:withvariablelab/dx.git - ``` - -2. Install dependencies: - - ```bash - pnpm install - ``` - -3. Run tests: - - ```bash - pnpm test - ``` - -### Commands - -This monorepo uses [Turborepo](https://turbo.build/repo/docs) to manage tasks. Here are some useful commands: - -- `pnpm build` - Build all packages -- `pnpm test` - Run tests for all packages - -Additionally, the monorepo itself uses the CLIs [`run-run`](./run-run/cli/README.md) and [`vland`](./vland/cli/README.md): - -- `pnpm rr` - Run the `run-run` CLI in development mode -- `pnpm vland` - Run the `vland` CLI in development mode - -If you have [mise](https://mise.jdx.dev) installed, you can use the following commands directly: - -- `rr` - Run the `run-run` CLI in development mode -- `vland` - Run the `vland` CLI in development mode - -### Release - -This monorepo uses [Changesets](https://github.com/changesets/changesets) to manage releases. The [Changesets bot](https://github.com/changesets/bot) is also installed in the repository. - -**Preview Release**: - -To preview changes in any package, create a pull request using the branch pattern `feat/*` or `fix/*` or add a label `preview` to the PR. This triggers a special GitHub workflow that publishes the package with the changes to the npm registry under the tag `pr-`. To preview your changes, install the package with the corresponding tag: - -```bash -pnpm add @variablelab/@pr-123 -``` - -For `@rrlab/*-plugin` packages, `rr plugins add` accepts the same `@` suffix and propagates it to the plugin's `@rrlab/*-config` sibling — falling back to `latest` for any sibling the preview didn't publish: - -```bash -rr plugins add biome@pr-123 -``` +

+  Variable Land +

diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..0f354a4 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,32 @@ +# Contributing + +dx takes bug reports, fixes and small features for run-run, vland and their packages. To set up the repo and run its checks, see the [development guide](development.md). + +## Issues + +- A bug report says what you ran, what you expected, what happened, and which Node version and package versions you use. `DEBUG=run-run:*` or `DEBUG=vland:*` before the command prints the debug log. +- A new feature, a new plugin, or a change to a command, a template or the plugin contract starts as an issue before any pull request. + +## Pull requests + +1. Branch from `main` with a prefix: `feat/`, `fix/`, `docs/`, `chore/` or `test/`. +2. Write commits as [Conventional Commits](https://www.conventionalcommits.org), such as `fix(oxc-plugin): stop installing a flaky oxlint-tsgolint`. The pull request title takes the same form, because it becomes the squash commit. +3. A feature lands with a test of the happy path and at least one failure case, and a fix with a regression test. +4. Run `pnpm rr check` and `pnpm test` before you push. +5. A pull request from a `feat/` or `fix/` branch, or with the `preview` label, publishes a preview to npm, under the `pr-` tag, of each package it changes and the packages that depend on them. The [development guide](development.md#preview-releases) shows how to install one. + +CI has to pass, and a maintainer squash-merges. + +## Changesets + +A change to what a package ships to npm needs a changeset. Run `pnpm changeset`, pick the packages and the bump (`patch` for a fix, `minor` for a feature, `major` for a breaking change), and write one sentence for the changelog. Changes to tests, CI, `decisions/` or these docs need none. + +The plugins take `@rrlab/cli` as a peer, and a changeset that bumps `@rrlab/cli` by `major` also lists every official plugin as `major`. [Decision 011](../decisions/011-cli-peer-bump-strategy.md) explains why. + +Nobody edits versions or `CHANGELOG.md` by hand, and nobody publishes from a clone. + +## Releases + +When changesets land on `main`, the Release job opens or updates a "chore: update versions" pull request as `vland-bot`. A maintainer merges it, and the next run on `main` publishes each new version to npm, with npm trusted publishing, and tags it. + +A new tag of `@rrlab/cli` or `@variablelab/vland` regenerates the `CLI.md` of both CLIs in a "chore: regenerate CLI docs" pull request, which a maintainer merges too. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..b42afb4 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,79 @@ +# Development + +How to work on dx in a clone. The [contributing guide](contributing.md) covers how a change gets in. + +## Layout + +- [`run-run/`](../run-run): run-run. `cli/` is `@rrlab/cli`, the kernel and the `rr` command. Each `*-plugin/` wraps one tool, and each `*-config/` is a preset that a plugin installs. [`run-run/CLAUDE.md`](../run-run/CLAUDE.md) covers the architecture: the plugin contract and how to add or change a plugin. +- [`vland/`](../vland): vland. `cli/` is `@variablelab/vland`, and `templates/` holds the projects `vland init` starts from. +- [`shared/`](../shared): `@variablelab/clibuddy` and `@variablelab/loggy`, the internal packages both CLIs depend on. +- [`decisions/`](../decisions): the architecture decisions, one file each. +- `docs/`: this guide and the [contributing guide](contributing.md). + +The workspace is pnpm, the tasks run through [Turborepo](https://turborepo.com), and tsdown builds each package that has a build step. + +## Setup + +[mise](https://mise.jdx.dev) pins Node 24, pnpm and [usage](https://usage.jdx.dev) in `mise.toml`, locked in `mise.lock`. It also puts `node_modules/.bin` on the `PATH`, so `rr` and `vland` run by name. + +```sh +git clone git@github.com:withvariablelab/dx.git +cd dx +mise install +pnpm install +``` + +`pnpm install` also installs the git hooks, through lefthook. + +The published packages declare `engines.node` as `>=22.18.0`, except `@rrlab/biome-config` and `@rrlab/ts-config`, which hold only JSON presets and declare none. `mise.floor.toml` pins that floor, and `MISE_ENV=floor` runs the repo on it, as CI does: + +```sh +MISE_ENV=floor mise install +MISE_ENV=floor mise exec -- pnpm test +``` + +To raise the floor, change `mise.floor.toml` and every `engines.node` together, then run `MISE_ENV=floor mise lock`. + +## Tasks + +```sh +pnpm build # build every package +pnpm test # build, then run every package's tests +pnpm rr check # format, lint and type check, with the repo's own rr +pnpm rr jsc --fix # apply Biome's fixes +pnpm tscheck # rr tsc in each package with a tscheck script +pnpm --filter @rrlab/cli test # one package's tests +``` + +`pnpm test:unit` and `pnpm test:integration` run one kind of test. Unit tests live in `src/**/__tests__/`, and integration tests in `test/integration/`. + +In the repo, `pnpm rr` and `pnpm vland`, or `rr` and `vland` with mise, run each CLI from its `src/`, so an edit shows up without a build. + +## CI + +- **On each pull request to `main`:** CI runs `pnpm install --frozen-lockfile`, `pnpm rr check`, `pnpm test` and `pnpm build`, once on the Node floor in `mise.floor.toml` and once on the version in `mise.toml`. The required `Test` check passes when both do. Workflow audit runs [zizmor](https://docs.zizmor.sh) on every workflow in the repo, including those the vland templates generate. +- **Git hooks** ([lefthook](https://lefthook.dev), in `lefthook/turborepo.yml`): on commit, `rr jscheck --fix-staged` on the staged files and, when TypeScript changed, `tscheck` on the changed packages and their dependents; on push, the tests of the affected packages. +- **Every Monday:** `pnpm audit` on the lockfile, which keeps an issue labeled `dependency-audit` open while it finds known vulnerabilities (Dependency audit). + +## Preview releases + +A pull request from a `feat/*` or `fix/*` branch, or with the `preview` label, publishes each package it changes, and the packages that depend on them, to npm under the `pr-` tag, once the tests pass. `vland-bot` comments the published versions on the pull request. To try a preview, install the package with that tag: + +```sh +pnpm add -D @rrlab/cli@pr-123 +``` + +For a `@rrlab/*-plugin` package, `rr plugins add` takes the same `@` suffix and passes it on to the plugin's `@rrlab/*-config` sibling, falling back to `latest` for a sibling the preview didn't publish: + +```sh +rr plugins add biome@pr-123 +``` + +## Generated files + +`run-run/cli/CLI.md` and `vland/cli/CLI.md` are generated, so don't edit them by hand. The cli docs workflow builds each CLI, which writes `dist/cli.usage.kdl`, and runs `usage generate markdown` on it. To see the result locally: + +```sh +pnpm --filter ./run-run/cli build +usage generate markdown --file run-run/cli/dist/cli.usage.kdl --out-file run-run/cli/CLI.md --replace-pre-with-code-fences +``` diff --git a/run-run/astro-plugin/LICENSE b/run-run/astro-plugin/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/astro-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/astro-plugin/README.md b/run-run/astro-plugin/README.md index 897ee59..9d59bd0 100644 --- a/run-run/astro-plugin/README.md +++ b/run-run/astro-plugin/README.md @@ -1,6 +1,6 @@ -# @rrlab/astro-plugin +# astro-plugin -Astro plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides the `typecheck` capability backed by [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check), so `rr tsc` and `rr check` type-check `.astro` files along with the rest of the project. +`@rrlab/astro-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check). It gives `rr` the `typecheck` capability, so `rr tsc` and `rr check` type-check `.astro` files along with the rest of the project. ## Install @@ -8,17 +8,19 @@ Astro plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides rr plugins add astro ``` -`rr plugins add` installs `@rrlab/astro-plugin` and adds `@astrojs/check` and `typescript` as `devDependencies`: `astro check` needs both. It scaffolds no config: your Astro project already has its `tsconfig.json`, and `astro` itself stays your project's own dependency. +`rr plugins add` installs `@rrlab/astro-plugin` and adds `@astrojs/check` and `typescript` as dev dependencies: `astro check` needs both. It writes no config file: your Astro project already has its `tsconfig.json`, and `astro` stays your project's own dependency. + +It needs `@rrlab/cli`, Astro 5 or later, `@astrojs/check` 0.9 or later, and TypeScript 5 or 6. ## What it provides -| Capability | Surface | -|---|---| +| Capability | Commands | +| --- | --- | | `typecheck` | `rr tsc` (workspace-aware in monorepos), `rr check`, `rr tsc doctor` | -`rr tsc` runs `astro check` in each package with a `tsconfig.json`. It reports the same diagnostics as `astro check`, for `.astro` files and plain `.ts` files alike, and fails when `astro check` exits non-zero (any error, by default). +`rr tsc` runs `astro check` in each package with a `tsconfig.json`. It reports the same diagnostics as `astro check`, for `.astro` files and plain `.ts` files alike, and fails when `astro check` exits non-zero, which it does on any error by default. -`astro check` also checks your `.ts` files, so in an Astro project it replaces `ts`. Configure one `typecheck` provider. If another plugin also provides one (`ts`, or `oxc`), narrow it, e.g. `oxc({ only: ["lint", "format"] })`. +`astro check` also checks your `.ts` files, so in an Astro project it replaces `ts`. Configure one `typecheck` provider. If another plugin also provides one, such as `ts` or `oxc`, narrow it: `oxc({ only: ["lint", "format"] })`. If `@astrojs/check` or `typescript` is missing, `rr tsc` fails and names it. Left alone, `astro check` would prompt to install them instead of checking anything. @@ -28,4 +30,12 @@ If `@astrojs/check` or `typescript` is missing, `rr tsc` fails and names it. Lef rr plugins remove astro ``` -Removes `@astrojs/check` and `typescript` from `package.json` and drops the `astro()` entry from `run-run.config.{ts,mts}`. `astro` and your `tsconfig.json` are left untouched. +It removes `@astrojs/check` and `typescript` from `package.json`, and drops `astro()` from `run-run.config.{ts,mts}`. It leaves `astro` and your `tsconfig.json` alone. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/biome-config/LICENSE b/run-run/biome-config/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/biome-config/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/biome-config/README.md b/run-run/biome-config/README.md index 5e6de83..2aaabae 100644 --- a/run-run/biome-config/README.md +++ b/run-run/biome-config/README.md @@ -1,36 +1,42 @@ -# @rrlab/biome-config +# biome-config -Shared [Biome](https://biomejs.dev) preset for projects using [`@rrlab/biome-plugin`](https://npmjs.com/package/@rrlab/biome-plugin). +`@rrlab/biome-config` is the [Biome](https://biomejs.dev) preset of [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli). The `biome.json` that [`@rrlab/biome-plugin`](https://www.npmjs.com/package/@rrlab/biome-plugin) writes extends it. ## Install -If you use [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli): +If you use run-run: ```sh rr plugins add biome ``` -Scaffolds a `biome.json` extending this config (with your confirmation). +Once you confirm, it installs this preset and writes a `biome.json` that extends it. -If you don't, install manually: +Without run-run, install it by hand: ```sh pnpm add -D @rrlab/biome-config @biomejs/biome ``` -…and create a `biome.json`: +Then create a `biome.json`: ```json { - "$schema": "https://biomejs.dev/schemas/2.4.4/schema.json", + "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", "extends": ["@rrlab/biome-config"] } ``` -## Override +It needs Biome 2 or later: the preset's `$schema` URL is tied to a Biome major, and the rule set changes between majors. -Local keys in your `biome.json` win over the preset. Add `linter.rules`, `formatter`, `files.includes`, etc. to taste. If you want to chain another shared config on top, append it to the `extends` array — entries later in the array override earlier ones, so the user's preferences and local overrides win over our base. +## Configuration -## Peer dependencies +Keys in your `biome.json` win over the preset. Add `linter.rules`, `formatter`, `files.includes` or any other setting as you need. To chain another shared config on top, append it to the `extends` array: later entries override earlier ones, so your preferences and local keys win over this base. -- `@biomejs/biome >= 2.0.0` — the `$schema` URL is tied to a biome major and the rule set evolves between majors. +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/biome-plugin/LICENSE b/run-run/biome-plugin/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/biome-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/biome-plugin/README.md b/run-run/biome-plugin/README.md index 75804eb..eb4d071 100644 --- a/run-run/biome-plugin/README.md +++ b/run-run/biome-plugin/README.md @@ -1,6 +1,6 @@ -# @rrlab/biome-plugin +# biome-plugin -Biome plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides `lint`, `format`, and `jsc` capabilities backed by [Biome](https://biomejs.dev). +`@rrlab/biome-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [Biome](https://biomejs.dev). It gives `rr` the `lint`, `format` and `jscheck` capabilities. ## Install @@ -8,28 +8,30 @@ Biome plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides rr plugins add biome ``` -`rr plugins add` installs `@rrlab/biome-plugin`, adds `@biomejs/biome` as a `devDependency`, and (with your confirmation) scaffolds a `biome.json` extending [`@rrlab/biome-config`](https://npmjs.com/package/@rrlab/biome-config). When `biome.json` already exists you can choose to patch it, leave it alone, or overwrite it. +`rr plugins add` installs `@rrlab/biome-plugin` and adds `@biomejs/biome` as a dev dependency. Once you confirm, it writes a `biome.json` that extends [`@rrlab/biome-config`](https://www.npmjs.com/package/@rrlab/biome-config). If `biome.json` already exists, you choose to patch it, keep it or overwrite it. + +It needs `@rrlab/cli` and Biome 2 or later. ## What it provides -| Capability | Surface | -|---|---| +| Capability | Commands | +| --- | --- | | `lint` | `rr lint`, `rr lint doctor` | | `format` | `rr format`, `rr format doctor` | -| `jsc` | `rr jsc` (lint + format together), `rr jsc doctor` | +| `jscheck` | `rr jsc` (lint and format together), `rr jsc doctor` | ## Configuration -The scaffolded `biome.json` is a thin wrapper: +The `biome.json` it writes only extends the preset: ```json { - "$schema": "https://biomejs.dev/schemas/2.4.4/schema.json", + "$schema": "./node_modules/@biomejs/biome/configuration_schema.json", "extends": ["@rrlab/biome-config"] } ``` -Override any biome setting by adding it to your local `biome.json`. The preset lives in [`@rrlab/biome-config`](https://npmjs.com/package/@rrlab/biome-config) — bump the package to get updated defaults. +Any Biome setting in your `biome.json` overrides the preset. The preset lives in `@rrlab/biome-config`: update that package to get new defaults. ## Removal @@ -37,4 +39,12 @@ Override any biome setting by adding it to your local `biome.json`. The preset l rr plugins remove biome ``` -Removes `@biomejs/biome` + `@rrlab/biome-config` from `package.json`, edits or deletes `biome.json` (depending on whether you have other settings in it), and drops the `biome()` entry from `run-run.config.{ts,mts}`. +It removes `@biomejs/biome` and `@rrlab/biome-config` from `package.json`, and edits or deletes `biome.json`, depending on whether it holds other settings. Then it drops `biome()` from `run-run.config.{ts,mts}`. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/cli/LICENSE b/run-run/cli/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/cli/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/cli/README.md b/run-run/cli/README.md index f0931ee..740e77a 100644 --- a/run-run/cli/README.md +++ b/run-run/cli/README.md @@ -1,22 +1,20 @@

- +

-

run-run

+

run-run

One way to run the scripts in a repo.

-## Prerequisites +`rr` gives a repo one set of commands, such as `rr check`, `rr test` and `rr pack`. Every tool behind them is a plugin you add, so the commands stay the same in every repo. -- Node.js >= 22.18.0 - -## Installation +## Install ```sh pnpm add -D @rrlab/cli ``` -It adds the `rr` command to your project. +It adds the `rr` command to your project. It needs Node 22.18 or later. ## Usage @@ -28,7 +26,7 @@ pnpm rr help > If you have `node_modules/.bin` on your `PATH` (e.g. via `mise` or `direnv` — see [Shell completion](#shell-completion)), you can drop the `pnpm` prefix and invoke `rr` directly. -See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release). +The [CLI reference](https://github.com/withvariablelab/dx/blob/main/run-run/cli/CLI.md) lists every command and flag. It is generated on each release. ## Plugins @@ -122,9 +120,9 @@ test -f ~/.cache/rr-completion.fish; and source ~/.cache/rr-completion.fish Regenerate the cache after upgrading `@rrlab/cli` to pick up new commands. -### Prerequisite +### The usage CLI -The [`usage`](https://usage.jdx.dev) CLI must be on your `PATH` (it powers completion at runtime). Install via one of: +Completion runs on the [`usage`](https://usage.jdx.dev) CLI, so it has to be on your `PATH`. Install it with one of: ```sh mise use -g usage @@ -138,3 +136,11 @@ To enable debug mode, set the `DEBUG` environment variable to `run-run:*` before ```sh DEBUG=run-run:* pnpm rr ``` + +## License + +The code is [MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). The Sign in `brand/` is not: its use is set by [BRAND-USE.md](https://github.com/withvariablelab/brand/blob/main/BRAND-USE.md). + +

+  Variable Land +

diff --git a/run-run/oxc-plugin/LICENSE b/run-run/oxc-plugin/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/oxc-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/oxc-plugin/README.md b/run-run/oxc-plugin/README.md index 31da8f0..1c06acd 100644 --- a/run-run/oxc-plugin/README.md +++ b/run-run/oxc-plugin/README.md @@ -1,6 +1,6 @@ -# @rrlab/oxc-plugin +# oxc-plugin -[oxc](https://oxc.rs) plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides `lint` (oxlint), `format` (oxfmt), and `tsc` (oxlint type-aware) capabilities. +`@rrlab/oxc-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [oxc](https://oxc.rs). It gives `rr` the `lint` (oxlint), `format` (oxfmt) and `typecheck` (oxlint type-aware) capabilities. ## Install @@ -8,22 +8,25 @@ rr plugins add oxc ``` -Installs `@rrlab/oxc-plugin` and adds `oxlint`, `oxfmt`, and `oxlint-tsgolint` as `devDependencies`. No config file is scaffolded — oxlint and oxfmt work with sensible defaults and the projects that need to customise add their own `oxlintrc.json` / `.oxfmtrc` on demand. +`rr plugins add` installs `@rrlab/oxc-plugin` and adds `oxlint`, `oxfmt` and `oxlint-tsgolint` as dev dependencies. It writes no config file: oxlint and oxfmt run with their defaults, and a project that needs to change them adds its own `oxlintrc.json` or `.oxfmtrc`. -For `rr jsc` (lint + format together), the kernel composes oxlint + oxfmt automatically when both capabilities are present and no plugin provides `jsc` directly. +It needs `@rrlab/cli`, oxlint 1 or later and oxfmt 0.67 or later. The type check also needs `oxlint-tsgolint` 0.24 or later, an optional peer. ## What it provides -| Capability | Surface | Underlying command | -|---|---|---| -| `lint` | `rr lint`, `rr lint doctor` | `oxlint --check` / `--fix` | -| `format` | `rr format`, `rr format doctor` | `oxfmt --check` / `--fix` | -| `typecheck` | `rr tsc`, `rr tsc doctor` | `oxlint --type-aware --type-check` (via `oxlint-tsgolint`) | -| `jsc` (composed) | `rr jsc` (synthesised lint + format) | | +| Capability | Commands | Underlying command | +| --- | --- | --- | +| `lint` | `rr lint`, `rr lint doctor` | `oxlint`, `oxlint --fix` | +| `format` | `rr format`, `rr format doctor` | `oxfmt --check`, `oxfmt --write` | +| `typecheck` | `rr tsc`, `rr tsc doctor` | `oxlint --type-aware --type-check` | + +The type check runs through `oxlint-tsgolint`. + +`rr jsc` runs lint and format together. When no plugin provides `jscheck`, `rr` composes it from the `lint` and `format` providers, so with oxc alone it runs oxlint and oxfmt. ## Picking only some capabilities -Pass `only` to mix oxc with another plugin. Example: biome for lint+format, oxc just for the type-aware checks: +Pass `only` to mix oxc with another plugin, such as Biome for lint and format and oxc for the type-aware checks: ```ts import biome from "@rrlab/biome-plugin"; @@ -38,7 +41,7 @@ export default defineConfig({ }); ``` -The `only` array is typed against the kinds *this* plugin provides (`"lint" | "format" | "typecheck"` for oxc), so typos like `oxc({ only: ["pack"] })` are caught at compile time. +The `only` array is typed against the capabilities *this* plugin provides (`"lint" | "format" | "typecheck"` for oxc), so a typo like `oxc({ only: ["pack"] })` fails at compile time. ## Removal @@ -46,4 +49,12 @@ The `only` array is typed against the kinds *this* plugin provides (`"lint" | "f rr plugins remove oxc ``` -Removes `oxlint`, `oxfmt`, and `oxlint-tsgolint` from `package.json` and drops the `oxc()` entry from `run-run.config.{ts,mts}`. Tool config files (`oxlintrc.json`, `.oxfmtrc`) — if any — are left alone, they belong to the user. +It removes `oxlint`, `oxfmt` and `oxlint-tsgolint` from `package.json`, and drops `oxc()` from `run-run.config.{ts,mts}`. It leaves `oxlintrc.json` and `.oxfmtrc` alone, if you have them: they belong to you. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/ts-config/LICENSE b/run-run/ts-config/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/ts-config/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/ts-config/README.md b/run-run/ts-config/README.md index 84d7989..f2e86fb 100644 --- a/run-run/ts-config/README.md +++ b/run-run/ts-config/README.md @@ -1,38 +1,38 @@ -# @rrlab/ts-config +# ts-config -Shared TypeScript presets for projects using [`@rrlab/ts-plugin`](https://npmjs.com/package/@rrlab/ts-plugin). Built on top of [`@total-typescript/tsconfig`](https://github.com/total-typescript/tsconfig). +`@rrlab/ts-config` holds the TypeScript presets of [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli), built on [`@total-typescript/tsconfig`](https://github.com/total-typescript/tsconfig). The `tsconfig.json` that [`@rrlab/ts-plugin`](https://www.npmjs.com/package/@rrlab/ts-plugin) writes extends one of them. ## Install -If you use [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli): +If you use run-run: ```sh rr plugins add ts ``` -Picks a preset interactively and scaffolds your `tsconfig.json`. +It asks for a preset and writes your `tsconfig.json`. -If you don't, install manually: +Without run-run, install it by hand: ```sh pnpm add -D @rrlab/ts-config typescript @types/node ``` -…and point your `tsconfig.json` at one of the entries below. +Then point your `tsconfig.json` at one of the presets below. + +It needs TypeScript 5 or later: the presets use compiler options that are stable since TypeScript 5. The `no-dom` presets also need `@types/node` 20 or later, an optional peer. ## Presets -| Entry | Use when | -|---|---| -| `@rrlab/ts-config/react` | React app (browser DOM + JSX). | -| `@rrlab/ts-config/dom/app` | Web app, DOM available, no React. | -| `@rrlab/ts-config/dom/lib` | Browser library (DOM lib in scope). | -| `@rrlab/ts-config/no-dom/app` | Node.js app / CLI. Requires `@types/node`. | -| `@rrlab/ts-config/no-dom/lib` | Node.js library. Requires `@types/node`. | +- `@rrlab/ts-config/react`: a React app, with the browser DOM and JSX. +- `@rrlab/ts-config/dom/app`: a web app, with the DOM and no React. +- `@rrlab/ts-config/dom/lib`: a browser library, with the DOM lib in scope. +- `@rrlab/ts-config/no-dom/app`: a Node.js app or CLI. It needs `@types/node`. +- `@rrlab/ts-config/no-dom/lib`: a Node.js library. It needs `@types/node`. ## Usage -A typical `tsconfig.json` is a 3-line wrapper: +A typical `tsconfig.json` only extends a preset: ```json { @@ -40,9 +40,12 @@ A typical `tsconfig.json` is a 3-line wrapper: } ``` -Override compiler options or add `include`/`exclude` by setting them in your local file — local keys win over the preset. +Set compiler options, `include` or `exclude` in your `tsconfig.json`: your keys win over the preset. + +## License -## Peer dependencies +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). -- `typescript >= 5.0` — the presets use compiler options stable since TS 5. -- `@types/node >= 20` — only required by the `no-dom-*` presets (declared as optional peer). +

+  Variable Land +

diff --git a/run-run/ts-plugin/LICENSE b/run-run/ts-plugin/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/ts-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/ts-plugin/README.md b/run-run/ts-plugin/README.md index f5f71b6..59ef81a 100644 --- a/run-run/ts-plugin/README.md +++ b/run-run/ts-plugin/README.md @@ -1,6 +1,6 @@ -# @rrlab/ts-plugin +# ts-plugin -TypeScript plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides the `tsc` capability backed by the TypeScript compiler. +`@rrlab/ts-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [TypeScript](https://www.typescriptlang.org). It gives `rr` the `typecheck` capability, backed by `tsc`. ## Install @@ -8,25 +8,27 @@ TypeScript plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Prov rr plugins add ts ``` -`rr plugins add` installs `@rrlab/ts-plugin`, adds `typescript` as a `devDependency`, and (with your confirmation) scaffolds a `tsconfig.json` extending one of the [`@rrlab/ts-config`](https://npmjs.com/package/@rrlab/ts-config) presets. When you opt into scaffolding, you're prompted to pick: +`rr plugins add` installs `@rrlab/ts-plugin` and adds `typescript` as a dev dependency. Once you confirm, it writes a `tsconfig.json` that extends one of the [`@rrlab/ts-config`](https://www.npmjs.com/package/@rrlab/ts-config) presets, which you pick: -- `react` — React app. -- `dom-app` — Web app (DOM, no React). -- `dom-lib` — Browser library. -- `no-dom-app` — Node.js app / CLI (default). -- `no-dom-lib` — Node.js library. +- `react`: a React app. +- `dom-app`: a web app, with the DOM and no React. +- `dom-lib`: a browser library. +- `no-dom-app`: a Node.js app or CLI. +- `no-dom-lib`: a Node.js library. -The `no-dom-*` presets also bring `@types/node` along. If `tsconfig.json` already exists, you can choose to patch (the safe migration default), skip, or overwrite. +The default is `react` when your project depends on `react`, and `no-dom-app` otherwise. The `no-dom-*` presets also add `@types/node`. If `tsconfig.json` already exists, you choose to patch it, which is the default, keep it or overwrite it. + +It needs `@rrlab/cli` and TypeScript 5 or later. ## What it provides -| Capability | Surface | -|---|---| -| `tsc` | `rr tsc` (workspace-aware in monorepos), `rr tsc doctor` | +| Capability | Commands | +| --- | --- | +| `typecheck` | `rr tsc` (workspace-aware in monorepos), `rr tsc doctor` | ## Configuration -The scaffolded `tsconfig.json` is a thin wrapper: +The `tsconfig.json` it writes only extends the preset: ```json { @@ -34,7 +36,7 @@ The scaffolded `tsconfig.json` is a thin wrapper: } ``` -Override compiler options or `include`/`exclude` by adding them to your local `tsconfig.json`. The preset lives in [`@rrlab/ts-config`](https://npmjs.com/package/@rrlab/ts-config). +Set compiler options, `include` or `exclude` in your `tsconfig.json` to override the preset. The presets live in `@rrlab/ts-config`. ## Removal @@ -42,4 +44,12 @@ Override compiler options or `include`/`exclude` by adding them to your local `t rr plugins remove ts ``` -Removes `typescript`, `@rrlab/ts-config`, and `@types/node` from `package.json`. If `tsconfig.json` was only the wrapper we scaffolded, deletes it; otherwise unsets the `extends` and leaves the rest of your settings untouched. Drops the `ts()` entry from `run-run.config.{ts,mts}`. +It removes `typescript`, `@rrlab/ts-config` and `@types/node` from `package.json`. If `tsconfig.json` holds only the `extends` it wrote, it deletes the file; otherwise it unsets `extends` and leaves the rest of your settings. Then it drops `ts()` from `run-run.config.{ts,mts}`. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/tsdown-config/LICENSE b/run-run/tsdown-config/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/tsdown-config/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/tsdown-config/README.md b/run-run/tsdown-config/README.md new file mode 100644 index 0000000..dc7df9d --- /dev/null +++ b/run-run/tsdown-config/README.md @@ -0,0 +1,47 @@ +# tsdown-config + +`@rrlab/tsdown-config` holds the [tsdown](https://tsdown.dev) configuration helpers of [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli). The `tsdown.config.ts` that [`@rrlab/tsdown-plugin`](https://www.npmjs.com/package/@rrlab/tsdown-plugin) writes calls one of them. + +## Install + +If you use run-run: + +```sh +rr plugins add tsdown +``` + +Once you confirm, it asks for the kind of build, installs this package and writes a `tsdown.config.ts` that calls the matching helper. + +Without run-run, install it by hand: + +```sh +pnpm add -D @rrlab/tsdown-config tsdown +``` + +It needs tsdown 0.22 or later and Node 22.18 or later. + +## Presets + +- `defineLibConfig()`: a library. ESM with `.d.ts` declarations, from the entry `src/index.ts`. +- `defineBinConfig()`: a CLI or Node binary. ESM for the `node` platform, from the entry `src/run.ts`. + +Each helper wraps tsdown's `defineConfig()` and takes tsdown's `UserConfig`. Your options are spread over the defaults, so they win. + +## Usage + +```ts +// tsdown.config.ts +import { defineLibConfig } from "@rrlab/tsdown-config"; + +export default defineLibConfig(); +``` + +Pass tsdown options to override a default, such as `defineLibConfig({ entry: ["src/lib.ts"] })`. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/tsdown-plugin/LICENSE b/run-run/tsdown-plugin/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/tsdown-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/tsdown-plugin/README.md b/run-run/tsdown-plugin/README.md index 5882b86..d985019 100644 --- a/run-run/tsdown-plugin/README.md +++ b/run-run/tsdown-plugin/README.md @@ -1,6 +1,6 @@ -# @rrlab/tsdown-plugin +# tsdown-plugin -[tsdown](https://tsdown.dev) plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides the `pack` capability for packaging TypeScript libraries for distribution. +`@rrlab/tsdown-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [tsdown](https://tsdown.dev). It gives `rr` the `pack` capability, which builds a TypeScript package for npm. ## Install @@ -8,15 +8,34 @@ rr plugins add tsdown ``` -Installs `@rrlab/tsdown-plugin` and adds `tsdown` as a `devDependency`. No config file is scaffolded — tsdown reads `tsdown.config.ts` if present, otherwise uses sensible defaults. Add your own when you need to customise. +`rr plugins add` installs `@rrlab/tsdown-plugin` and adds `tsdown` as a dev dependency. Once you confirm, it writes a `tsdown.config.ts` that calls a helper from [`@rrlab/tsdown-config`](https://www.npmjs.com/package/@rrlab/tsdown-config), for the kind of build you pick: + +- `lib`: a library, with declarations and the entry `src/index.ts`. It is the default. +- `bin`: a CLI or Node binary, with the entry `src/run.ts`. + +If a `tsdown.config.*` already exists, you choose to patch it, keep it or overwrite it. Patching turns a default export that calls `defineConfig()` from `tsdown`, or either helper, into a call to the helper you picked, and keeps its options. It refuses any other shape. + +It needs `@rrlab/cli` and tsdown 0.22 or later. ## What it provides -| Capability | Surface | -|---|---| +| Capability | Commands | +| --- | --- | | `pack` | `rr pack`, `rr pack doctor` | -`rr pack` builds your library: emits ESM JavaScript + `.d.ts` declarations to `dist/` so consumers can `import` from the published package. +With the `lib` preset, `rr pack` writes ESM JavaScript and `.d.ts` declarations to `dist/`, so consumers can `import` from the published package. + +## Configuration + +The `tsdown.config.ts` it writes for the `lib` preset: + +```ts +import { defineLibConfig } from "@rrlab/tsdown-config"; + +export default defineLibConfig(); +``` + +Pass tsdown options to the helper to override its defaults, such as `defineLibConfig({ entry: ["src/lib.ts"] })`. ## Removal @@ -24,4 +43,12 @@ Installs `@rrlab/tsdown-plugin` and adds `tsdown` as a `devDependency`. No confi rr plugins remove tsdown ``` -Removes `tsdown` from `package.json` and drops the `tsdown()` entry from `run-run.config.{ts,mts}`. `tsdown.config.ts` — if you have one — is left alone. +It removes `tsdown` and `@rrlab/tsdown-config` from `package.json`. If `tsdown.config.*` is the file it wrote, it deletes it; if you passed options to the helper, it rewrites the file to `defineConfig()` from `tsdown` and keeps them; any other config is left alone. Then it drops `tsdown()` from `run-run.config.{ts,mts}`. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/run-run/vitest-plugin/LICENSE b/run-run/vitest-plugin/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/run-run/vitest-plugin/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/run-run/vitest-plugin/README.md b/run-run/vitest-plugin/README.md index 1c66348..0f897fd 100644 --- a/run-run/vitest-plugin/README.md +++ b/run-run/vitest-plugin/README.md @@ -1,11 +1,23 @@ -# @rrlab/vitest-plugin +# vitest-plugin -Adds the `test` capability to [`@rrlab/cli`](../cli) — a thin passthrough to [vitest](https://vitest.dev). +`@rrlab/vitest-plugin` is a [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) plugin for [Vitest](https://vitest.dev). It gives `rr` the `test` capability, a thin passthrough to vitest. -```bash +## Install + +```sh rr plugins add vitest ``` +`rr plugins add` installs `@rrlab/vitest-plugin` and adds `vitest` as a dev dependency. It writes no config file. + +It needs `@rrlab/cli` and Vitest 3 or later. + +## What it provides + +| Capability | Commands | +| --- | --- | +| `test` | `rr test`, `rr test doctor` | + ## Usage `rr test` forwards every flag and argument straight to vitest, so anything you'd type after `vitest` works unchanged: @@ -25,7 +37,7 @@ By default `rr test` loads an env file before running, picking the **first that 1. `.env.test` 2. `.env` -Override it with `--env` (must come before the forwarded args): +Override it with `--env`, which must come before the forwarded args: ```bash rr test --env=.env.ci run @@ -34,5 +46,20 @@ rr test --env=.env.ci run > It's `--env`, not `--env-file`: Node's early `--env-file` scanner would grab > that exact token off the `rr` process before the CLI could read it. -An explicit `--env` file that doesn't exist is an error (typo protection); the -defaults above are loaded only when present. +An explicit `--env` file that doesn't exist is an error, to catch typos. The defaults above are loaded only when present. + +## Removal + +```sh +rr plugins remove vitest +``` + +It removes `vitest` from `package.json`, and drops `vitest()` from `run-run.config.{ts,mts}`. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/shared/clibuddy/LICENSE b/shared/clibuddy/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/shared/clibuddy/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/shared/clibuddy/README.md b/shared/clibuddy/README.md index fe497eb..6aa9d99 100644 --- a/shared/clibuddy/README.md +++ b/shared/clibuddy/README.md @@ -1,9 +1,19 @@ -# Clibuddy +# clibuddy -A helper library to create CLIs in Variable Land +`@variablelab/clibuddy` holds the helpers that [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) and [vland](https://github.com/withvariablelab/dx/tree/main/vland/cli) build their CLIs with: running shell commands, reading packages and workspaces, the task board, and terminal colors and text. It is published because `@rrlab/cli` and `@variablelab/vland` depend on it, and it isn't meant for use outside them. -## Installation +## Install ```sh pnpm add @variablelab/clibuddy ``` + +It needs Node 22.18 or later. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/shared/loggy/LICENSE b/shared/loggy/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/shared/loggy/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/shared/loggy/README.md b/shared/loggy/README.md index 13b256c..35fd6a8 100644 --- a/shared/loggy/README.md +++ b/shared/loggy/README.md @@ -1,9 +1,19 @@ -# Loggy +# loggy -Console wrapper to make logging fun again +`@variablelab/loggy` is the logger of [run-run](https://github.com/withvariablelab/dx/tree/main/run-run/cli) and [vland](https://github.com/withvariablelab/dx/tree/main/vland/cli). It writes messages through [consola](https://github.com/unjs/consola), and debug output through [debug](https://github.com/debug-js/debug) under a namespace, which `DEBUG=:*` turns on. It is published because `@rrlab/cli` and `@variablelab/vland` depend on it, and it isn't meant for use outside them. -## Installation +## Install ```sh pnpm add @variablelab/loggy ``` + +It needs Node 22.18 or later. + +## License + +[MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). + +

+  Variable Land +

diff --git a/vland/cli/LICENSE b/vland/cli/LICENSE new file mode 100644 index 0000000..338c113 --- /dev/null +++ b/vland/cli/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rcrd + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/vland/cli/README.md b/vland/cli/README.md index 9a155cc..32f0384 100644 --- a/vland/cli/README.md +++ b/vland/cli/README.md @@ -1,28 +1,25 @@

- +

-

vland

+

vland

Starts a project in Variable Land.

-## Prerequisites +`vland init` fetches a template from the dx repository and fills in the project's name and author. Then it offers to install the dependencies and to initialise a git repository. -- Node.js >= 22.18.0 - -## Installation - -Run it directly with `npx`: +## Install ```sh -npx @variablelab/vland init +pnpm add -g @variablelab/vland ``` -…or install it globally: +It needs Node 22.18 or later. + +To run it once without installing it, use `npx`: ```sh -pnpm add -g @variablelab/vland -vland init +npx @variablelab/vland init ``` ## Usage @@ -33,7 +30,7 @@ vland init my-app -t library # explicit template vland init my-app -t backend --no-install --no-git ``` -See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release). +The [CLI reference](https://github.com/withvariablelab/dx/blob/main/vland/cli/CLI.md) lists every command and flag. It is generated on each release. ### Templates @@ -43,7 +40,7 @@ See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release). | `backend` | An Elysia (`@elysiajs/node`) backend with evlog, Vitest, Dockerfile, CI shape. | | `monorepo` | pnpm + Turbo workspace with an Elysia API, a Vite-React SPA, and a few internal packages. | -All templates target Node.js, pin Node.js and pnpm with [mise](https://mise.jdx.dev) (`mise.toml` and `mise.lock`), run their GitHub Actions on SHA-pinned actions checked by [zizmor](https://docs.zizmor.sh), and ship [`@rrlab/cli`](https://github.com/withvariablelab/dx/tree/main/run-run) (`rr`) as the single entry point for lint, format, type-check, and build. The per-tool config files (`biome.json`, `tsconfig.json`, `tsdown.config.ts`) are not bundled — run `rr plugins add biome ts tsdown` (one at a time) in your new project to opt in. See the scaffolded README for the exact post-install setup. +All templates target Node.js, pin Node.js and pnpm with [mise](https://mise.jdx.dev) (`mise.toml` and `mise.lock`), run their GitHub Actions on SHA-pinned actions checked by [zizmor](https://docs.zizmor.sh), and ship [`@rrlab/cli`](https://github.com/withvariablelab/dx/tree/main/run-run/cli) (`rr`) as the single entry point for lint, format, type-check, and build. The per-tool config files (`biome.json`, `tsconfig.json`, `tsdown.config.ts`) are not bundled: in your new project, run `rr plugins add` once per tool (`biome`, `ts`, `tsdown`) to opt in. The scaffolded README has the exact post-install setup. ## Shell completion @@ -62,7 +59,7 @@ command -v vland >/dev/null 2>&1; and vland completion fish 2>/dev/null | source The `command -v` guard skips the line when no `vland` is on `PATH`. The `2>/dev/null` covers a mise shim with no active version: it passes the guard, then fails on stderr. If completion doesn't load, run `vland completion zsh` by hand to see why. -**Prerequisite:** the [`usage`](https://usage.jdx.dev) CLI must be on your `PATH` (it powers completion at runtime). Install via one of: +Completion runs on the [`usage`](https://usage.jdx.dev) CLI, so it has to be on your `PATH`. Install it with one of: ```sh mise use -g usage @@ -84,3 +81,11 @@ To point `init` at local templates instead of fetching from GitHub (useful when ```sh VLAND_TEMPLATES_DIR=/absolute/path/to/dx/vland/templates vland init my-app -t library ``` + +## License + +The code is [MIT](https://github.com/withvariablelab/dx/blob/main/LICENSE). The Sign in `brand/` is not: its use is set by [BRAND-USE.md](https://github.com/withvariablelab/brand/blob/main/BRAND-USE.md). + +

+  Variable Land +