@tyyyho/treg 0.1.2

package/README.md

@@ -0,0 +1,92 @@
+# @tyyyho/treg
+
+Treg is a CLI tool for initializing development conventions in existing projects.
+
+It installs and configures tools and records clear usage guidelines as skills.
+
+Treg helps both human developers and AI agents work within the same set of expectations, reducing configuration drift and long-term maintenance overhead.
+
+## Usage
+
+```bash
+pnpm dlx @tyyyho/treg init <project-dir> --framework react
+# or
+npx @tyyyho/treg init <project-dir> --framework react
+```
+
+By default, all features are applied:
+
+- `husky`
+- `typescript`
+- `lint`
+- `format`
+- `test`
+
+## Options
+
+```bash
+npx @tyyyho/treg <command> [projectDir] [options]
+
+init                                 Initialize infra rules (requires --framework)
+add                                  Add selected infra features
+list                                 List supported targets
+
+--framework <node|react|next|vue|svelte|nuxt>
+                                      Target framework
+--framework-version <major>          Optional major version hint (currently react only)
+--pm <pnpm|npm|yarn|auto>            Package manager (auto-detected by default)
+--features <lint,format,typescript,test,husky>
+                                      Features to install (all selected by default)
+--test-runner <jest|vitest>          Test runner when test feature is enabled
+--force                               Overwrite existing config files
+--dry-run                             Show planned changes without writing files
+--skip-husky-install                  Do not run husky install
+--skills                              Update AGENTS.md/CLAUDE.md with feature skill guidance
+--help                                Show help
+```
+
+## Examples
+
+Initialize a React project:
+
+```bash
+npx @tyyyho/treg init . --framework react
+```
+
+Add only lint and format:
+
+```bash
+npx @tyyyho/treg add . --features lint,format
+```
+
+Use Vitest:
+
+```bash
+npx @tyyyho/treg init . --framework node --features test --test-runner vitest
+```
+
+Set framework major version explicitly (for variant rules):
+
+```bash
+npx @tyyyho/treg init . --framework react --framework-version 18
+```
+
+Preview changes only:
+
+```bash
+npx @tyyyho/treg init . --framework react --dry-run
+```
+
+Enable AI skill guidance update:
+
+```bash
+npx @tyyyho/treg add . --features lint,format,husky --skills
+```
+
+## Publish
+
+```bash
+pnpm install
+pnpm run prepublishOnly
+npm publish --access public
+```

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tyyyho/treg",
+  "version": "0.1.2",
+  "description": "CLI tool for initializing development conventions in existing projects.",
+  "license": "MIT",
+  "bin": {
+    "treg": "./scripts/init-project.mjs"
+  },
+  "files": [
+    "scripts/init-project.mjs",
+    "scripts/init-project"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "lint:check": "eslint . --max-warnings 0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "type-check": "tsc --noEmit",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm format:check && pnpm lint:check && pnpm type-check && pnpm test"
+  },
+  "dependencies": {
+    "mrm-core": "^7.1.22"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "eslint": "^9",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "prettier": "^3.8.0",
+    "typescript": "^5"
+  }
+}

package/scripts/init-project/cli.mjs

