pi-opa-net 0.1.0

package/src/parser/CommandParser.ts

@@ -0,0 +1,32 @@
+import { RegexFallbackParser } from './RegexFallbackParser.ts';
+import { ShellQuoteParser } from './ShellQuoteParser.ts';
+import type { CommandParser, ParsedCommand } from './types.ts';
+
+/**
+ * Hybrid parser coordinator [OT1 resolution].
+ *
+ * Strategy: AST primary (ShellQuoteParser), regex fallback when AST reports
+ * `failed`. `partial` and `regex-only` results are returned as-is — the
+ * `parseConfidence` field surfaces which path fired per-decision.
+ */
+export class CommandParserCoordinator implements CommandParser {
+  readonly name = 'hybrid';
+  private readonly primary: CommandParser;
+  private readonly fallback: CommandParser;
+
+  constructor(
+    primary: CommandParser = new ShellQuoteParser(),
+    fallback: CommandParser = new RegexFallbackParser(),
+  ) {
+    this.primary = primary;
+    this.fallback = fallback;
+  }
+
+  parse(raw: string): ParsedCommand {
+    const result = this.primary.parse(raw);
+    if (result.parseConfidence === 'failed') {
+      return this.fallback.parse(raw);
+    }
+    return result;
+  }
+}

package/src/parser/RegexFallbackParser.ts

@@ -0,0 +1,31 @@
+import type { CommandParser, ParsedCommand } from './types.ts';
+
+/** Programs with a subcommand shape — mirror of ShellQuoteParser's set. */
+const SUBCOMMAND_PROGRAMS = new Set(['git', 'docker', 'gh', 'glab']);
+
+/**
+ * Regex-only fallback parser [OT1 resolution: fallback path].
+ *
+ * Used when the AST parser returns `failed`. Splits on whitespace, lowercases,
+ * and applies the same program-aware subcommand classification as ShellQuoteParser.
+ * Confidence is always `regex-only` (or `failed` on empty input).
+ */
+export class RegexFallbackParser implements CommandParser {
+  readonly name = 'regex';
+
+  parse(raw: string): ParsedCommand {
+    const trimmed = raw.trim();
+    if (trimmed === '') {
+      return { raw, program: '', subcommand: '', args: [], parseConfidence: 'failed' };
+    }
+
+    const tokens = trimmed.split(/\s+/);
+    const [program, ...rest] = tokens.map((t) => t.toLowerCase());
+
+    if (SUBCOMMAND_PROGRAMS.has(program) && rest.length > 0 && !rest[0].startsWith('-')) {
+      const [sub, ...args] = rest;
+      return { raw, program, subcommand: sub, args, parseConfidence: 'regex-only' };
+    }
+    return { raw, program, subcommand: '', args: rest, parseConfidence: 'regex-only' };
+  }
+}

package/src/parser/ShellQuoteParser.ts

@@ -0,0 +1,72 @@
+import { parse as shellQuoteParse } from 'shell-quote';
+import type { CommandParser, ParsedCommand } from './types.ts';
+
+/**
+ * Programs that use a `[program, subcommand, args...]` shape.
+ * For programs NOT in this set (rm, bd, gcloud, bq, ls, ...), every token
+ * after the program is an arg and subcommand is "". This matches how the
+ * rego policy queries each family (git/docker/gh/glab check subcommand;
+ * rm/bd/gcloud/bq check args).
+ */
+const SUBCOMMAND_PROGRAMS = new Set(['git', 'docker', 'gh', 'glab']);
+
+/**
+ * AST-based parser using shell-quote [OT1 resolution: primary path].
+ *
+ * Produces `parseConfidence: full` when shell-quote tokenizes cleanly into
+ * a simple [program, subcommand?, args...] shape. Falls back to `partial`
+ * when redirects/pipelines/subshells are detected (structured tokens still
+ * extracted but the command is flagged as not a plain invocation).
+ */
+export class ShellQuoteParser implements CommandParser {
+  readonly name = 'shell-quote';
+
+  parse(raw: string): ParsedCommand {
+    const trimmed = raw.trim();
+    if (trimmed === '') {
+      return emptyParsed(raw, 'failed');
+    }
+
+    let tokens: unknown[];
+    try {
+      tokens = shellQuoteParse(trimmed);
+    } catch {
+      // shell-quote throws on unbalanced quotes etc. — defer to regex fallback.
+      return emptyParsed(raw, 'failed');
+    }
+
+    const hasMeta = tokens.some(isMetaToken);
+    const strings = tokens.filter((t): t is string => typeof t === 'string');
+
+    if (strings.length === 0) {
+      return emptyParsed(raw, hasMeta ? 'partial' : 'failed');
+    }
+
+    return classify(strings, raw, hasMeta);
+  }
+}
+
+/** Apply program-aware subcommand classification. */
+function classify(strings: string[], raw: string, hasMeta: boolean): ParsedCommand {
+  const [programRaw, ...rest] = strings;
+  const program = programRaw.toLowerCase();
+  const confidence = hasMeta ? 'partial' : 'full';
+
+  // Subcommand-style programs: tokens[1] is the subcommand (unless it's a flag).
+  if (SUBCOMMAND_PROGRAMS.has(program) && rest.length > 0 && !rest[0].startsWith('-')) {
+    const [sub, ...args] = rest;
+    return { raw, program, subcommand: sub.toLowerCase(), args, parseConfidence: confidence };
+  }
+
+  // Non-subcommand programs: everything after program is an arg.
+  return { raw, program, subcommand: '', args: rest, parseConfidence: confidence };
+}
+
+/** shell-quote emits objects ({op, ...}) for redirects/pipelines/subshells. */
+function isMetaToken(token: unknown): boolean {
+  return typeof token === 'object' && token !== null;
+}
+
+function emptyParsed(raw: string, confidence: ParsedCommand['parseConfidence']): ParsedCommand {
+  return { raw, program: '', subcommand: '', args: [], parseConfidence: confidence };
+}

