guardrails-ref 1.2.1 → 1.2.3

package/README.md

@@ -20,23 +20,31 @@ Creates `.agents/guardrails/`, adds the `no-plaintext-secrets` example, and conf
 
 > **Note:** IDEs don't yet recognize guardrails natively. The `setup` command adds a rule so the AI reads them. Once IDEs add support, this won't be needed.
 
+**User-level guardrails:** Use `--user` or path `~` to work with `~/.agents/guardrails/` (applies across all projects). Example: `npx guardrails-ref init --user`.
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `npx guardrails-ref init [path]` | Create `.agents/guardrails/`, add no-plaintext-secrets, configure Cursor, Claude Code, and VS Code Copilot |
 | `npx guardrails-ref init --minimal [path]` | Create `.agents/guardrails/` only (no example, no setup) |
+| `npx guardrails-ref init --user` | Create `~/.agents/guardrails/` (user-level; setup is project-specific) |
 | `npx guardrails-ref add <name> [name2 ...] [path]` | Add example guardrail(s) — pass multiple names to add several at once |
-| `npx guardrails-ref remove <name> [path]` | Remove a guardrail (name required) |
+| `npx guardrails-ref add <name> --user` or `add <name> ~` | Add to user-level `~/.agents/guardrails/` |
+| `npx guardrails-ref remove <name> [path]` | Remove a guardrail |
+| `npx guardrails-ref remove <name> --user` or `remove <name> ~` | Remove from user-level |
 | `npx guardrails-ref setup [path]` | Add the guardrail rule to Cursor, Claude Code, and VS Code Copilot |
 | `npx guardrails-ref setup --remove [path]` | Remove the guardrail rule from IDE configs |
 | `npx guardrails-ref setup --ide <name> [path]` | Target IDE: `cursor`, `claude`, `copilot`, or `auto` (only configured IDEs) |
 | `npx guardrails-ref setup --dry-run [path]` | Show what would be added/removed without writing files |
 | `npx guardrails-ref setup --check [path]` | Show which IDEs are configured and whether they have the rule |
 | `npx guardrails-ref validate [path]` | Validate GUARDRAIL.md files (use `--json` for JSON, `--strict` to fail on warnings) |
+| `npx guardrails-ref validate --user` or `validate ~` | Validate user-level guardrails |
 | `npx guardrails-ref check [path]` | Validate with minimal output (CI-friendly, use `--strict` to fail on warnings) |
 | `npx guardrails-ref upgrade [path]` | Update installed guardrails to latest templates (use `--dry-run` to preview, `--diff` to show changes) |
+| `npx guardrails-ref upgrade --user` or `upgrade ~` | Upgrade user-level guardrails |
 | `npx guardrails-ref list [path]` | List discovered guardrails (use `--json` for JSON output) |
+| `npx guardrails-ref list --user` or `list ~` | List user-level guardrails |
 | `npx guardrails-ref why <name>` | Show guardrail template content (e.g. `why no-destructive-commands`) |
 
 ## Supported IDEs
@@ -66,12 +74,19 @@ Or with full output or JSON:
 ## Examples
 
 ```bash
+# Project-level (default)
 npx guardrails-ref init
 npx guardrails-ref add no-destructive-commands no-hardcoded-urls
 npx guardrails-ref add no-new-deps-without-approval
 npx guardrails-ref why no-destructive-commands
 npx guardrails-ref validate .
 npx guardrails-ref list .
+
+# User-level (~/.agents/guardrails/)
+npx guardrails-ref init --user
+npx guardrails-ref add no-plaintext-secrets --user
+npx guardrails-ref list --user
+npx guardrails-ref validate ~
 ```
 
 ## Available guardrails (add command)
@@ -82,9 +97,14 @@ npx guardrails-ref list .
 | `no-placeholder-credentials` | Fake or placeholder API keys instead of asking for real values |
 | `no-silent-error-handling` | Catching errors without surfacing them to the user |
 | `require-access-control` | Exposing sensitive data or admin actions without role checks |
+| `artifact-verification` | Destructive ops without plan.md and audit log |
+| `context-rotation` | Continuing in polluted context; reset when 80% full or 10+ errors |
 | `database-migrations` | Direct schema changes instead of migrations |
 | `no-destructive-commands` | rm -rf, DROP TABLE, TRUNCATE without approval |
+| `no-eval-or-dynamic-code` | eval(), new Function(), or dynamic code execution |
 | `no-new-deps-without-approval` | New packages without approval |
