dependency-lens

1import type { EngineInterface, Register } from 'claude-code'
2import { object, revision, safeText, safeData, reportText, type Observation, type Port } from './core/runtime.ts'
3export interface Model { data: object; command(args: string, io: Port): Promise<string>; observe?(event: Observation, io: Port): Promise<void> }
4import { Feature } from './core/feature.ts'
5const name = 'dependency-lens'
6const command = 'deps'
7type AdapterState = { queue: Promise<unknown>; replaying: boolean }
8const state: AdapterState = { queue: Promise.resolve(), replaying: false }
9const observesTools = 'observe' in Feature.prototype
10const serial = <T>(fn: () => Promise<T>): Promise<T> => {
11  const work = state.queue.then(fn); state.queue = work.catch(() => {}); return work
12}
13const port = async ($: EngineInterface): Promise<Port> => {
14  const cwd = await $.session.cwd()
15  const unavailable = async (): Promise<never> => { throw new Error('Capability not used by this feature') }
16  const io: Port = { cwd, read: unavailable, run: unavailable, env: unavailable, revision: async () => undefined }
17  io.read = async path => await $.fs.read(path)
18  io.list = async path => (await $.fs.list(path)).map(entry => entry.name)
19  io.run = argv => {
20    if (argv[0] !== 'git') throw new Error('Only local Git evidence commands are supported')
21    return $.process.run(['git', ...argv.slice(1)], { cwd, timeoutMs: 10_000 })
22  }
23  return io
24}
25const identity = ($: EngineInterface) => Promise.all([$.session.cwd(), $.session.id()])
26const transact = async ($: EngineInterface, fn: (model: Model, io: Port) => Promise<string | void>, expected: string[], forceSave = false): Promise<string> => serial(async () => {
27  const [io, id] = await Promise.all([port($), $.session.id()])
28  if (io.cwd !== expected[0] || id !== expected[1]) return 'Session changed; operation not applied'
29  const key = `${name}:v1:${JSON.stringify([io.cwd, id])}`
30  const raw = await $.store.get(key)
31  const loaded = await identity($)
32  if (loaded[0] !== expected[0] || loaded[1] !== expected[1]) return 'Session changed; operation not applied'
33  const model = new Feature(raw)
34  const previous = JSON.stringify(safeData(model.data))
35  const result = await fn(model, io)
36  // No raw event payloads reach storage. Keep the serialized state bounded.
37  const serialized = JSON.stringify(safeData(model.data))
38  if (forceSave || serialized !== previous) {
39    if (serialized.length > 256 * 1024) throw new Error('state limit exceeded; not saved')
40    try { await $.store.set(key, JSON.parse(serialized)) }
41    catch { throw new Error('state not saved; retry after storage recovers') }
42  }
43  return reportText(result ?? '')
44})
45export const register: Register = on => {
46  on('session.start', async ($, e, next) => {
47    try { await $.command.register({ name: command, description: `${name}: /${command} help` }) } catch { /* Startup still forwards. */ }
48    return next(e)
49  })
50  on('command.run', { command }, async ($, e) => {
51    try {
52      const expected = await identity($)
53      return { text: await transact($, async (model, io) => {
54        if ((e.args ?? '').trim() === 'reset') { model.data = new Feature().data; return `${name}: records reset` }
55        return model.command(e.args ?? '', io)
56    }, expected, (e.args ?? '').trim() === 'reset') } } catch (error) { return { text: `${name}: ${safeText(error instanceof Error ? error.message : error)}` } }
57  })
58  on('tool.call', async ($, e, next) => {
59    const ownReplay = state.replaying && (next.origin?.plugin === name || next.origin?.plugin.startsWith(name + '@'))
60    if (!observesTools || ownReplay) return next(e)
61    const expected = await identity($).catch(() => undefined)
62    let before: string | undefined
63    if (['verify-board', 'handoff-pack'].includes(name) && e.tool === 'Bash') {
64      try { before = await (await port($)).revision() } catch { /* Unknown evidence. */ }
65    }
66    // next runs outside observation catch: an observer never retries a tool or hides its exception.
67    const result = await next(e)
68    try {
69      const now = await Promise.all([$.session.cwd(), $.session.id()])
70      if (!expected || expected[0] !== now[0] || expected[1] !== now[1]) return result
71      await transact($, async (model, io) => {
72        const after = before !== undefined ? await io.revision() : undefined
73        await model.observe?.({ tool: e.tool, input: object(e), result, before, after }, io)
74      }, expected)
75    } catch { try { $.ui.toast(`${name}: observation not saved`) } catch { /* Noninteractive host. */ } }
76    return result
77  })
78}
79

