@tyyyho/treg 0.1.2

package/scripts/init-project/index.mjs

@@ -0,0 +1,89 @@
+import { existsSync } from "node:fs"
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import {
+  parseArgs,
+  printSupportedTargets,
+  resolveFeatures,
+  USAGE,
+} from "./cli.mjs"
+import { resolveFramework } from "./frameworks/index.mjs"
+import { runFeatureRules } from "./mrm-rules/index.mjs"
+import { detectPackageManager, runScript } from "./package-manager.mjs"
+import { formatStep } from "./utils.mjs"
+
+const TOTAL_STEPS = 3
+
+export async function main(argv = process.argv.slice(2)) {
+  let options
+  try {
+    options = parseArgs(argv)
+  } catch (error) {
+    console.error(error.message ?? error)
+    console.log(USAGE)
+    process.exitCode = 1
+    return
+  }
+
+  if (options.help) {
+    console.log(USAGE)
+    return
+  }
+  if (options.command === "list") {
+    printSupportedTargets()
+    return
+  }
+
+  const projectDir = path.resolve(options.projectDir ?? process.cwd())
+  const packageJsonPath = path.join(projectDir, "package.json")
+  if (!existsSync(packageJsonPath)) {
+    console.error(`package.json not found in ${projectDir}`)
+    process.exitCode = 1
+    return
+  }
+
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"))
+  const pm =
+    !options.pm || options.pm === "auto"
+      ? detectPackageManager(projectDir)
+      : options.pm
+  const framework = resolveFramework(
+    options.framework,
+    options.frameworkVersion,
+    packageJson
+  )
+  if (options.frameworkVersion && framework.id !== "react") {
+    console.error(
+      `Unsupported --framework-version for framework: ${framework.id}`
+    )
+    process.exitCode = 1
+    return
+  }
+  const enabledFeatures = resolveFeatures(options)
+
+  const context = {
+    ...options,
+    projectDir,
+    pm,
+    framework,
+    enabledFeatures,
+  }
+
+  console.log(formatStep(1, TOTAL_STEPS, "Resolve plan", options.dryRun))
+  console.log(
+    `${options.dryRun ? "[dry-run] " : ""}Framework=${framework.id}${framework.variant ? `/${framework.variant}` : ""}, features=${Object.entries(
+      enabledFeatures
+    )
+      .filter(([, enabled]) => enabled)
+      .map(([name]) => name)
+      .join(", ")}, testRunner=${options.testRunner}`
+  )
+
+  console.log(formatStep(2, TOTAL_STEPS, "Run mrm rules", options.dryRun))
+  await runFeatureRules(context)
+
+  console.log(formatStep(3, TOTAL_STEPS, "Finalize", options.dryRun))
+  if (enabledFeatures.format) {
+    runScript(pm, "format", projectDir, options.dryRun)
+  }
+}

package/scripts/init-project/mrm-core.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module"
+
+const require = createRequire(import.meta.url)
+
+export const { file, json, lines, packageJson, install } = require("mrm-core")

package/scripts/init-project/mrm-rules/ai-skills.mjs

