ai-install-guard 0.0.0 → 0.2.0

package/hooks/scan/checks/text.ts

@@ -0,0 +1,362 @@
+const EXCERPT_WIDTH = 100
+
+export type Match = {
+  /** Where the match starts in the text. */
+  index: number
+  line: number
+  /** The matched text. */
+  text: string
+  /** A short window of the line around the match, for evidence. */
+  excerpt: string
+}
+
+/**
+ * Every match of `pattern` in `text`, with 1-based line numbers, up to
+ * `limit` of those `keep` accepts. Rejected matches are skipped before they
+ * count, so no number of decoys can use up the limit.
+ */
+export function findAll(text: string, pattern: RegExp, limit = 20, keep?: (index: number) => boolean): Match[] {
+  const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`
+  const global = new RegExp(pattern.source, flags)
+  const starts = lineStarts(text)
+  const matches: Match[] = []
+  for (const found of text.matchAll(global)) {
+    const index = found.index ?? 0
+    if (keep !== undefined && !keep(index)) {
+      if (found[0].length === 0) global.lastIndex += 1
+      continue
+    }
+    const line = lineAt(starts, index)
+    const lineStart = starts[line - 1] as number
+    const lineEnd = line < starts.length ? (starts[line] as number) - 1 : text.length
+    // Only a window around the match is copied, so a match on a huge line stays cheap.
+    const from = Math.max(lineStart, index - EXCERPT_WIDTH)
+    const to = Math.min(lineEnd, index + found[0].length + EXCERPT_WIDTH)
+    const window = text.slice(from, to)
+    const cut = excerpt(window, index - from, found[0].length)
+    matches.push({ index, line, text: found[0], excerpt: `${from > lineStart && !cut.startsWith('…') ? '…' : ''}${cut}${to < lineEnd && !cut.endsWith('…') ? '…' : ''}` })
+    if (matches.length >= limit) break
+    if (found[0].length === 0) global.lastIndex += 1
+  }
+  return matches
+}
+
+/** The first match, or undefined. */
+export function findFirst(text: string, pattern: RegExp): Match | undefined {
+  return findAll(text, pattern, 1)[0]
+}
+
+/** The 1-based line holding `needle`, or undefined. */
+export function lineOf(text: string, needle: string): number | undefined {
+  const index = text.indexOf(needle)
+  return index === -1 ? undefined : lineAt(lineStarts(text), index)
+}
+
+/** A window of `line` around [start, start + length), trimmed and marked with … where cut. */
+export function excerpt(line: string, start = 0, length = 0): string {
+  const trimmed = line.replace(/\r$/, '')
+  if (trimmed.length <= EXCERPT_WIDTH) {
+    return trimmed.trim()
+  }
+  const center = start + Math.floor(length / 2)
+  const from = Math.max(0, Math.min(center - EXCERPT_WIDTH / 2, trimmed.length - EXCERPT_WIDTH))
+  const to = from + EXCERPT_WIDTH
+  return `${from > 0 ? '…' : ''}${trimmed.slice(from, to).trim()}${to < trimmed.length ? '…' : ''}`
+}
+
+function lineStarts(text: string): number[] {
+  const starts = [0]
+  for (let i = 0; i < text.length; i += 1) {
+    if (text.charCodeAt(i) === 10) starts.push(i + 1)
+  }
+  return starts
+}
+
+function lineAt(starts: readonly number[], index: number): number {
+  let low = 0
+  let high = starts.length - 1
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2)
+    if ((starts[mid] as number) <= index) low = mid
+    else high = mid - 1
+  }
+  return low + 1
+}
+
+/** `a/b` + `../c` → `c`; undefined when the path climbs out of the root. */
+export function joinPath(dir: string, rel: string): string | undefined {
+  const parts = rel.startsWith('/') ? [] : dir.split('/').filter(part => part !== '')
+  for (const part of rel.split('/')) {
+    if (part === '..') {
+      if (parts.length === 0) return undefined
+      parts.pop()
+    } else if (part !== '.' && part !== '') {
+      parts.push(part)
+    }
+  }
+  return parts.join('/')
+}
+
+export function dirname(path: string): string {
+  const slash = path.lastIndexOf('/')
+  return slash === -1 ? '' : path.slice(0, slash)
+}
+
+export function basename(path: string): string {
+  return path.slice(path.lastIndexOf('/') + 1)
+}
+
+export function extension(path: string): string {
+  const name = basename(path)
+  const dot = name.lastIndexOf('.')
+  return dot <= 0 ? '' : name.slice(dot + 1).toLowerCase()
+}
+
+/**
+ * `comment` is a comment that fills its line from the start; `trailing-comment`
+ * starts after code on its line. The tokenizer can be fooled, and a comment
+ * hiding a command is a classic trick, so only a whole-line comment is fully
+ * trusted to be inert.
+ */
+export type SpanKind = 'code' | 'string' | 'comment' | 'trailing-comment' | 'regex'
+
+/**
+ * What each character of a source file is: code, inside a string, a
+ * comment or (in JavaScript) a regular expression literal. A lightweight
+ * tokenizer, good enough to tell a pattern or a remark about `.ssh` from code
+ * that opens it.
+ */
+export function spanKinds(text: string, language: 'js' | 'python' | 'shell' | 'other'): (index: number) => SpanKind {
+  const kinds = new Uint8Array(text.length)
+  const CODE = 0
+  const STRING = 1
+  const COMMENT = 2
+  const REGEX = 3
+  const TRAILING = 4
+  const mark = (from: number, to: number, kind: number): void => {
+    kinds.fill(kind, from, Math.min(to, text.length))
+  }
+  // What ends a line comment: JavaScript also ends one at a lone CR, U+2028
+  // and U+2029, Python at a lone CR. Missing one would read a whole
+  // CR-only file as one comment.
+  const isLineEnd = (char: string | undefined): boolean =>
+    char === '\n' || (language !== 'shell' && char === '\r') || (language === 'js' && (char === '\u2028' || char === '\u2029'))
+  const lineEndFrom = (from: number): number => {
+    let j = from
+    while (j < text.length && !isLineEnd(text[j])) j += 1
+    return j
+  }
+  // Whether anything but blanks came earlier on the current line, kept as
+  // the scan goes, so telling a whole-line comment from a trailing one is
+  // constant time however many comments share a line.
+  let lineHasCode = false
+  const commentKind = (): number => (lineHasCode ? TRAILING : COMMENT)
+
+  let i = 0
+  let lastSignificant = ''
+  let lastWord = ''
+  // After a `/` that opened no literal on its line, the rest of that line is
+  // not tried again: one pass per line, so `[/[/[/...` cannot stall the scan.
+  let noRegexBefore = 0
+  // Which `(` were opened by if, while, for or with: after their `)` a
+  // statement starts, so a slash there opens a pattern, not a division.
+  const parens: boolean[] = []
+
+  while (i < text.length) {
+    const char = text[i] as string
+    const next = text[i + 1]
+    if (isLineEnd(char)) {
+      lineHasCode = false
+      i += 1
+      continue
+    }
+    if (language === 'js' && char === '/' && next === '/') {
+      const stop = lineEndFrom(i)
+      mark(i, stop, commentKind())
+      i = stop
+      continue
+    }
+    if (language === 'js' && char === '/' && next === '*') {
+      const close = text.indexOf('*/', i + 2)
+      const stop = close === -1 ? text.length : close + 2
+      mark(i, stop, commentKind())
+      // A block comment may end mid-line: what follows on that line is code.
+      if (text.slice(i, stop).includes('\n')) lineHasCode = false
+      i = stop
+      continue
+    }
+    // In shell, `#` starts a comment only at the start of a word: after an
+    // unescaped blank (`echo \ #` keeps the `#` in the word) or a line start.
+    const isShellComment = language === 'shell' && (i === 0 || (/\s/.test(text[i - 1] as string) && text[i - 2] !== '\\'))
+    if (char === '#' && (language === 'python' || isShellComment)) {
+      const stop = lineEndFrom(i)
+      mark(i, stop, commentKind())
+      i = stop
+      continue
+    }
+    if (/[ \t\f\v]/.test(char)) {
+      i += 1
+      continue
+    }
+    lineHasCode = true
+    // In shell a backslash escapes the next character outside strings too:
+    // `\'` is a quote character, not the start of a string.
+    if (language === 'shell' && char === '\\') {
+      i += 2
+      lastSignificant = 'a'
+      continue
+    }
+    if (char === '`' && language === 'js') {
+      // A template literal: its text is a string, each `${...}` inside it is
+      // code (and may hold strings and templates of its own).
+      i = templateEnd(text, i, mark, STRING, CODE)
+      lastSignificant = '`'
+      continue
+    }
+    if (char === '"' || char === "'") {
+      const triple = language === 'python' && text.startsWith(char.repeat(3), i)
+      const quote = triple ? char.repeat(3) : char
+      let j = i + quote.length
+      while (j < text.length) {
+        // A backslash escapes in every string but a shell's plain single-quoted
+        // one; in a shell `$'...'` string it escapes again.
+        if (text[j] === '\\' && !(language === 'shell' && char === "'" && text[i - 1] !== '$')) {
+          j += 2
+          continue
+        }
+        if (text.startsWith(quote, j)) {
+          j += quote.length
+          break
+        }
+        if (!triple && text[j] === '\n' && language !== 'shell') break
+        j += 1
+      }
+      mark(i, j, STRING)
+      i = j
+      lastSignificant = char
+      continue
+    }
+    if (language === 'js' && char === '/' && i >= noRegexBefore && regexCanStart(lastSignificant, lastWord)) {
+      let j = i + 1
+      let inClass = false
+      while (j < text.length && !isLineEnd(text[j])) {
+        if (text[j] === '\\') {
+          j += 2
+          continue
+        }
+        if (text[j] === '[') inClass = true
+        else if (text[j] === ']') inClass = false
+        else if (text[j] === '/' && !inClass) break
+        j += 1
+      }
+      if (text[j] === '/') {
+        // The literal is skipped as one unit either way, so a `/*` inside it
+        // never opens a comment. Only one with an escape counts as a pattern;
+        // without one, what it holds is judged as code.
+        const isPattern = text.slice(i + 1, j).includes('\\')
+        j += 1
+        while (j < text.length && /[a-z]/i.test(text[j] as string)) j += 1
+        mark(i, j, isPattern ? REGEX : CODE)
+        i = j
+        lastSignificant = '/'
+        continue
+      }
+      noRegexBefore = j
+    }
+    const before = lastSignificant
+    // `x++ / y` and `x-- / y` divide: a postfix operator ends an operand.
+    lastSignificant = (char === '+' || char === '-') && text[i - 1] === char ? 'a' : char
+    if (char === '(') parens.push(/^(?:if|while|for|with)$/.test(lastWord))
+    if (char === ')' && parens.pop() === true) lastSignificant = ';'
+    if (/[A-Za-z_$]/.test(char)) {
+      let j = i
+      while (j < text.length && /[\w$]/.test(text[j] as string)) j += 1
+      // `obj.in` or `x.return` is a property, an operand, never a keyword.
+      lastWord = before === '.' ? '' : text.slice(i, j)
+      lastSignificant = 'a'
+      i = j
+      continue
+    }
+    lastWord = ''
+    i += 1
+  }
+  return index => (['code', 'string', 'comment', 'regex', 'trailing-comment'] as const)[kinds[index] ?? CODE] as SpanKind
+}
+
+/**
+ * Marks a template literal starting at `start` (its backtick) and returns the
+ * index after its closing backtick: text as `string`, each `${...}` as `code`,
+ * with nested quotes and templates inside an interpolation skipped whole.
+ */
+const MAX_TEMPLATE_DEPTH = 32
+
+function templateEnd(text: string, start: number, mark: (from: number, to: number, kind: number) => void, STRING: number, CODE: number, depth = 0): number {
+  // Nested deeper than any real code: the rest is judged as code, never hidden.
+  if (depth > MAX_TEMPLATE_DEPTH) {
+    mark(start, text.length, CODE)
+    return text.length
+  }
+  let j = start + 1
+  let segment = start
+  while (j < text.length) {
+    if (text[j] === '\\') {
+      j += 2
+      continue
+    }
+    if (text[j] === '`') {
+      mark(segment, j + 1, STRING)
+      return j + 1
+    }
+    if (text[j] === '$' && text[j + 1] === '{') {
+      mark(segment, j + 2, STRING)
+      const close = interpolationEnd(text, j + 2, mark, STRING, CODE, depth + 1)
+      j = close + 1
+      segment = j
+      continue
+    }
+    j += 1
+  }
+  mark(segment, text.length, STRING)
+  return text.length
+}
+
+/** The index of the `}` closing an interpolation opened just before `start`. */
+function interpolationEnd(text: string, start: number, mark: (from: number, to: number, kind: number) => void, STRING: number, CODE: number, nesting: number): number {
+  let depth = 1
+  let j = start
+  let codeFrom = start
+  while (j < text.length) {
+    const char = text[j]
+    if (char === '`') {
+      mark(codeFrom, j, CODE)
+      j = templateEnd(text, j, mark, STRING, CODE, nesting + 1)
+      codeFrom = j
+      continue
+    }
+    if (char === '"' || char === "'") {
+      let k = j + 1
+      while (k < text.length && text[k] !== char && text[k] !== '\n') k += text[k] === '\\' ? 2 : 1
+      j = k + 1
+      continue
+    }
+    if (char === '{') depth += 1
+    if (char === '}') {
+      depth -= 1
+      if (depth === 0) {
+        mark(codeFrom, j, CODE)
+        return j
+      }
+    }
+    j += 1
+  }
+  mark(codeFrom, text.length, CODE)
+  return text.length
+}
+
+function regexCanStart(lastSignificant: string, lastWord: string): boolean {
+  if (lastSignificant === '') return true
+  if (lastSignificant === 'a') return /^(?:return|typeof|case|do|else|in|of|new|delete|void|throw|yield|await|instanceof)$/.test(lastWord)
+  // Not after `)`, `]` or `}`: there a slash divides, and reading code as a
+  // pattern would hide it.
+  return /[(,=:[!&|?{;+\-*%<>~^]/.test(lastSignificant)
+}

package/hooks/scan/checks/types.ts

@@ -0,0 +1,105 @@
+import { redactSecrets } from './patterns'
+
+export type Status = 'pass' | 'warn' | 'fail' | 'info'
+
+export type Severity = 'none' | 'low' | 'medium' | 'high' | 'critical'
+
+export type GroupId =
+  | 'provenance'
+  | 'structure'
+  | 'mod'
+  | 'hooks'
+  | 'mcp'
+  | 'prompts'
+  | 'code'
+  | 'secrets'
+  | 'quality'
+  | 'update'
+
+/** The report's groups, in the order it shows them. */
+export const GROUPS: readonly { id: GroupId; title: string }[] = [
+  { id: 'provenance', title: 'Provenance and trust' },
+  { id: 'structure', title: 'Structure and manifest' },
+  { id: 'mod', title: 'Mod capabilities' },
+  { id: 'hooks', title: 'Classic hooks' },
+  { id: 'mcp', title: 'MCP servers' },
+  { id: 'prompts', title: 'Skills, commands and agents' },
+  { id: 'code', title: 'Code patterns' },
+  { id: 'secrets', title: 'Committed secrets' },
+  { id: 'quality', title: 'Quality signals' },
+  { id: 'update', title: 'New since the version you approved' },
+]
+
+/**
+ * One place a check points at. `excerpt` is quoted from the candidate and is
+ * untrusted: reports pass it through `safeText` and never render it as
+ * markup. `status` says how bad this one place is, when a row mixes them.
+ */
+export type Evidence = {
+  file: string
+  line?: number
+  excerpt: string
+  status?: Status
+}
+
+export type CheckResult = {
+  id: string
+  group: GroupId
+  title: string
+  status: Status
+  severity: Severity
+  evidence: Evidence[]
+  advice: string
+  /**
+   * What the evidence means, in plain words for a person: a headline, then a
+   * few lines. Shown before the evidence, which stays one step further in.
+   */
+  summary?: string[]
+}
+
+const RANK: Record<Status, number> = { info: 0, pass: 1, warn: 2, fail: 3 }
+
+/** The worse of two statuses: fail > warn > pass > info. */
+export function worse(a: Status, b: Status): Status {
+  return RANK[a] >= RANK[b] ? a : b
+}
+
+export function rankOf(status: Status): number {
+  return RANK[status]
+}
+
+export function severityFor(status: Status): Severity {
+  return status === 'fail' ? 'high' : status === 'warn' ? 'medium' : 'none'
+}
+
+/**
+ * At most `max` pieces of evidence, the worst first, and a line counting the
+ * rest. Every piece is judged before capping, so a late failure still counts.
+ */
+export function capEvidence(evidence: Evidence[], max: number, fallback: Status = 'warn'): Evidence[] {
+  if (evidence.length <= max) return evidence
+  const worstFirst = [...evidence].sort((a, b) => RANK[b.status ?? fallback] - RANK[a.status ?? fallback])
+  return [...worstFirst.slice(0, max), { file: '-', excerpt: `and ${evidence.length - max} more`, status: 'info' }]
+}
+
+/**
+ * Builds a check's row from its evidence: the row takes the worst status any
+ * piece of evidence carries (`fallback` when none does), and `pass` when
+ * there is no evidence at all.
+ */
+export function row(
+  base: { id: string; group: GroupId; title: string; advice: string; summary?: string[] },
+  evidence: Evidence[],
+  fallback: Status = 'warn',
+  severity?: Severity,
+): CheckResult {
+  if (evidence.length === 0) {
+    const { summary: _unused, ...rest } = base
+    return { ...rest, status: 'pass', severity: 'none', evidence: [] }
+  }
+  const status = evidence.reduce<Status>((acc, item) => worse(acc, item.status ?? fallback), 'info')
+  const worstFirst = [...evidence]
+    .sort((a, b) => RANK[b.status ?? fallback] - RANK[a.status ?? fallback])
+    .map(item => ({ ...item, excerpt: redactSecrets(item.excerpt) }))
+  return { ...base, status, severity: severity ?? severityFor(status), evidence: worstFirst }
+}

package/hooks/scan/checks/validator.ts

@@ -0,0 +1,111 @@
+import type { Host } from '../host'
+import { isRecord, parseJson } from './context'
+
+export type ValidatorProblem = { file: string; message: string }
+
+export type ValidatorReport =
+  | {
+      ran: true
+      errors: ValidatorProblem[]
+      warnings: ValidatorProblem[]
+      /** Per module: the events it hooks and the `$` calls it makes, as Claude Code reads them. */
+      modules: { module: string; hooks: string[]; calls: string[] }[]
+    }
+  | { ran: false; reason: string }
+
+const TIMEOUT_MS = 60_000
+
+/**
+ * Runs `claude plugin validate --json` on the candidate. It reads the
+ * manifest and the hooks module's source the way Claude Code will and runs
+ * none of it, so it is the one external tool the scan uses on a candidate.
+ */
+export async function runValidator(host: Host, root: string): Promise<ValidatorReport> {
+  const result = await host
+    .run(['claude', 'plugin', 'validate', '--json', root], { timeoutMs: TIMEOUT_MS })
+    .catch((error: unknown) => ({ exitCode: -1, stdout: '', stderr: error instanceof Error ? error.message : String(error) }))
+  const parsed = parseJson(result.stdout)
+  // Only a report shaped like one counts: an error object is not a pass.
+  const isReport = parsed.ok && isRecord(parsed.value) && typeof parsed.value.success === 'boolean' && ('manifest' in parsed.value || 'contents' in parsed.value)
+  if (!isReport || !parsed.ok || !isRecord(parsed.value)) {
+    const reason = result.stderr.trim().split('\n')[0] ?? ''
+    return { ran: false, reason: reason === '' ? `exit code ${result.exitCode}` : reason.slice(0, 200) }
+  }
+  const report = relativeTo(root, parseValidatorReport(parsed.value))
+  if (report.ran && parsed.value.success === false && report.errors.length === 0) {
+    report.errors.push({ file: '-', message: `claude plugin validate failed (exit code ${result.exitCode})` })
+  }
+  return report
+}
+
+export function parseValidatorReport(report: Record<string, unknown>): ValidatorReport {
+  const errors: ValidatorProblem[] = []
+  const warnings: ValidatorProblem[] = []
+  const modules: { module: string; hooks: string[]; calls: string[] }[] = []
+  const sections = [report.manifest, ...(Array.isArray(report.contents) ? report.contents : [])]
+  for (const section of sections) {
+    if (!isRecord(section)) continue
+    const file = typeof section.file === 'string' ? section.file : '-'
+    for (const item of Array.isArray(section.errors) ? section.errors : []) errors.push(problem(file, item))
+    for (const item of Array.isArray(section.warnings) ? section.warnings : []) warnings.push(problem(file, item))
+    for (const note of Array.isArray(section.notes) ? section.notes : []) {
+      if (typeof note !== 'string') continue
+      const hooks = /^(\S+) hooks: (.*)$/.exec(note)
+      const calls = /^(\S+) calls: (.*)$/.exec(note)
+      const match = hooks ?? calls
+      if (match === null) continue
+      const name = match[1] as string
+      let entry = modules.find(item => item.module === name)
+      if (entry === undefined) {
+        entry = { module: name, hooks: [], calls: [] }
+        modules.push(entry)
+      }
+      const list = splitList(match[2] as string)
+      if (hooks !== null) entry.hooks.push(...list)
+      else entry.calls.push(...list.map(call => call.replace(/^\$\./, '').replace(/\s*\(via [^)]*\)$/, '')))
+    }
+  }
+  return { ran: true, errors, warnings, modules }
+}
+
+function problem(file: string, item: unknown): ValidatorProblem {
+  if (typeof item === 'string') return { file, message: item }
+  if (isRecord(item)) {
+    const path = typeof item.path === 'string' && item.path !== '' ? `${item.path}: ` : ''
+    return { file, message: `${path}${typeof item.message === 'string' ? item.message : JSON.stringify(item)}` }
+  }
+  return { file, message: String(item) }
+}
+
+/** Splits `a, b{x=1, y=2}, c` on top-level commas. */
+function splitList(text: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let current = ''
+  for (const char of text) {
+    if (char === '{' || char === '(') depth += 1
+    if (char === '}' || char === ')') depth -= 1
+    if (char === ',' && depth === 0) {
+      if (current.trim() !== '') out.push(current.trim())
+      current = ''
+    } else {
+      current += char
+    }
+  }
+  if (current.trim() !== '') out.push(current.trim())
+  return out
+}
+
+/**
+ * The report with the scanned folder's own path taken out of file names and
+ * messages: a remote scan's folder is a temporary one, and every other place
+ * in the report is relative to the candidate.
+ */
+function relativeTo(root: string, report: ValidatorReport): ValidatorReport {
+  if (!report.ran) return report
+  const roots = [root, `/private${root}`].map(path => path.replace(/\/+$/, ''))
+  const strip = (text: string): string =>
+    roots.reduce((out, path) => out.split(`${path}/`).join('').split(path).join('.'), text)
+  const fix = (item: ValidatorProblem): ValidatorProblem => ({ file: strip(item.file), message: strip(item.message) })
+  return { ...report, errors: report.errors.map(fix), warnings: report.warnings.map(fix) }
+}