1import { redactSecrets } from './redact.ts'
2export type ProcessResult = { exitCode: number; stdout: string; stderr: string; isStdoutTruncated?: boolean; isStderrTruncated?: boolean }
3export type Port = {
4  cwd: string
5  read(path: string): Promise<string>
6  bytes?(path: string): Promise<string>
7  stat?(path: string): Promise<{ isLink: boolean }>
8  list?(path: string): Promise<string[]>
9  run(argv: readonly string[]): Promise<ProcessResult>
10  env(name: string): Promise<string | undefined>
11  revision(): Promise<string | undefined>
12  replay?(command: string): Promise<unknown>
13}
14export type Observation = { tool: string; input: Record<string, unknown>; result: unknown; before?: string; after?: string }
15export function object(v: unknown): Record<string, unknown> { return v !== null && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {} }
16export function safeText(v: unknown, limit = 4000): string {
17  const text = String(v ?? '').replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '')
18  // Some masking patterns backtrack on very long words. Omit an oversized line whole:
19  // cutting it first could expose an unterminated quoted secret.
20  const lines = text.split('\n')
21  // Dropping a credential's opening line could expose its quoted continuation.
22  if (lines.some(line => line.length > 8192 && /["'\\]|password|passwd|pwd|token|key|secret|authorization|credential|cookie/i.test(line))) return '[OMITTED: oversized sensitive value]'
23  return redactSecrets(lines.map(line => line.length > 8192 ? '[OMITTED: oversized line]' : line).join('\n')).slice(0, limit)
24}
25export function hash(text: string): string {
26  return [0, 0x9747b28c].map(seed => {
27    let h = (0x811c9dc5 ^ seed) >>> 0
28    for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193)
29    return (h >>> 0).toString(16).padStart(8, '0')
30  }).join('')
31}
32export function relativePath(root: string, path: string): string | undefined {
33  const normalize = (p: string) => {
34    const parts: string[] = []
35    for (const s of p.replace(/\\/g, '/').split('/')) {
36      if (!s || s === '.') continue
37      if (s === '..') { if (!parts.length) return undefined; parts.pop() } else parts.push(s)
38    }
39    return parts.join('/')
40  }
41  const base = normalize(root); if (base === undefined) return undefined
42  const full = normalize(path.startsWith('/') ? path : `${root}/${path}`)
43  if (full === undefined) return undefined
44  if (base === '') return root.startsWith('/') ? full : undefined
45  if (!(full === base || full.startsWith(base + '/'))) return undefined
46  return full.slice(base.length).replace(/^\//, '')
47}
48export function changedPaths(status: string): string[] {
49  const entries = status.split('\0'); const paths: string[] = []
50  for (let i = 0; i < entries.length; i++) {
51    const line = entries[i]!; if (line.length < 4) continue
52    paths.push(line.slice(3))
53    if (/[RC]/.test(line.slice(0, 2)) && entries[i + 1]) paths.push(entries[++i]!)
54  }
55  return [...new Set(paths)]
56}
57export async function git(io: Port, args: string[]): Promise<string> {
58  const r = await io.run(['git', '-C', io.cwd, ...args])
59  if (r.exitCode !== 0 || r.isStdoutTruncated || r.isStderrTruncated) throw new Error('Git evidence unavailable or incomplete')
60  if (r.stdout.length > 2 * 1024 * 1024) throw new Error('Git evidence exceeds 2 MiB limit')
61  return r.stdout
62}
63export async function statusPaths(io: Port): Promise<string[]> { return changedPaths(await git(io, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])) }
64export async function revision(io: Port): Promise<string | undefined> {
65  try {
66    const root = (await git(io, ['rev-parse', '--show-toplevel'])).replace(/\n$/, '')
67    if (!root.startsWith('/')) return undefined
68    const repo = { ...io, cwd: root }
69    const head = await git(repo, ['rev-parse', '--verify', 'HEAD'])
70    const diff = await git(repo, ['diff', '--no-ext-diff', '--no-textconv', '--binary', '--ignore-submodules=none', 'HEAD', '--'])
71    const staged = await git(repo, ['diff', '--no-ext-diff', '--no-textconv', '--binary', '--ignore-submodules=none', '--cached', 'HEAD', '--'])
72    if (/^\+Subproject commit [a-f0-9]+-dirty$/m.test(diff) || /^\+Subproject commit [a-f0-9]+-dirty$/m.test(staged)) return undefined
73    const status = await git(repo, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignore-submodules=none'])
74    const paths = (await git(repo, ['ls-files', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean).sort()
75    if (paths.length > 200) return undefined
76    const bodies: string[] = [head, diff, staged, status]; let size = diff.length + staged.length + status.length
77    for (const path of paths) {
78      if (relativePath(root, path) !== path || (io.stat && (await io.stat(`${root}/${path}`)).isLink)) return undefined
79      const body = await (io.bytes ?? io.read)(`${root}/${path}`); size += body.length
80      if (size > 2 * 1024 * 1024) return undefined
81      bodies.push(path, body)
82    }
83    return hash(JSON.stringify(bodies))
84  } catch { return undefined }
85}
86export function outcome(result: unknown): 'pass' | 'fail' | 'unknown' {
87  const a = object(result), r = object(a.result)
88  if (a.deny !== undefined) return 'unknown'
89  for (const v of [a, r]) {
90    if (['interrupted', 'cancelled', 'canceled', 'timedOut', 'timed_out', 'truncated', 'output_truncated', 'isStdoutTruncated', 'isStderrTruncated', 'backgroundedByUser', 'backgroundedByTurnAbort', 'backgroundedToDeliverMessage'].some(k => v[k] === true)) return 'unknown'
91    if (['task_id', 'taskId', 'backgroundTaskId', 'background_task_id', 'timedOutAfterMs', 'rawOutputPath', 'persistedOutputPath'].some(k => v[k] !== undefined && v[k] !== null && v[k] !== '')) return 'unknown'
92  }
93  if (a.isError === true) return 'fail'
94  const text = [a.text, r.stdout, r.stderr].filter((v): v is string => typeof v === 'string').join('\n').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
95  if (text.length > 65_536) return 'unknown'
96  if (/^# fail [1-9]\d*\s*$/m.test(text) || /^\s*Tests(?::|\s+)[^\n]*\b[1-9]\d* failed\b/m.test(text) || /^=+[^\n]*\b[1-9]\d* (?:failed|errors?)\b/m.test(text) || /^test result: FAILED\./m.test(text) || /^\s*--- FAIL: /m.test(text)) return 'fail'
97  const code = 'exitCode' in r ? r.exitCode : r.exit_code
98  if ('exitCode' in r || 'exit_code' in r) return typeof code === 'number' && Number.isInteger(code) ? code === 0 ? 'pass' : 'fail' : 'unknown'
99  // Builtin Bash exposes tool failure via isError and foreground completion via interrupted/streams, not exitCode.
100  return typeof r.stdout === 'string' && typeof r.stderr === 'string' && r.interrupted === false ? 'pass' : 'unknown'
101}
102export function isCheck(command: string): boolean {
103  if (/^(?:npx\s+)?vitest\b.*\slist(?:\s|$)/.test(command.trim())) return false
104  // Known introspection-only options do not run the check itself.
105  if (/(?:^|\s)(?:--help|-h|--version|-V|--collect-only|--co|--listTests|--list-tests|--showConfig|--show-config|--list|-list)(?:\s|=|$)/.test(command)) return false
106  // Conservative whole-command allowlist; compound shell programs are not proof of a check.
107  return /^(?:(?:npm|pnpm|yarn) (?:run )?(?:test(?::[\w-]+)?|typecheck|lint)|npx (?:tsc|vitest|jest|eslint)|(?:pytest|vitest|jest|tsc|eslint)|cargo (?:test|check|clippy)|go test)\b[^;&|<>\n]*$/.test(command.trim())
108}
109export function restore<T extends object>(value: unknown, defaults: T): T {
110  const v = object(value); const out = { ...defaults } as Record<string, unknown>
111  for (const [k, fallback] of Object.entries(defaults)) {
112    const item = v[k]
113    if (Array.isArray(fallback) ? Array.isArray(item) : typeof item === typeof fallback && item !== null) out[k] = item
114  }
115  return out as T
116}
117export const entries = (args: string): string[] => args.split('|').map(s => s.trim())
118export function bounded<T>(items: T[]): T[] { return items.slice(-200) }
119// Clean string leaves before JSON serialization, never regex-rewrite serialized JSON syntax.
120export function safeData(value: unknown): unknown {
121  if (typeof value === 'string') return safeText(value)
122  if (Array.isArray(value)) return value.map(safeData)
123  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, safeData(v)]))
124  return value
125}
126
127export function reportText(value: unknown): string {
128  const limit = 32 * 1024, notice = '\nINCOMPLETE: report truncated; filter or inspect smaller groups.'
129  const text = safeText(value, limit + 1)
130  return text.length > limit || String(value ?? '').length > limit ? text.slice(0, limit - notice.length) + notice : text
131}
132

1import { git, object, restore, safeText, type Port } from './runtime.ts'
2function stable(value: unknown): unknown {
3  if (Array.isArray(value)) return value.map(stable)
4  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, stable(item)]))
5  return value
6}
7function validPackages(value: unknown): boolean {
8  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.values(value).every(item => item !== null && typeof item === 'object' && !Array.isArray(item))
9}
10export function compare(beforeValue: unknown, afterValue: unknown, oldValue: unknown, newValue: unknown): string[] {
11  const before = object(beforeValue), after = object(afterValue), old = object(oldValue), next = object(newValue), lines: string[] = [], direct = new Set<string>()
12  for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
13    const a = object(before[section]), b = object(after[section])
14    for (const name of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
15      direct.add(`node_modules/${name}`)
16      if (a[name] !== b[name]) lines.push(`DIRECT ${section} ${safeText(name)}: ${safeText(a[name] ?? '(absent)')} -> ${safeText(b[name] ?? '(absent)')}`)
17    }
18  }
19  const aScripts = object(before.scripts), bScripts = object(after.scripts)
20  for (const name of ['preinstall', 'install', 'postinstall']) if (aScripts[name] !== bScripts[name]) lines.push(`LIFECYCLE ${name}: ${aScripts[name] === undefined ? 'added' : bScripts[name] === undefined ? 'removed' : 'changed'}`)
21  if (![2, 3].includes(Number(old.lockfileVersion)) || ![2, 3].includes(Number(next.lockfileVersion)) || !validPackages(old.packages) || !validPackages(next.packages)) {
22    lines.push('INCOMPLETE: npm package-lock v2/v3 required on both sides; manifest comparison only')
23    return lines.length > 200 ? [...lines.slice(0, 200), 'INCOMPLETE: report limited to 200 entries'] : lines
24  }
25  const a = object(old.packages), b = object(next.packages); let added = 0, removed = 0, changed = 0
26  for (const path of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
27    if (!path) continue
28    const av = object(a[path]), bv = object(b[path])
29    if (JSON.stringify(stable(av)) === JSON.stringify(stable(bv))) continue
30    const kind = a[path] === undefined ? 'ADDED' : b[path] === undefined ? 'REMOVED' : 'CHANGED'
31    if (kind === 'ADDED') added++; else if (kind === 'REMOVED') removed++; else changed++
32    lines.push(`${direct.has(path) ? 'DIRECT-LOCK' : 'TRANSITIVE'} ${kind} ${safeText(path)}: ${safeText(av.version ?? '(absent)')} -> ${safeText(bv.version ?? '(absent)')}`)
33    if (bv.hasInstallScript === true) lines.push(`INSTALL-SCRIPT ${safeText(path)}`)
34  }
35  lines.unshift(`Lock delta: +${added} -${removed} ~${changed}; install-script markers are metadata, not a security verdict.`)
36  return lines.length > 200 ? [...lines.slice(0, 200), 'INCOMPLETE: report limited to 200 entries'] : lines
37}
38function parse(text: string): Record<string, unknown> {
39  if (text.length > 2 * 1024 * 1024) throw new Error('JSON exceeds 2 MiB limit')
40  const value: unknown = JSON.parse(text)
41  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('JSON object required')
42  return value as Record<string, unknown>
43}
44export class Feature {
45  data: { base: string }
46  constructor(value?: unknown) { this.data = restore(value, { base: 'HEAD' }) }
47  async command(args: string, io: Port): Promise<string> {
48    if (args.trim() === 'help') return '/deps [base <git-ref> | list | reset] — compares HEAD (or explicit ref) with working npm manifest and package-lock v2/v3; never installs packages.'
49    if (args.trim().startsWith('base ')) {
50      const ref = args.trim().slice(5).trim()
51      if (!/^[A-Za-z0-9_][A-Za-z0-9_./~^{}@-]{0,199}$/.test(ref)) return 'Invalid Git base ref'
52      this.data.base = ref
53    } else if (args.trim() && args.trim() !== 'list') return 'Usage: /deps [base <git-ref> | list | reset]'
54    const title = `Dependency Lens — base: ${safeText(this.data.base)}`
55    try {
56      await git(io, ['rev-parse', '--verify', `${this.data.base}^{commit}`])
57      const oldFile = async (path: string) => {
58        const names = await git(io, ['ls-tree', '-z', '--name-only', this.data.base, '--', path])
59        if (!names.split('\0').includes(path)) return undefined
60        return parse(await git(io, ['show', `${this.data.base}:${path}`]))
61      }
62      const newFile = async (path: string) => {
63        let body: string
64        try { body = await io.read(`${io.cwd}/${path}`) } catch (error) {
65          if (object(error).code === 'ENOENT') return undefined
66          if (io.list && !(await io.list(io.cwd)).includes(path)) return undefined
67          throw new Error(`${path} unavailable; absence could not be established`)
68        }
69        return parse(body)
70      }
71      const before = await oldFile('package.json'), after = await newFile('package.json')
72      if (!before && !after) throw new Error('package.json unavailable on both sides')
73      const oldLock = await oldFile('package-lock.json'), newLock = await newFile('package-lock.json')
74      return [title, ...compare(before, after, oldLock, newLock)].join('\n')
75    } catch (error) { return `${title}\nINCOMPLETE: ${safeText(error instanceof Error ? error.message : error)}` }
76  }
77}
78

