roblox-guard 0.4.0 → 0.6.0

package/AGENTS.md

@@ -0,0 +1,77 @@
+# Roblox and Luau standards
+
+Scope: every `.luau` and `.lua` file in a Roblox project. These rules govern how each script is
+written, not how the project is structured, so they hold under any framework or folder layout.
+
+They are active instruction, not background reading. Carry them forward verbatim into any
+summary, handoff, or task note. Never reconstruct them from memory: a half-remembered layout
+rule looks deliberate and is worse than none.
+
+```text
+ROBLOX LUAU SKILL - INVARIANT CARD
+1  Three sections, this order:
+   -- // VARIABLES // --   Services > Modules > Objects > Configuration > State Management
+   -- // FUNCTIONS // --   definitions only (ModuleScript: Private before Public)
+   -- // INITIALIZATION // --   everything that runs
+   Omit a section that would be empty. Never write a placeholder header.
+2  Documentation Comments (Luau Comments) - default style, adapts to the project.
+   Default block: --[[ ]] above the function, desc > @param > @return.
+   Moonwave --[=[ ]=] or --- is equally correct when that is the project's style.
+   - Desc <= 3 lines and <= 250 chars, contract-level, states PURPOSE.
+   - Desc never names what the body does to get there: no APIs, algorithms,
+     collaborators, data structures, or code paths.
+   - Desc carries NO volatile content: no numbers, thresholds, tunable names,
+     feature names, or anything that needs editing when the body is retuned.
+   - Tags use Moonwave syntax: @param <name> <type> -- <description>
+     and @return <type> -- <description>. Only when they add what the
+     signature cannot show.
+   - English preferred. No em dashes or double-hyphen dashes as punctuation
+     (the -- in a tag is a separator, not punctuation). No emoji.
+   - IN-BODY COMMENTS: banned in code you write. Make names and structure say
+     it; put the why in the block above. Never delete an existing one;
+     propose removal once, Advisory only.
+   - Self-documenting code outranks commentary everywhere.
+   - Existing project comment style wins. Recommend this style when the user
+     asks to restyle; never impose it.
+3  Server is authoritative. Validate every remote arg: type, range, ownership, rate.
+4  Clean up everything created. Every connection has an owner and a teardown path.
+5  No avoidable per-frame garbage. Never poll what has a signal.
+6  UpdateAsync + backoff. Save on PlayerRemoving. Flush on BindToClose.
+7  Re-validate after every yield: player gone? instance dead? session changed?
+8  Never add --!strict unbidden. Never make a [Beta] feature the production default.
+9  Reuse before writing: project, then stdlib, then engine API. No wrapper or
+   abstraction without a caller. But brevity has two hard limits:
+   - It NEVER reduces what was asked for. Short because it does less = failed.
+   - It NEVER costs readability. One statement per line, descriptive names,
+     blank lines kept. Less code means less WORK, not less whitespace.
+10 No deprecated APIs: wait, spawn, delay, tick, lowercase :connect,
+   Humanoid:LoadAnimation, SetPrimaryPartCFrame, Body* movers.
+11 Engine facts are cited, not remembered. Confirm a newer API against the
+   version dump or an in-Studio probe before relying on it.
+12 User authority outranks these rules. Recommend; never refactor unasked.
+```
+
+## Full standards
+
+This card is the part that must survive a summary. The complete standards, with the reference
+files behind each rule, live in this repository:
+
+| Path | Covers |
+|---|---|
+| `skills/best-practices/SKILL.md` | Writing and refactoring Luau |
+| `skills/code-review/SKILL.md` | Reviewing, auditing, and scoring existing code |
+| `skills/studio-ops/SKILL.md` | Studio MCP, sync toolchains, verifying in a running session |
+
+Read the one whose task matches. Each reference file is self-contained; read one, not the set.
+
+## The checks run outside you
+
+`scripts/roblox-guard.mjs` reports deprecated APIs and out-of-order section headers
+deterministically, with no model involved. Run it on the files you touched before you report
+work as done:
+
+```
+node scripts/roblox-guard.mjs --check <files>
+```
+
+It exits 1 when a file has findings, and each finding names the line and the replacement.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Muhammad Andriansyah
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Muhammad Andriansyah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,7 @@ Professional Roblox and Luau standards for AI agents, and a checker that runs wi
 [![CI](https://github.com/andrian-syh/roblox-optimum/actions/workflows/ci.yml/badge.svg)](https://github.com/andrian-syh/roblox-optimum/actions/workflows/ci.yml)
 [![version](https://img.shields.io/github/package-json/v/andrian-syh/roblox-optimum?label=version&color=blue)](CHANGELOG.md)
 [![license](https://img.shields.io/github/license/andrian-syh/roblox-optimum?color=green)](LICENSE)
+[![npm](https://img.shields.io/npm/v/roblox-guard?label=npm&color=CB3837)](https://www.npmjs.com/package/roblox-guard)
 [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
 [![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
 
@@ -25,8 +26,8 @@ Claude Code, and as a project instruction file everywhere else. [AGENTS.md](AGEN
 ready to copy, along with a matching file for Cursor, Windsurf, Cline, Kiro, Qoder, Copilot,
 Qwen Code, and Antigravity.
 
-**The checker** is [`scripts/roblox-guard.mjs`](scripts/roblox-guard.mjs), one Node file with no
-dependencies. It reads Luau and reports the same findings whoever wrote the file, so it works as
+**The checker** is [`roblox-guard`](https://www.npmjs.com/package/roblox-guard) on npm, one Node
+file with no dependencies. It reads Luau and reports the same findings whoever wrote the file, so it works as
 an agent hook, a commit hook, or a CI step. It never asks a model anything, which is why it still
 holds after a long session has been summarized and the rules have fallen out of context.
 
@@ -54,9 +55,15 @@ Qwen Code:
 qwen extensions install https://github.com/andrian-syh/roblox-optimum
 ```
 
-Cursor, Antigravity, and Kiro install it as a plugin from this repository. For those, plus
-OpenCode, Copilot, or a plain commit hook, see **[INSTALL.md](INSTALL.md)**, which also states
-plainly what each setup can and cannot do.
+Cursor, Antigravity, Kiro, and Copilot CLI install it as a plugin from this repository. For those,
+plus OpenCode or a plain commit hook, see **[INSTALL.md](INSTALL.md)**, which also states plainly
+what each setup can and cannot do.
+
+The checker on its own needs no repository at all:
+
+```
+npx roblox-guard --check src/**/*.luau
+```
 
 ## Skills
 
@@ -113,6 +120,16 @@ or synced, belong to a project rather than to a person, and are resolved per ses
 Deprecated APIs and out-of-order section headers. Where the agent can receive them, findings go
 straight back to it and it fixes its own output before you see it.
 
+```
+$ npx roblox-guard --check CoinService.luau
+Roblox standards check failed for CoinService.luau:
+  - Line 5: :connect() is deprecated. Use :Connect().
+  - Line 6: wait() is deprecated. Use task.wait().
+  - Line 8: Humanoid:LoadAnimation() is deprecated. Use Animator:LoadAnimation().
+```
+
+Exit 1, so a commit hook or a build step stops on it.
+
 The check is deliberately conservative, because a wrong complaint gets a guard switched off:
 
 - Comments and string literals are excluded, so a rule quoted in prose is never reported as a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roblox-guard",
-  "version": "0.4.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",
@@ -17,7 +17,8 @@
     "roblox-guard": "scripts/roblox-guard.mjs"
   },
   "files": [
-    "scripts/roblox-guard.mjs"
+    "scripts/roblox-guard.mjs",
+    "AGENTS.md"
   ],
   "scripts": {
     "test": "node scripts/roblox-guard.mjs --selftest"

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.
@@ -188,15 +232,21 @@ export function inspect(source) {
   }
 
   const lines = code.split("\n");
+  const deprecated = [];
+
   for (const [pattern, name, replacement] of DEPRECATED) {
     for (let k = 0; k < lines.length; k++) {
       if (pattern.test(lines[k])) {
-        problems.push(`Line ${k + 1}: ${name} is deprecated. Use ${replacement}.`);
+        deprecated.push({ line: k + 1, text: `Line ${k + 1}: ${name} is deprecated. Use ${replacement}.` });
         break;
       }
     }
   }
 
+  // Report in reading order. Grouping by pattern is how they are found, not how they are read.
+  deprecated.sort((a, b) => a.line - b.line);
+  problems.push(...deprecated.map((d) => d.text));
+
   return problems;
 }
 
@@ -340,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.
@@ -399,6 +552,15 @@ Players.PlayerAdded:Connect(greet)
     inspect(good.replace("task.wait(1)", "wait(1)")).some((p) => p.includes("wait()")),
     "bare wait() is caught",
   );
+  ok(
+    (() => {
+      const lines = inspect(`-- // VARIABLES // --\nlocal a = 1\n-- // INITIALIZATION // --\nspawn(function()\n\twait(1)\nend)\nx:connect(f)`)
+        .map((p) => Number(p.match(/^Line (\d+)/)?.[1]))
+        .filter(Number.isFinite);
+      return lines.length === 3 && lines.every((n, k) => k === 0 || n >= lines[k - 1]);
+    })(),
+    "findings are reported in line order, not pattern order",
+  );
   ok(
     !inspect(good).some((p) => p.includes("wait()")),
     "task.wait() is not mistaken for wait()",
@@ -482,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",
@@ -504,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 {