package/src/parser/index.ts

@@ -0,0 +1,4 @@
+export { CommandParserCoordinator } from './CommandParser.ts';
+export { RegexFallbackParser } from './RegexFallbackParser.ts';
+export { ShellQuoteParser } from './ShellQuoteParser.ts';
+export type { CommandParser, ParseConfidence, ParsedCommand } from './types.ts';

package/src/parser/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Normalized command structure — the "decide half" input to OPA.
+ * Matches the `EvaluatedInput` schema (minus `raw` which is added at output).
+ */
+export interface ParsedCommand {
+  /** Original command string verbatim. */
+  readonly raw: string;
+  /** Normalized program name (lowercase). Empty string if unparseable. */
+  readonly program: string;
+  /** Normalized subcommand. Empty string if none (bare-default case [OT3]). */
+  readonly subcommand: string;
+  /** Normalized arg tokens. Empty array if none. */
+  readonly args: readonly string[];
+  /** Parser fidelity — surfaces how well the command was parsed [OT1]. */
+  readonly parseConfidence: ParseConfidence;
+}
+
+export type ParseConfidence = 'full' | 'partial' | 'regex-only' | 'failed';
+
+/**
+ * Strategy interface for command parsing [OT1 resolution: hybrid].
+ * Implementations: ShellQuoteParser (AST primary), RegexFallbackParser (fallback).
+ */
+export interface CommandParser {
+  readonly name: string;
+  parse(raw: string): ParsedCommand;
+}

package/src/rules/RuleRegistry.ts