+| `privilege-boundaries` | Touching node_modules, .git, lockfiles, .env without approval |
+| `require-commit-approval` | git commit or push without explicit user approval |
 | `no-hardcoded-urls` | Hardcoded API URLs, base URLs, endpoints |
 | `no-sudo-commands` | sudo/su/root commands without approval |
 | `rate-limiting` | Runaway tool calls and API loops |

package/dist/add.d.ts

@@ -1 +1 @@
-export declare function runAdd(name: string, projectPath?: string): boolean;
+export declare function runAdd(name: string, projectPath?: string, userScope?: boolean): boolean;

package/dist/add.js

@@ -1,8 +1,9 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { resolve } from "path";
+import { join } from "path";
 import chalk from "chalk";
+import { resolveGuardrailsDir } from "./path-utils.js";
 import { TEMPLATES, TEMPLATE_NAMES } from "./templates.js";
-export function runAdd(name, projectPath = ".") {
+export function runAdd(name, projectPath = ".", userScope = false) {
     const normalized = name.toLowerCase().replace(/\s+/g, "-");
     const content = TEMPLATES[normalized];
     if (!content) {
@@ -10,20 +11,20 @@ export function runAdd(name, projectPath = ".") {
         console.log(chalk.gray("Available: " + TEMPLATE_NAMES.join(", ")));
         return false;
     }
-    const root = resolve(projectPath);
-    const guardrailsDir = resolve(root, ".agents", "guardrails");
-    const exampleDir = resolve(guardrailsDir, normalized);
-    const exampleFile = resolve(exampleDir, "GUARDRAIL.md");
+    const guardrailsDir = resolveGuardrailsDir(projectPath, userScope);
+    const exampleDir = join(guardrailsDir, normalized);
+    const exampleFile = join(exampleDir, "GUARDRAIL.md");
+    const pathLabel = userScope ? "~/.agents/guardrails/" : ".agents/guardrails/";
     if (existsSync(exampleFile)) {
-        console.log(chalk.yellow(".agents/guardrails/" + normalized + "/GUARDRAIL.md already exists"));
+        console.log(chalk.yellow(pathLabel + normalized + "/GUARDRAIL.md already exists"));
         return true;
     }
     if (!existsSync(guardrailsDir)) {
         mkdirSync(guardrailsDir, { recursive: true });
-        console.log(chalk.green("✓") + " Created .agents/guardrails/");
+        console.log(chalk.green("✓") + " Created " + pathLabel);
     }
     mkdirSync(exampleDir, { recursive: true });
     writeFileSync(exampleFile, content);
-    console.log(chalk.green("✓") + " Added .agents/guardrails/" + normalized + "/GUARDRAIL.md");
+    console.log(chalk.green("✓") + " Added " + pathLabel + normalized + "/GUARDRAIL.md");
     return true;
 }

package/dist/cli.js

@@ -11,6 +11,7 @@ import { runAdd } from "./add.js";
 import { runWhy } from "./why.js";
 import { runRemove } from "./remove.js";
 import { runUpgrade } from "./upgrade.js";
+import { resolveGuardrailsDir } from "./path-utils.js";
 import { TEMPLATE_NAMES } from "./templates.js";
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -20,7 +21,9 @@ program
     .description("Validate and list Agent Guardrails (GUARDRAIL.md) files")
     .version(pkg.version);
 function runValidate(path, options) {
-    const result = validatePath(path);
+    const userScope = options.user ?? path === "~";
+    const pathToScan = userScope ? resolveGuardrailsDir("~", true) : path;
+    const result = validatePath(pathToScan);
     const hasWarnings = result.results.some((r) => r.warnings.length > 0);
     const hasErrors = result.invalid > 0;
     const strictFail = options.strict && hasWarnings;
@@ -93,6 +96,7 @@ program
     .description("Validate GUARDRAIL.md files in a directory or a single file")
     .option("-j, --json", "Output as JSON")
     .option("-s, --strict", "Fail on warnings (CI mode)")
+    .option("-u, --user", "Use user-level guardrails (~/.agents/guardrails/)")
     .action(function (path) {
     const opts = this.opts();
     runValidate(path ?? ".", opts);
@@ -109,15 +113,17 @@ program
     .command("init [path]")
     .description("Create .agents/guardrails/, add no-plaintext-secrets, and run setup (one command to get started)")
     .option("-m, --minimal", "Create .agents/guardrails/ only, no example and no setup")
+    .option("-u, --user", "Create ~/.agents/guardrails/ (user-level); setup is project-specific")
     .action(function (path) {
     const opts = this.opts();
-    runInit(path ?? ".", opts.minimal);
+    runInit(path ?? ".", opts.minimal, opts.user);
 });
 program
     .command("add [names...]")
     .description("Add example guardrail(s) by name — pass multiple to add several at once")
     .option("-l, --list", "List available guardrails to add")
     .option("-p, --path <path>", "Target directory", ".")
+    .option("-u, --user", "Add to user-level ~/.agents/guardrails/")
     .action(function (names = []) {
     const opts = this.opts();
     if (opts.list) {
@@ -132,7 +138,7 @@ program
     // --path takes precedence when explicitly provided (opts.path !== ".")
     let targetPath = opts.path ?? ".";
     const args = names.filter((n) => n != null && String(n).trim());
-    const looksLikePath = (s) => s === "." || s === ".." || s.includes("/") || s.includes("\\");
+    const looksLikePath = (s) => s === "." || s === ".." || s === "~" || s.includes("/") || s.includes("\\");
     if (args.length >= 1 && looksLikePath(args[args.length - 1])) {
         if (args.length === 1) {
             console.log("Usage: npx guardrails-ref add <name> [name2 ...] [path]");
@@ -151,11 +157,13 @@ program
         process.exit(1);
         return;
     }
+    const userScope = opts.user ?? targetPath === "~";
+    const addPath = userScope ? "~" : targetPath;
     let failed = 0;
     for (const name of args) {
         if (!name.trim())
             continue;
-        if (!runAdd(name, targetPath))
+        if (!runAdd(name, addPath, userScope))
             failed++;
     }
     process.exit(failed > 0 ? 1 : 0);
@@ -165,15 +173,22 @@ program
     .description("Update installed guardrails to latest template versions")
     .option("-n, --dry-run", "Show what would be updated without writing")
     .option("-d, --diff", "Show diff for each updated guardrail")
+    .option("-u, --user", "Upgrade user-level ~/.agents/guardrails/")
     .action(function (path) {
     const opts = this.opts();
-    runUpgrade(path ?? ".", opts.dryRun, opts.diff);
+    const p = path ?? ".";
+    const userScope = opts.user ?? p === "~";
+    runUpgrade(userScope ? "~" : p, opts.dryRun, opts.diff, userScope);
 });
 program
     .command("remove <name> [path]")
     .description("Remove a guardrail from .agents/guardrails/")
-    .action((name, path = ".") => {
-    const ok = runRemove(name, path);
+    .option("-u, --user", "Remove from user-level ~/.agents/guardrails/")
+    .action(function (name, path) {
+    const opts = this.opts();
+    const p = path ?? ".";
+    const userScope = opts.user ?? p === "~";
+    const ok = runRemove(name, userScope ? "~" : p, userScope);
     process.exit(ok ? 0 : 1);
 });
 program
@@ -220,9 +235,12 @@ program
     .command("list [path]")
     .description("List discovered guardrails")
     .option("-j, --json", "Output as JSON")
+    .option("-u, --user", "List user-level ~/.agents/guardrails/")
     .action(function (path) {
     const opts = this.opts();
-    const guardrails = listGuardrails(path ?? ".");
+    const userScope = opts.user ?? path === "~";
+    const pathToScan = userScope ? resolveGuardrailsDir("~", true) : (path ?? ".");
+    const guardrails = listGuardrails(pathToScan);
     if (opts.json) {
         console.log(JSON.stringify({ guardrails, total: guardrails.length }, null, 2));
         process.exit(guardrails.length === 0 ? 1 : 0);

package/dist/init.d.ts

@@ -3,4 +3,4 @@ export interface InitResult {
     exampleCreated: boolean;
     setupDone: string;
 }
-export declare function runInit(projectPath?: string, minimal?: boolean): InitResult;
+export declare function runInit(projectPath?: string, minimal?: boolean, userScope?: boolean): InitResult;

package/dist/init.js

@@ -1,23 +1,29 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { resolve } from "path";
+import { join } from "path";
 import chalk from "chalk";
+import { resolveGuardrailsDir } from "./path-utils.js";
 import { runSetup } from "./setup.js";
 import { TEMPLATES } from "./templates.js";
-export function runInit(projectPath = ".", minimal = false) {
-    const root = resolve(projectPath);
-    const guardrailsDir = resolve(root, ".agents", "guardrails");
-    const exampleDir = resolve(guardrailsDir, "no-plaintext-secrets");
-    const exampleFile = resolve(exampleDir, "GUARDRAIL.md");
+export function runInit(projectPath = ".", minimal = false, userScope = false) {
+    const guardrailsDir = resolveGuardrailsDir(projectPath, userScope);
+    const exampleDir = join(guardrailsDir, "no-plaintext-secrets");
+    const exampleFile = join(exampleDir, "GUARDRAIL.md");
     let exampleCreated = false;
     if (!existsSync(guardrailsDir)) {
         mkdirSync(guardrailsDir, { recursive: true });
-        console.log(chalk.green("✓") + " Created .agents/guardrails/");
+        console.log(chalk.green("✓") + " Created " + (userScope ? "~/.agents/guardrails/" : ".agents/guardrails/"));
     }
-    if (minimal) {
+    if (minimal || userScope) {
+        if (userScope && !existsSync(exampleFile)) {
+            mkdirSync(exampleDir, { recursive: true });
+            writeFileSync(exampleFile, TEMPLATES["no-plaintext-secrets"]);
+            exampleCreated = true;
+            console.log(chalk.green("✓") + " Created ~/.agents/guardrails/no-plaintext-secrets/GUARDRAIL.md");
+        }
         return {
             guardrailsDir,
-            exampleCreated: false,
-            setupDone: "",
+            exampleCreated,
+            setupDone: userScope ? "(setup is project-specific; run setup in each project)" : "",
         };
     }
     if (!existsSync(exampleFile)) {
@@ -29,7 +35,7 @@ export function runInit(projectPath = ".", minimal = false) {
     else {
         console.log(chalk.yellow("  .agents/guardrails/no-plaintext-secrets/GUARDRAIL.md already exists"));
     }
-    const setupResult = runSetup(projectPath);
+    const setupResult = runSetup(projectPath); // project-level only
     console.log(setupResult.message);
     return {
         guardrailsDir,

package/dist/path-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolve the guardrails directory path.
+ * When userScope or path is "~", returns ~/.agents/guardrails (user-level).
+ * Otherwise returns <path>/.agents/guardrails (project-level).
+ */
+export declare function resolveGuardrailsDir(path: string, userScope?: boolean): string;

package/dist/path-utils.js

@@ -0,0 +1,14 @@
+import { homedir } from "os";
+import { join, resolve } from "path";
+/**
+ * Resolve the guardrails directory path.
+ * When userScope or path is "~", returns ~/.agents/guardrails (user-level).
+ * Otherwise returns <path>/.agents/guardrails (project-level).
+ */
+export function resolveGuardrailsDir(path, userScope) {
+    if (userScope || path === "~" || path === "~/") {
+        return join(homedir(), ".agents", "guardrails");
+    }
+    const root = resolve(path);
+    return join(root, ".agents", "guardrails");
+}

package/dist/remove.d.ts

@@ -1 +1 @@
-export declare function runRemove(name: string, projectPath?: string): boolean;
+export declare function runRemove(name: string, projectPath?: string, userScope?: boolean): boolean;

package/dist/remove.js

@@ -1,30 +1,31 @@
 import { existsSync, readdirSync, rmSync, rmdirSync } from "fs";
-import { resolve } from "path";
+import { join } from "path";
 import chalk from "chalk";
+import { resolveGuardrailsDir } from "./path-utils.js";
 import { listGuardrails } from "./validate.js";
-export function runRemove(name, projectPath = ".") {
+export function runRemove(name, projectPath = ".", userScope = false) {
     const normalized = name.toLowerCase().replace(/\s+/g, "-");
-    const root = resolve(projectPath);
-    const guardrailsDir = resolve(root, ".agents", "guardrails");
-    const targetDir = resolve(guardrailsDir, normalized);
-    const targetFile = resolve(targetDir, "GUARDRAIL.md");
+    const guardrailsDir = resolveGuardrailsDir(projectPath, userScope);
+    const targetDir = join(guardrailsDir, normalized);
+    const targetFile = join(targetDir, "GUARDRAIL.md");
+    const pathLabel = userScope ? "~/.agents/guardrails/" : ".agents/guardrails/";
     if (!existsSync(targetFile)) {
         const guardrails = listGuardrails(guardrailsDir);
         const names = guardrails.map((g) => g.name);
-        console.log(chalk.red("Guardrail not found:") + " .agents/guardrails/" + normalized);
+        console.log(chalk.red("Guardrail not found:") + " " + pathLabel + normalized);
         if (names.length > 0) {
             console.log(chalk.gray("Installed: " + names.join(", ")));
         }
         return false;
     }
     rmSync(targetDir, { recursive: true });
-    console.log(chalk.green("✓") + " Removed .agents/guardrails/" + normalized);
+    console.log(chalk.green("✓") + " Removed " + pathLabel + normalized);
     // Remove parent dir if empty
     try {
         const remaining = readdirSync(guardrailsDir);
         if (remaining.length === 0) {
             rmdirSync(guardrailsDir);
-            console.log(chalk.green("✓") + " Removed empty .agents/guardrails/");
+            console.log(chalk.green("✓") + " Removed empty " + pathLabel);
         }
     }
     catch {

package/dist/templates.js

@@ -37,6 +37,7 @@ Implementing authentication endpoints, adding logging, integrating third-party A
 - Use bcrypt with 12 salt rounds for password hashing
 - Always require HTTPS for authentication endpoints
 - Use a \`redactSensitive()\` helper when logging objects that may contain secrets
+- Audit all logs before committing to ensure no credentials are included
 
 ## Reason
 API keys were exposed in git during a 2025 security audit. Plaintext credentials in logs led to emergency key rotation.

package/dist/upgrade.d.ts

@@ -3,4 +3,4 @@ export interface UpgradeResult {
     skipped: string[];
     notFound: string[];
 }
-export declare function runUpgrade(projectPath?: string, dryRun?: boolean, showDiff?: boolean): UpgradeResult;
+export declare function runUpgrade(projectPath?: string, dryRun?: boolean, showDiff?: boolean, userScope?: boolean): UpgradeResult;

package/dist/upgrade.js

@@ -1,7 +1,8 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "fs";
-import { resolve } from "path";
+import { join } from "path";
 import chalk from "chalk";
 import { createPatch } from "diff";
+import { resolveGuardrailsDir } from "./path-utils.js";
 import { TEMPLATES } from "./templates.js";
 function printDiff(name, current, template) {
     const patch = createPatch(".agents/guardrails/" + name + "/GUARDRAIL.md", current, template, "current", "template");
@@ -12,12 +13,12 @@ function printDiff(name, current, template) {
         console.log(chalk.gray(body));
     }
 }
-export function runUpgrade(projectPath = ".", dryRun = false, showDiff = false) {
-    const root = resolve(projectPath);
-    const guardrailsDir = resolve(root, ".agents", "guardrails");
+export function runUpgrade(projectPath = ".", dryRun = false, showDiff = false, userScope = false) {
+    const guardrailsDir = resolveGuardrailsDir(projectPath, userScope);
     const result = { updated: [], skipped: [], notFound: [] };
+    const pathLabel = userScope ? "~/.agents/guardrails/" : ".agents/guardrails/";
     if (!existsSync(guardrailsDir)) {
-        console.log(chalk.yellow("No .agents/guardrails/ directory found"));
+        console.log(chalk.yellow("No " + pathLabel + " directory found"));
         return result;
     }
     const entries = readdirSync(guardrailsDir, { withFileTypes: true });
@@ -26,7 +27,7 @@ export function runUpgrade(projectPath = ".", dryRun = false, showDiff = false)
             continue;
         const name = ent.name.toLowerCase().replace(/\s+/g, "-");
         const template = TEMPLATES[name];
-        const filePath = resolve(guardrailsDir, ent.name, "GUARDRAIL.md");
+        const filePath = join(guardrailsDir, ent.name, "GUARDRAIL.md");
         if (!existsSync(filePath))
             continue;
         if (!template) {
@@ -44,10 +45,10 @@ export function runUpgrade(projectPath = ".", dryRun = false, showDiff = false)
                 printDiff(name, current, template);
             }
             writeFileSync(filePath, template);
-            console.log(chalk.green("✓") + " Updated .agents/guardrails/" + name + "/GUARDRAIL.md");
+            console.log(chalk.green("✓") + " Updated " + pathLabel + name + "/GUARDRAIL.md");
         }
         else {
-            console.log(chalk.cyan("Would update") + " .agents/guardrails/" + name + "/GUARDRAIL.md");
+            console.log(chalk.cyan("Would update") + " " + pathLabel + name + "/GUARDRAIL.md");
             if (showDiff) {
                 printDiff(name, current, template);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardrails-ref",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Validate and manage Agent Guardrails (GUARDRAIL.md) — init, add, remove, setup, validate, check, upgrade, list, why",
   "type": "module",
   "main": "dist/validate.js",