mobile-debug-mcp 0.33.0 → 0.35.0

package/scripts/architecture-graph.mjs

@@ -0,0 +1,69 @@
+import ts from 'typescript'
+import path from 'node:path'
+import { isBuiltin } from 'node:module'
+import { extractGraph } from 'archunit'
+
+// ArchUnitTS 2.5.4 extracts static imports. Add re-exports, import types and
+// literal dynamic imports using the same project's TypeScript resolution.
+export async function architectureGraph(configFile = 'tsconfig.json') {
+  const configPath = path.resolve(configFile)
+  const root = path.dirname(configPath)
+  const config = ts.readConfigFile(configPath, ts.sys.readFile)
+  if (config.error) throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, root)
+  if (parsed.errors.length) throw new Error(ts.formatDiagnosticsWithColorAndContext(parsed.errors, {
+    getCanonicalFileName: file => file, getCurrentDirectory: () => root, getNewLine: () => '\n'
+  }))
+  const graph = await extractGraph(configPath, { clearCache: true })
+  const local = file => path.relative(root, file).split(path.sep).join('/')
+  const edges = new Map(graph.map(edge => [JSON.stringify([edge.source, edge.target]), edge]))
+  const recorded = new Set()
+  for (const file of parsed.fileNames) {
+    const code = ts.sys.readFile(file)
+    if (code === undefined) throw new Error(`Cannot read architecture source: ${file}`)
+    const ast = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true)
+    const source = local(file)
+    function add(specifier, typeOnly = false) {
+      const module = specifier.text
+      const resolved = ts.resolveModuleName(module, file, parsed.options, ts.sys).resolvedModule
+      if (!resolved && !isBuiltin(module)) throw new Error(`Unresolved dependency: ${source} -> ${module}`)
+      const external = !resolved || !!resolved.isExternalLibraryImport
+      const target = resolved ? local(resolved.resolvedFileName) : module.replace(/^(?!node:)/, 'node:')
+      const key = JSON.stringify([source, target])
+      const kind = typeOnly ? 'type' : 'value'
+      const previous = edges.get(key)
+      // Replace the initial static classification, then union repeated dependencies.
+      if (previous && recorded.has(key)) {
+        previous.importKinds = [...new Set([...previous.importKinds, kind])]
+      } else edges.set(key, { source, target, external, importKinds: [kind] })
+      recorded.add(key)
+    }
+    function visit(node) {
+      if (ts.isImportDeclaration(node)) {
+        const clause = node.importClause
+        const bindings = clause?.namedBindings
+        const typeOnly = clause?.isTypeOnly || (!clause?.name && bindings && ts.isNamedImports(bindings) &&
+          bindings.elements.length > 0 && bindings.elements.every(element => element.isTypeOnly))
+        add(node.moduleSpecifier, !!typeOnly)
+      } else if (ts.isExportDeclaration(node) && node.moduleSpecifier) {
+        const bindings = node.exportClause
+        const typeOnly = node.isTypeOnly || (bindings && ts.isNamedExports(bindings) &&
+          bindings.elements.length > 0 && bindings.elements.every(element => element.isTypeOnly))
+        add(node.moduleSpecifier, !!typeOnly)
+      } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+        if (!node.moduleReference.expression) throw new Error(`Missing import target in ${source}`)
+        add(node.moduleReference.expression, node.isTypeOnly)
+      } else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+        add(node.argument.literal, true)
+      } else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) {
+        const argument = node.arguments[0]
+        if (!argument || !ts.isStringLiteralLike(argument)) throw new Error(`Nonliteral dependency in ${source}; architecture cannot resolve it`)
+        add(argument)
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(ast)
+  }
+  return [...edges.values()]
+}

package/scripts/check-architecture.mjs

