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

package/README.md

@@ -0,0 +1,45 @@
+# @rrlab/ts-plugin
+
+TypeScript plugin for [`@rrlab/cli`](https://npmjs.com/package/@rrlab/cli). Provides the `tsc` capability backed by the TypeScript compiler.
+
+## Install
+
+```sh
+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:
+
+- `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.
+
+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.
+
+## What it provides
+
+| Capability | Surface |
+|---|---|
+| `tsc` | `rr tsc` (workspace-aware in monorepos), `rr tsc doctor` |
+
+## Configuration
+
+The scaffolded `tsconfig.json` is a thin wrapper:
+
+```json
+{
+  "extends": "@rrlab/ts-config/no-dom/app"
+}
+```
+
+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).
+
+## Removal
+
+```sh
+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}`.

package/dist/index.d.mts

@@ -0,0 +1,24 @@
+import { InstallContext, InstallResult, ToolService, TypeCheckOptions, TypeChecker, UninstallContext, UninstallResult } from "@rrlab/cli/plugin";
+import { ShellService } from "@vlandoss/clibuddy";
+
+//#region src/tool-versions.d.ts
+declare const TOOL_VERSIONS: {
+  readonly typescript: {
+    readonly install: "^6.0.0";
+    readonly peer: ">=5.0.0";
+  };
+  readonly "@types/node": {
+    readonly install: ">=20";
+  };
+};
+//#endregion
+//#region src/index.d.ts
+declare class TscService extends ToolService implements TypeChecker {
+  constructor(shellService: ShellService);
+  check(options?: TypeCheckOptions): Promise<void>;
+}
+declare function install(ctx: InstallContext): Promise<InstallResult>;
+declare function uninstall(ctx: UninstallContext): Promise<UninstallResult>;
+declare const ts: (options: void) => import("@rrlab/cli/plugin").Plugin;
+//#endregion
+export { TOOL_VERSIONS, TscService, ts as default, install, uninstall };

