agentsafe 0.1.0

package/examples/unsafe-rules/GEMINI.md

@@ -0,0 +1,3 @@
+# Unsafe Gemini Instructions
+
+The examples in this directory are intentionally unsafe and must never be executed.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "agentsafe",
+  "version": "0.1.0",
+  "description": "Offline safety and hygiene toolkit for AI coding workspaces",
+  "type": "module",
+  "bin": {
+    "agentsafe": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test",
+    "scan:example": "npm run build --silent && node dist/index.js rules scan examples/unsafe-rules --markdown"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+import {
+  formatJsonReport,
+  formatMarkdownReport,
+  formatTextReport,
+} from "./rules/report.js";
+import { scanRules } from "./rules/scan.js";
+
+type OutputFormat = "text" | "json" | "markdown";
+
+interface CliOptions {
+  directory: string;
+  format: OutputFormat;
+}
+
+interface CliOutput {
+  stdout(value: string): void;
+  stderr(value: string): void;
+}
+
+const usage = `Usage:
+  agentsafe rules scan [directory] [--json | --markdown]
+
+Scans AI rule files using local, static analysis only.
+`;
+
+export async function runCli(
+  args: string[],
+  cwd = process.cwd(),
+  output: CliOutput = {
+    stdout: (value) => process.stdout.write(value),
+    stderr: (value) => process.stderr.write(value),
+  },
+): Promise<number> {
+  if (args.includes("--help") || args.includes("-h")) {
+    output.stdout(usage);
+    return 0;
+  }
+
+  let options: CliOptions;
+  try {
+    options = parseArguments(args);
+  } catch (error) {
+    output.stderr(`${getErrorMessage(error)}\n\n${usage}`);
+    return 1;
+  }
+
+  try {
+    const report = await scanRules(resolve(cwd, options.directory));
+    const formatted =
+      options.format === "json"
+        ? formatJsonReport(report)
+        : options.format === "markdown"
+          ? formatMarkdownReport(report)
+          : formatTextReport(report);
+    output.stdout(formatted);
+    return 0;
+  } catch (error) {
+    output.stderr(`AgentSafe scan failed: ${getErrorMessage(error)}\n`);
+    return 1;
+  }
+}
+
+function parseArguments(args: string[]): CliOptions {
+  if (args[0] !== "rules" || args[1] !== "scan") {
+    throw new Error("Unknown command.");
+  }
+
+  let format: OutputFormat = "text";
+  let directory = ".";
+  let hasDirectory = false;
+
+  for (const argument of args.slice(2)) {
+    if (argument === "--json" || argument === "--markdown") {
+      const requestedFormat = argument.slice(2) as OutputFormat;
+      if (format !== "text") {
+        throw new Error("Use only one report format flag.");
+      }
+      format = requestedFormat;
+    } else if (argument.startsWith("-")) {
+      throw new Error(`Unknown option: ${argument}`);
+    } else if (hasDirectory) {
+      throw new Error("Only one scan directory may be provided.");
+    } else {
+      directory = argument;
+      hasDirectory = true;
+    }
+  }
+
+  return { directory, format };
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unknown error.";
+}
+
+const invokedPath = process.argv[1];
+if (invokedPath && pathToFileURL(invokedPath).href === import.meta.url) {
+  process.exitCode = await runCli(process.argv.slice(2));
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from "./cli.js";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/src/rules/report.ts

@@ -0,0 +1,83 @@
+import type { Finding, ScanReport } from "./types.js";
+
+export function formatJsonReport(report: ScanReport): string {
+  return `${JSON.stringify(report, null, 2)}\n`;
+}
+
+export function formatMarkdownReport(report: ScanReport): string {
+  const lines = [
+    "# AgentSafe Rules Scan",
+    "",
+    `- Target: \`${report.target}\``,
+    `- Files scanned: ${report.summary.files}`,
+    `- High severity: ${report.summary.high}`,
+    `- Warnings: ${report.summary.warnings}`,
+    `- Total findings: ${report.summary.total}`,
+    "",
+    "## Findings",
+    "",
+  ];
+
+  if (report.findings.length === 0) {
+    lines.push("_No findings._");
+  } else {
+    lines.push("| Severity | Rule | Location | Message |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const finding of report.findings) {
+      lines.push(
+        `| ${finding.severity.toUpperCase()} | \`${escapeMarkdown(finding.code)}\` | ${formatMarkdownLocation(finding)} | ${escapeMarkdown(finding.message)} |`,
+      );
+    }
+  }
+
+  lines.push("", "## Scanned Files", "");
+  if (report.files.length === 0) {
+    lines.push("_No supported rule files found._");
+  } else {
+    for (const file of report.files) {
+      lines.push(`- \`${escapeMarkdown(file)}\``);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatTextReport(report: ScanReport): string {
+  const lines = [
+    "AgentSafe Rules Scan",
+    `Files scanned: ${report.summary.files}`,
+    `Findings: ${report.summary.total} (${report.summary.high} high, ${report.summary.warnings} warnings)`,
+  ];
+
+  if (report.findings.length === 0) {
+    lines.push("", "No findings.");
+  } else {
+    lines.push("");
+    for (const finding of report.findings) {
+      lines.push(
+        `[${finding.severity.toUpperCase()}] ${formatTextLocation(finding)} ${finding.code}: ${finding.message}`,
+      );
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function formatMarkdownLocation(finding: Finding): string {
+  if (!finding.path) {
+    return "project";
+  }
+  const location = finding.line ? `${finding.path}:${finding.line}` : finding.path;
+  return `\`${escapeMarkdown(location)}\``;
+}
+
+function formatTextLocation(finding: Finding): string {
+  if (!finding.path) {
+    return "project";
+  }
+  return finding.line ? `${finding.path}:${finding.line}` : finding.path;
+}
+
+function escapeMarkdown(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/`/g, "\\`");
+}