roblox-guard 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roblox-guard",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Deterministic Roblox and Luau standards checks: deprecated APIs and out-of-order section headers, as an agent hook, a commit hook, or a CI step.",
   "keywords": [
     "roblox",

package/scripts/roblox-guard.mjs

@@ -5,9 +5,12 @@
  * rules have fallen out of the model's context.
  */
 
-import { readFileSync, existsSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
-import { pathToFileURL } from "node:url";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** The installed package, so `install` can read the standards it ships with. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 /** Proof that a source file is Roblox rather than another Lua dialect. */
 const ROBLOX_MARKERS =
@@ -64,10 +67,51 @@ const SKIP_REASON = {
   unreadable: "could not be read as a file",
 };
 
+/** Marks a file this tool wrote, so it may be replaced without asking. */
+export const GENERATED = "<!-- Generated from AGENTS.md. Edit that file. -->";
+
+/**
+ * Where each agent reads its instructions, the front matter that host expects above the shared
+ * body, and the directory whose presence says the host is in use here. An agent that reads
+ * plain Markdown takes no front matter; one with no marker of its own is written on request.
+ */
+export const RULE_TARGETS = [
+  {
+    path: ".cursor/rules/roblox-optimum.mdc",
+    marker: ".cursor",
+    agent: "Cursor",
+    frontMatter: `---
+description: Roblox and Luau coding standards
+globs: ["**/*.luau", "**/*.lua"]
+alwaysApply: false
+---
+`,
+  },
+  {
+    path: ".kiro/steering/roblox-optimum.md",
+    marker: ".kiro",
+    agent: "Kiro",
+    frontMatter: `---
+inclusion: fileMatch
+fileMatchPattern: ["**/*.luau", "**/*.lua"]
+---
+`,
+  },
+  { path: "rules/roblox-optimum.md", marker: "rules", agent: "a plugin rules directory", frontMatter: "" },
+  { path: ".windsurf/rules/roblox-optimum.md", marker: ".windsurf", agent: "Windsurf", frontMatter: "" },
+  { path: ".clinerules/roblox-optimum.md", marker: ".clinerules", agent: "Cline", frontMatter: "" },
+  { path: ".qoder/rules/roblox-optimum.md", marker: ".qoder", agent: "Qoder", frontMatter: "" },
+  { path: ".agents/rules/roblox-optimum.md", marker: ".agents", agent: "Antigravity", frontMatter: "" },
+  { path: ".github/copilot-instructions.md", marker: ".github", agent: "GitHub Copilot", frontMatter: "" },
+  { path: "QWEN.md", marker: null, agent: "Qwen Code", frontMatter: "" },
+];
+
 const USAGE = `roblox-guard - deterministic Roblox and Luau standards checks
 
 Usage:
   roblox-guard --check <file...>   Check files. Exit 1 when a file has findings.
+  roblox-guard install [--all]     Write the standards into this project, for every agent it
+                                   finds. --all writes every agent's file regardless.
   roblox-guard --selftest          Run the built-in assertions.
   roblox-guard                     Read a post-write hook payload on stdin. Exit 2 reports
                                    findings back to the agent.
@@ -346,6 +390,109 @@ function runCheck(paths) {
   return 0;
 }
 
+/** The commit hook, which is the one setup that works whoever wrote the file. */
+const PRE_COMMIT = `#!/bin/sh
+# Installed by roblox-guard. Delete this file to remove it.
+files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.luau?$')
+[ -z "$files" ] || npx roblox-guard --check $files
+`;
+
+/**
+ * Whether a path may be written: either it is absent, or this tool wrote what is there.
+ * Anyone else's file is left alone, because a standards tool that overwrites work silently
+ * has already cost more than it saves.
+ *
+ * @param path string -- Absolute path to consider.
+ * @param mark string -- The line this tool stamps into what it writes.
+ * @return boolean
+ */
+function writable(path, mark) {
+  if (!existsSync(path)) return true;
+  try {
+    return readFileSync(path, "utf8").includes(mark);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Writes the standards into the current project for every agent it can see, and reports the
+ * installs it cannot perform itself.
+ *
+ * @param all boolean -- Write every agent's file, not just the ones with a marker present.
+ * @return number -- Process exit code.
+ */
+function runInstall(all) {
+  const source = join(PACKAGE_ROOT, "AGENTS.md");
+  if (!existsSync(source)) {
+    process.stderr.write(`roblox-guard install: AGENTS.md is missing from the package.\n`);
+    return 2;
+  }
+
+  const body = readFileSync(source, "utf8").replace(/\r\n/g, "\n");
+  const cwd = process.cwd();
+  const written = [];
+  const kept = [];
+
+  for (const target of [{ path: "AGENTS.md", marker: null, frontMatter: "" }, ...RULE_TARGETS]) {
+    if (!all && target.marker && !existsSync(join(cwd, target.marker))) continue;
+    if (!all && target.path === "QWEN.md") continue;
+
+    const full = join(cwd, target.path);
+    if (!writable(full, GENERATED) && target.path !== "AGENTS.md") {
+      kept.push(target.path);
+      continue;
+    }
+    if (target.path === "AGENTS.md" && existsSync(full) && !writable(full, GENERATED)) {
+      kept.push(target.path);
+      continue;
+    }
+
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, `${target.frontMatter}${GENERATED}\n\n${body}`);
+    written.push(target.path);
+  }
+
+  const hook = join(cwd, ".git", "hooks", "pre-commit");
+  let hookNote = "";
+  if (existsSync(join(cwd, ".git"))) {
+    if (writable(hook, "roblox-guard")) {
+      mkdirSync(dirname(hook), { recursive: true });
+      writeFileSync(hook, PRE_COMMIT, { mode: 0o755 });
+      written.push(".git/hooks/pre-commit");
+    } else {
+      hookNote =
+        "\nA pre-commit hook already exists, so it was left alone. To add the check to it:\n" +
+        "  npx roblox-guard --check $(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.luau?$')\n";
+    }
+  }
+
+  process.stdout.write(
+    (written.length > 0
+      ? `roblox-guard installed ${written.length} file(s):\n` + written.map((p) => `  ${p}\n`).join("")
+      : "roblox-guard wrote nothing new.\n") +
+      (kept.length > 0
+        ? `\nLeft alone, because something else wrote them:\n` + kept.map((p) => `  ${p}\n`).join("")
+        : "") +
+      hookNote +
+      `
+Agents that install themselves, run whichever you use:
+  Claude Code    /plugin marketplace add andrian-syh/roblox-optimum
+                 /plugin install roblox-optimum@andrian-syh
+  Codex          codex plugin marketplace add andrian-syh/roblox-optimum
+                 codex plugin add roblox-optimum@andrian-syh
+  Copilot CLI    copilot plugin marketplace add andrian-syh/roblox-optimum
+                 copilot plugin install roblox-optimum@andrian-syh
+  Qwen Code      qwen extensions install ${HOME_PAGE}
+  Kiro           install a power from ${HOME_PAGE}
+
+Standards: ${HOME_PAGE}
+`,
+  );
+
+  return 0;
+}
+
 /**
  * Tells the agent to re-read the skill once a summary has dropped the rules, and stays
  * silent outside a Roblox project so unrelated sessions are not disturbed.
@@ -497,6 +644,17 @@ Players.PlayerAdded:Connect(greet)
     "LoadAnimation on an Animator is not reported",
   );
 
+  ok(
+    RULE_TARGETS.every((t) => typeof t.path === "string" && typeof t.frontMatter === "string"),
+    "every rule target names a path and its front matter",
+  );
+  ok(
+    new Set(RULE_TARGETS.map((t) => t.path)).size === RULE_TARGETS.length,
+    "no two rule targets claim the same path",
+  );
+  ok(writable(join(ROOT_ABSENT, "nothing.md"), GENERATED), "an absent file may be written");
+  ok(!writable("package.json", GENERATED), "a file this tool did not write is left alone");
+
   ok(checkFile("notes.txt").status === "not-luau", "a non-Luau path is reported as skipped");
   ok(
     checkFile(join("proj", "Packages", "Cmdr.luau")).status === "vendored",
@@ -519,6 +677,7 @@ if (invokedDirectly) {
   if (mode === "--selftest") selftest();
   else if (mode === "--compact") process.exit(await runCompactReminder());
   else if (mode === "--check") process.exit(runCheck(rest));
+  else if (mode === "install") process.exit(runInstall(rest.includes("--all")));
   else if (mode === "--help" || mode === "-h") process.stdout.write(USAGE);
   else if (mode === undefined) process.exit(await runPostToolUse());
   else {