@@ -0,0 +1,220 @@
+import { existsSync } from "node:fs"
+import { promises as fs } from "node:fs"
+import path from "node:path"
+
+const START_MARKER = "<!-- treg:skills:start -->"
+const END_MARKER = "<!-- treg:skills:end -->"
+const SKILLS_BASE_DIR = ".treg/skills"
+
+const FEATURE_SKILLS = {
+  format: {
+    name: "treg/format",
+    description: "Run and verify formatting rules.",
+    when: "在提交前或大範圍改動後，統一格式化程式碼。",
+    checklist: ["執行 format", "執行 format:check", "確認未變動非目標檔案"],
+  },
+  husky: {
+    name: "treg/husky",
+    description: "Verify and maintain git hook automation.",
+    when: "需要保證 pre-commit / pre-push 自動檢查時。",
+    checklist: [
+      "確認 hooks 可執行",
+      "確認含 format:check 與 lint:check",
+      "若啟用型別/測試，也要納入 hooks",
+    ],
+  },
+  lint: {
+    name: "treg/lint",
+    description: "Run and validate lint rules.",
+    when: "新增規則或調整工具鏈後，驗證 lint 一致性。",
+    checklist: ["執行 lint", "執行 lint:check", "修正 max-warnings 問題"],
+  },
+  test: {
+    name: "treg/test",
+    description: "Validate test runner setup and execution.",
+    when: "新增測試規則或調整測試設定時。",
+    checklist: [
+      "確認 test runner 與專案一致",
+      "執行 test",
+      "視需要執行 test:coverage",
+    ],
+  },
+  typescript: {
+    name: "treg/typescript",
+    description: "Validate TypeScript strictness and config.",
+    when: "調整 tsconfig 或型別嚴格度規則時。",
+    checklist: [
+      "執行 type-check",
+      "確認 strict 相關選項仍生效",
+      "檢查 exclude 不含產品邏輯路徑",
+    ],
+  },
+}
+
+function resolveSkillsDoc(projectDir) {
+  const agentsPath = path.join(projectDir, "AGENTS.md")
+  if (existsSync(agentsPath)) {
+    return agentsPath
+  }
+
+  const claudePath = path.join(projectDir, "CLAUDE.md")
+  if (existsSync(claudePath)) {
+    return claudePath
+  }
+
+  return null
+}
+
+function getEnabledFeatures(enabledFeatures) {
+  return Object.entries(enabledFeatures)
+    .filter(([, value]) => value)
+    .map(([name]) => name)
+    .sort((a, b) => a.localeCompare(b))
+}
+
+function getSkillRelativePath(feature) {
+  return `${SKILLS_BASE_DIR}/${feature}/SKILL.md`
+}
+
+function buildSkillFile(feature, skill, testRunner) {
+  const extra =
+    feature === "test"
+      ? `\n## Current Test Runner\n\n- \`${testRunner}\`\n`
+      : ""
+  return `---
+name: ${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name}
+
+## When To Use
+
+${skill.when}
+
+## Validation Checklist
+
+- ${skill.checklist.join("\n- ")}
+${extra}`
+}
+
+async function ensureSkillFiles(projectDir, enabled, testRunner, dryRun) {
+  for (const feature of enabled) {
+    const skill = FEATURE_SKILLS[feature]
+    if (!skill) continue
+
+    const relativePath = getSkillRelativePath(feature)
+    const fullPath = path.join(projectDir, relativePath)
+    const content = buildSkillFile(feature, skill, testRunner)
+
+    if (dryRun) {
+      console.log(`[dry-run] Would upsert ${relativePath}`)
+      continue
+    }
+
+    await fs.mkdir(path.dirname(fullPath), { recursive: true })
+    const current = existsSync(fullPath)
+      ? await fs.readFile(fullPath, "utf8")
+      : null
+    if (current === content) {
+      continue
+    }
+    await fs.writeFile(fullPath, content, "utf8")
+    console.log(`${current === null ? "Created" : "Updated"} ${relativePath}`)
+  }
+}
+
+function buildSkillSection(context) {
+  const { enabledFeatures, testRunner } = context
+  const enabled = getEnabledFeatures(enabledFeatures)
+
+  const lines = [
+    START_MARKER,
+    "## treg AI Skills",
+    "",
+    "以下 skill 可在 agent 任務完成前引用，確保基礎建設規則正確且可重跑：",
+    "",
+  ]
+
+  for (const feature of enabled) {
+    const skill = FEATURE_SKILLS[feature]
+    if (!skill) continue
+    const skillRelativePath = getSkillRelativePath(feature)
+
+    lines.push(`### ${feature}`)
+    lines.push(`- Skill: [${skill.name}](${skillRelativePath})`)
+    lines.push(`- 使用時機: ${skill.when}`)
+    if (feature === "test") {
+      lines.push(`- 目前測試工具: \`${testRunner}\``)
+    }
+    lines.push(`- 驗證清單: ${skill.checklist.join("、")}`)
+    lines.push("")
+  }
+
+  lines.push(END_MARKER)
+  lines.push("")
+  return lines.join("\n")
+}
+
+function upsertSkillSection(content, nextSection) {
+  const start = content.indexOf(START_MARKER)
+  const end = content.indexOf(END_MARKER)
+
+  if (start !== -1 && end !== -1 && end > start) {
+    const suffixStart = end + END_MARKER.length
+    const before = content.slice(0, start).trimEnd()
+    const after = content.slice(suffixStart).trimStart()
+    const rebuilt = `${before}\n\n${nextSection.trim()}\n`
+    return after ? `${rebuilt}\n${after}\n` : `${rebuilt}`
+  }
+
+  if (!content.trim()) {
+    return `${nextSection.trim()}\n`
+  }
+
+  return `${content.trimEnd()}\n\n${nextSection.trim()}\n`
+}
+
+export async function runAiSkillsRule(context) {
+  const { projectDir, dryRun } = context
+  const targetFile = resolveSkillsDoc(projectDir)
+
+  if (!targetFile) {
+    console.log("Skip ai-skills (AGENTS.md/CLAUDE.md not found)")
+    return
+  }
+
+  const enabled = getEnabledFeatures(context.enabledFeatures)
+  await ensureSkillFiles(projectDir, enabled, context.testRunner, dryRun)
+
+  const section = buildSkillSection(context)
+  const current = await fs.readFile(targetFile, "utf8")
+  const updated = upsertSkillSection(current, section)
+
+  if (dryRun) {
+    console.log(
+      `[dry-run] Would update ${path.basename(targetFile)} with AI skill guidance`
+    )
+    return
+  }
+
+  if (updated !== current) {
+    await fs.writeFile(targetFile, updated, "utf8")
+    console.log(`Updated ${path.basename(targetFile)} with AI skill guidance`)
+    return
+  }
+
+  console.log(
+    `${path.basename(targetFile)} already contains latest AI skill guidance`
+  )
+}
+
+export const __testables__ = {
+  buildSkillSection,
+  buildSkillFile,
+  ensureSkillFiles,
+  getEnabledFeatures,
+  getSkillRelativePath,
+  resolveSkillsDoc,
+  upsertSkillSection,
+}

