npm - @proflandrigan/shards - Versions diffs - 1.1.0 - Mend

@proflandrigan/shards 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (397) hide show

package/tools/gate-hook/parser.js ADDED Viewed

@@ -0,0 +1,205 @@
+// Parse ::GATE:: ... ::ENDGATE:: fences from text
+'use strict';
+const path = require('path');
+// Matches ::GATE:: <attrs>\n<body>\n::ENDGATE::
+const FENCE = /^::GATE::\s+([^\n]+)\n([\s\S]*?)\n::ENDGATE::\s*$/gm;
+// Authoritative kind enum. See CLAUDE.md "The gate pattern" section.
+//   phase      — intermediate phase gate; advances phase on confirm.
+//   final      — last phase of a track; advances phase on confirm.
+//   checkpoint — mid-build component seam; does NOT advance phase. Advisory
+//                under SHARDS_CHECKPOINT_ENFORCE=0.
+//   execute    — runs an experiment/AR iteration; advances phase on confirm
+//                (labeled "Execute gate").
+//   confirm    — micro-confirmation checkpoint used in AR; does NOT advance
+//                phase. Advisory under SHARDS_CHECKPOINT_ENFORCE=0.
+//   handoff    — specialist-to-specialist transition; advances on confirm.
+const VALID_KINDS = new Set(['phase', 'final', 'checkpoint', 'execute', 'confirm', 'handoff']);
+// Kinds that behave like checkpoints (do not advance phase; advisory-eligible).
+const NON_ADVANCING_KINDS = new Set(['checkpoint', 'confirm']);
+function parseAttrs(line) {
+  const out = {};
+  for (const pair of line.trim().split(/\s+/)) {
+    const [k, v] = pair.split('=');
+    if (k && v) out[k] = v;
+  }
+  return out;
+}
+// Lazy require to avoid circular dependency on log.js (log.js does not require
+// parser, but defensive). Falls back to stderr-only logging if log.js fails
+// to load for any reason.
+function logUnknownKind(kindRaw, attrs) {
+  try {
+    process.stderr.write(`[shards gate-hook] warning: unknown gate kind '${kindRaw}' on gate id='${attrs.id || '<unknown>'}' — normalizing to 'phase'\n`);
+  } catch {}
+  try {
+    const { appendViolation } = require(path.join(__dirname, 'log.js'));
+    appendViolation({
+      type: 'unknown-gate-kind',
+      gate_id: attrs.id || null,
+      reason: `unknown gate kind '${kindRaw}' — normalized to 'phase'`,
+    });
+  } catch {
+    // logging is best-effort
+  }
+}
+// Validate and normalize the kind= attribute on a parsed gate. Unknown kinds
+// are normalized to 'phase' (backward-compatible) and a warning is logged.
+function normalizeKind(attrs) {
+  const raw = attrs.kind;
+  if (!raw) {
+    attrs.kind = 'phase';
+    return attrs;
+  }
+  if (VALID_KINDS.has(raw)) return attrs;
+  // Unknown kind — warn + normalize.
+  logUnknownKind(raw, attrs);
+  attrs.kind = 'phase';
+  return attrs;
+}
+// Pair-up ``` (or longer-backtick) lines into [start, end] character ranges so
+// gate markers that only appear inside a quoted markdown code block don't open
+// real gates. Without this, the assistant cannot quote a phase template or
+// explain the gate pattern in this repo without tripping enforcement.
+const CODE_FENCE_LINE = /^(`{3,})[^\n]*$/gm;
+function findCodeBlockRanges(text) {
+  const fences = [];
+  CODE_FENCE_LINE.lastIndex = 0;
+  let m;
+  while ((m = CODE_FENCE_LINE.exec(text)) !== null) {
+    fences.push({ start: m.index, end: m.index + m[0].length, ticks: m[1].length });
+  }
+  const ranges = [];
+  let i = 0;
+  while (i < fences.length) {
+    const open = fences[i];
+    // A closing fence must use the same number of backticks (CommonMark rule —
+    // longer-tick fences nest shorter ones). Find the next fence with matching
+    // tick count.
+    let j = i + 1;
+    while (j < fences.length && fences[j].ticks !== open.ticks) j++;
+    if (j < fences.length) {
+      ranges.push({ start: open.start, end: fences[j].end });
+      i = j + 1;
+    } else {
+      // Unclosed fence — treat rest of doc as inside-code, conservative.
+      ranges.push({ start: open.start, end: text.length });
+      break;
+    }
+  }
+  return ranges;
+}
+function isInsideAnyRange(idx, ranges) {
+  for (const r of ranges) if (idx >= r.start && idx < r.end) return true;
+  return false;
+}
+function parseGates(text) {
+  const gates = [];
+  const codeRanges = findCodeBlockRanges(text);
+  FENCE.lastIndex = 0;
+  let m;
+  while ((m = FENCE.exec(text)) !== null) {
+    if (isInsideAnyRange(m.index, codeRanges)) continue;
+    const attrs = normalizeKind(parseAttrs(m[1]));
+    gates.push({ attrs, body: m[2], raw: m[0], index: m.index, fenceEnd: m.index + m[0].length });
+  }
+  return gates;
+}
+// Violation heuristic: check for content after ::ENDGATE:: that looks like phase advance.
+// Patterns must be phase-specific — generic forward-looking prose ("moving on to wrap up
+// the docs") is a common legitimate sign-off and previously triggered false positives.
+const PHASE_ADVANCE_PATTERNS = [
+  /^##\s*Phase\s+\d+/im,
+  /^Phase\s+\d+\b/im,
+  /\bproceed(ing)?\s+to\s+phase\b/i,
+  /\bmoving\s+on\s+to\s+(the\s+next\s+phase|phase\s+\d+)\b/i,
+  /```(python|sql|bash)/i,
+];
+// Use the actual parsed fence end position so an ENDGATE token nested inside
+// an unclosed code block (which the FENCE regex would not match as a real
+// fence) does not confuse violation detection. Falls back to indexOf for
+// backward compat when no gates parsed.
+function checkViolation(fullMessage) {
+  const gates = parseGates(fullMessage);
+  let endIdx;
+  if (gates.length > 0) {
+    endIdx = gates[gates.length - 1].fenceEnd;
+  } else {
+    const literalIdx = fullMessage.indexOf('::ENDGATE::');
+    if (literalIdx === -1) return null;
+    endIdx = literalIdx + '::ENDGATE::'.length;
+  }
+  const postFence = fullMessage.slice(endIdx).trim();
+  const wordCount = postFence.split(/\s+/).filter(Boolean).length;
+  if (wordCount === 0) return null;
+  if (wordCount > 40) return 'Post-fence content exceeds 40-word limit (' + wordCount + ' words)';
+  for (const pattern of PHASE_ADVANCE_PATTERNS) {
+    if (pattern.test(postFence)) {
+      return 'Post-fence content matches phase-advance pattern: ' + pattern.toString();
+    }
+  }
+  return null;
+}
+// ─── Auto-verify markers ─────────────────────────────────────────────────────
+//
+// Open marker: ::AUTO-VERIFY:: <attrs>          (single-line, no fence body)
+// Close marker: ::ENDAUTO::                      (bare, no attrs)
+//
+// Example:
+//   ::AUTO-VERIFY:: agent=data-modeller phase=6 tool_budget=20 ttl_minutes=10
+//   ... read-only verification work ...
+//   ::ENDAUTO::
+const AUTO_OPEN = /^::AUTO-VERIFY::\s+([^\n]+)$/gm;
+const AUTO_CLOSE = /^::ENDAUTO::\s*$/gm;
+function parseAutoVerify(text) {
+  const opens = [];
+  AUTO_OPEN.lastIndex = 0;
+  let m;
+  while ((m = AUTO_OPEN.exec(text)) !== null) {
+    opens.push({ attrs: parseAttrs(m[1]), index: m.index });
+  }
+  // Process all close markers in position order — the prior implementation
+  // used .exec() which finds only the first, so a message with multiple
+  // close markers (e.g. open-close-open-close in one assistant turn) would
+  // miss the later closes.
+  const closes = [];
+  AUTO_CLOSE.lastIndex = 0;
+  let cm;
+  while ((cm = AUTO_CLOSE.exec(text)) !== null) {
+    closes.push({ index: cm.index });
+  }
+  return {
+    opens,
+    closes,
+    // Back-compat: keep `close` as the first close marker. Callers that need
+    // all markers should use `closes`.
+    close: closes.length > 0 ? closes[0] : null,
+  };
+}
+module.exports = {
+  parseGates,
+  checkViolation,
+  parseAutoVerify,
+  parseAttrs,
+  VALID_KINDS,
+  NON_ADVANCING_KINDS,
+};

