mobile-debug-mcp 0.34.0 → 0.35.0

package/docs/tools/manage.md

@@ -1,16 +1,21 @@
-# Manage (build & device management)
+# App management
 
-This document covers tools that perform project builds, device selection, installation, and app lifecycle operations.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
-For app launch and restart flows, agents should use:
+Use these tools to select a device, build and install an app, and control its
+lifecycle.
 
-**ACT -> WAIT (if needed) -> EXPECT**
+After `start_app` or `restart_app`, [inspect the resulting UI](observe.md) and
+[assert the expected screen or element](interact.md#expect_screen). If the app
+is still loading, use a [readiness check](observe.md#app-readiness) or an
+appropriate [UI wait](interact.md#wait_for_ui) before continuing.
 
-For example:
+## On this page
 
-1. `start_app` or `restart_app`
-2. optional `wait_for_screen_change`
-3. `expect_screen` when the expected landing screen is known
+- [List devices](#list_devices).
+- [Build an app](#build_app).
+- [Install an existing artifact](#install_app).
+- [Launch, stop, restart, or reset an app](#start_app--terminate_app--restart_app--reset_app_data).
 
 ## list_devices
 Enumerate connected Android devices and iOS simulators.
@@ -51,50 +56,21 @@ Notes:
 - Requires `platform`, `projectType`, and `projectPath`.
 - Android builds prefer the project `gradlew` when present.
 - iOS builds honor environment-based Xcode destination and derived-data settings where configured.
-- Android setup typically needs `ADB_PATH` or `ANDROID_SDK_ROOT`/`ANDROID_HOME`, plus `GRADLE_JAVA_HOME` or `JAVA_HOME` for Gradle-backed builds.
+- Standard toolchains are discovered automatically. Use [path overrides](../../README.md#environment-setup) when discovery needs help. Gradle-backed builds require a suitable Java installation.
 - iOS setup typically needs `XCRUN_PATH` and `MCP_IDB_PATH` or `IDB_PATH` when `idb` is not on `PATH`.
 
 ---
 
-## build_and_install (buildAndInstallHandler)
-Orchestrates build then install and returns streamed NDJSON events plus a final result object.
-
-This is a documented repository helper, not part of the main public MCP tool list in `toolDefinitions`.
-
-Input:
-
-```json
-{ "projectPath": "/path/to/project", "platform": "android", "deviceId": "emulator-5554", "projectType": "kmp" }
-```
-
-NDJSON events (example stream):
-
-```json
-{"type":"build","status":"started","platform":"android"}
-{"type":"build","status":"finished","artifactPath":"/path/to/app.apk"}
-{"type":"install","status":"started","artifactPath":"/path/to/app.apk","deviceId":"emulator-5554"}
-{"type":"install","status":"finished","artifactPath":"/path/to/app.apk","device":{"platform":"android","id":"emulator-5554"}}
-```
-
-Final result:
-
-```json
-{ "success": true, "artifactPath": "/path/to/app.apk", "device": { "platform": "android", "id": "emulator-5554" }, "output": "Performing Streamed Install\nSuccess" }
-```
-
-Notes:
-- If `projectType` === `kmp`, the handler prefers Android by default. Set `platform` explicitly to override.
-- If `MCP_DISABLE_AUTODETECT=1`, callers MUST provide `platform` or `projectType`.
-
----
-
 ## install_app
-Install an app onto a connected device or simulator.
+Install a built artifact, or build and install from a project directory.
+`platform`, `projectType`, and `appPath` are required. `projectType` is one of
+`native`, `kmp`, `react-native`, or `flutter`; acceptance of a project type does
+not establish tested support for every framework.
 
 Input:
 
 ```json
-{ "platform": "android", "appPath": "/path/to/app.apk", "deviceId": "emulator-5554" }
+{ "platform": "android", "projectType": "native", "appPath": "/path/to/app.apk", "deviceId": "emulator-5554" }
 ```
 
 Response:
@@ -155,4 +131,9 @@ Notes:
 - Use `details.observed_app` as the quick decision signal for what the tool actually saw after launch.
 - Android launch feedback usually includes package/activity matching; iOS launch feedback includes launch output and PID when available.
 - When the landing screen is known, use `expect_screen` as the final verification step.
-- If launch timing is uncertain, insert `wait_for_screen_change` before `expect_screen`.
+- If launch timing is uncertain, use a UI wait or readiness check before the final assertion.
+
+`terminate_app`, `restart_app`, and `reset_app_data` also require `platform` and
+`appId`, with optional `deviceId`. Resetting app data removes application state;
+use it only when a clean app state is intended. Execution controls apply to
+`start_app` and `restart_app`; see [verification modes](interact.md#interaction-execution-controls-rfc-018).

package/docs/tools/observe.md

@@ -1,31 +1,33 @@
-# Observe (logs, screenshots, UI trees)
+# Observation
 
-Tools that retrieve device state, logs, screenshots, fingerprints, and UI hierarchies.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
-These tools are primarily for:
+Use observations to understand the current UI and investigate unexpected behaviour.
+Screenshots show layout; UI trees expose labels, identifiers, and control state.
+Logs and debug snapshots provide context when the UI does not explain a failure.
+Use [interaction assertions](interact.md#expect_element_visible) to establish an
+expected outcome.
 
-- building context before an action
-- supporting synchronization
-- diagnostics when verification fails
+## On this page
 
-They are **not** the primary success signal when an applicable `expect_*` tool exists.
+- Inspect the UI: [screenshot](#capture_screenshot), [UI tree](#get_ui_tree), [current screen](#get_current_screen), [fingerprint](#get_screen_fingerprint).
+- Investigate a failure: [logs](#get_logs), [debug snapshot](#capture_debug_snapshot), [log streams](#start_log_stream--read_log_stream--stop_log_stream).
+- Check whether the UI has settled: [app readiness](#app-readiness).
 
-Covered observations support optional `actionRef` and return acquisition/freshness
-metadata; see [correlated evidence](evidence.md).
-
-Android performance investigations can use [system traces](system-traces.md)
-to bracket a journey and retrieve a local Perfetto artifact.
+To connect an observation to a specific action, use [evidence
+correlation](correlated-evidence.md). For Android performance questions, collect a
+[system trace](system-traces.md) around the interaction.
 
 ## get_logs
 
-Fetch recent logs as structured entries optimized for AI agents.
+Fetch recent logs as structured entries for diagnosis.
 
 Use logs as a debugging aid only. Prefer `expect_*` for verification, and use logs after verification fails or when an error is suspected.
 
 Input (example):
 
 ```json
-{ "platform": "android|ios", "appId": "com.example.app", "deviceId": "emulator-5554", "pid": 1234, "tag": "MyTag", "level": "ERROR", "contains": "timeout", "since_seconds": 60, "limit": 50 }
+{ "platform": "android", "appId": "com.example.app", "deviceId": "emulator-5554", "pid": 1234, "tag": "MyTag", "level": "ERROR", "contains": "timeout", "since_seconds": 60, "limit": 50 }
 ```
 
 Defaults:
@@ -86,10 +88,10 @@ Input:
 { "platform": "android", "deviceId": "emulator-5554" }
 ```
 
-Response (example):
+Response (selected fields):
 
 ```json
-{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "snapshot_revision": 12, "captured_at_ms": 1710000000123, "loading_state": { "active": true, "signal": "spinner", "source": "ui_tree" }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "snapshot_session_id": "example-server-session", "snapshot_revision": 12, "captured_at_ms": 1710000000123, "loading_state": { "active": true, "signal": "spinner", "source": "ui_tree" }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
 ```
 
 Notes:
@@ -133,8 +135,9 @@ Input:
 {
   "reason": "optional string describing why snapshot is taken",
   "includeLogs": true,
+  "includeScreenshot": true,
   "logLines": 200,
-  "platform": "android | ios",
+  "platform": "android",
   "appId": "optional package/bundle id to scope logs",
   "deviceId": "optional device serial/udid",
   "sessionId": "optional log stream session id to prefer"
@@ -152,17 +155,17 @@ Behavior:
 - `semantic` is optional, derived from `raw`, and intended for planning only.
 - `raw` now includes `snapshot_revision`, `captured_at_ms`, and `loading_state` when detectable.
 
-Response (example):
+Response (selected fields):
 
 ```json
 {
   "raw": {
-    "timestamp": 1710000000,
+    "timestamp": 1710000000000,
     "reason": "Crash after tapping checkout",
     "activity": "CheckoutActivity",
     "fingerprint": "abc123",
     "screenshot": "<base64 PNG string>",
-    "ui_tree": { ... },
+    "ui_tree": { "elements": [] },
     "logs": [ { "timestamp": "2024-03-09T12:00:00.000Z", "level": "ERROR", "tag": "CheckoutViewModel", "pid": 1234, "message": "NullPointerException at CheckoutViewModel" } ]
   },
   "semantic": {
@@ -214,12 +217,41 @@ Guidance:
 ---
 
 ## start_log_stream / read_log_stream / stop_log_stream
-Start a background adb logcat stream and retrieve parsed NDJSON entries.
+Start an app-scoped background stream on Android (`adb logcat`) or an iOS
+simulator (`xcrun simctl ... log stream`). Start with `start_log_stream`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "packageName": "com.example.app",
+  "sessionId": "app-diagnostics",
+  "level": "error"
+}
+```
+
+`packageName` is required and is also used for an iOS bundle ID. `platform`
+defaults to Android. Android accepts `level`: `error` (default), `warn`, `info`,
+or `debug`. The iOS adapter does not use that level argument. Omitted session IDs
+use `default`; supply an explicit ID to keep diagnostic streams distinct.
+
+Pass the same session ID to `read_log_stream` and, when finished,
+`stop_log_stream`:
+
+```json
+{ "sessionId": "app-diagnostics" }
+```
+
+Use distinct session IDs across platforms: when an ID exists only on iOS, read
+and stop select iOS; otherwise they select Android. Reads retain the stream's device scope.
+`read_log_stream` also accepts the optional [action reference](correlated-evidence.md)
+for evidence correlation. A read returns accumulated entries and any available
+crash summary; reading does not itself stop the background stream.
 
-read_log_stream response example:
+Example read response (selected fields):
 
 ```json
-{ "entries": [ { "timestamp": "2026-03-20T...Z", "level": "ERROR", "tag": "AppTag", "pid": 1234, "message": "FATAL EXCEPTION" } ], "crash_summary": { "crash_detected": true } }
+{ "entries": [ { "timestamp": "2026-03-20T12:00:00Z", "level": "ERROR", "tag": "AppTag", "pid": 1234, "message": "FATAL EXCEPTION" } ], "crash_summary": { "crash_detected": true } }
 ```
 
 ## App readiness

package/docs/tools/system-traces.md

@@ -1,5 +1,7 @@
 # Android system traces
 
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
+
 Use system traces to collect scheduling and system annotations around a slow
 interaction. Capture is optional, device-wide and Android-only; it does not
 automatically diagnose performance problems. No root or Android CLI installation
@@ -27,7 +29,7 @@ cleanup reserves its slot until resolved. Terminal records with complete cleanup
 expire after 10 minutes or eviction beyond 100 records. Server restart invalidates
 IDs. Repeated terminal operations return the stored outcome.
 
-## Agent workflow and interpretation
+## Capture workflow
 
 Trace a reproducible slow or stalled interaction when existing UI timing/state
 and logs leave a performance question unresolved. Check tool discovery first:
@@ -124,3 +126,9 @@ shutdown attempts owned cleanup for up to 10 seconds. A server crash can leave
 a uniquely named bounded device file for manual removal; restart performs no
 broad cleanup sweep. Device suspend can extend Perfetto's own monotonic duration
 limit; the server timer bounds wall-clock lifetime while the server is running.
+
+## Related guides
+
+- [Interaction](interact.md#interaction-execution-controls-rfc-018): run the journey being measured.
+- [Evidence correlation](correlated-evidence.md): interpret action and observation timing.
+- [Android runtime debugger](debugger.md): inspect paused application state.

package/docs/tools/system.md

@@ -1,6 +1,11 @@
-# System (environment & health checks)
+# Environment diagnostics
 
-Tools that provide a lightweight view of the local mobile debugging environment and surface issues early so agents can decide whether to proceed.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
+
+Check local toolchains and connected devices before building, installing, or
+interacting with an app. If discovery cannot find a tool, configure the relevant
+[path override](../../README.md#environment-setup), then check again. Once the
+required platform is available, continue with [device selection](manage.md#list_devices).
 
 ## get_system_status
 A fast, non-throwing healthcheck that inspects key dependencies and connections required for mobile debugging.
@@ -11,7 +16,7 @@ Input:
 {}
 ```
 
-Response (example):
+Response (selected fields):
 
 ```json
 {
@@ -63,13 +68,15 @@ Behavior notes:
 - Always returns structured JSON and never throws; any failures are surfaced in the `issues` array.
 - `status` gives a quick overall gate: `ready`, `degraded`, or `blocked`.
 - `summary.android`, `summary.ios`, and `summary.gradle` provide the fastest path to the actual blocker category.
-- Designed to be fast (<~1s probes where possible); startup callers may prefer a `fastMode` variant that only checks existence.
+- The public tool accepts an empty input object; it exposes no `fastMode` option.
+- Probes are best-effort and can take longer when native tooling is slow.
 - Useful to call at the start of an agent session to gate subsequent actions.
 
 Usage guidance:
 - Call before build/install flows to avoid wasted build attempts on misconfigured systems.
 - Call early in a session when device or toolchain availability is uncertain.
-- If `success: false`, attempt recovery steps or report issues to the user.
+- `success: false` can reflect issues on a platform you are not using. Inspect the
+  relevant platform status and blockers before deciding whether to proceed.
 
 Recommended setup patterns:
 - Default: let the server discover tools automatically from standard locations and call `get_system_status` first to confirm what is available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -17,29 +17,32 @@
     "test:integration": "npm run test:device",
     "test:device": "npm run build && tsx test/device/index.ts",
     "test": "npm run test:unit",
-    "lint": "eslint src test --quiet",
-    "lint:fix": "eslint src test --fix",
+    "lint": "eslint src test --quiet && npm run check:quality && npm run check:architecture",
+    "lint:fix": "eslint src test --fix && npm run check:quality && npm run check:architecture",
     "sync:agent-plugin": "node scripts/agent-plugin.mjs --sync",
+    "check:quality": "node scripts/code-quality.mjs",
+    "check:architecture": "node scripts/check-architecture.mjs",
     "check:agent-plugin": "node scripts/agent-plugin.mjs --check",
     "verify": "npm run lint && npm run build && npm run test:unit && npm run check:agent-plugin"
   },
-
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "fast-xml-parser": "^5.5.1",
-    "zod": "^3.22.4",
-    "sharp": "^0.32.1"
+    "sharp": "^0.35.5",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "@typescript-eslint/eslint-plugin": "^8.57.1",
     "@typescript-eslint/parser": "^8.57.1",
+    "archunit": "2.5.4",
     "eslint": "^9.39.4",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "tsx": "^4.21.0",
+    "minimist": "^1.2.8",
+    "tsx": "^4.23.15",
     "typescript": "^5.9.3"
   }
 }

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 })
+}