@@ -0,0 +1,47 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { gatherDependOnFileViolations, gatherCycleViolations, projectEdges, perEdge, perInternalEdge } from 'archunit'
+import { architectureGraph } from './architecture-graph.mjs'
+
+export const architectureRules = [
+  {
+    name: 'Shared contracts stay independent of application implementations',
+    source: /^src\/contracts\//,
+    forbidden: /^src\/(?!contracts\/)/
+  },
+  {
+    name: 'Capabilities and shared modules cannot import the MCP server layer',
+    source: /^src\/(?!server(?:\/|-core\.ts$|\.ts$))/,
+    forbidden: /^src\/server(?:\/|-core\.ts$|\.ts$)/
+  },
+  {
+    name: 'Pure interaction calculations cannot import native I/O or service facades',
+    source: /^src\/interact\/(?:adjustment\/(?:adjustment-plan|control-values|control-geometry|slider-labels)|targeting\/(?:candidate-scoring|candidate-ancestor|candidate-result|nearby-control|element-helpers|resolved-elements|tap-target|target-scope)|waits\/(?:ui-change-helpers|ui-wait-condition)|assertions\/state-comparison)\.ts$/,
+    forbidden: /^(?:node:(?:child_process|fs|net|http|https)(?:\/|$)|src\/(?:utils\/(?:android|ios)\/|(?:interact|observe|manage)\/(?:index|android|ios)\.ts$))/
+  }
+]
+const filter = regExp => ({ regExp, options: { target: 'path', matching: 'partial' } })
+
+export function checkArchitecture(graph) {
+  const projected = projectEdges(graph, perEdge())
+  const results = architectureRules.map(rule => ({
+    name: rule.name,
+    violations: gatherDependOnFileViolations(projected, [filter(rule.source)], [filter(rule.forbidden)], true)
+  }))
+  const runtime = graph.filter(edge => edge.importKinds.includes('value') || !edge.importKinds.includes('type'))
+  results.push({ name: 'Production runtime dependencies must be cycle-free',
+    violations: gatherCycleViolations(projectEdges(runtime, perInternalEdge()), []) })
+  return results
+}
+
+async function main() {
+  const graph = await architectureGraph(process.argv[2])
+  const results = checkArchitecture(graph)
+  const failures = results.filter(result => result.violations.length)
+  for (const result of failures) console.error(`${result.name}\n${JSON.stringify(result.violations, null, 2)}`)
+  if (failures.length) process.exitCode = 1
+  else console.log(`Architecture: PASS (${results.length} rules; ${graph.filter(edge => edge.source !== edge.target).length} dependency edges, including type, dynamic and re-export dependencies)`)
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => { console.error(error); process.exitCode = 1 })
+}

package/scripts/code-quality-baseline.json

@@ -0,0 +1 @@
+[]

package/scripts/code-quality.mjs