package/dist/index.mjs

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ToolService, definePlugin } from "@rrlab/cli/plugin";
+import { colorize } from "@vlandoss/clibuddy";
+import { parse } from "comment-json";
+//#region src/tool-versions.ts
+const TOOL_VERSIONS = {
+	typescript: {
+		install: "^6.0.0",
+		peer: ">=5.0.0"
+	},
+	"@types/node": { install: ">=20" }
+};
+//#endregion
+//#region src/index.ts
+const FROM = import.meta.url;
+const UI = colorize("#3178C6")("tsc");
+const TSCONFIG = "tsconfig.json";
+var TscService = class extends ToolService {
+	constructor(shellService) {
+		super({
+			pkg: "typescript",
+			bin: "tsc",
+			ui: UI,
+			shellService,
+			from: FROM
+		});
+	}
+	async check(options = {}) {
+		await this.exec(["--noEmit"], {
+			cwd: options.cwd,
+			verbose: !options.cwd
+		});
+	}
+};
+const PRESETS = {
+	react: {
+		extendsPath: "@rrlab/ts-config/react",
+		label: "React app",
+		needsNode: false
+	},
+	"dom-app": {
+		extendsPath: "@rrlab/ts-config/dom/app",
+		label: "Web app (DOM, no React)",
+		needsNode: false
+	},
+	"dom-lib": {
+		extendsPath: "@rrlab/ts-config/dom/lib",
+		label: "Browser library",
+		needsNode: false
+	},
+	"no-dom-app": {
+		extendsPath: "@rrlab/ts-config/no-dom/app",
+		label: "Node.js app / CLI",
+		needsNode: true
+	},
+	"no-dom-lib": {
+		extendsPath: "@rrlab/ts-config/no-dom/lib",
+		label: "Node.js library",
+		needsNode: true
+	}
+};
+const DEFAULT_PRESET = "no-dom-app";
+async function install(ctx) {
+	const scaffoldDecision = await decideScaffoldAction(ctx, await pathExists(path.join(ctx.appPkg.dirPath, TSCONFIG)));
+	if (scaffoldDecision === "skip") return { devDependencies: { typescript: TOOL_VERSIONS.typescript.install } };
+	const presetInfo = PRESETS[await pickPreset(ctx)];
+	const devDependencies = {
+		typescript: TOOL_VERSIONS.typescript.install,
+		"@rrlab/ts-config": "^0.1.0"
+	};
+	if (presetInfo.needsNode) devDependencies["@types/node"] = TOOL_VERSIONS["@types/node"].install;
+	const wrapper = { extends: presetInfo.extendsPath };
+	return {
+		devDependencies,
+		files: [scaffoldDecision === "create" || scaffoldDecision === "overwrite" ? {
+			kind: "create",
+			path: TSCONFIG,
+			content: `${JSON.stringify(wrapper, null, 2)}\n`,
+			overwrite: scaffoldDecision === "overwrite" || ctx.flags.force
+		} : {
+			kind: "edit-json",
+			path: TSCONFIG,
+			edits: [{
+				op: "set",
+				path: "/extends",
+				value: presetInfo.extendsPath,
+				mode: "replace"
+			}]
+		}]
+	};
+}
+async function uninstall(ctx) {
+	const tsconfigPath = path.join(ctx.appPkg.dirPath, TSCONFIG);
+	const removeDependencies = [
+		"typescript",
+		"@rrlab/ts-config",
+		"@types/node"
+	];
+	if (!await pathExists(tsconfigPath)) return { removeDependencies };
+	let existing;
+	try {
+		existing = parse(await fs.readFile(tsconfigPath, "utf8"));
+	} catch {}
+	const files = [];
+	if (existing) {
+		const { extends: _drop, ...rest } = existing;
+		if (Object.keys(rest).filter((k) => !k.startsWith("$")).length === 0) files.push({
+			kind: "delete",
+			path: TSCONFIG
+		});
+		else files.push({
+			kind: "edit-json",
+			path: TSCONFIG,
+			edits: [{
+				op: "unset",
+				path: "/extends"
+			}]
+		});
+	}
+	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 ${TSCONFIG} with an @rrlab/ts-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: `${TSCONFIG} already exists. What do you want to do?`,
+		options: [
+			{
+				value: "patch",
+				label: "Patch — update 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 pickPreset(ctx) {
+	if (ctx.flags.yes || ctx.flags.nonInteractive) return DEFAULT_PRESET;
+	const choice = await ctx.prompts.select({
+		message: "Which kind of TS project do you need?",
+		options: Object.entries(PRESETS).map(([value, meta]) => ({
+			value,
+			label: meta.label
+		})),
+		initialValue: DEFAULT_PRESET
+	});
+	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 ts = definePlugin(() => ({
+	name: "ts",
+	apiVersion: 1,
+	install,
+	uninstall,
+	async setup({ shell }) {
+		const svc = new TscService(shell);
+		try {
+			await svc.getBinDir();
+		} catch (_err) {
+			throw new Error("@rrlab/ts-plugin requires typescript to be installed in the host project. Run: rr plugins add ts  (or: pnpm add -D typescript)");
+		}
+		return { tsc: svc };
+	}
+}));
+//#endregion
+export { TOOL_VERSIONS, TscService, ts as default, install, uninstall };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@rrlab/ts-plugin",
+  "version": "0.0.1-git-06ed46c.0",
+  "description": "TypeScript plugin for @rrlab/cli — provides the tsc capability.",
+  "homepage": "https://github.com/variableland/dx/tree/main/run-run/ts-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/variableland/dx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/variableland/dx.git",
+    "directory": "run-run/ts-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": {
+    "typescript": ">=5.0.0",
+    "@rrlab/cli": "0.0.2-git-06ed46c.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3",
+    "@rrlab/tsdown-config": "^0.0.1-git-06ed46c.0",
+    "@rrlab/cli": "0.0.2-git-06ed46c.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  definePlugin,
+  type FileOp,
+  type InstallContext,
+  type InstallResult,
+  ToolService,
+  type TypeChecker,
+  type TypeCheckOptions,
+  type UninstallContext,
+  type UninstallResult,
+} from "@rrlab/cli/plugin";
+import { colorize, type ShellService } from "@vlandoss/clibuddy";
+import { parse as parseJsonc } from "comment-json";
+import { TOOL_VERSIONS } from "./tool-versions.ts";
+
+export { TOOL_VERSIONS } from "./tool-versions.ts";
+
+const FROM = import.meta.url;
+const UI = colorize("#3178C6")("tsc");
+const TSCONFIG = "tsconfig.json";
+
+export class TscService extends ToolService implements TypeChecker {
+  constructor(shellService: ShellService) {
+    super({ pkg: "typescript", bin: "tsc", ui: UI, shellService, from: FROM });
+  }
+
+  async check(options: TypeCheckOptions = {}): Promise<void> {
+    await this.exec(["--noEmit"], { cwd: options.cwd, verbose: !options.cwd });
+  }
+}
+
+type Preset = "react" | "dom-app" | "dom-lib" | "no-dom-app" | "no-dom-lib";
+
+type PresetInfo = {
+  extendsPath: string;
+  label: string;
+  /** `@types/node` is only required by the no-dom presets. */
+  needsNode: boolean;
+};
+
+const PRESETS: Record<Preset, PresetInfo> = {
+  react: { extendsPath: "@rrlab/ts-config/react", label: "React app", needsNode: false },
+  "dom-app": { extendsPath: "@rrlab/ts-config/dom/app", label: "Web app (DOM, no React)", needsNode: false },
+  "dom-lib": { extendsPath: "@rrlab/ts-config/dom/lib", label: "Browser library", needsNode: false },
+  "no-dom-app": { extendsPath: "@rrlab/ts-config/no-dom/app", label: "Node.js app / CLI", needsNode: true },
+  "no-dom-lib": { extendsPath: "@rrlab/ts-config/no-dom/lib", label: "Node.js library", needsNode: true },
+};
+
+const DEFAULT_PRESET: Preset = "no-dom-app";
+
+type ExistingFileAction = "skip" | "patch" | "overwrite";
+
+export async function install(ctx: InstallContext): Promise<InstallResult> {
+  const tsconfigPath = path.join(ctx.appPkg.dirPath, TSCONFIG);
+  const fileExists = await pathExists(tsconfigPath);
+
+  const scaffoldDecision = await decideScaffoldAction(ctx, fileExists);
+  if (scaffoldDecision === "skip") {
+    return { devDependencies: { typescript: TOOL_VERSIONS.typescript.install } };
+  }
+
+  const preset = await pickPreset(ctx);
+  const presetInfo = PRESETS[preset];
+
+  const devDependencies: Record<string, string> = {
+    typescript: TOOL_VERSIONS.typescript.install,
+    "@rrlab/ts-config": "^0.1.0",
+  };
+  if (presetInfo.needsNode) devDependencies["@types/node"] = TOOL_VERSIONS["@types/node"].install;
+
+  const wrapper = { extends: presetInfo.extendsPath };
+  const file: FileOp =
+    scaffoldDecision === "create" || scaffoldDecision === "overwrite"
+      ? {
+          kind: "create",
+          path: TSCONFIG,
+          content: `${JSON.stringify(wrapper, null, 2)}\n`,
+          overwrite: scaffoldDecision === "overwrite" || ctx.flags.force,
+        }
+      : {
+          kind: "edit-json",
+          path: TSCONFIG,
+          edits: [{ op: "set", path: "/extends", value: presetInfo.extendsPath, mode: "replace" }],
+        };
+
+  return { devDependencies, files: [file] };
+}
+
+export async function uninstall(ctx: UninstallContext): Promise<UninstallResult> {
+  const tsconfigPath = path.join(ctx.appPkg.dirPath, TSCONFIG);
+  const removeDependencies = ["typescript", "@rrlab/ts-config", "@types/node"];
+
+  if (!(await pathExists(tsconfigPath))) {
+    return { removeDependencies };
+  }
+
+  // Read the current tsconfig to decide between full delete and surgical unset.
+  let existing: Record<string, unknown> | undefined;
+  try {
+    const text = await fs.readFile(tsconfigPath, "utf8");
+    existing = parseJsonc(text) as Record<string, unknown>;
+  } catch {
+    /* malformed — leave it alone, only edit if we can parse */
+  }
+
+  const files: FileOp[] = [];
+  if (existing) {
+    const { extends: _drop, ...rest } = existing;
+    const semanticKeys = Object.keys(rest).filter((k) => !k.startsWith("$"));
+    if (semanticKeys.length === 0) {
+      files.push({ kind: "delete", path: TSCONFIG });
+    } else {
+      files.push({ kind: "edit-json", path: TSCONFIG, edits: [{ op: "unset", path: "/extends" }] });
+    }
+  }
+
+  return { removeDependencies, files };
+}
+
+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 ${TSCONFIG} with an @rrlab/ts-config preset?`,
+      initialValue: true,
+    });
+    if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+    return choice ? "create" : "skip";
+  }
+
+  // Existing file. Default to patch for migration safety.
+  if (ctx.flags.yes || ctx.flags.nonInteractive) return "patch";
+
+  const choice = await ctx.prompts.select<ExistingFileAction>({
+    message: `${TSCONFIG} already exists. What do you want to do?`,
+    options: [
+      { value: "patch", label: "Patch — update 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 pickPreset(ctx: InstallContext): Promise<Preset> {
+  if (ctx.flags.yes || ctx.flags.nonInteractive) return DEFAULT_PRESET;
+
+  const choice = await ctx.prompts.select<Preset>({
+    message: "Which kind of TS project do you need?",
+    options: (Object.entries(PRESETS) as Array<[Preset, PresetInfo]>).map(([value, meta]) => ({
+      value,
+      label: meta.label,
+    })),
+    initialValue: DEFAULT_PRESET,
+  });
+  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 ts = definePlugin<void>(() => ({
+  name: "ts",
+  apiVersion: 1,
+  install,
+  uninstall,
+  async setup({ shell }) {
+    const svc = new TscService(shell);
+    try {
+      await svc.getBinDir();
+    } catch (_err) {
+      throw new Error(
+        "@rrlab/ts-plugin requires typescript to be installed in the host project. " +
+          "Run: rr plugins add ts  (or: pnpm add -D typescript)",
+      );
+    }
+    return { tsc: svc };
+  },
+}));
+
+export default ts;

package/src/tool-versions.ts

@@ -0,0 +1,6 @@
+export const TOOL_VERSIONS = {
+  // install range > peer range on purpose: pin latest stable for fresh installs,
+  // accept TS 5+ if the host already has it.
+  typescript: { install: "^6.0.0", peer: ">=5.0.0" },
+  "@types/node": { install: ">=20" },
+} as const;