@rrlab/biome-plugin 0.0.1-git-06ed46c.0

package/README.md

@@ -0,0 +1,40 @@
+# @rrlab/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).
+
+## Install
+
+```sh
+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.
+
+## What it provides
+
+| Capability | Surface |
+|---|---|
+| `lint` | `rr lint`, `rr lint doctor` |
+| `format` | `rr format`, `rr format doctor` |
+| `jsc` | `rr jsc` (lint + format together), `rr jsc doctor` |
+
+## Configuration
+
+The scaffolded `biome.json` is a thin wrapper:
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.4/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.
+
+## Removal
+
+```sh
+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}`.

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+import { FormatOptions, Formatter, InstallContext, InstallResult, LintOptions, Linter, StaticChecker, StaticCheckerOptions, ToolService, UninstallContext, UninstallResult } from "@rrlab/cli/plugin";
+import { ShellService } from "@vlandoss/clibuddy";
+
+//#region src/tool-versions.d.ts
+declare const TOOL_VERSIONS: {
+  readonly "@biomejs/biome": {
+    readonly install: "^2.0.0";
+    readonly peer: ">=2.0.0";
+  };
+};
+//#endregion
+//#region src/index.d.ts
+declare class BiomeService extends ToolService implements Formatter, Linter, StaticChecker {
+  constructor(shellService: ShellService);
+  format(options: FormatOptions): Promise<void>;
+  lint(options: LintOptions): Promise<void>;
+  check(options: StaticCheckerOptions): Promise<void>;
+}
+declare function install(ctx: InstallContext): Promise<InstallResult>;
+declare function uninstall(ctx: UninstallContext): Promise<UninstallResult>;
+declare const biome: (options: void) => import("@rrlab/cli/plugin").Plugin;
+//#endregion
+export { BiomeService, TOOL_VERSIONS, biome as default, install, uninstall };

package/dist/index.mjs

@@ -0,0 +1,190 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ToolService, definePlugin } from "@rrlab/cli/plugin";
+import { colorize, isCI } from "@vlandoss/clibuddy";
+import { parse } from "comment-json";
+//#region src/tool-versions.ts
+const TOOL_VERSIONS = { "@biomejs/biome": {
+	install: "^2.0.0",
+	peer: ">=2.0.0"
+} };
+//#endregion
+//#region src/index.ts
+const FROM = import.meta.url;
+const UI = colorize("#61A5FA")("biome");
+const COMMON_FLAGS = ["--colors=force", "--no-errors-on-unmatched"];
+const BIOME_JSON = "biome.json";
+const BIOME_CONFIG_PKG = "@rrlab/biome-config";
+const BIOME_SCHEMA = "https://biomejs.dev/schemas/2.4.4/schema.json";
+var BiomeService = class extends ToolService {
+	constructor(shellService) {
+		super({
+			pkg: "@biomejs/biome",
+			bin: "biome",
+			ui: UI,
+			shellService,
+			from: FROM
+		});
+	}
+	async format(options) {
+		const args = ["format", ...COMMON_FLAGS];
+		if (options.fix) args.push("--fix");
+		await this.exec(args);
+	}
+	async lint(options) {
+		const args = [
+			"check",
+			...COMMON_FLAGS,
+			"--formatter-enabled=false"
+		];
+		if (options.fix) args.push("--fix", "--unsafe");
+		await this.exec(args);
+	}
+	async check(options) {
+		if (options.fix) await this.exec([
+			"check",
+			...COMMON_FLAGS,
+			"--fix"
+		]);
+		else if (options.fixStaged) await this.exec([
+			"check",
+			...COMMON_FLAGS,
+			"--fix",
+			"--staged"
+		]);
+		else await this.exec([isCI ? "ci" : "check", ...COMMON_FLAGS]);
+	}
+};
+async function install(ctx) {
+	const scaffoldDecision = await decideScaffoldAction(ctx, await pathExists(path.join(ctx.appPkg.dirPath, BIOME_JSON)));
+	if (scaffoldDecision === "skip") return { devDependencies: { "@biomejs/biome": TOOL_VERSIONS["@biomejs/biome"].install } };
+	return {
+		devDependencies: {
+			"@biomejs/biome": TOOL_VERSIONS["@biomejs/biome"].install,
+			[BIOME_CONFIG_PKG]: "^0.1.0"
+		},
+		files: [scaffoldDecision === "create" || scaffoldDecision === "overwrite" ? {
+			kind: "create",
+			path: BIOME_JSON,
+			content: `${JSON.stringify({
+				$schema: BIOME_SCHEMA,
+				extends: [BIOME_CONFIG_PKG]
+			}, null, 2)}\n`,
+			overwrite: scaffoldDecision === "overwrite" || ctx.flags.force
+		} : {
+			kind: "edit-json",
+			path: BIOME_JSON,
+			edits: [{
+				op: "set",
+				path: "/$schema",
+				value: BIOME_SCHEMA,
+				mode: "if-missing"
+			}, {
+				op: "include",
+				path: "/extends",
+				value: BIOME_CONFIG_PKG,
+				position: "start"
+			}]
+		}]
+	};
+}
+async function uninstall(ctx) {
+	const biomeJsonPath = path.join(ctx.appPkg.dirPath, BIOME_JSON);
+	const removeDependencies = ["@biomejs/biome", BIOME_CONFIG_PKG];
+	if (!await pathExists(biomeJsonPath)) return { removeDependencies };
+	let existing;
+	try {
+		existing = parse(await fs.readFile(biomeJsonPath, "utf8"));
+	} catch {}
+	const files = [];
+	if (existing) {
+		const otherExtends = (Array.isArray(existing.extends) ? existing.extends : []).filter((e) => e !== BIOME_CONFIG_PKG);
+		const { $schema: _schema, extends: _extends, ...rest } = existing;
+		const semanticKeys = Object.keys(rest);
+		if (otherExtends.length === 0 && semanticKeys.length === 0) files.push({
+			kind: "delete",
+			path: BIOME_JSON
+		});
+		else {
+			const edits = [{
+				op: "exclude",
+				path: "/extends",
+				value: BIOME_CONFIG_PKG
+			}];
+			if (otherExtends.length === 0) edits.push({
+				op: "unset",
+				path: "/extends"
+			});
+			files.push({
+				kind: "edit-json",
+				path: BIOME_JSON,
+				edits
+			});
+		}
+	}
+	return {
+		removeDependencies,
+		files
+	};
+}
+async function decideScaffoldAction(ctx, fileExists) {
+	if (!fileExists) {
+		if (ctx.flags.yes || ctx.flags.nonInteractive) return "create";
+		const choice = await ctx.prompts.confirm({
+			message: `Scaffold ${BIOME_JSON} with the @rrlab/biome-config preset?`,
+			initialValue: true
+		});
+		if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+		return choice ? "create" : "skip";
+	}
+	if (ctx.flags.yes || ctx.flags.nonInteractive) return "patch";
+	const choice = await ctx.prompts.select({
+		message: `${BIOME_JSON} already exists. What do you want to do?`,
+		options: [
+			{
+				value: "patch",
+				label: "Patch — add @rrlab/biome-config to extends, keep my other settings"
+			},
+			{
+				value: "skip",
+				label: "Skip — leave it alone"
+			},
+			{
+				value: "overwrite",
+				label: "Overwrite — replace with a fresh scaffold"
+			}
+		],
+		initialValue: "patch"
+	});
+	if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+	return choice;
+}
+async function pathExists(p) {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+const biome = definePlugin(() => ({
+	name: "biome",
+	apiVersion: 1,
+	install,
+	uninstall,
+	async setup({ shell }) {
+		const svc = new BiomeService(shell);
+		try {
+			await svc.getBinDir();
+		} catch (_err) {
+			throw new Error("@rrlab/biome-plugin requires @biomejs/biome to be installed in the host project. Run: rr plugins add biome  (or: pnpm add -D @biomejs/biome)");
+		}
+		return {
+			lint: svc,
+			format: svc,
+			jsc: svc
+		};
+	}
+}));
+//#endregion
+export { BiomeService, TOOL_VERSIONS, biome as default, install, uninstall };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@rrlab/biome-plugin",
+  "version": "0.0.1-git-06ed46c.0",
+  "description": "Biome plugin for @rrlab/cli — provides lint, format, and jsc capabilities.",
+  "homepage": "https://github.com/variableland/dx/tree/main/run-run/biome-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/variableland/dx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/variableland/dx.git",
+    "directory": "run-run/biome-plugin"
+  },
+  "license": "MIT",
+  "author": "rcrd <rcrd@variable.land>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "comment-json": "4.2.5",
+    "@vlandoss/clibuddy": "0.6.1"
+  },
+  "peerDependencies": {
+    "@biomejs/biome": ">=2.0.0",
+    "@rrlab/cli": "0.0.2-git-06ed46c.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.4",
+    "@rrlab/cli": "0.0.2-git-06ed46c.0",
+    "@rrlab/tsdown-config": "^0.0.1-git-06ed46c.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,192 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  definePlugin,
+  type FileOp,
+  type FormatOptions,
+  type Formatter,
+  type InstallContext,
+  type InstallResult,
+  type Linter,
+  type LintOptions,
+  type StaticChecker,
+  type StaticCheckerOptions,
+  ToolService,
+  type UninstallContext,
+  type UninstallResult,
+} from "@rrlab/cli/plugin";
+import { colorize, isCI, type ShellService } from "@vlandoss/clibuddy";
+import { parse as parseJsonc } from "comment-json";
+import { TOOL_VERSIONS } from "./tool-versions.ts";
+
+const FROM = import.meta.url;
+const UI = colorize("#61A5FA")("biome");
+const COMMON_FLAGS = ["--colors=force", "--no-errors-on-unmatched"];
+const BIOME_JSON = "biome.json";
+const BIOME_CONFIG_PKG = "@rrlab/biome-config";
+const BIOME_SCHEMA = "https://biomejs.dev/schemas/2.4.4/schema.json";
+
+export { TOOL_VERSIONS } from "./tool-versions.ts";
+
+export class BiomeService extends ToolService implements Formatter, Linter, StaticChecker {
+  constructor(shellService: ShellService) {
+    super({ pkg: "@biomejs/biome", bin: "biome", ui: UI, shellService, from: FROM });
+  }
+
+  async format(options: FormatOptions) {
+    const args = ["format", ...COMMON_FLAGS];
+    if (options.fix) args.push("--fix");
+    await this.exec(args);
+  }
+
+  async lint(options: LintOptions) {
+    const args = ["check", ...COMMON_FLAGS, "--formatter-enabled=false"];
+    if (options.fix) args.push("--fix", "--unsafe");
+    await this.exec(args);
+  }
+
+  async check(options: StaticCheckerOptions): Promise<void> {
+    if (options.fix) {
+      await this.exec(["check", ...COMMON_FLAGS, "--fix"]);
+    } else if (options.fixStaged) {
+      await this.exec(["check", ...COMMON_FLAGS, "--fix", "--staged"]);
+    } else {
+      await this.exec([isCI ? "ci" : "check", ...COMMON_FLAGS]);
+    }
+  }
+}
+
+export async function install(ctx: InstallContext): Promise<InstallResult> {
+  const biomeJsonPath = path.join(ctx.appPkg.dirPath, BIOME_JSON);
+  const fileExists = await pathExists(biomeJsonPath);
+  const scaffoldDecision = await decideScaffoldAction(ctx, fileExists);
+
+  if (scaffoldDecision === "skip") {
+    return { devDependencies: { "@biomejs/biome": TOOL_VERSIONS["@biomejs/biome"].install } };
+  }
+
+  const devDependencies: Record<string, string> = {
+    "@biomejs/biome": TOOL_VERSIONS["@biomejs/biome"].install,
+    [BIOME_CONFIG_PKG]: "^0.1.0",
+  };
+
+  const file: FileOp =
+    scaffoldDecision === "create" || scaffoldDecision === "overwrite"
+      ? {
+          kind: "create",
+          path: BIOME_JSON,
+          content: `${JSON.stringify({ $schema: BIOME_SCHEMA, extends: [BIOME_CONFIG_PKG] }, null, 2)}\n`,
+          overwrite: scaffoldDecision === "overwrite" || ctx.flags.force,
+        }
+      : {
+          kind: "edit-json",
+          path: BIOME_JSON,
+          edits: [
+            { op: "set", path: "/$schema", value: BIOME_SCHEMA, mode: "if-missing" },
+            { op: "include", path: "/extends", value: BIOME_CONFIG_PKG, position: "start" },
+          ],
+        };
+
+  return { devDependencies, files: [file] };
+}
+
+export async function uninstall(ctx: UninstallContext): Promise<UninstallResult> {
+  const biomeJsonPath = path.join(ctx.appPkg.dirPath, BIOME_JSON);
+  const removeDependencies = ["@biomejs/biome", BIOME_CONFIG_PKG];
+
+  if (!(await pathExists(biomeJsonPath))) {
+    return { removeDependencies };
+  }
+
+  let existing: Record<string, unknown> | undefined;
+  try {
+    const text = await fs.readFile(biomeJsonPath, "utf8");
+    existing = parseJsonc(text) as Record<string, unknown>;
+  } catch {
+    /* malformed — skip surgical edits */
+  }
+
+  const files: FileOp[] = [];
+  if (existing) {
+    const extendsArr = Array.isArray(existing.extends) ? existing.extends : [];
+    const otherExtends = extendsArr.filter((e) => e !== BIOME_CONFIG_PKG);
+    const { $schema: _schema, extends: _extends, ...rest } = existing;
+    const semanticKeys = Object.keys(rest);
+    if (otherExtends.length === 0 && semanticKeys.length === 0) {
+      files.push({ kind: "delete", path: BIOME_JSON });
+    } else {
+      const edits = [{ op: "exclude" as const, path: "/extends", value: BIOME_CONFIG_PKG }];
+      if (otherExtends.length === 0) {
+        edits.push({ op: "unset" as const, path: "/extends" } as never);
+      }
+      files.push({ kind: "edit-json", path: BIOME_JSON, edits });
+    }
+  }
+
+  return { removeDependencies, files };
+}
+
+type ExistingFileAction = "skip" | "patch" | "overwrite";
+
+async function decideScaffoldAction(
+  ctx: InstallContext,
+  fileExists: boolean,
+): Promise<"create" | "patch" | "overwrite" | "skip"> {
+  if (!fileExists) {
+    if (ctx.flags.yes || ctx.flags.nonInteractive) return "create";
+    const choice = await ctx.prompts.confirm({
+      message: `Scaffold ${BIOME_JSON} with the @rrlab/biome-config preset?`,
+      initialValue: true,
+    });
+    if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+    return choice ? "create" : "skip";
+  }
+
+  if (ctx.flags.yes || ctx.flags.nonInteractive) return "patch";
+
+  const choice = await ctx.prompts.select<ExistingFileAction>({
+    message: `${BIOME_JSON} already exists. What do you want to do?`,
+    options: [
+      { value: "patch", label: "Patch — add @rrlab/biome-config to extends, keep my other settings" },
+      { value: "skip", label: "Skip — leave it alone" },
+      { value: "overwrite", label: "Overwrite — replace with a fresh scaffold" },
+    ],
+    initialValue: "patch",
+  });
+  if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+  return choice;
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const biome = definePlugin<void>(() => ({
+  name: "biome",
+  apiVersion: 1,
+  install,
+  uninstall,
+  async setup({ shell }) {
+    const svc = new BiomeService(shell);
+    try {
+      await svc.getBinDir();
+    } catch (_err) {
+      throw new Error(
+        "@rrlab/biome-plugin requires @biomejs/biome to be installed in the host project. " +
+          "Run: rr plugins add biome  (or: pnpm add -D @biomejs/biome)",
+      );
+    }
+    return {
+      lint: svc,
+      format: svc,
+      jsc: svc,
+    };
+  },
+}));
+
+export default biome;

package/src/tool-versions.ts

@@ -0,0 +1,3 @@
+export const TOOL_VERSIONS = {
+  "@biomejs/biome": { install: "^2.0.0", peer: ">=2.0.0" },
+} as const;