@@ -0,0 +1,173 @@
+const ALLOWED_COMMANDS = ["init", "add", "list"]
+const ALLOWED_PACKAGE_MANAGERS = ["pnpm", "npm", "yarn", "auto"]
+const ALLOWED_FRAMEWORKS = ["node", "react", "next", "vue", "svelte", "nuxt"]
+const ALLOWED_FEATURES = ["lint", "format", "typescript", "test", "husky"]
+const ALLOWED_TEST_RUNNERS = ["jest", "vitest"]
+
+export const USAGE = `Usage: treg <command> [projectDir] [options]
+
+Commands:
+  init                                Initialize infra rules in a project (requires --framework)
+  add                                 Add selected infra features to an existing project
+  list                                List supported frameworks, features, and test runners
+
+Options:
+  --framework <node|react|next|vue|svelte|nuxt>
+                                      Target framework
+  --framework-version <major>         Optional framework major version hint
+  --features <lint,format,typescript,test,husky>
+                                      Features to install (all selected by default)
+  --test-runner <jest|vitest>         Test runner when test feature is enabled
+  --pm <pnpm|npm|yarn|auto>           Package manager (auto-detected if omitted)
+  --force                             Overwrite existing config files
+  --dry-run                           Print planned changes without writing files
+  --skip-husky-install                Do not run husky install
+  --skills                            Update AGENTS.md/CLAUDE.md with feature skill guidance
+  -h, --help                          Show help
+`
+
+export function parseArgs(argv) {
+  const options = {
+    command: "init",
+    projectDir: null,
+    framework: null,
+    frameworkVersion: null,
+    features: [],
+    testRunner: "jest",
+    pm: null,
+    force: false,
+    dryRun: false,
+    skipHuskyInstall: false,
+    skills: false,
+    help: false,
+  }
+
+  let cursor = 0
+  const firstArg = argv[0]
+  if (firstArg && ALLOWED_COMMANDS.includes(firstArg)) {
+    options.command = firstArg
+    cursor = 1
+  }
+
+  for (let i = cursor; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === "-h" || arg === "--help") {
+      options.help = true
+    } else if (arg === "--framework") {
+      options.framework = argv[i + 1]
+      i += 1
+    } else if (arg.startsWith("--framework=")) {
+      options.framework = arg.split("=")[1]
+    } else if (arg === "--framework-version") {
+      options.frameworkVersion = argv[i + 1]
+      i += 1
+    } else if (arg.startsWith("--framework-version=")) {
+      options.frameworkVersion = arg.split("=")[1]
+    } else if (arg === "--features") {
+      options.features.push(...parseCsvValue(argv[i + 1], "--features"))
+      i += 1
+    } else if (arg.startsWith("--features=")) {
+      options.features.push(...parseCsvValue(arg.split("=")[1], "--features"))
+    } else if (arg === "--test-runner") {
+      options.testRunner = argv[i + 1]
+      i += 1
+    } else if (arg.startsWith("--test-runner=")) {
+      options.testRunner = arg.split("=")[1]
+    } else if (arg === "--pm") {
+      options.pm = argv[i + 1]
+      i += 1
+    } else if (arg.startsWith("--pm=")) {
+      options.pm = arg.split("=")[1]
+    } else if (arg === "--force") {
+      options.force = true
+    } else if (arg === "--dry-run") {
+      options.dryRun = true
+    } else if (arg === "--skip-husky-install") {
+      options.skipHuskyInstall = true
+    } else if (arg === "--skills") {
+      options.skills = true
+    } else if (!arg.startsWith("-") && !options.projectDir) {
+      options.projectDir = arg
+    } else {
+      throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  validateParsedOptions(options)
+  return options
+}
+
+function parseCsvValue(rawValue, flagName) {
+  if (!rawValue) {
+    throw new Error(`Missing value for ${flagName}`)
+  }
+
+  return rawValue
+    .split(",")
+    .map(item => item.trim())
+    .filter(Boolean)
+}
+
+function validateParsedOptions(options) {
+  if (!ALLOWED_COMMANDS.includes(options.command)) {
+    throw new Error(`Unsupported command: ${options.command}`)
+  }
+
+  if (options.pm && !ALLOWED_PACKAGE_MANAGERS.includes(options.pm)) {
+    throw new Error(`Unsupported package manager: ${options.pm}`)
+  }
+
+  if (options.framework && !ALLOWED_FRAMEWORKS.includes(options.framework)) {
+    throw new Error(`Unsupported framework: ${options.framework}`)
+  }
+
+  if (options.frameworkVersion && !/^\d+$/.test(options.frameworkVersion)) {
+    throw new Error(
+      "Invalid --framework-version: major version must be numeric"
+    )
+  }
+
+  if (
+    options.frameworkVersion &&
+    options.framework &&
+    options.framework !== "react"
+  ) {
+    throw new Error(
+      `Unsupported --framework-version for framework: ${options.framework}`
+    )
+  }
+
+  if (!ALLOWED_TEST_RUNNERS.includes(options.testRunner)) {
+    throw new Error(`Unsupported test runner: ${options.testRunner}`)
+  }
+
+  for (const feature of options.features) {
+    if (!ALLOWED_FEATURES.includes(feature)) {
+      throw new Error(`Unsupported feature in --features: ${feature}`)
+    }
+  }
+
+  if (options.command === "init" && !options.help && !options.framework) {
+    throw new Error("Missing required option: --framework")
+  }
+}
+
+export function resolveFeatures(options) {
+  const selected = new Set(
+    options.features.length > 0 ? options.features : ALLOWED_FEATURES
+  )
+
+  return {
+    lint: selected.has("lint"),
+    format: selected.has("format"),
+    typescript: selected.has("typescript"),
+    test: selected.has("test"),
+    husky: selected.has("husky"),
+  }
+}
+
+export function printSupportedTargets() {
+  console.log("Frameworks: node, react, next, vue, svelte, nuxt")
+  console.log("Features: lint, format, typescript, test, husky")
+  console.log("Test runners: jest, vitest")
+}

package/scripts/init-project/cli.test.mjs

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "@jest/globals"
+import { parseArgs, resolveFeatures } from "./cli.mjs"
+
+describe("parseArgs", () => {
+  it("parses init command options", () => {
+    const parsed = parseArgs([
+      "init",
+      "demo-app",
+      "--framework",
+      "react",
+      "--features",
+      "lint,test",
+      "--test-runner",
+      "vitest",
+      "--pm=npm",
+      "--force",
+      "--dry-run",
+      "--skip-husky-install",
+    ])
+
+    expect(parsed).toEqual({
+      command: "init",
+      projectDir: "demo-app",
+      framework: "react",
+      frameworkVersion: null,
+      features: ["lint", "test"],
+      testRunner: "vitest",
+      pm: "npm",
+      force: true,
+      dryRun: true,
+      skipHuskyInstall: true,
+      skills: false,
+      help: false,
+    })
+  })
+
+  it("parses list command", () => {
+    const parsed = parseArgs(["list"])
+    expect(parsed.command).toBe("list")
+  })
+
+  it("accepts additional frameworks", () => {
+    const parsed = parseArgs(["init", "--framework", "nuxt"])
+    expect(parsed.framework).toBe("nuxt")
+  })
+
+  it("parses skills flag", () => {
+    const parsed = parseArgs(["add", "--skills"])
+    expect(parsed.skills).toBe(true)
+  })
+
+  it("accepts svelte framework", () => {
+    const parsed = parseArgs(["init", "--framework", "svelte"])
+    expect(parsed.framework).toBe("svelte")
+  })
+
+  it("throws when init is missing framework", () => {
+    expect(() => parseArgs(["init"])).toThrow(
+      "Missing required option: --framework"
+    )
+  })
+
+  it("throws for unsupported framework", () => {
+    expect(() => parseArgs(["init", "--framework", "angular"])).toThrow(
+      "Unsupported framework: angular"
+    )
+  })
+
+  it("throws for unsupported feature", () => {
+    expect(() =>
+      parseArgs(["init", "--framework", "node", "--features", "husky,ai"])
+    ).toThrow("Unsupported feature in --features: ai")
+  })
+
+  it("throws for non-numeric framework version", () => {
+    expect(() =>
+      parseArgs([
+        "init",
+        "--framework",
+        "react",
+        "--framework-version",
+        "latest",
+      ])
+    ).toThrow("Invalid --framework-version: major version must be numeric")
+  })
+
+  it("throws when non-react uses framework version", () => {
+    expect(() =>
+      parseArgs(["init", "--framework", "vue", "--framework-version", "3"])
+    ).toThrow("Unsupported --framework-version for framework: vue")
+  })
+})
+
+describe("resolveFeatures", () => {
+  it("enables all features by default", () => {
+    expect(resolveFeatures(parseArgs(["add"]))).toEqual({
+      lint: true,
+      format: true,
+      typescript: true,
+      test: true,
+      husky: true,
+    })
+  })
+
+  it("uses selected features", () => {
+    expect(
+      resolveFeatures(parseArgs(["add", "--features", "lint,format,husky"]))
+    ).toEqual({
+      lint: true,
+      format: true,
+      typescript: false,
+      test: false,
+      husky: true,
+    })
+  })
+})

package/scripts/init-project/frameworks/index.mjs

@@ -0,0 +1,48 @@
+import { nextFramework } from "./next/index.mjs"
+import { nodeFramework } from "./node/index.mjs"
+import { nuxtFramework } from "./nuxt/index.mjs"
+import { reactFramework, resolveReactFramework } from "./react/index.mjs"
+import { svelteFramework } from "./svelte/index.mjs"
+import { vueFramework } from "./vue/index.mjs"
+
+const FRAMEWORK_REGISTRY = {
+  next: nextFramework,
+  node: nodeFramework,
+  nuxt: nuxtFramework,
+  react: reactFramework,
+  svelte: svelteFramework,
+  vue: vueFramework,
+}
+
+const FRAMEWORK_DETECT_ORDER = [
+  nuxtFramework,
+  nextFramework,
+  reactFramework,
+  vueFramework,
+  svelteFramework,
+  nodeFramework,
+]
+
+export function resolveFramework(frameworkArg, frameworkVersion, packageJson) {
+  if (frameworkArg === "react") {
+    return resolveReactFramework(packageJson, frameworkVersion)
+  }
+
+  if (frameworkArg) {
+    return FRAMEWORK_REGISTRY[frameworkArg]
+  }
+
+  const detected = detectFramework(packageJson)
+  if (detected.id === "react") {
+    return resolveReactFramework(packageJson, frameworkVersion)
+  }
+
+  return detected
+}
+
+export function detectFramework(packageJson) {
+  const matched = FRAMEWORK_DETECT_ORDER.find(framework =>
+    framework.matches(packageJson)
+  )
+  return matched ?? nodeFramework
+}

package/scripts/init-project/frameworks/next/index.mjs

@@ -0,0 +1,10 @@
+import { hasPackage } from "../../utils.mjs"
+
+export const nextFramework = {
+  id: "next",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: [".next", "dist", "coverage", "jest.config.js", "public"],
+  matches(packageJson) {
+    return hasPackage(packageJson, "next")
+  },
+}

package/scripts/init-project/frameworks/node/index.mjs

@@ -0,0 +1,8 @@
+export const nodeFramework = {
+  id: "node",
+  testEnvironment: "node",
+  tsRequiredExcludes: ["dist", "coverage"],
+  matches() {
+    return true
+  },
+}

package/scripts/init-project/frameworks/nuxt/index.mjs

@@ -0,0 +1,10 @@
+import { hasPackage } from "../../utils.mjs"
+
+export const nuxtFramework = {
+  id: "nuxt",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: [".nuxt", ".output", "dist", "coverage", "public"],
+  matches(packageJson) {
+    return hasPackage(packageJson, "nuxt")
+  },
+}

package/scripts/init-project/frameworks/react/index.mjs

@@ -0,0 +1,35 @@
+import { hasPackage } from "../../utils.mjs"
+import { reactV18Framework } from "./v18/index.mjs"
+import { reactV19Framework } from "./v19/index.mjs"
+
+export const reactFramework = {
+  id: "react",
+  variant: "v19",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: ["dist", "coverage", "jest.config.js", "public"],
+  matches(packageJson) {
+    return (
+      hasPackage(packageJson, "react") || hasPackage(packageJson, "react-dom")
+    )
+  },
+}
+
+const REACT_VARIANTS = {
+  18: reactV18Framework,
+  19: reactV19Framework,
+}
+
+export function resolveReactFramework(packageJson, frameworkVersion) {
+  if (frameworkVersion && REACT_VARIANTS[frameworkVersion]) {
+    return REACT_VARIANTS[frameworkVersion]
+  }
+
+  const detected =
+    packageJson?.dependencies?.react ?? packageJson?.devDependencies?.react
+  const major = typeof detected === "string" ? detected.match(/\d+/)?.[0] : null
+  if (major && REACT_VARIANTS[major]) {
+    return REACT_VARIANTS[major]
+  }
+
+  return reactFramework
+}

package/scripts/init-project/frameworks/react/v18/index.mjs

@@ -0,0 +1,6 @@
+export const reactV18Framework = {
+  id: "react",
+  variant: "v18",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: ["dist", "coverage", "jest.config.js", "public"],
+}

package/scripts/init-project/frameworks/react/v19/index.mjs

@@ -0,0 +1,6 @@
+export const reactV19Framework = {
+  id: "react",
+  variant: "v19",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: ["dist", "coverage", "jest.config.js", "public"],
+}

package/scripts/init-project/frameworks/svelte/index.mjs

@@ -0,0 +1,10 @@
+import { hasPackage } from "../../utils.mjs"
+
+export const svelteFramework = {
+  id: "svelte",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: ["dist", "coverage", ".svelte-kit"],
+  matches(packageJson) {
+    return hasPackage(packageJson, "svelte")
+  },
+}

package/scripts/init-project/frameworks/vue/index.mjs

@@ -0,0 +1,10 @@
+import { hasPackage } from "../../utils.mjs"
+
+export const vueFramework = {
+  id: "vue",
+  testEnvironment: "jsdom",
+  tsRequiredExcludes: ["dist", "coverage"],
+  matches(packageJson) {
+    return hasPackage(packageJson, "vue")
+  },
+}

package/scripts/init-project/frameworks.test.mjs

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "@jest/globals"
+import { detectFramework, resolveFramework } from "./frameworks/index.mjs"
+
+describe("frameworks", () => {
+  it("detects nuxt before next", () => {
+    const framework = detectFramework({
+      dependencies: { nuxt: "4.0.0", next: "15.0.0", react: "19.0.0" },
+    })
+    expect(framework.id).toBe("nuxt")
+  })
+
+  it("detects next before react", () => {
+    const framework = detectFramework({
+      dependencies: { next: "15.0.0", react: "19.0.0" },
+    })
+    expect(framework.id).toBe("next")
+  })
+
+  it("detects react from dependencies", () => {
+    const framework = detectFramework({ dependencies: { react: "19.0.0" } })
+    expect(framework.id).toBe("react")
+  })
+
+  it("detects vue from dependencies", () => {
+    expect(detectFramework({ dependencies: { vue: "3.5.0" } }).id).toBe("vue")
+  })
+
+  it("detects svelte from dependencies", () => {
+    expect(detectFramework({ dependencies: { svelte: "5.0.0" } }).id).toBe(
+      "svelte"
+    )
+  })
+
+  it("falls back to node", () => {
+    expect(detectFramework({ dependencies: {} }).id).toBe("node")
+  })
+
+  it("resolves explicit framework", () => {
+    expect(
+      resolveFramework("node", null, { dependencies: { react: "19.0.0" } }).id
+    ).toBe("node")
+  })
+
+  it("resolves explicit nuxt framework", () => {
+    expect(resolveFramework("nuxt", null, { dependencies: {} }).id).toBe("nuxt")
+  })
+
+  it("resolves react v18 from --framework-version", () => {
+    const framework = resolveFramework("react", "18", {
+      dependencies: { react: "^19.0.0" },
+    })
+    expect(framework.id).toBe("react")
+    expect(framework.variant).toBe("v18")
+  })
+
+  it("resolves detected react v19 from package version", () => {
+    const framework = resolveFramework(null, null, {
+      dependencies: { react: "^19.2.0" },
+    })
+    expect(framework.id).toBe("react")
+    expect(framework.variant).toBe("v19")
+  })
+})