@@ -0,0 +1,161 @@
+import { ESLint } from 'eslint'
+import { createHash } from 'node:crypto'
+import ts from 'typescript'
+import { parse } from '@typescript-eslint/parser'
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const limits = Object.freeze({ 'max-lines': 500, 'class-lines': 300,
+  'max-lines-per-function': 80, complexity: 20, 'max-depth': 4, 'explicit-any': 0 })
+const functionKinds = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'])
+const measuredRules = new Set(['max-lines', 'max-lines-per-function', 'complexity', 'max-depth'])
+
+function children(node) {
+  return Object.entries(node).filter(([key]) => !['parent', 'tokens', 'comments', 'loc', 'range'].includes(key))
+    .flatMap(([, value]) => Array.isArray(value) ? value : [value])
+    .filter(value => value && typeof value === 'object' && typeof value.type === 'string')
+}
+function label(node, parent) {
+  if (node.id?.name) return node.id.name
+  if (parent?.type === 'MethodDefinition' || parent?.type === 'Property' || parent?.type === 'PropertyDefinition') {
+    const name = parent.key.name ?? parent.key.value ?? '[computed]'
+    return ['get', 'set'].includes(parent.kind) ? `${parent.kind}:${name}` : name
+  }
+  if (parent?.type === 'VariableDeclarator') return parent.id.name ?? '[destructured]'
+  if (parent?.type === 'CallExpression' || parent?.type === 'NewExpression') {
+    const callee = parent.callee.name ?? parent.callee.property?.name ?? '[call]'
+    return `${callee}:argument${parent.arguments.indexOf(node)}`
+  }
+  return `[${node.type}]`
+}
+function syntax(code) {
+  const ast = parse(code, { loc: true, range: true, comment: true, sourceType: 'module', ecmaVersion: 'latest' })
+  const symbols = [], anys = [], imports = []
+  function visit(node, parent, scope = '<module>') {
+    if (['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'].includes(node.type)) scope = `${scope}/${node.id.name}`
+    if (functionKinds.has(node.type) || node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+      const anonymous = !node.id?.name && !['MethodDefinition', 'Property', 'PropertyDefinition', 'VariableDeclarator'].includes(parent?.type)
+      const suffix = anonymous ? ':' + createHash('sha256').update(code.slice(...node.range).replace(/\s/g, '')).digest('hex').slice(0, 12) : ''
+      scope = `${scope}/${label(node, parent)}${suffix}`
+      symbols.push({ node, identity: scope })
+    }
+    if (node.type === 'TSAnyKeyword') anys.push({ node, identity: scope })
+    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration', 'ImportExpression', 'TSImportType'].includes(node.type) && node.source) {
+      imports.push({ node, value: node.source.value })
+    }
+    if (node.type === 'CallExpression' && node.callee.name === 'require' && node.arguments[0]?.type === 'Literal') {
+      imports.push({ node, value: node.arguments[0].value })
+    }
+    for (const child of children(node)) visit(child, node, scope)
+  }
+  visit(ast, null)
+  return { ast, symbols, anys, imports }
+}
+function lineCount(code, comments, start = 0, end = code.length) {
+  const chars = code.split('')
+  for (const c of comments) for (let i = c.range[0]; i < c.range[1]; i++) if (chars[i] !== '\n') chars[i] = ' '
+  return chars.slice(start, end).join('').split('\n').filter(line => line.trim()).length
+}
+const eslint = new ESLint({ overrideConfig: [{ files: ['**/*.ts'], linterOptions: { noInlineConfig: true }, rules: {
+  'max-lines': ['error', { max: limits['max-lines'], skipBlankLines: true, skipComments: true }],
+  'max-lines-per-function': ['error', { max: limits['max-lines-per-function'], skipBlankLines: true, skipComments: true }],
+  complexity: ['error', { max: limits.complexity, variant: 'classic' }], 'max-depth': ['error', limits['max-depth']]
+} }] })
+
+export async function measure(file, code) {
+  if (file.endsWith('.java')) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, code)
+    const comments = []
+    for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+      if ([ts.SyntaxKind.SingleLineCommentTrivia, ts.SyntaxKind.MultiLineCommentTrivia].includes(token)) {
+        comments.push({ range: [scanner.getTokenPos(), scanner.getTextPos()] })
+      }
+    }
+    const value = lineCount(code, comments)
+    return value > limits['max-lines'] ? [{ file, rule: 'max-lines', symbol: '<module>', value, line: 1 }] : []
+  }
+  const { ast, symbols, anys, imports } = syntax(code)
+  const findings = []
+  const add = (rule, symbol, value, line) => findings.push({ file, rule, symbol, value, line })
+  const identities = new Set()
+  for (const { node, identity } of symbols) {
+    if (identities.has(identity) && !identity.includes(':argument')) add('duplicate-symbol', identity, 1, node.loc.start.line)
+    identities.add(identity)
+    if (node.type.startsWith('Class')) {
+      const value = lineCount(code, ast.comments, ...node.range)
+      if (value > limits['class-lines']) add('class-lines', identity, value, node.loc.start.line)
+    }
+  }
+  const anyCounts = new Map()
+  for (const { node, identity } of anys) {
+    const current = anyCounts.get(identity) ?? { value: 0, line: node.loc.start.line }
+    current.value++; anyCounts.set(identity, current)
+  }
+  for (const [identity, { value, line }] of anyCounts) add('explicit-any', identity, value, line)
+  const [result] = await eslint.lintText(code, { filePath: file })
+  for (const m of result.messages.filter(m => measuredRules.has(m.ruleId))) {
+    const value = Number(/(?:has too many lines \(|complexity of |nested too deeply \()([\d]+)/.exec(m.message)?.[1])
+    if (!Number.isFinite(value)) throw new Error(`Cannot read ${m.ruleId} metric: ${m.message}`)
+    const candidates = symbols.filter(({ node }) => m.line >= node.loc.start.line && m.line <= node.loc.end.line)
+      .sort((a, b) => a.node.range[1] - a.node.range[0] - (b.node.range[1] - b.node.range[0]))
+    const symbol = m.ruleId === 'max-lines' ? '<module>' : candidates[0]?.identity ?? '<module>'
+    add(m.ruleId, symbol, value, m.line)
+  }
+  for (const comment of ast.comments) {
+    if (/(?:eslint-(?:disable|enable)|^\s*eslint\s)/.test(comment.value) &&
+      (!/eslint-(?:disable|enable)(?:-next-line|-line)?\s+(?!-)[\w@]/.test(comment.value) ||
+      /max-lines|complexity|max-depth|no-explicit-any|code-quality/.test(comment.value))) {
+      add('inline-suppression', '<module>', 1, comment.loc.start.line)
+    }
+  }
+  if (file.startsWith('src/interact/') || file.startsWith('src/runtime/')) {
+    for (const { node, value } of imports) if (typeof value === 'string' && /(?:^|\/)server(?:\/|-core)/.test(value)) {
+      add('import-boundary', '<module>', 1, node.loc.start.line)
+    }
+  }
+  // Multiple nested blocks can report depth in the same function; retain its maximum.
+  return [...findings.reduce((out, f) => {
+    const key = `${f.rule}:${f.symbol}`
+    if (!out.has(key) || out.get(key).value < f.value) out.set(key, f)
+    return out
+  }, new Map()).values()]
+}
+export function compare(findings, baseline) {
+  const errors = [], entries = new Map()
+  const key = f => JSON.stringify([f.file, f.rule, f.symbol])
+  for (const b of baseline) {
+    if (!b.file || !b.rule || !b.symbol || !b.reason || !Number.isInteger(b.value) || b.value < 1) {
+      errors.push('Invalid baseline entry'); continue
+    }
+    if (entries.has(key(b))) errors.push(`Duplicate baseline entry: ${key(b)}`)
+    entries.set(key(b), b)
+  }
+  for (const f of findings) {
+    const b = entries.get(key(f))
+    if (['duplicate-symbol', 'inline-suppression', 'import-boundary'].includes(f.rule) || !b || f.value > b.value) {
+      errors.push(`${f.file}:${f.line}: ${f.rule} ${f.symbol} = ${f.value}; allowed ${b?.value ?? limits[f.rule] ?? 0}`)
+    } else if (f.value < b.value) errors.push(`Lower baseline ceiling for ${key(f)}: ${b.value} -> ${f.value}`)
+    entries.delete(key(f))
+  }
+  for (const b of entries.values()) errors.push(`Remove obsolete baseline entry: ${key(b)}`)
+  return errors
+}
+export async function collect(root = 'src') {
+  const out = []
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const file = path.posix.join(root, entry.name)
+    if (entry.isDirectory()) out.push(...await collect(file))
+    else if (/\.(ts|java)$/.test(file)) out.push(...await measure(file, await readFile(file, 'utf8')))
+  }
+  return out
+}
+async function main() {
+  const baseline = JSON.parse(await readFile(new URL('./code-quality-baseline.json', import.meta.url), 'utf8'))
+  const errors = compare(await collect(), baseline)
+  if (errors.length) { console.error(errors.join('\n')); process.exitCode = 1 }
+  else console.log('Code quality: PASS (size, complexity, nesting, types, boundaries and legacy ceilings)')
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => { console.error(error); process.exitCode = 1 })
+}