package/tools/gate-hook/sql-guard.js ADDED Viewed

@@ -0,0 +1,230 @@
+// SELECT-only SQL guard for warehouse-CLI invocations.
+//
+// Default-deny posture: this module returns true ONLY for invocations it can
+// fully parse and confirm consist exclusively of SELECT/WITH statements. Any
+// ambiguity (unknown CLI, unparseable quoting, comment-smuggled DDL, etc.)
+// returns false and the call falls through to the normal permission prompt.
+'use strict';
+// ─── Step 1: extract the SQL argument from a CLI invocation ──────────────────
+// Recognized CLI invocation patterns. Each entry returns the SQL string or
+// null if the invocation isn't recognized / can't be parsed cleanly.
+function extractSql(command) {
+  if (typeof command !== 'string') return null;
+  const cmd = command.trim();
+  if (!cmd) return null;
+  // bq query — the SQL is whatever comes after the flags. Format:
+  //   bq query --use_legacy_sql=false 'SELECT ...'
+  //   bq query --nouse_legacy_sql --format=json "SELECT ..."
+  // We accept it only if the last token is a single quoted string and the
+  // command doesn't have --destination_table / write flags.
+  if (/^bq\s+query\b/.test(cmd)) {
+    if (/--destination_table\b/i.test(cmd)) return null;
+    if (/--replace\b/i.test(cmd)) return null;
+    if (/--append_table\b/i.test(cmd)) return null;
+    return extractTrailingQuoted(cmd);
+  }
+  // psql -c "SELECT ..."  or  psql --command="SELECT ..."
+  if (/^psql\b/.test(cmd)) {
+    return extractFlagValue(cmd, ['-c', '--command']);
+  }
+  // snowsql -q "SELECT ..."  or  snowsql --query "SELECT ..."
+  if (/^snowsql\b/.test(cmd)) {
+    return extractFlagValue(cmd, ['-q', '--query']);
+  }
+  // clickhouse-client --query "SELECT ..."  or  -q
+  if (/^clickhouse-client\b/.test(cmd)) {
+    return extractFlagValue(cmd, ['-q', '--query']);
+  }
+  // duckdb db.duckdb -c "SELECT ..."
+  if (/^duckdb\b/.test(cmd)) {
+    return extractFlagValue(cmd, ['-c', '--command']);
+  }
+  // mysql -e "SELECT ..."
+  if (/^mysql\b/.test(cmd)) {
+    return extractFlagValue(cmd, ['-e', '--execute']);
+  }
+  return null;
+}
+// Extract the value following one of the named flags. Handles both
+// --flag=value and --flag value forms, with single or double quoted values.
+// Returns null if it can't find a clean match.
+function extractFlagValue(command, flags) {
+  for (const flag of flags) {
+    // --flag="..."
+    const eqRe = new RegExp(`${escapeRegex(flag)}=(['"])([\\s\\S]*?)\\1(?:\\s|$)`);
+    const eq = command.match(eqRe);
+    if (eq) return eq[2];
+    // --flag '...'  or  --flag "..."
+    const spRe = new RegExp(`${escapeRegex(flag)}\\s+(['"])([\\s\\S]*?)\\1(?:\\s|$)`);
+    const sp = command.match(spRe);
+    if (sp) return sp[2];
+  }
+  return null;
+}
+// Extract the last quoted argument in the command. Used for `bq query '...'`.
+function extractTrailingQuoted(command) {
+  const m = command.match(/(['"])([\s\S]*?)\1\s*$/);
+  return m ? m[2] : null;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ─── Step 2: strip SQL comments ──────────────────────────────────────────────
+//
+// Strips both `-- line comments` and `/* block comments */` so that:
+// (a) a comment containing "DROP" doesn't trigger the deny check, and
+// (b) a comment can't smuggle a real DDL after a `;` (e.g. `SELECT 1; -- \n DROP TABLE x`)
+function stripComments(sql) {
+  if (typeof sql !== 'string') return '';
+  let out = '';
+  let i = 0;
+  let inSingle = false;
+  let inDouble = false;
+  while (i < sql.length) {
+    const c = sql[i];
+    const next = sql[i + 1];
+    if (!inSingle && !inDouble) {
+      if (c === '-' && next === '-') {
+        // Line comment — skip to newline
+        const nl = sql.indexOf('\n', i);
+        if (nl === -1) return out;
+        i = nl + 1;
+        out += '\n';
+        continue;
+      }
+      if (c === '/' && next === '*') {
+        // Block comment — skip to */
+        const end = sql.indexOf('*/', i + 2);
+        if (end === -1) return out; // unterminated block comment — bail
+        i = end + 2;
+        continue;
+      }
+    }
+    if (c === "'" && !inDouble) {
+      // Handle escaped quote ''
+      if (inSingle && next === "'") { out += "''"; i += 2; continue; }
+      inSingle = !inSingle;
+    } else if (c === '"' && !inSingle) {
+      inDouble = !inDouble;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+// ─── Step 3: split on ; respecting quotes ────────────────────────────────────
+function splitStatements(sql) {
+  const out = [];
+  let cur = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < sql.length; i++) {
+    const c = sql[i];
+    if (c === "'" && !inDouble) {
+      if (inSingle && sql[i + 1] === "'") { cur += "''"; i++; continue; }
+      inSingle = !inSingle;
+    } else if (c === '"' && !inSingle) {
+      inDouble = !inDouble;
+    }
+    if (c === ';' && !inSingle && !inDouble) {
+      out.push(cur);
+      cur = '';
+      continue;
+    }
+    cur += c;
+  }
+  if (cur.trim()) out.push(cur);
+  return out.map(s => s.trim()).filter(Boolean);
+}
+// ─── Step 4: classify a statement ────────────────────────────────────────────
+const FORBIDDEN = [
+  'INTO', 'INSERT', 'UPDATE', 'DELETE', 'MERGE', 'CREATE', 'DROP', 'ALTER',
+  'TRUNCATE', 'GRANT', 'REVOKE', 'COPY', 'CALL', 'EXECUTE', 'EXPORT', 'LOAD',
+  'REPLACE', 'RENAME', 'COMMENT', 'ANALYZE', 'VACUUM', 'CLUSTER', 'REFRESH',
+];
+function isReadOnlyStatement(stmt) {
+  if (!stmt) return false;
+  const head = stmt.replace(/^\(+/, '').match(/^\s*(\w+)/);
+  if (!head) return false;
+  const verb = head[1].toUpperCase();
+  if (verb !== 'SELECT' && verb !== 'WITH') return false;
+  // Check for forbidden keywords as whole words. We strip string literals
+  // first so a literal value like 'INSERT INTO logs' doesn't trigger.
+  const stripped = stripStringLiterals(stmt);
+  for (const kw of FORBIDDEN) {
+    const re = new RegExp(`\\b${kw}\\b`, 'i');
+    if (re.test(stripped)) return false;
+  }
+  return true;
+}
+function stripStringLiterals(sql) {
+  let out = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < sql.length; i++) {
+    const c = sql[i];
+    if (c === "'" && !inDouble) {
+      if (inSingle && sql[i + 1] === "'") { i++; continue; }
+      inSingle = !inSingle;
+      continue;
+    }
+    if (c === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+    if (inSingle || inDouble) continue;
+    out += c;
+  }
+  return out;
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+// isReadOnlyCliInvocation(command) → true only if:
+//   1. We recognize the CLI shape and can extract the SQL cleanly
+//   2. Every statement in the SQL starts with SELECT or WITH
+//   3. No statement contains any forbidden DDL/DML keyword (after stripping
+//      comments and string literals)
+function isReadOnlyCliInvocation(command) {
+  const sql = extractSql(command);
+  if (!sql) return false;
+  const stripped = stripComments(sql);
+  const statements = splitStatements(stripped);
+  if (statements.length === 0) return false;
+  return statements.every(isReadOnlyStatement);
+}
+module.exports = {
+  isReadOnlyCliInvocation,
+  // exported for tests
+  _extractSql: extractSql,
+  _stripComments: stripComments,
+  _splitStatements: splitStatements,
+  _isReadOnlyStatement: isReadOnlyStatement,
+};

package/tools/gate-hook/state.js ADDED Viewed

@@ -0,0 +1,170 @@
+// Gate state read/write for .shards/gates/state.json
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const GATE_DIR = path.join(process.cwd(), '.shards', 'gates');
+const STATE = path.join(GATE_DIR, 'state.json');
+// On-disk v2 shape:
+//   { version: 2, sessions: { "<sessionId>": { open, id, phase, kind, agent,
+//     opened_at, opened_in_turn, transcript_ref } }, history: [ ... ] }
+//
+// `history` is a SHARED, append-only array of closed/swept/force-closed gates
+// from every session. Each session slot holds at most one open gate; a closed
+// slot is simply absent (treat missing as closed).
+//
+// Legacy v1 shape was a single global slot: { open, id, phase, kind, agent,
+// opened_at, ..., history }. read() upgrades that to v2 in memory so an in-
+// flight gate during the format upgrade still enforces.
+// Stable key for a legacy OPEN gate that has no session attribution. We use the
+// gate's `agent` field when present (matches handleStop's `agent || sessionId`
+// fallback) so the next confirm/sweep can find it, else the literal sentinel.
+const LEGACY_KEY = '__legacy__';
+function ensureDir() {
+  // `recursive: true` is idempotent — safe even if a concurrent writer just
+  // created the directory between calls.
+  fs.mkdirSync(GATE_DIR, { recursive: true });
+}
+// Normalize any parsed object into the canonical v2 shape. Backward-compatible:
+// a legacy single-slot object (no `version`/`sessions`, has top-level `open`)
+// is transparently upgraded in memory. A legacy OPEN gate is placed under the
+// gate's `agent` field if present, else LEGACY_KEY, so it still enforces.
+function normalize(obj) {
+  if (!obj || typeof obj !== 'object') {
+    return { version: 2, sessions: {}, history: [] };
+  }
+  // Already v2 — just backfill missing collections defensively.
+  if (obj.version === 2 || obj.sessions) {
+    return {
+      version: 2,
+      sessions: (obj.sessions && typeof obj.sessions === 'object') ? obj.sessions : {},
+      history: Array.isArray(obj.history) ? obj.history : [],
+    };
+  }
+  // Legacy single-slot upgrade.
+  const history = Array.isArray(obj.history) ? obj.history : [];
+  const sessions = {};
+  if (obj.open) {
+    const key = obj.agent || LEGACY_KEY;
+    sessions[key] = {
+      open: true,
+      id: obj.id,
+      phase: typeof obj.phase !== 'undefined' ? obj.phase : null,
+      kind: obj.kind || null,
+      agent: obj.agent || null,
+      opened_at: obj.opened_at || null,
+      opened_in_turn: typeof obj.opened_in_turn !== 'undefined' ? obj.opened_in_turn : null,
+      transcript_ref: typeof obj.transcript_ref !== 'undefined' ? obj.transcript_ref : null,
+    };
+  }
+  return { version: 2, sessions, history };
+}
+function read() {
+  try {
+    return normalize(JSON.parse(fs.readFileSync(STATE, 'utf8')));
+  } catch {
+    return { version: 2, sessions: {}, history: [] };
+  }
+}
+// Atomic write via tmp + rename. Reference: src/ui/session-index.js.
+// Three concurrent readers (UI 2s poll, /chat/end snapshot, gate-hook's own
+// pre-tool-use/user-prompt-submit handlers) can hit during a bare writeFileSync
+// and observe a partial file → JSON.parse throws → read() silently returns
+// default closed state. tmp+rename ensures readers always see the full
+// previous or the full next content.
+//
+// Unique per-PID tmp name avoids same-PID collisions (multiple hook
+// invocations chained on the same process aren't expected, but the cost is
+// negligible and it matches the session-index.js reference primitive).
+function write(s) {
+  ensureDir();
+  const tmp = `${STATE}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(s, null, 2));
+    fs.renameSync(tmp, STATE);
+  } catch (err) {
+    // Best-effort cleanup so a failed write doesn't leak per-writer tmps.
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+// ─── Per-session helpers ──────────────────────────────────────────────────────
+// The gate object for one session, or a closed sentinel if that slot is absent.
+//
+// Backward-compat: a legacy single-slot gate that was upgraded with no agent
+// attribution lives under LEGACY_KEY. Since the original v1 slot was global
+// (it blocked whichever session was active), we fall back to that LEGACY_KEY
+// slot for ANY session that has no slot of its own — so an in-flight gate
+// during the format upgrade keeps enforcing regardless of session_id.
+function getGate(state, sessionId) {
+  const sessions = (state && state.sessions) || {};
+  const slot = sessions[sessionId];
+  if (slot && slot.open) return slot;
+  if (sessionId !== LEGACY_KEY) {
+    const legacy = sessions[LEGACY_KEY];
+    if (legacy && legacy.open) return legacy;
+  }
+  return { open: false };
+}
+// Return a NEW state object with `sessionId`'s slot set to `gate`. Does not
+// mutate the input; preserves `history` and all other sessions.
+function setGate(state, sessionId, gate) {
+  const base = normalize(state);
+  return {
+    version: 2,
+    sessions: { ...base.sessions, [sessionId]: gate },
+    history: base.history,
+  };
+}
+// Return a NEW state object with `sessionId`'s slot removed (closed). History
+// and other sessions preserved.
+function clearGate(state, sessionId) {
+  const base = normalize(state);
+  const sessions = { ...base.sessions };
+  delete sessions[sessionId];
+  return { version: 2, sessions, history: base.history };
+}
+// True if any session slot is currently open.
+function anyOpen(state) {
+  const base = normalize(state);
+  return Object.values(base.sessions).some(g => g && g.open);
+}
+// The most-recently-opened still-open gate across all sessions (by opened_at),
+// or null. Used by the UI read side to reduce the per-session map to a single
+// flat gate for the legacy browser contract.
+function firstOpen(state) {
+  const base = normalize(state);
+  let best = null;
+  let bestT = -Infinity;
+  for (const [sessionId, g] of Object.entries(base.sessions)) {
+    if (!g || !g.open) continue;
+    const t = g.opened_at ? Date.parse(g.opened_at) : NaN;
+    const score = Number.isNaN(t) ? -Infinity : t;
+    // Prefer the most recent; a gate with no/invalid opened_at still wins over
+    // nothing (best === null) but loses to any dated gate.
+    if (best === null || score > bestT) {
+      best = { sessionId, ...g };
+      bestT = score;
+    }
+  }
+  return best;
+}
+module.exports = {
+  read, write, STATE, GATE_DIR,
+  getGate, setGate, clearGate, anyOpen, firstOpen,
+  LEGACY_KEY,
+};