package/scripts/init-project/mrm-rules/ai-skills.test.mjs

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "@jest/globals"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { __testables__ } from "./ai-skills.mjs"
+
+describe("ai-skills helpers", () => {
+  it("builds skill section from enabled features", () => {
+    const content = __testables__.buildSkillSection({
+      enabledFeatures: {
+        lint: true,
+        format: true,
+        typescript: false,
+        test: true,
+        husky: false,
+      },
+      testRunner: "vitest",
+    })
+
+    expect(content).toContain("## treg AI Skills")
+    expect(content).toContain("### format")
+    expect(content).toContain("### lint")
+    expect(content).toContain("### test")
+    expect(content).toContain("目前測試工具: `vitest`")
+    expect(content).not.toContain("### typescript")
+  })
+
+  it("upserts an existing skill section", () => {
+    const replaced = __testables__.upsertSkillSection(
+      "# Header\n\n<!-- treg:skills:start -->\nold\n<!-- treg:skills:end -->\n",
+      "<!-- treg:skills:start -->\nnew\n<!-- treg:skills:end -->"
+    )
+
+    expect(replaced).toContain("new")
+    expect(replaced).not.toContain("old")
+  })
+
+  it("prefers AGENTS.md when both docs exist", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "treg-skill-"))
+    try {
+      writeFileSync(path.join(dir, "AGENTS.md"), "# Agents\n", "utf8")
+      writeFileSync(path.join(dir, "CLAUDE.md"), "# Claude\n", "utf8")
+
+      expect(__testables__.resolveSkillsDoc(dir)).toBe(
+        path.join(dir, "AGENTS.md")
+      )
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it("builds skill file content with frontmatter", () => {
+    const content = __testables__.buildSkillFile(
+      "test",
+      {
+        name: "treg/test",
+        description: "Validate test runner setup and execution.",
+        when: "新增測試規則或調整測試設定時。",
+        checklist: ["確認 test runner 與專案一致", "執行 test"],
+      },
+      "vitest"
+    )
+
+    expect(content).toContain("name: treg/test")
+    expect(content).toContain("description: Validate test runner setup")
+    expect(content).toContain("## Current Test Runner")
+    expect(content).toContain("`vitest`")
+  })
+
+  it("creates skill files for enabled features", async () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "treg-skill-files-"))
+    try {
+      await __testables__.ensureSkillFiles(dir, ["lint", "test"], "jest", false)
+
+      const lintSkill = await readFile(
+        path.join(dir, ".treg/skills/lint/SKILL.md"),
+        "utf8"
+      )
+      const testSkill = await readFile(
+        path.join(dir, ".treg/skills/test/SKILL.md"),
+        "utf8"
+      )
+
+      expect(lintSkill).toContain("name: treg/lint")
+      expect(testSkill).toContain("## Current Test Runner")
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/scripts/init-project/mrm-rules/format.mjs

@@ -0,0 +1,55 @@
+import { lines, packageJson } from "../mrm-core.mjs"
+import { installPackages, withProjectCwd, writeFile } from "./shared.mjs"
+
+const PRETTIER_CONFIG = `{
+  "semi": false,
+  "trailingComma": "es5",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}
+`
+
+const PRETTIER_IGNORE = [
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  "*.log",
+  ".env*",
+  ".vercel",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+]
+
+export async function runFormatRule(context) {
+  const { projectDir, pm, force, dryRun } = context
+  installPackages(projectDir, pm, ["prettier"], true, dryRun)
+
+  await writeFile(
+    projectDir,
+    ".prettierrc.json",
+    PRETTIER_CONFIG,
+    force,
+    dryRun
+  )
+
+  withProjectCwd(projectDir, () => {
+    if (dryRun) {
+      console.log("[dry-run] Would update .prettierignore")
+      console.log("[dry-run] Would set package scripts: format, format:check")
+      return
+    }
+    lines(".prettierignore").add(PRETTIER_IGNORE).save()
+    packageJson()
+      .setScript("format", "prettier --write .")
+      .setScript("format:check", "prettier --check .")
+      .save()
+  })
+}

package/scripts/init-project/mrm-rules/husky.mjs

@@ -0,0 +1,78 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { packageJson } from "../mrm-core.mjs"
+import { existsSync } from "node:fs"
+import { getRunCommand, runCommand } from "../package-manager.mjs"
+import { installPackages, withProjectCwd, writeFile } from "./shared.mjs"
+
+function buildHookCommands(runner, enabledFeatures) {
+  const preCommit = [
+    `${runner} format:check || exit 1`,
+    `${runner} lint:check || exit 1`,
+  ]
+  if (enabledFeatures.typescript) {
+    preCommit.push(`${runner} type-check || exit 1`)
+  }
+
+  const prePush = [...preCommit]
+  if (enabledFeatures.test) {
+    prePush.push(`${runner} test || exit 1`)
+  }
+
+  return { preCommit, prePush }
+}
+
+export async function runHuskyRule(context) {
+  const { projectDir, pm, force, dryRun, skipHuskyInstall, enabledFeatures } =
+    context
+
+  installPackages(projectDir, pm, ["husky"], true, dryRun)
+  const runner = getRunCommand(pm)
+  const { preCommit, prePush } = buildHookCommands(runner, enabledFeatures)
+
+  await writeFile(
+    projectDir,
+    ".husky/pre-commit",
+    `# Husky pre-commit\n${preCommit.join("\n")}\n`,
+    force,
+    dryRun
+  )
+  await writeFile(
+    projectDir,
+    ".husky/pre-push",
+    `# Husky pre-push\n${prePush.join("\n")}\n`,
+    force,
+    dryRun
+  )
+
+  if (!dryRun) {
+    await fs.chmod(path.join(projectDir, ".husky/pre-commit"), 0o755)
+    await fs.chmod(path.join(projectDir, ".husky/pre-push"), 0o755)
+  }
+
+  withProjectCwd(projectDir, () => {
+    if (dryRun) {
+      console.log("[dry-run] Would set package script: prepare")
+      return
+    }
+    packageJson().setScript("prepare", "husky").save()
+  })
+
+  if (skipHuskyInstall) {
+    console.log("Skip husky install (--skip-husky-install)")
+    return
+  }
+  if (!existsSync(path.join(projectDir, ".git"))) {
+    console.log("Skip husky install (.git not found)")
+    return
+  }
+  if (!dryRun) {
+    if (pm === "pnpm") {
+      runCommand("pnpm exec husky", projectDir, false)
+    } else if (pm === "yarn") {
+      runCommand("yarn husky", projectDir, false)
+    } else {
+      runCommand("npx husky", projectDir, false)
+    }
+  }
+}

package/scripts/init-project/mrm-rules/index.mjs

@@ -0,0 +1,35 @@
+import { runAiSkillsRule } from "./ai-skills.mjs"
+import { runFormatRule } from "./format.mjs"
+import { runHuskyRule } from "./husky.mjs"
+import { runLintRule } from "./lint.mjs"
+import { runTestJestRule } from "./test-jest.mjs"
+import { runTestVitestRule } from "./test-vitest.mjs"
+import { runTypescriptRule } from "./typescript.mjs"
+
+export async function runFeatureRules(context) {
+  const { enabledFeatures, skills, testRunner } = context
+
+  if (enabledFeatures.format) {
+    await runFormatRule(context)
+  }
+  if (enabledFeatures.lint) {
+    await runLintRule(context)
+  }
+  if (enabledFeatures.typescript) {
+    await runTypescriptRule(context)
+  }
+  if (enabledFeatures.test) {
+    if (testRunner === "vitest") {
+      await runTestVitestRule(context)
+    } else {
+      await runTestJestRule(context)
+    }
+  }
+  if (enabledFeatures.husky) {
+    await runHuskyRule(context)
+  }
+
+  if (skills) {
+    await runAiSkillsRule(context)
+  }
+}

package/scripts/init-project/mrm-rules/lint.mjs

@@ -0,0 +1,18 @@
+import { packageJson } from "../mrm-core.mjs"
+import { installPackages, withProjectCwd } from "./shared.mjs"
+
+export async function runLintRule(context) {
+  const { projectDir, pm, dryRun } = context
+  installPackages(projectDir, pm, ["eslint"], true, dryRun)
+
+  withProjectCwd(projectDir, () => {
+    if (dryRun) {
+      console.log("[dry-run] Would set package scripts: lint, lint:check")
+      return
+    }
+    packageJson()
+      .setScript("lint", "eslint .")
+      .setScript("lint:check", "eslint . --max-warnings 0")
+      .save()
+  })
+}

package/scripts/init-project/mrm-rules/shared.mjs

@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import { installPackages as installByPackageManager } from "../package-manager.mjs"
+
+export function withProjectCwd(projectDir, fn) {
+  const original = process.cwd()
+  process.chdir(projectDir)
+  try {
+    return fn()
+  } finally {
+    process.chdir(original)
+  }
+}
+
+export function getInstallOptions(pm) {
+  if (pm === "pnpm") return { pnpm: true }
+  if (pm === "yarn") return { yarn: true }
+  return {}
+}
+
+export function installPackages(
+  projectDir,
+  pm,
+  packages,
+  dev = true,
+  dryRun = false
+) {
+  if (packages.length === 0) return
+  installByPackageManager(pm, projectDir, packages, dev, dryRun)
+}
+
+export async function writeFile(
+  projectDir,
+  relativePath,
+  content,
+  force,
+  dryRun
+) {
+  const targetPath = path.join(projectDir, relativePath)
+  try {
+    await fs.access(targetPath)
+    if (!force) {
+      console.log(`Skip ${relativePath} (already exists)`)
+      return false
+    }
+  } catch {
+    // File doesn't exist.
+  }
+
+  if (dryRun) {
+    console.log(
+      `[dry-run] Would ${force ? "update" : "create"} ${relativePath}`
+    )
+    return true
+  }
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true })
+  await fs.writeFile(targetPath, content, "utf8")
+  console.log(`${force ? "Updated" : "Created"} ${relativePath}`)
+  return true
+}