@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/trace/events.ts

@@ -0,0 +1,102 @@
+/**
+ * Trace events and hooks: the machine's observation and interception API.
+ *
+ * Events are emitted synchronously in execution order. "pid" fields are the
+ * VM's virtual shell-process ids (`$BASHPID` inside the VM); real OS pids of
+ * external commands appear as `osPid` on `command:spawn`.
+ */
+
+import type { Span } from '../parser/ast.ts'
+import type { Channel } from '../vm/io.ts'
+import type { Effect } from '../policy/effects.ts'
+import type { PolicyFinding } from '../policy/policy.ts'
+
+export type CommandKind = 'builtin' | 'function' | 'external' | 'assignment' | 'not-found'
+
+/** `script`: a nested `bash -c` / `bash file` executed inside the VM. */
+export type SubshellReason = 'subshell' | 'pipeline' | 'cmdsubst' | 'procsubst' | 'background' | 'script'
+
+export interface RedirectInfo {
+  fd: number
+  op: string
+  /** Target path for file redirections. */
+  path?: string
+  /** Target fd for duplications. */
+  dupFd?: number
+}
+
+export type TraceEvent =
+  | { type: 'run:start'; runId: number; pid: number }
+  | { type: 'run:end'; runId: number; status: number }
+  /** Before any command node (simple or compound) executes, like bash's DEBUG trap. */
+  | { type: 'step'; nodeId: number; span: Span; line: number; node: string; pid: number; depth: number }
+  | {
+    type: 'command:start'
+    execId: number
+    nodeId: number
+    span: Span
+    argv: string[]
+    kind: CommandKind
+    /** Resolved executable path for external commands. */
+    path?: string
+    cwd: string
+    pid: number
+    redirects: RedirectInfo[]
+    /** 1-based line of the command in its source. */
+    line?: number
+  }
+  | { type: 'command:spawn'; execId: number; osPid: number | undefined }
+  | { type: 'command:end'; execId: number; nodeId: number; status: number; signal?: string; durationMs: number }
+  | { type: 'command:denied'; execId: number; nodeId: number; argv: string[]; reason: string; findings: PolicyFinding[] }
+  | { type: 'subshell:start'; pid: number; parentPid: number; nodeId: number; reason: SubshellReason }
+  | { type: 'subshell:end'; pid: number; status: number }
+  | { type: 'loop:iteration'; nodeId: number; iteration: number; variable?: string; value?: string; pid: number }
+  | { type: 'branch'; nodeId: number; taken: number | 'else' | 'none'; pid: number }
+  | { type: 'function:enter'; name: string; nodeId: number; pid: number; args: string[] }
+  | { type: 'function:exit'; name: string; status: number; pid: number }
+  | { type: 'assign'; name: string; value: string; pid: number; nodeId: number }
+  | { type: 'channel:open'; channel: Channel }
+  | { type: 'data'; channel: Channel; direction: 'write' | 'read'; bytes: Uint8Array }
+  | { type: 'job:start'; jobPid: number; nodeId: number }
+  | { type: 'job:end'; jobPid: number; status: number }
+  | { type: 'error'; message: string; nodeId?: number; pid: number }
+
+export type TraceListener = (event: TraceEvent) => void
+
+/** What a `beforeCommand` hook sees. */
+export interface CommandContext {
+  execId: number
+  nodeId: number
+  span: Span
+  /** The source text of the command (before expansion). */
+  text: string
+  argv: string[]
+  kind: CommandKind
+  path?: string
+  cwd: string
+  env: Readonly<Record<string, string>>
+  /** Effects predicted by the behavior definition (or derived from redirections). */
+  effects: Effect[]
+  /** Whether the behavior definition fully describes the command's effects. */
+  effectsComplete: boolean
+  /** The policy's verdict on those effects. */
+  findings: PolicyFinding[]
+  /** The machine's default decision given policy settings. */
+  decision: 'allow' | 'deny'
+  pid: number
+}
+
+export type HookDecision =
+  | { action: 'allow' }
+  | { action: 'deny'; reason: string; status?: number }
+  /** Abort the whole run (exit status 126 unless given). */
+  | { action: 'abort'; reason: string; status?: number }
+  /** Do not execute; pretend the command ran with this output. */
+  | { action: 'simulate'; stdout?: string; stderr?: string; status?: number }
+
+export interface Hooks {
+  /** Called before every command runs (after expansion, after policy assessment). May veto or simulate. */
+  beforeCommand?(ctx: CommandContext): HookDecision | void | Promise<HookDecision | void>
+  /** Called after a command finishes. */
+  afterCommand?(ctx: CommandContext, status: number): void | Promise<void>
+}

package/src/trace/progress.ts

