trae-coding-engine 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @trae/coding-engine
+
+> Install the Trae AI-Coding best-practice guardrails (AGENTS.md, Skill Router, 31 check scripts, 15 SKILL.md) into any repo with a single command.
+
+## Quick start
+
+```bash
+# One-shot (no install needed)
+npx @trae/coding-engine setup
+
+# Or install globally
+npm install -g @trae/coding-engine
+coding-engine setup
+```
+
+This will assemble the following into your project:
+
+| Destination | Content |
+|---|---|
+| `AGENTS.md` (repo root) | Cross-tool source of truth — instructions for every AI coding agent (Trae, Cursor, Copilot, Claude Code, etc.) |
+| `Makefile` (repo root) | Pre-packaged `make` targets for all 31 check scripts |
+| `REGISTRY.md` (repo root) | Skill registry / router index |
+| `MR-Template-Default.md` (repo root) | Merge-request template |
+| `scripts/` (31 files) | Engineering check scripts (`.sh` + `.py`) — ADR, MR hygiene, skill sync, docs audit, self-maintenance, etc. |
+| `.agents/skills/coding-*/SKILL.md` (15 dirs) | Skill definitions: architecture, code-review, cve-remediation, db-schema, deploy-config, docs-audit, docs-audit-autofix, http-api, issue-autodev, merge-request, observability, refactor-insight, release-merge, runtime-adapter, testing |
+
+## Commands
+
+```bash
+coding-engine setup   [options]   # Install everything
+coding-engine update  [options]   # Alias of `setup --force`
+coding-engine list                # Show every file this package would install
+coding-engine doctor  [options]   # Diagnose an existing install (missing / drifted files)
+coding-engine --help
+coding-engine --version
+```
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--target <dir>` | Target repo root. Default: current working directory. |
+| `--scripts-dir <dir>` | Where to place shell / py scripts. Default: `<target>/scripts` |
+| `--skills-dir <dir>` | Where to place the SKILL.md tree. Default: `<target>/.agents/skills` |
+| `--force` | Overwrite existing files (a `.bak` copy is kept for anything modified) |
+| `--dry-run` | Print the plan without touching disk |
+| `--no-chmod` | Skip `chmod +x` on installed shell / py scripts |
+| `--only <group>` | Comma-separated groups to install: `agents-md,makefile,registry,mr-template,scripts,skills` |
+| `--yes` / `-y` | Skip the confirmation prompt |
+
+## Examples
+
+```bash
+# Install everything into the current repo
+coding-engine setup
+
+# Preview without writing
+coding-engine setup --dry-run
+
+# Install only AGENTS.md and scripts
+coding-engine setup --only agents-md,scripts
+
+# Force-update everything (existing files get .bak backups)
+coding-engine update
+
+# Check what's missing or drifted in an existing install
+coding-engine doctor --target /path/to/repo
+
+# Install into a specific repo
+coding-engine setup --target ~/projects/my-app
+```
+
+## How it works
+
+1. The npm package ships a `templates/` directory containing all 51 source files.
+2. `setup` walks `templates/` and copies each file to the corresponding destination in your repo.
+3. Root files (`AGENTS.md`, `Makefile`, `REGISTRY.md`, `MR-Template-Default.md`) go to the repo root.
+4. `scripts/*` go to `<target>/scripts/` (configurable via `--scripts-dir`).
+5. `.agents/skills/**` go to `<target>/.agents/skills/` (configurable via `--skills-dir`).
+6. `.sh` and `.py` files are `chmod +x` by default (skip with `--no-chmod`).
+7. If a file already exists with different content, it is **skipped** by default. Use `--force` to overwrite — a `.bak` copy of the original is kept.
+8. Re-running `setup` is idempotent: identical files are detected and no action is taken.
+
+## Requirements
+
+- Node.js >= 16
+- No external dependencies (zero-dependency CLI, uses only Node.js stdlib)
+
+## License
+
+Apache-2.0

package/bin/coding-engine.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// coding-engine — CLI entry
+// Zero external deps; Node >=16.
+
+'use strict';
+
+const path = require('path');
+const cli = require(path.join(__dirname, '..', 'lib', 'cli.js'));
+
+cli.run(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`\n[coding-engine] error: ${err && err.message ? err.message : err}\n`);
+  if (process.env.CODING_ENGINE_DEBUG) {
+    process.stderr.write(String(err && err.stack) + '\n');
+  }
+  process.exit(1);
+});

package/lib/cli.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const setup = require('./setup');
+
+const HELP = `
+coding-engine — Trae AI-Coding best-practice installer
+
+Usage:
+  coding-engine setup   [options]   Install AGENTS.md + scripts/ + .agents/skills/ into target repo
+  coding-engine update  [options]   Alias of \`setup --force\` (overwrite bundled assets, keep local edits backed up)
+  coding-engine list                Show every file this package would install
+  coding-engine doctor  [--target] Diagnose an existing install (missing / drifted files)
+  coding-engine --help              Print this help
+  coding-engine --version           Print installed package version
+
+setup / update options:
+  --target <dir>       Target repo root. Default: current working directory.
+  --scripts-dir <dir>  Where to place shell / py scripts. Default: <target>/scripts
+  --skills-dir <dir>   Where to place SKILL.md tree. Default: <target>/.agents/skills
+  --force              Overwrite existing files (a .bak copy is kept for anything modified)
+  --dry-run            Print the plan without touching disk
+  --no-chmod           Skip \`chmod +x\` on installed shell/py scripts
+  --only <group>       Comma-separated groups to install: agents-md, makefile, registry,
+                       mr-template, scripts, skills   (default: all)
+  --yes / -y           Skip the confirmation prompt
+`;
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { args.flags.help = true; continue; }
+    if (a === '--version' || a === '-v') { args.flags.version = true; continue; }
+    if (a === '--force') { args.flags.force = true; continue; }
+    if (a === '--dry-run') { args.flags.dryRun = true; continue; }
+    if (a === '--no-chmod') { args.flags.noChmod = true; continue; }
+    if (a === '--yes' || a === '-y') { args.flags.yes = true; continue; }
+    if (a === '--target') { args.flags.target = argv[++i]; continue; }
+    if (a === '--scripts-dir') { args.flags.scriptsDir = argv[++i]; continue; }
+    if (a === '--skills-dir') { args.flags.skillsDir = argv[++i]; continue; }
+    if (a === '--only') { args.flags.only = argv[++i]; continue; }
+    if (a.startsWith('--')) { throw new Error(`unknown flag: ${a}`); }
+    args._.push(a);
+  }
+  return args;
+}
+
+function pkgVersion() {
+  try {
+    const p = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+    return p.version;
+  } catch (_) { return 'unknown'; }
+}
+
+async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (args.flags.version && !args._[0]) {
+    process.stdout.write(pkgVersion() + '\n');
+    return;
+  }
+  if (args.flags.help || !args._[0]) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const cmd = args._[0];
+  switch (cmd) {
+    case 'setup':
+      return setup.run({ ...args.flags });
+    case 'update':
+      return setup.run({ ...args.flags, force: true });
+    case 'list':
+      return setup.list();
+    case 'doctor':
+      return setup.doctor({ ...args.flags });
+    case 'help':
+      process.stdout.write(HELP); return;
+    default:
+      throw new Error(`unknown command: ${cmd}. Run \`coding-engine --help\`.`);
+  }
+}
+
+module.exports = { run };

package/lib/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+// Public API
+const cli = require('./cli');
+
+module.exports = { run: cli.run };

package/lib/setup.js

@@ -0,0 +1,290 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+// Groups for --only filter
+const GROUPS = ['agents-md', 'makefile', 'registry', 'mr-template', 'scripts', 'skills'];
+
+// Map template-relative path → group
+function groupOf(relPath) {
+  const top = relPath.split(path.sep)[0];
+  if (relPath === 'AGENTS.md') return 'agents-md';
+  if (relPath === 'Makefile') return 'makefile';
+  if (relPath === 'REGISTRY.md') return 'registry';
+  if (relPath === 'MR-Template-Default.md') return 'mr-template';
+  if (top === 'scripts') return 'scripts';
+  if (relPath.startsWith('.agents' + path.sep)) return 'skills';
+  return 'other';
+}
+
+// Walk a directory recursively, return array of absolute file paths
+function walkDir(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkDir(full));
+    } else if (entry.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Resolve destination path for a template file
+function resolveDest(relPath, target, scriptsDir, skillsDir) {
+  const parts = relPath.split(path.sep);
+
+  // .agents/skills/... → skillsDir/...
+  if (parts[0] === '.agents' && parts[1] === 'skills') {
+    const rest = parts.slice(2).join(path.sep); // <skill-name>/SKILL.md
+    return path.join(skillsDir, rest);
+  }
+
+  // scripts/... → scriptsDir/...
+  if (parts[0] === 'scripts') {
+    return path.join(scriptsDir, parts.slice(1).join(path.sep));
+  }
+
+  // root files → target/
+  return path.join(target, relPath);
+}
+
+// Get list of { src, dest, rel, group } for all bundled files
+function getManifest(target, scriptsDir, skillsDir) {
+  const files = walkDir(TEMPLATES_DIR);
+  const manifest = [];
+  for (const src of files) {
+    const rel = path.relative(TEMPLATES_DIR, src);
+    const dest = resolveDest(rel, target, scriptsDir, skillsDir);
+    manifest.push({ src, dest, rel, group: groupOf(rel) });
+  }
+  // Sort: root files first, then scripts, then skills — predictable order
+  manifest.sort((a, b) => {
+    const order = { 'agents-md': 0, 'makefile': 1, 'registry': 2, 'mr-template': 3, 'scripts': 4, 'skills': 5, 'other': 6 };
+    return (order[a.group] || 6) - (order[b.group] || 6) || a.rel.localeCompare(b.rel);
+  });
+  return manifest;
+}
+
+function parseOnly(flag) {
+  if (!flag) return null;
+  const list = flag.split(',').map(s => s.trim()).filter(Boolean);
+  for (const g of list) {
+    if (!GROUPS.includes(g)) {
+      throw new Error(`unknown group "${g}". Valid groups: ${GROUPS.join(', ')}`);
+    }
+  }
+  return new Set(list);
+}
+
+function ensureDir(filePath) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest) {
+  ensureDir(dest);
+  fs.copyFileSync(src, dest);
+}
+
+function filesIdentical(a, b) {
+  try {
+    const ba = fs.readFileSync(a);
+    const bb = fs.readFileSync(b);
+    if (ba.length !== bb.length) return false;
+    return ba.equals(bb);
+  } catch {
+    return false;
+  }
+}
+
+function isExecutable(rel) {
+  return rel.endsWith('.sh') || rel.endsWith('.py');
+}
+
+// ─── run() ──────────────────────────────────────────────────────────────────
+
+function run(flags) {
+  const target = path.resolve(flags.target || process.cwd());
+  const scriptsDir = path.resolve(target, flags.scriptsDir || 'scripts');
+  const skillsDir = path.resolve(target, flags.skillsDir || path.join('.agents', 'skills'));
+  const onlySet = parseOnly(flags.only);
+  const dryRun = !!flags.dryRun;
+  const force = !!flags.force;
+  const noChmod = !!flags.noChmod;
+
+  const manifest = getManifest(target, scriptsDir, skillsDir);
+  const filtered = onlySet ? manifest.filter(m => onlySet.has(m.group)) : manifest;
+
+  if (filtered.length === 0) {
+    process.stdout.write('\nNo files match the selected groups.\n\n');
+    return;
+  }
+
+  // Plan
+  const plan = [];
+  for (const item of filtered) {
+    const destExists = fs.existsSync(item.dest);
+    let action;
+    if (!destExists) {
+      action = 'create';
+    } else if (force) {
+      action = filesIdentical(item.src, item.dest) ? 'same' : 'overwrite';
+    } else {
+      action = filesIdentical(item.src, item.dest) ? 'same' : 'skip';
+    }
+    plan.push({ ...item, action });
+  }
+
+  // Print plan
+  process.stdout.write('\n');
+  process.stdout.write(`  Target:       ${target}\n`);
+  process.stdout.write(`  Scripts dir:  ${scriptsDir}\n`);
+  process.stdout.write(`  Skills dir:   ${skillsDir}\n`);
+  process.stdout.write(`  Mode:         ${dryRun ? 'DRY RUN' : force ? 'FORCE (overwrite with .bak)' : 'safe (skip existing)'}\n`);
+  if (onlySet) process.stdout.write(`  Only:         ${[...onlySet].join(', ')}\n`);
+  process.stdout.write(`  Files:        ${filtered.length}\n\n`);
+
+  let created = 0, overwritten = 0, skipped = 0, same = 0, backedUp = 0;
+
+  for (const p of plan) {
+    let symbol;
+    switch (p.action) {
+      case 'create':    symbol = '+'; break;
+      case 'overwrite': symbol = '~'; break;
+      case 'skip':      symbol = '!'; break;
+      case 'same':      symbol = '='; break;
+      default:          symbol = '?';
+    }
+    process.stdout.write(`  ${symbol}  ${p.rel}\n`);
+
+    if (dryRun) continue;
+
+    if (p.action === 'create') {
+      copyFile(p.src, p.dest);
+      if (isExecutable(p.rel) && !noChmod) {
+        fs.chmodSync(p.dest, 0o755);
+      }
+      created++;
+    } else if (p.action === 'overwrite') {
+      // backup
+      const bak = p.dest + '.bak';
+      if (fs.existsSync(bak)) fs.unlinkSync(bak);
+      fs.copyFileSync(p.dest, bak);
+      copyFile(p.src, p.dest);
+      if (isExecutable(p.rel) && !noChmod) {
+        fs.chmodSync(p.dest, 0o755);
+      }
+      overwritten++;
+      backedUp++;
+    } else if (p.action === 'same') {
+      same++;
+    } else {
+      skipped++;
+    }
+  }
+
+  process.stdout.write('\n');
+
+  if (dryRun) {
+    process.stdout.write('  (dry run — no files were changed)\n\n');
+    return;
+  }
+
+  process.stdout.write('  Summary:\n');
+  process.stdout.write(`    created:      ${created}\n`);
+  process.stdout.write(`    overwritten:  ${overwritten} (backups: ${backedUp})\n`);
+  process.stdout.write(`    skipped:      ${skipped}\n`);
+  process.stdout.write(`    unchanged:    ${same}\n\n`);
+
+  if (skipped > 0) {
+    process.stdout.write('  ⚠ Some files were skipped because they already exist with different content.\n');
+    process.stdout.write('    Run with --force to overwrite (a .bak copy will be kept for each modified file).\n\n');
+  }
+
+  if (created > 0 || overwritten > 0) {
+    process.stdout.write('  ✅ Coding-Engine guardrails installed successfully.\n');
+    process.stdout.write('     Next steps:\n');
+    process.stdout.write('       1. Review AGENTS.md at your repo root.\n');
+    process.stdout.write('       2. Run `make help` to see available check targets.\n');
+    process.stdout.write('       3. Commit the new files to your repo.\n\n');
+  }
+}
+
+// ─── list() ─────────────────────────────────────────────────────────────────
+
+function list() {
+  const manifest = walkDir(TEMPLATES_DIR).map(src => {
+    const rel = path.relative(TEMPLATES_DIR, src);
+    return { rel, group: groupOf(rel) };
+  });
+  manifest.sort((a, b) => {
+    const order = { 'agents-md': 0, 'makefile': 1, 'registry': 2, 'mr-template': 3, 'scripts': 4, 'skills': 5, 'other': 6 };
+    return (order[a.group] || 6) - (order[b.group] || 6) || a.rel.localeCompare(b.rel);
+  });
+
+  process.stdout.write('\n  Files bundled in this package:\n\n');
+
+  let currentGroup = null;
+  for (const item of manifest) {
+    if (item.group !== currentGroup) {
+      currentGroup = item.group;
+      process.stdout.write(`\n  [${item.group}]\n`);
+    }
+    process.stdout.write(`    ${item.rel}\n`);
+  }
+
+  process.stdout.write(`\n  Total: ${manifest.length} files\n\n`);
+}
+
+// ─── doctor() ───────────────────────────────────────────────────────────────
+
+function doctor(flags) {
+  const target = path.resolve(flags.target || process.cwd());
+  const scriptsDir = path.resolve(target, flags.scriptsDir || 'scripts');
+  const skillsDir = path.resolve(target, flags.skillsDir || path.join('.agents', 'skills'));
+
+  const manifest = getManifest(target, scriptsDir, skillsDir);
+
+  process.stdout.write('\n');
+  process.stdout.write(`  Target:       ${target}\n`);
+  process.stdout.write(`  Scripts dir:  ${scriptsDir}\n`);
+  process.stdout.write(`  Skills dir:   ${skillsDir}\n\n`);
+
+  let present = 0, missing = 0, drifted = 0;
+
+  for (const item of manifest) {
+    if (!fs.existsSync(item.dest)) {
+      process.stdout.write(`  ✗ MISSING   ${item.rel}\n`);
+      missing++;
+      continue;
+    }
+    if (!filesIdentical(item.src, item.dest)) {
+      process.stdout.write(`  ~ DRIFTED   ${item.rel}\n`);
+      drifted++;
+    } else {
+      process.stdout.write(`  ✓ OK        ${item.rel}\n`);
+      present++;
+    }
+  }
+
+  process.stdout.write('\n');
+  process.stdout.write('  Summary:\n');
+  process.stdout.write(`    OK:        ${present}\n`);
+  process.stdout.write(`    Missing:   ${missing}\n`);
+  process.stdout.write(`    Drifted:   ${drifted}\n\n`);
+
+  if (missing > 0 || drifted > 0) {
+    process.stdout.write('  ⚠ Some files are missing or have drifted from the bundled version.\n');
+    process.stdout.write('    Run `coding-engine update` to restore them (existing modifications get .bak backups).\n\n');
+  } else {
+    process.stdout.write('  ✅ All files are present and up to date.\n\n');
+  }
+}
+
+module.exports = { run, list, doctor };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "trae-coding-engine",
+  "version": "0.1.0",
+  "description": "Install the Trae Coding-Engine AI-Agent guardrails (AGENTS.md, Skill Router, 31 check scripts, 15 SKILL.md) into any repo with a single command.",
+  "keywords": [
+    "trae",
+    "ai-coding",
+    "agents",
+    "agents-md",
+    "skill-router",
+    "gitlab",
+    "codereview"
+  ],
+  "license": "Apache-2.0",
+  "bin": {
+    "coding-engine": "bin/coding-engine.js",
+    "trae-coding-engine": "bin/coding-engine.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "test": "node test/smoke.js"
+  }
+}