@@ -0,0 +1,65 @@
+import type { RawDeny } from '../engine/types.ts';
+
+export type RuleFamily =
+  | 'git'
+  | 'docker'
+  | 'rm'
+  | 'gcloud'
+  | 'bq'
+  | 'gh'
+  | 'glab'
+  | 'bd'
+  | 'builtin'
+  | 'custom';
+
+export interface RuleMeta {
+  readonly ruleId: string;
+  readonly family: RuleFamily;
+  readonly message: string;
+  /** Safe alternatives for the "did you mean?" UX. Optional. */
+  readonly suggestions?: readonly string[];
+}
+
+/**
+ * Registry mapping deny messages to stable rule provenance [D3].
+ *
+ * OPA returns deny as a set of message strings (the rego rule bodies).
+ * This registry is the single source of truth for rule_id + family + severity,
+ * so audits trace decision → rule → source line. Messages not in the registry
+ * fall back to a synthesized `custom:<hash>` id with family=custom.
+ *
+ * Keeping this in TS (not rego) is intentional: rego is the policy, this is the
+ * provenance metadata layer. DRY — one canonical list, consumed by the builder.
+ */
+export class RuleRegistry {
+  private readonly byMessage: Map<string, RuleMeta>;
+
+  constructor(rules: readonly RuleMeta[]) {
+    this.byMessage = new Map(rules.map((r) => [r.message, r]));
+  }
+
+  /** Look up metadata for a deny message; synthesizes a custom entry if unknown. */
+  lookup(deny: RawDeny): RuleMeta {
+    const found = this.byMessage.get(deny.message);
+    if (found) return found;
+    return {
+      ruleId: `custom:${hashMessage(deny.message)}`,
+      family: 'custom',
+      message: deny.message,
+    };
+  }
+
+  /** True if the message is a known registered rule. */
+  isKnown(message: string): boolean {
+    return this.byMessage.has(message);
+  }
+}
+
+function hashMessage(msg: string): string {
+  // Simple stable hash for synthesis — not cryptographic.
+  let h = 0;
+  for (let i = 0; i < msg.length; i++) {
+    h = (Math.imul(31, h) + msg.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}

package/src/rules/catalog.ts

@@ -0,0 +1,221 @@
+import type { RuleMeta } from './RuleRegistry.ts';
+
+/**
+ * Canonical rule catalog — mirrors policy/safety.rego message-for-message.
+ *
+ * Single source of truth for rule_id + family + suggestions. When you add a
+ * deny rule to safety.rego, add its message here too. The registry test
+ * (`rule-catalog-parity.test.ts`) fails if the rego and this list drift.
+ */
+export const RULES: readonly RuleMeta[] = [
+  // ── GROUP A: git ──
+  {
+    ruleId: 'block-git-commit-am',
+    family: 'git',
+    message:
+      'git commit -am stages ALL tracked modifications indiscriminately. Use explicit paths.',
+    suggestions: ['git commit -m "msg" <paths>'],
+  },
+  {
+    ruleId: 'block-git-commit-no-verify',
+    family: 'git',
+    message: 'ALWAYS run pre-commit hooks. Bypassing hooks risks shipping broken changes.',
+  },
+  {
+    ruleId: 'block-git-stash-mutations',
+    family: 'git',
+    message: 'Do not mutate stashes in shared work. Others may be relying on them.',
+    suggestions: ['git stash list', 'git stash show'],
+  },
+  {
+    ruleId: 'builtin:bare-stash-default',
+    family: 'builtin',
+    message: 'Bare `git stash` defaults to push. Use `git stash list/show` explicitly.',
+    suggestions: ['git stash list', 'git stash show', 'git stash branch <name>'],
+  },
+  {
+    ruleId: 'block-git-reset-hard',
+    family: 'git',
+    message: "Hard reset discards local work and can remove others' uncommitted changes.",
+  },
+  {
+    ruleId: 'block-git-reset-mixed',
+    family: 'git',
+    message: 'Mixed reset rewrites index state and can disrupt shared work.',
+  },
+  {
+    ruleId: 'block-git-reset-modes',
+    family: 'git',
+    message: 'Reset modes can unexpectedly alter local changes in shared work.',
+  },
+  {
+    ruleId: 'block-git-clean-force',
+    family: 'git',
+    message: 'git clean can permanently remove untracked files from the working tree.',
+  },
+  {
+    ruleId: 'block-git-checkout-discard',
+    family: 'git',
+    message: "checkout -- discards local file changes and may destroy others' work.",
+  },
+  {
+    ruleId: 'block-git-checkout-B',
+    family: 'git',
+    message: 'git checkout -B force-resets branch refs and can trash shared branches.',
+  },
+  {
+    ruleId: 'block-git-restore',
+    family: 'git',
+    message: 'git restore can discard tracked modifications in shared work.',
+  },
+  {
+    ruleId: 'block-git-add-all',
+    family: 'git',
+    message: 'git add -A / -a stages ALL changed files indiscriminately. Use explicit paths.',
+    suggestions: ['git add <explicit-paths>'],
+  },
+  {
+    ruleId: 'block-git-add-dot',
+    family: 'git',
+    message: 'git add . stages ALL files in the current directory indiscriminately.',
+    suggestions: ['git add <explicit-paths>'],
+  },
+  {
+    ruleId: 'block-git-switch-C',
+    family: 'git',
+    message: 'git switch -C force-resets branch refs and can rewrite shared history.',
+  },
+  {
+    ruleId: 'block-git-branch-force',
+    family: 'git',
+    message: 'Forced branch moves or renames can rewrite refs and disrupt shared work.',
+  },
+  {
+    ruleId: 'block-git-rebase',
+    family: 'git',
+    message: 'Rebase rewrites commit history and is blocked in this environment.',
+  },
+  {
+    ruleId: 'block-git-rebase-lifecycle',
+    family: 'git',
+    message: 'git rebase --continue/--skip/--abort should be run only with explicit approval.',
+  },
+  // ── GROUP B: docker subcommands ──
+  {
+    ruleId: 'block-docker-stop',
+    family: 'docker',
+    message: 'Direct container stop is blocked to protect services managed by Nomad.',
+  },
+  {
+    ruleId: 'block-docker-kill',
+    family: 'docker',
+    message: 'Direct container kill is blocked. Abrupt termination risks data loss.',
+  },
+  {
+    ruleId: 'block-docker-rm',
+    family: 'docker',
+    message: 'Direct container removal is blocked. Re-deploying via Nomad is safer.',
+  },
+  {
+    ruleId: 'block-docker-restart',
+    family: 'docker',
+    message: 'NEVER restart containers directly. This bypasses scheduling safety.',
+  },
+  {
+    ruleId: 'block-docker-exec',
+    family: 'docker',
+    message: 'Direct exec into containers is blocked for security.',
+  },
+  {
+    ruleId: 'block-docker-update',
+    family: 'docker',
+    message: 'Direct resource updates are blocked. Use Nomad job specification.',
+  },
+  {
+    ruleId: 'block-docker-rename',
+    family: 'docker',
+    message: 'Container renaming is blocked to prevent breaking service discovery.',
+  },
+  {
+    ruleId: 'block-docker-volume-rm-prune',
+    family: 'docker',
+    message: 'Direct volume removal is strictly blocked to prevent data loss.',
+  },
+  {
+    ruleId: 'block-docker-volume-create',
+    family: 'docker',
+    message: 'Manual volume creation is blocked to maintain infra-as-code parity.',
+  },
+  // ── GROUP C: docker compose carve-outs ──
+  {
+    ruleId: 'block-docker-compose-down-litellm',
+    family: 'docker',
+    message: 'NEVER bring down litellm/litellm-local/omniroute via docker compose.',
+  },
+  {
+    ruleId: 'block-docker-compose-rm-litellm',
+    family: 'docker',
+    message: 'NEVER remove litellm/litellm-local/omniroute containers via docker compose.',
+  },
+  {
+    ruleId: 'block-docker-compose-target-litellm',
+    family: 'docker',
+    message: 'NEVER stop litellm/litellm-local/omniroute via docker compose --target.',
+  },
+  // ── GROUP D: command-level ──
+  {
+    ruleId: 'block-bd-notes',
+    family: 'bd',
+    message: 'Use --append-notes instead to preserve existing notes.',
+    suggestions: ['bd --append-notes'],
+  },
+  // ── GROUP E: rm ──
+  {
+    ruleId: 'block-rm-bd-sub-skills',
+    family: 'rm',
+    message: "Removing deprecated bd sub-skill directories is blocked (rule is misnamed 'allow').",
+  },
+  {
+    ruleId: 'block-rm-beads-subdirs',
+    family: 'rm',
+    message: "Removing symlink subdirs in beads/ skill is blocked (rule is misnamed 'allow').",
+  },
+  // ── GROUP F: gh / glab ──
+  {
+    ruleId: 'block-gh-repo-delete-archive',
+    family: 'gh',
+    message: 'Destructive GitHub repository lifecycle actions are blocked by default.',
+  },
+  {
+    ruleId: 'block-gh-repo-public',
+    family: 'gh',
+    message: 'Public GitHub repository creation is blocked by default.',
+  },
+  {
+    ruleId: 'block-gh-repo-visibility',
+    family: 'gh',
+    message: 'GitHub repository visibility changes are blocked by default.',
+  },
+  {
+    ruleId: 'block-glab-repo-delete-archive',
+    family: 'glab',
+    message: 'Destructive GitLab repository lifecycle actions are blocked by default.',
+  },
+  {
+    ruleId: 'block-glab-repo-public',
+    family: 'glab',
+    message: 'Public GitLab repository creation is blocked by default.',
+  },
+];
+
+/** gcloud/bq produce sprintf messages — family inferred from program. */
+export function inferFamilyFromProgram(program: string): 'gcloud' | 'bq' | 'custom' {
+  switch (program) {
+    case 'gcloud':
+      return 'gcloud';
+    case 'bq':
+      return 'bq';
+    default:
+      return 'custom';
+  }
+}

package/src/rules/index.ts

@@ -0,0 +1,3 @@
+export { RuleRegistry } from './RuleRegistry.ts';
+export { RULES, inferFamilyFromProgram } from './catalog.ts';
+export type { RuleFamily, RuleMeta } from './RuleRegistry.ts';

package/src/util/digest.ts

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+/**
+ * Compute a SHA-256 hex prefix of file content for rulebook drift detection.
+ * @param path     file path to hash
+ * @param reader   optional reader override (testability)
+ * @returns first 12 hex chars, or 12 zeros if unreadable
+ */
+export function sha256Prefix(path: string, reader?: (p: string) => string): string {
+  const read = reader ?? ((p: string) => readFileSync(p, 'utf8'));
+  try {
+    const content = read(path);
+    return createHash('sha256').update(content).digest('hex').slice(0, 12);
+  } catch {
+    return '0'.repeat(12);
+  }
+}