1// Canonical source; run node scripts/sync-redactors.mjs after editing.
2// Best-effort removal of obvious secrets from command lines before they are exported.
3const VALUE = String.raw`("(?:\\[\s\S]|[^"\\])*"|'[^']*'|(?:\\[\s\S]|[^\s'"\\])+)`
4const HEADER = String.raw`(?:authorization|[a-z0-9][a-z0-9-]*-(?:key|token|secret))`
5// Only match user:password arguments, leaving username-only options (e.g. mysql -u) alone.
6const CREDENTIAL = String.raw`("(?:\\[\s\S]|[^":\\])*:(?:\\[\s\S]|[^"\\])*"|'[^':]*:[^']*'|[^\s'":]*:[^\s'"]*)`
7const RULES: [RegExp, string][] = [
8  // Shell-quoted headers must be handled before key/value rules: an escaped quote is
9  // part of the secret, while the opposite quote is ordinary data inside this shell word.
10  [new RegExp(String.raw`("` + HEADER + String.raw`\s*:\s*)(?:\\[\s\S]|[^"\\])*"`, 'gi'), '$1[REDACTED]"'],
11  [new RegExp(String.raw`('` + HEADER + String.raw`\s*:\s*)[^']*'`, 'gi'), "$1[REDACTED]'"],
12  [new RegExp(String.raw`(\b` + HEADER + String.raw`\s*:\s*)(?:\\[\s\S]|[^'"\r\n\\])+`, 'gi'), '$1[REDACTED]'],
13  [new RegExp(String.raw`((?:["']?)(?:password|passwd|pwd|token|(?:access|refresh|id|session|auth)[_-]?token|(?:api|access|secret|private)[_-]?key|client[_-]?secret|secret|authorization|credentials?|cookies?)(?:["']?)\s*:\s*)` + VALUE, 'gi'), '$1[REDACTED]'],
14  [/(\bbearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1[REDACTED]'],
15  [new RegExp(String.raw`(--(?:password|token|api-key|secret)(?:=|\s+))` + VALUE, 'gi'), '$1[REDACTED]'],
16  [/([a-z][a-z0-9+.-]*:\/\/[^\s/:@'"]*:)[^\s/@'"]*@/gi, '$1[REDACTED]@'],
17  [new RegExp(String.raw`(\s(?:--user(?:=|\s+)|-u\s*))` + CREDENTIAL, 'g'), '$1[REDACTED]'],
18  [/(\bmysql\w*\b[^\n;&|]*?\s-p)(?=\S)("[^"]*"|'[^']*'|\S+)/g, '$1[REDACTED]'],
19  [new RegExp(String.raw`\b([A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Za-z0-9_]*)=` + VALUE, 'gi'), '$1=[REDACTED]'],
20]
21
22export function redactSecrets(text: string): string {
23  return RULES.reduce((out, [pattern, replacement]) => out.replace(pattern, replacement), text)
24}
25
26// Match complete key names, including common camelCase/underscore/hyphen spellings.
27// Do not match ordinary names such as token_count or keyboard.
28export function isSecretKey(key: string): boolean {
29  return /^(?:password|passwd|pwd|authorization|proxyauthorization|apikey|accesskey|secretkey|privatekey|clientsecret|secret|token|accesstoken|refreshtoken|idtoken|sessiontoken|authtoken|credential|credentials|cookie|setcookie)$/i.test(key.replace(/[_\s-]/g, '')) || /^[a-z0-9][a-z0-9-]*-(?:key|token|secret)$/i.test(key)
30}
31