@@ -0,0 +1,119 @@
+/**
+ * Progress tracking: folds trace events (optionally with a static analysis
+ * plan) into a snapshot a UI can render — which commands are running, how
+ * many statically-known command sites have executed, loop iteration counts,
+ * subshell tree, and bytes flowing through each channel.
+ */
+
+import type { AnalysisReport } from '../analysis/analyze.ts'
+import type { Span } from '../parser/ast.ts'
+import type { TraceEvent } from './events.ts'
+
+export interface RunningCommand {
+  execId: number
+  nodeId: number
+  argv: string[]
+  pid: number
+  osPid?: number
+  startedAt: number
+}
+
+export interface ProgressSnapshot {
+  /** Commands currently executing (innermost last). */
+  running: RunningCommand[]
+  /** Distinct statically-known command sites that have started at least once. */
+  sitesVisited: number
+  /** Total command sites in the static plan (0 without a plan). */
+  sitesTotal: number
+  /** Executions started / finished. */
+  started: number
+  finished: number
+  /** Loop node id → iterations so far. */
+  loops: Map<number, number>
+  /** Live subshells: pid → parent pid. */
+  subshells: Map<number, number>
+  /** Channel label → bytes written. */
+  bytes: Map<string, number>
+  /** Most recent step (for highlighting). */
+  current?: { nodeId: number; span: Span }
+  denied: { argv: string[]; reason: string }[]
+  done: boolean
+  status?: number
+}
+
+export class ProgressTracker {
+  private readonly planIds: Set<number>
+  private readonly visited = new Set<number>()
+  private readonly running = new Map<number, RunningCommand>()
+  private snapshotState: ProgressSnapshot
+
+  constructor(plan?: AnalysisReport) {
+    this.planIds = new Set(plan?.commands.map((c) => c.nodeId) ?? [])
+    this.snapshotState = {
+      running: [], sitesVisited: 0, sitesTotal: this.planIds.size, started: 0, finished: 0,
+      loops: new Map(), subshells: new Map(), bytes: new Map(), denied: [], done: false,
+    }
+  }
+
+  /** Feed an event; use as `machine.on((e) => tracker.update(e))`. */
+  update(e: TraceEvent): void {
+    const s = this.snapshotState
+    switch (e.type) {
+      case 'step':
+        s.current = { nodeId: e.nodeId, span: e.span }
+        if (this.planIds.has(e.nodeId)) this.visited.add(e.nodeId)
+        s.sitesVisited = this.visited.size
+        break
+      case 'command:start':
+        s.started++
+        this.running.set(e.execId, { execId: e.execId, nodeId: e.nodeId, argv: e.argv, pid: e.pid, startedAt: Date.now() })
+        if (this.planIds.has(e.nodeId)) this.visited.add(e.nodeId)
+        s.sitesVisited = this.visited.size
+        break
+      case 'command:spawn': {
+        const r = this.running.get(e.execId)
+        if (r) r.osPid = e.osPid
+        break
+      }
+      case 'command:end':
+        s.finished++
+        this.running.delete(e.execId)
+        break
+      case 'command:denied':
+        s.denied.push({ argv: e.argv, reason: e.reason })
+        break
+      case 'loop:iteration':
+        s.loops.set(e.nodeId, e.iteration)
+        break
+      case 'subshell:start':
+        s.subshells.set(e.pid, e.parentPid)
+        break
+      case 'subshell:end':
+        s.subshells.delete(e.pid)
+        break
+      case 'data':
+        if (e.direction === 'write') s.bytes.set(e.channel.label, (s.bytes.get(e.channel.label) ?? 0) + e.bytes.length)
+        break
+      case 'run:end':
+        s.done = true
+        s.status = e.status
+        break
+      default:
+        break
+    }
+    s.running = [...this.running.values()]
+  }
+
+  snapshot(): ProgressSnapshot {
+    return this.snapshotState
+  }
+
+  /** One-line human summary. */
+  summary(): string {
+    const s = this.snapshotState
+    const cur = s.running[s.running.length - 1]
+    const plan = s.sitesTotal > 0 ? `${s.sitesVisited}/${s.sitesTotal} sites` : `${s.finished} done`
+    const loops = [...s.loops.values()].length > 0 ? ` loop#${[...s.loops.values()].join(',')}` : ''
+    return `${plan}${loops}${cur ? ` running: ${cur.argv.join(' ')}` : ''}${s.done ? ` (exit ${s.status})` : ''}`
+  }
+}

package/src/vm/arith.ts