package/src/contracts/execution-controls.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+export const verificationModes = ['none', 'light', 'full'] as const
+export const responseModes = ['compact', 'debug'] as const
+export const verificationModeSchema = z.enum(verificationModes)
+export const responseModeSchema = z.enum(responseModes)
+export type VerificationMode = z.infer<typeof verificationModeSchema>
+export type ResponseMode = z.infer<typeof responseModeSchema>
+
+export const verificationModeJson = { type: 'string', enum: [...verificationModes] }
+export const responseModeJson = { type: 'string', enum: [...responseModes] }
+
+export function interactionControls(args: Record<string, unknown>) {
+  const verificationMode = ((typeof args.verificationMode === 'string' ? args.verificationMode : undefined) as VerificationMode | undefined) ?? 'full'
+  const responseMode = ((typeof args.responseMode === 'string' ? args.responseMode : undefined) as ResponseMode | undefined) ?? 'debug'
+  if (!verificationModes.includes(verificationMode) || !responseModes.includes(responseMode)) throw new Error('INVALID_ARGUMENT')
+  for (const key of ['verificationMode', 'responseMode']) if (args[key] !== undefined && typeof args[key] !== 'string') throw new Error('INVALID_ARGUMENT')
+  for (const key of ['actionTimeoutMs', 'verificationTimeoutMs']) if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isInteger(args[key]))) throw new Error('INVALID_ARGUMENT')
+  const actionTimeoutMs = (typeof args.actionTimeoutMs === 'number' && Number.isFinite(args.actionTimeoutMs) ? args.actionTimeoutMs : undefined)
+  const verificationTimeoutMs = (typeof args.verificationTimeoutMs === 'number' && Number.isFinite(args.verificationTimeoutMs) ? args.verificationTimeoutMs : undefined)
+  return { verificationMode, responseMode,
+    actionTimeoutMs: actionTimeoutMs === undefined ? undefined : Math.max(100, Math.min(30000, actionTimeoutMs)),
+    verificationTimeoutMs: verificationTimeoutMs === undefined ? 3000 : Math.max(100, Math.min(60000, verificationTimeoutMs)) }
+
+}
+

package/src/contracts/selector.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export type UiSelector = {
+  text?: string
+  resource_id?: string
+  accessibility_id?: string
+  contains?: boolean
+}
+
+export const selectorSchema = z.object({
+  text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+  accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target')
+
+export const selectorJson = { type: 'object', additionalProperties: false, properties: {
+  text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+}, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) }

package/src/contracts/target.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+import { selectorSchema as selector, selectorJson } from './selector.js'
+
+export interface DeviceTarget { platform?: 'android' | 'ios'; deviceId?: string }
+export type ScrollSelector = { text?: string; resourceId?: string; contentDesc?: string; className?: string }
+const pollIntervalMs = z.number().int().min(50).max(1000).optional()
+export const waitForSchema = z.object({
+  condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+  timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+  match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict()
+export const targetFields = { selector: selector.optional(), elementId: z.string().min(1).optional() }
+export const exactlyOneTarget = (value: { selector?: unknown, elementId?: string }) => Number(!!value.selector) + Number(!!value.elementId) === 1
+export const tapElementControlsSchema = z.object({
+  elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitForSchema.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor))
+
+export const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } }
+export const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }]

package/src/contracts/ui.ts

@@ -0,0 +1,94 @@
+export interface UIElementState {
+  checked?: boolean | null;
+  selected?: boolean | string | { id: string; label?: string } | null;
+  focused?: boolean | null;
+  expanded?: boolean | null;
+  enabled?: boolean | null;
+  text_value?: string | null;
+  value?: number | string | null;
+  raw_value?: number | string | null;
+  value_range?: {
+    min: number;
+    max: number;
+    step?: number | null;
+  } | null;
+  step?: number | null;
+}
+
+export interface SelectorConfidence {
+  score: number;
+  reason: string;
+}
+
+export interface UIResolutionSelector {
+  value: string | null;
+  confidence: SelectorConfidence | null;
+}
+
+export interface UIElementSemanticMetadata {
+  is_clickable: boolean;
+  is_container: boolean;
+  semantic_role?: 'slider' | 'stepper' | 'dropdown' | 'segmented_control' | 'custom_adjustable' | 'composite_control' | null;
+  supported_actions?: string[] | null;
+  adjustable?: boolean | null;
+  state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
+}
+
+export interface LoadingState {
+  active: boolean;
+  signal: string;
+  source: string;
+}
+
+export interface SnapshotDelta {
+  previous_snapshot_revision: number | null;
+  added_elements: number;
+  removed_elements: number;
+  mutated_elements: number;
+  total_elements: number;
+}
+
+export interface StateDelta {
+  base_snapshot_revision: number | null;
+  snapshot_revision: number;
+  added: UIElement[];
+  removed: Array<{ stable_id?: string; resourceId?: string; contentDescription?: string; text?: string; index: number }>;
+  changed: UIElement[];
+  truncated: boolean;
+  omitted_changes?: number;
+}
+
+export interface UIElement {
+  text: string | null;
+  contentDescription: string | null;
+  type: string;
+  clickable: boolean;
+  enabled: boolean;
+  visible: boolean;
+  bounds: [number, number, number, number];
+  resourceId: string | null;
+  parentId?: number;
+  children?: number[];
+  center?: [number, number];
+  depth?: number;
+  state?: UIElementState | null;
+  stable_id?: string | null;
+  role?: string | null;
+  test_tag?: string | null;
+  selector?: UIResolutionSelector | null;
+  semantic?: UIElementSemanticMetadata | null;
+}
+
+export interface ReadinessSummary {
+  state: 'loading' | 'transitioning' | 'settled' | 'unknown' | 'unresponsive' | 'debugger_paused';
+  scope: 'device_ui';
+  basis: 'observed' | 'heuristic' | 'insufficient';
+  captured_at_ms: number | null;
+  sample_count: number;
+  stable_for_ms: number;
+  snapshot_session_id: string | null;
+  snapshot_revision: number | null;
+  evidence: Array<{ code: string; source: string; captured_at_ms: number | null; snapshot_revision: number | null }>;
+  limitations: string[];
+  capabilities: { loading: boolean; transitioning: boolean; settled: boolean; unresponsive: boolean; debugger_paused: boolean };
+}