@@ -0,0 +1,236 @@
+/**
+ * Bash arithmetic: 64-bit signed integers (BigInt, wrapped with asIntN).
+ *
+ * `$`-expansions inside an expression are substituted textually and the
+ * result re-parsed, as bash does (`op=+; echo $((3 $op 4))` works). Variable
+ * names are evaluated recursively: a variable holding `y+1` evaluates as that
+ * expression.
+ */
+
+import type * as A from '../parser/ast.ts'
+import { arithText, parseArithmetic, ParseError } from '../parser/parser.ts'
+
+export class ArithError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ArithError'
+  }
+}
+
+export interface ArithEnv {
+  /** Variable value as a string (scalar or array element); undefined if unset. */
+  get(name: string, index: string | null): string | undefined
+  /** Whether `name` is an associative array (subscripts are strings then). */
+  isAssoc(name: string): boolean
+  set(name: string, index: string | null, value: bigint): void
+  /** Expand a word (for `$x` inside arithmetic). */
+  expandWord(word: A.Word): Promise<string>
+  /** `set -u` */
+  nounset: boolean
+}
+
+const wrap = (n: bigint): bigint => BigInt.asIntN(64, n)
+
+function collectWords(e: A.ArithExpr, out: A.ArithWord[]): void {
+  switch (e.type) {
+    case 'ArithWord': out.push(e); break
+    case 'ArithNum': break
+    case 'ArithVar': if (e.index) collectWords(e.index, out); break
+    case 'ArithUnary': collectWords(e.operand, out); break
+    case 'ArithBinary': collectWords(e.left, out); collectWords(e.right, out); break
+    case 'ArithAssign': collectWords(e.target, out); collectWords(e.value, out); break
+    case 'ArithTernary': collectWords(e.cond, out); collectWords(e.then, out); collectWords(e.else, out); break
+    case 'ArithIncDec': collectWords(e.target, out); break
+    case 'ArithGroup': collectWords(e.expr, out); break
+  }
+}
+
+/** Evaluate an arithmetic expression from the AST. */
+export async function evaluateArith(expr: A.ArithExpr | null, env: ArithEnv): Promise<bigint> {
+  if (expr === null) return 0n
+  const words: A.ArithWord[] = []
+  collectWords(expr, words)
+  if (words.length === 0) return new Evaluator(env).eval(expr)
+  const text = arithText(expr)
+  const values: string[] = []
+  for (const w of words) values.push(await env.expandWord(w.word))
+  if (text === undefined) {
+    // No source text available: evaluate structurally, each word as a sub-expression.
+    const map = new Map<A.ArithWord, string>()
+    words.forEach((w, i) => map.set(w, values[i]))
+    return new Evaluator(env, map).eval(expr)
+  }
+  let out = ''
+  let cursor = expr.span.start
+  words.forEach((w, i) => {
+    out += text.slice(cursor - expr.span.start, w.span.start - expr.span.start) + values[i]
+    cursor = w.span.end
+  })
+  out += text.slice(cursor - expr.span.start)
+  return evaluateArithText(out, env)
+}
+
+/** Evaluate arithmetic source text (no `$`-expansions left in it). */
+export function evaluateArithText(text: string, env: ArithEnv, depth = 0): bigint {
+  if (text.trim() === '') return 0n
+  let parsed: A.ArithExpr
+  try {
+    parsed = parseArithmetic(text)
+  } catch (e) {
+    if (e instanceof ParseError) throw new ArithError(`${text.trim()}: syntax error in expression`)
+    throw e
+  }
+  return new Evaluator(env, undefined, depth).eval(parsed)
+}
+
+export function parseIntegerLiteral(text: string): bigint | null {
+  const t = text.trim()
+  let m: RegExpExecArray | null
+  if ((m = /^([+-]?)0[xX]([0-9a-fA-F]+)$/.exec(t))) return wrap((m[1] === '-' ? -1n : 1n) * BigInt('0x' + m[2]))
+  if ((m = /^([+-]?)(\d+)#([0-9a-zA-Z@_]+)$/.exec(t))) {
+    const base = Number(m[2])
+    if (base < 2 || base > 64) return null
+    let n = 0n
+    for (const ch of m[3]) {
+      let d: number
+      if (/[0-9]/.test(ch)) d = ch.charCodeAt(0) - 48
+      else if (/[a-z]/.test(ch)) d = ch.charCodeAt(0) - 97 + 10
+      else if (/[A-Z]/.test(ch)) d = base <= 36 ? ch.charCodeAt(0) - 65 + 10 : ch.charCodeAt(0) - 65 + 36
+      else if (ch === '@') d = 62
+      else d = 63
+      if (d >= base) return null
+      n = n * BigInt(base) + BigInt(d)
+    }
+    return wrap((m[1] === '-' ? -1n : 1n) * n)
+  }
+  if ((m = /^([+-]?)0([0-7]+)$/.exec(t))) return wrap((m[1] === '-' ? -1n : 1n) * BigInt('0o' + m[2]))
+  if ((m = /^([+-]?)(\d+)$/.exec(t))) {
+    if (/^[+-]?0\d/.test(t) && /[89]/.test(t)) return null
+    return wrap(BigInt(t))
+  }
+  return null
+}
+
+class Evaluator {
+  private readonly env: ArithEnv
+  private readonly words: Map<A.ArithWord, string> | undefined
+  private readonly depth: number
+
+  constructor(env: ArithEnv, words?: Map<A.ArithWord, string>, depth = 0) {
+    this.env = env
+    this.words = words
+    this.depth = depth
+  }
+
+  private indexKey(v: A.ArithVar): string | null {
+    if (!v.index) return null
+    if (this.env.isAssoc(v.name)) {
+      return arithText(v.index) ?? String(this.eval(v.index))
+    }
+    return String(this.eval(v.index))
+  }
+
+  private varValue(v: A.ArithVar): bigint {
+    const key = this.indexKey(v)
+    const raw = this.env.get(v.name, key)
+    if (raw === undefined) {
+      if (this.env.nounset) throw new ArithError(`${v.name}: unbound variable`)
+      return 0n
+    }
+    return this.valueOfString(raw)
+  }
+
+  private valueOfString(raw: string): bigint {
+    if (raw.trim() === '') return 0n
+    const lit = parseIntegerLiteral(raw)
+    if (lit !== null) return lit
+    if (this.depth > 64) throw new ArithError(`${raw}: expression recursion level exceeded`)
+    return evaluateArithText(raw, this.env, this.depth + 1)
+  }
+
+  eval(e: A.ArithExpr): bigint {
+    switch (e.type) {
+      case 'ArithNum': {
+        const n = parseIntegerLiteral(e.text)
+        if (n === null) throw new ArithError(`${e.text}: value too great for base`)
+        return n
+      }
+      case 'ArithVar':
+        return this.varValue(e)
+      case 'ArithWord': {
+        const s = this.words?.get(e) ?? ''
+        return this.valueOfString(s)
+      }
+      case 'ArithGroup':
+        return this.eval(e.expr)
+      case 'ArithUnary': {
+        const v = this.eval(e.operand)
+        switch (e.op) {
+          case '-': return wrap(-v)
+          case '+': return v
+          case '!': return v === 0n ? 1n : 0n
+          case '~': return wrap(~v)
+        }
+        break
+      }
+      case 'ArithIncDec': {
+        const old = this.varValue(e.target)
+        const nv = wrap(e.op === '++' ? old + 1n : old - 1n)
+        this.env.set(e.target.name, this.indexKey(e.target), nv)
+        return e.prefix ? nv : old
+      }
+      case 'ArithAssign': {
+        const key = this.indexKey(e.target)
+        let v = this.eval(e.value)
+        if (e.op !== '=') {
+          const raw = this.env.get(e.target.name, key)
+          const old = raw === undefined ? 0n : this.valueOfString(raw)
+          v = this.binary(e.op.slice(0, -1) as A.ArithBinaryOp, old, v)
+        }
+        this.env.set(e.target.name, key, v)
+        return v
+      }
+      case 'ArithTernary':
+        return this.eval(e.cond) !== 0n ? this.eval(e.then) : this.eval(e.else)
+      case 'ArithBinary': {
+        if (e.op === '&&') return this.eval(e.left) !== 0n && this.eval(e.right) !== 0n ? 1n : 0n
+        if (e.op === '||') return this.eval(e.left) !== 0n || this.eval(e.right) !== 0n ? 1n : 0n
+        if (e.op === ',') {
+          this.eval(e.left)
+          return this.eval(e.right)
+        }
+        return this.binary(e.op, this.eval(e.left), this.eval(e.right))
+      }
+    }
+    throw new ArithError('bad arithmetic node')
+  }
+
+  private binary(op: A.ArithBinaryOp, a: bigint, b: bigint): bigint {
+    switch (op) {
+      case '+': return wrap(a + b)
+      case '-': return wrap(a - b)
+      case '*': return wrap(a * b)
+      case '/':
+        if (b === 0n) throw new ArithError('division by 0')
+        return wrap(a / b)
+      case '%':
+        if (b === 0n) throw new ArithError('division by 0')
+        return wrap(a % b)
+      case '**':
+        if (b < 0n) throw new ArithError('exponent less than 0')
+        return wrap(a ** b)
+      case '<<': return wrap(a << (b & 63n))
+      case '>>': return wrap(a >> (b & 63n))
+      case '&': return wrap(a & b)
+      case '|': return wrap(a | b)
+      case '^': return wrap(a ^ b)
+      case '<': return a < b ? 1n : 0n
+      case '>': return a > b ? 1n : 0n
+      case '<=': return a <= b ? 1n : 0n
+      case '>=': return a >= b ? 1n : 0n
+      case '==': return a === b ? 1n : 0n
+      case '!=': return a !== b ? 1n : 0n
+      default: throw new ArithError(`bad operator ${op}`)
+    }
+  }
+}