package/src/debugger/android.ts

@@ -0,0 +1,66 @@
+import { resolveAdbCmd } from '../utils/android/utils.js'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
+const exec = promisify(execFile)
+export interface DebugTarget { app_id: string; pid: number; process_name: string; start_identity: string; uid: number }
+export interface DebugNative {
+  candidates(device: string, app: string): Promise<DebugTarget[]>
+  identity(device: string, target: DebugTarget): Promise<DebugTarget>
+  forward(device: string, pid: number): Promise<number>
+  removeForward(device: string, port: number, pid: number): Promise<void>
+}
+export class AndroidDebugNative implements DebugNative {
+  async adb(device: string, args: string[]) {
+    try { return (await exec(resolveAdbCmd(), ['-s', device, ...args], { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout.trim() }
+    catch (e) { throw nativeError(e, 'DEVICE_UNAVAILABLE') }
+  }
+  async identity(device: string, target: DebugTarget): Promise<DebugTarget> {
+    try {
+      const stat = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/stat`])
+      const fields = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/)
+      const status = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/status`])
+      const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1])
+      const name = (await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/cmdline`])).split('\0')[0]
+      if (!/^\d+$/.test(fields[19] ?? '') || uid !== target.uid || name !== target.process_name || (target.start_identity && fields[19] !== target.start_identity)) throw new Error('identity')
+      return { ...target, start_identity: fields[19] }
+    } catch (e) { if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEVICE_UNAVAILABLE'].includes(e.code)) throw e; throw new DebuggerError('PROCESS_CHANGED') }
+  }
+  async candidates(device: string, app: string) {
+    if (!/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/.test(app)) throw new DebuggerError('INVALID_ARGUMENT')
+    const packages = await this.adb(device, ['shell', 'cmd', 'package', 'list', 'packages', '-U', app])
+    const uid = Number(new RegExp(`^package:${app.replaceAll('.', '\\.')} uid:(\\d+)$`, 'm').exec(packages)?.[1])
+    if (!Number.isSafeInteger(uid)) throw new DebuggerError('PROCESS_NOT_FOUND')
+    // `adb jdwp` is a subscription, not a one-shot command. Bound the sample.
+    let jdwpOutput: string
+    try { jdwpOutput = (await exec(resolveAdbCmd(), ['-s', device, 'jdwp'], { timeout: debuggerRemaining(500), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout }
+    catch (error: unknown) {
+      const e = error as { killed?: boolean; stderr?: string; stdout?: string }
+      if (debuggerSignal()?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+      debuggerRemaining(1)
+      if (!e.killed || e.stderr?.trim()) throw nativeError(e, 'DEVICE_UNAVAILABLE')
+      jdwpOutput = e.stdout ?? ''
+    }
+    const jdwp = new Set(jdwpOutput.split(/\s+/).filter(id => /^\d+$/.test(id)))
+    const ps = await this.adb(device, ['shell', 'ps', '-A', '-o', 'PID,NAME'])
+    const result: DebugTarget[] = []
+    for (const line of ps.split('\n').slice(1)) {
+      const [pid, name] = line.trim().split(/\s+/)
+      if (jdwp.has(pid) && (name === app || name.startsWith(app + ':'))) result.push(await this.identity(device, { app_id: app, pid: Number(pid), process_name: name, start_identity: '', uid }))
+    }
+    return result
+  }
+  async forward(device: string, pid: number) {
+    const port = Number(await this.adb(device, ['forward', '--no-rebind', 'tcp:0', `jdwp:${pid}`]))
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new DebuggerError('DEBUGGER_ATTACH_FAILED')
+    return port
+  }
+  async removeForward(device: string, port: number, pid: number) {
+    const list = await this.adb(device, ['forward', '--list'])
+    const entry = list.split('\n').find(line => line.trim().split(/\s+/)[1] === `tcp:${port}`)
+    if (!entry) return
+    const [serial, local, remote] = entry.trim().split(/\s+/)
+    if (serial !== device || local !== `tcp:${port}` || remote !== `jdwp:${pid}`) throw new DebuggerError('DEBUGGER_CLEANUP_FAILED')
+    await this.adb(device, ['forward', '--remove', `tcp:${port}`])
+  }
+}

package/src/debugger/diagnostics.ts

@@ -0,0 +1,43 @@
+/** Only catalog values cross the debugger error boundary. Never inspect exception text. */
+export const stages = ['prerequisite', 'compilation', 'worker_start', 'ipc', 'target_resolution', 'forwarding', 'attach', 'command', 'transport', 'cleanup', 'unknown'] as const
+export const reasons = ['unavailable', 'unsupported', 'spawn_failed', 'process_exited', 'invalid_message', 'message_limit', 'write_failed', 'connection_refused', 'transport_lost', 'timeout', 'cancelled', 'operation_failed', 'unknown'] as const
+export type DiagnosticStage = typeof stages[number]
+export type DiagnosticReason = typeof reasons[number]
+export interface DebuggerDiagnostic { stage: DiagnosticStage; reason: DiagnosticReason; recovery: string }
+const recovery: Record<DiagnosticStage, string> = {
+  prerequisite: 'Check JDK 17+ availability, including java, javac and jdk.jdi.',
+  compilation: 'Check the JDK compiler and worker source/cache availability.',
+  worker_start: 'Check Java worker launch availability. Inspect session state and cleanup before attaching again.',
+  ipc: 'Inspect session state and cleanup. Detach before attempting a fresh attach.',
+  target_resolution: 'Check the explicit device and running debuggable app/process.',
+  forwarding: 'Check the explicit device and debugger forwarding availability.',
+  attach: 'Check the running debuggable target and whether another debugger is attached. Inspect cleanup before a fresh attach.',
+  command: 'Inspect debugger session state and cleanup before another state-changing command.',
+  transport: 'Inspect session state and cleanup. Detach before attempting a fresh attach; execution state may be unknown.',
+  cleanup: 'Retry detach_debugger and inspect cleanup.remaining_resources. Do not kill the app or ADB server.',
+  unknown: 'Inspect debugger session state and cleanup; the failure cause is unknown.'
+}
+export function diagnostic(stage: DiagnosticStage, reason: DiagnosticReason): DebuggerDiagnostic {
+  const guidance = reason === 'timeout' || reason === 'cancelled'
+    ? 'Execution may be uncertain. Inspect session state and cleanup before another state-changing command.' : recovery[stage]
+  return { stage, reason, recovery: guidance }
+}
+export function parseDiagnostic(value: unknown): DebuggerDiagnostic {
+  if (!value || typeof value !== 'object') throw new Error('INVALID_WORKER_DIAGNOSTIC')
+  const { stage, reason } = value as Record<string, unknown>
+  if (!stages.includes(stage as DiagnosticStage) || !reasons.includes(reason as DiagnosticReason)) throw new Error('INVALID_WORKER_DIAGNOSTIC')
+  return diagnostic(stage as DiagnosticStage, reason as DiagnosticReason)
+}
+export class DebuggerError extends Error {
+  constructor(public code: string, public diagnostic?: DebuggerDiagnostic) { super(code) }
+}
+const validationCodes = new Set(['INVALID_ARGUMENT', 'DEBUGGER_BUSY', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_PAUSED', 'DEBUGGER_NOT_PAUSED', 'DEBUGGER_STALE_REFERENCE'])
+export function classify(error: unknown, stage: DiagnosticStage, fallback: string, reason: DiagnosticReason = 'unknown'): DebuggerError {
+  const existing = error instanceof DebuggerError ? error : new DebuggerError(fallback)
+  if (existing.diagnostic || validationCodes.has(existing.code)) return existing
+  const knownReason = existing.code === 'DEBUGGER_TIMEOUT' ? 'timeout' : existing.code === 'DEBUGGER_CANCELLED' ? 'cancelled' : reason
+  return new DebuggerError(existing.code, diagnostic(stage, knownReason))
+}
+export async function atStage<T>(stage: DiagnosticStage, fallback: string, operation: () => Promise<T>): Promise<T> {
+  try { return await operation() } catch (error) { throw classify(error, stage, fallback) }
+}

package/src/debugger/guard.ts

@@ -0,0 +1,31 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { DebuggerError } from './worker.js'
+interface PauseEvidence {
+  debug_session_id: string
+  captured_at_ms: number
+  target: unknown
+}
+let pauseProvider: (device: string) => PauseEvidence | null = () => null
+export function registerDebuggerPauseProvider(provider: typeof pauseProvider) { pauseProvider = provider }
+const context = new AsyncLocalStorage<{ platform: string; device: string; dispatched: boolean }>()
+export function withDebuggerGuard<T>(platform: string, device: string, operation: () => Promise<T>) {
+  return context.run({ platform, device, dispatched: false }, operation)
+}
+// Synchronous checks and native submission share a JS turn with pause updates.
+export function checkDebuggerGuard(dispatch = false) {
+  const current = context.getStore()
+  if (!current || current.platform !== 'android') return
+  if (pauseProvider(current.device)) throw new DebuggerError('DEBUGGER_PAUSED')
+  if (dispatch) current.dispatched = true
+}
+export function guardDispatched() { return context.getStore()?.dispatched ?? false }
+export function pausedReadiness(device: string) {
+  const paused = pauseProvider(device)
+  if (!paused) return null
+  return { state: 'debugger_paused' as const, scope: 'device_ui' as const, basis: 'observed' as const,
+    captured_at_ms: paused.captured_at_ms, sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
+    evidence: [{ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms, snapshot_revision: null }],
+    limitations: ['FOREGROUND_APP_UNVERIFIED', 'DEVICE_WIDE_UI_GUARD'],
+    capabilities: { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: true },
+    debug_session_id: paused.debug_session_id, target: paused.target }
+}