deveco-harness 0.1.0

package/skills/arkts-runtime-fix/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: arkts-runtime-fix
+description: Load for ArkTS/JavaScript jscrash, runtime crash, uncaught exception, stack trace, faultlog, or hilog diagnosis. Also load when the app 闪退/崩溃/白屏, exits after 点击/启动/launch, or build succeeds but runtime fails (no compile error). Use before broad Read/Glob on crash-only tasks.
+---
+
+# Harmony JSCrash Fixes
+
+Use this skill to diagnose and fix ArkTS or JavaScript runtime crashes with minimal edits.
+
+Use this skill's private Node scripts under `skills/arkts-runtime-fix/scripts/` to parse crash evidence, inspect recent faultlogger entries, or collect hilog when no better evidence is available.
+
+If `node` is unavailable, stop and explain that the private scripts cannot run.
+
+## When To Load
+
+Load this skill when the issue looks like one of these:
+
+- Runtime logs show `TypeError`, `ReferenceError`, `RangeError`, `SyntaxError`, `BusinessError`, or similar exceptions.
+- The app exits, flashes back, or white-screens during launch or after a tap.
+- The user provides a `jscrash` log, stack trace, or a temporary log file with `@file`.
+- Build succeeds, but runtime behavior fails immediately.
+
+## Core Approach
+
+Prefer a concrete crash anchor before broad code exploration. A good anchor can come from:
+
+- a provided crash log
+- a stack trace
+- a clear page or module named by the user
+- a recent device-side faultlog or hilog when no better evidence is available
+
+Avoid broad `Read` / `Glob` / `Explore` across the whole project until you have at least one concrete anchor such as:
+
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`
+- or a clearly named crash entry point from the user
+
+Do not over-collect logs. If the user already gave enough crash evidence, parse that evidence first and move into focused reading and minimal fixes.
+
+## Tool And Script Contract
+
+### Private Node scripts
+
+Run the private scripts through Shell like this:
+
+```bash
+node "{SKILL_DIR}/scripts/<script>.mjs" ...
+```
+
+`{SKILL_DIR}` is the absolute path of this skill directory at runtime.
+
+Scripts print stable `key: value` text to stdout. A non-zero exit code means the current step could not continue and the agent should report the reason instead of guessing.
+
+## Preferred Flows
+
+### Case A: The user already provided raw crash text
+
+```bash
+node "{SKILL_DIR}/scripts/jscrash-report.mjs" --log-text "{crashLog}" --bundle-name "{bundleName}" --include-text
+```
+
+### Case B: The user provided `@file` or a local log path
+
+```bash
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{logFilePath}" --bundle-name "{bundleName}" --include-text
+```
+
+### Case C: The user only described symptoms and did not provide logs
+
+Log collection is optional here. Use it when you still need a concrete runtime anchor.
+
+Before collecting device evidence:
+
+1. Read `AppScope/app.json5` and take the exact `app.bundleName` value (for example `com.example.hmos.sample`). Use that string as `{bundleName}` in every script below.
+2. Do not guess `bundleName` from `vendor`, module folder names, or prefixes such as `com.example`.
+3. Resolve the target device:
+   - If the user provided a `deviceId`, use it for every device-side command.
+   - If no `deviceId` is provided, call `hdc_log(action="list_devices")` first.
+   - If exactly one device is connected, use that device.
+   - If multiple devices are connected, ask the user which device to inspect. Do not probe faultlogger, fetch faultlog, or collect hilog until the user selects a device.
+   - If no devices are connected, report that device-side evidence cannot be collected and ask for a connected device or a local crash log.
+
+After the user reproduces the crash on the selected device, inspect recent faultlogger evidence:
+
+```bash
+node "{SKILL_DIR}/scripts/probe-faultlogger.mjs" --bundle-name "{bundleName}" --device-id "{deviceId}" --max-age-minutes "30" --limit "10"
+```
+
+If `status: found`, fetch and parse the latest faultlog:
+
+```bash
+node "{SKILL_DIR}/scripts/fetch-faultlog.mjs" --faultlog-name "{latestFaultlog}" --device-id "{deviceId}" --output-dir "{tempDir}"
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{localFaultlogPath}" --bundle-name "{bundleName}" --source file --include-text
+```
+
+If `status: not_found`, do not broad-read the project or guess from symptoms alone. Ask the user to reproduce the crash on the selected device, then probe faultlogger again immediately.
+
+If faultlogger is unavailable, the reproduced crash still does not create a matching faultlog, or the parsed faultlog is still not enough, fall back to hilog:
+
+```bash
+node "{SKILL_DIR}/scripts/collect-hilog.mjs" --device-id "{deviceId}" --lines "4000" --output-dir "{tempDir}"
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{hilogPathFromCollect}" --bundle-name "{bundleName}" --source hilog --include-text
+```
+
+## Output Contract
+
+The leading `key: value` block from `jscrash-report.mjs` and `parse-jscrash-log.mjs` includes:
+
+- `status`: `detected` | `no_crash_signature` | `parse_failed`
+- `source`: `file` | `text` | `hilog` and similar sources
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`: `|`-joined frames
+- `keywords`: comma-separated
+- `next_action`
+
+`--include-text` appends a human-readable summary after the structured block.
+
+If `status: no_crash_signature`, explain that the evidence is weak and ask for a better log, clearer repro, or an additional runtime clue before broad code reading.
+
+## Common Crash Signatures
+
+| Signature | Typical Cause | First Fix Direction |
+|---|---|---|
+| `TypeError` on property access | Null or undefined state during render or lifecycle | Guard null state, initialize earlier, or move logic to a safer lifecycle |
+| `ReferenceError` | Wrong scope, stale import, missing symbol | Fix symbol ownership, import path, or callback capture |
+| `RangeError` | Invalid index, recursion loop, oversized access | Add bounds checks, break loops, clamp indexes |
+| `BusinessError` / `ParameterError` | Framework API preconditions not met | Validate args, permissions, or call timing |
+
+## Interpretation Rules
+
+- Prefer application frames over framework noise.
+- Treat the first concrete `.ets`, `.ts`, or `.js` path as the starting point, not the final truth.
+- If the user gave repro steps, trust them over a simplistic stack-only guess.
+- If the stack points to a non-entry page, assume an interaction-triggered path unless evidence proves a cold-start crash.
+- Do not refactor broadly. Fix the crash path first.
+
+## Conversational Shape
+
+1. Say what evidence you already have.
+2. If logs are missing, say whether you are using faultlogger or hilog to get a better anchor.
+3. Once you have an anchor, switch into focused code reading and minimal fixing.
+
+## Constraints
+
+- Never claim a crash fix from prompt reasoning alone.
+- Never replace a root-cause fix with retries, arbitrary delays, or broad defensive rewrites.
+- If unfamiliar `@ohos.*` or `@kit.*` APIs are involved, check their constraints before editing.
+- This skill does not decide the final compile / run / verification order; the primary agent owns that.

package/skills/arkts-runtime-fix/SKILL_CN.md

@@ -0,0 +1,123 @@
+---
+name: arkts-runtime-fix-cn
+description: ArkTS Runtime Fix 的中文参考版本，仅用于保留中文说明，不作为主入口 skill。
+---
+
+# ArkTS Runtime Fix（中文参考）
+
+本技能通过 **skill 私有脚本**（Node）完成证据采集与结构化解析，不再使用全局崩溃分析工具。执行前若环境无 `node`，须停止并向用户说明。
+
+## 症状与触发
+
+在以下情况必须加载本技能：
+
+- 日志中出现 `TypeError`、`ReferenceError`、`RangeError`、`SyntaxError`、`BusinessError` 等运行时异常
+- 应用启动闪退、白屏、点击后崩溃
+- 用户提供 `jscrash` 日志、堆栈、`@file` 临时日志文件
+- 构建成功但运行期立即失败
+
+## 证据优先约束
+
+在已拿到以下锚点之前，避免对工程做大规模 `Read` / `Glob` / `Explore`：
+
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`
+- 或者用户明确指出的崩溃页面 / 模块
+
+在证据不足时，可以执行本节的私有脚本、向用户追问复现与包名、或读取用户已显式给出的单个日志文件路径。
+
+一旦锚点齐备，再定向读取疑似 `ets/ts/js` 与相关导航入口，做最小修改。
+
+## 私有脚本执行约定
+
+所有脚本通过 Shell 执行，形式与 `deveco-create-project` 一致：
+
+```bash
+node "{SKILL_DIR}/scripts/<script>.mjs" ...
+```
+
+`{SKILL_DIR}` 由执行环境替换为当前技能根目录的绝对路径。脚本 `stdout` 采用稳定 `key: value` 行文本；退出码非 0 表示当前步骤无法继续，应向用户报告 `next_action` 中的原因并停止。
+
+## 场景 A：用户已提供原始日志文本
+
+```bash
+node "{SKILL_DIR}/scripts/jscrash-report.mjs" --log-text "{crashLog}" --bundle-name "{bundleName}" --include-text
+```
+
+## 场景 B：用户提供 `@file` 或本地日志路径
+
+```bash
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{logFilePath}" --bundle-name "{bundleName}" --include-text
+```
+
+## 场景 C：仅有症状，无日志
+
+设备采证前必须先读取 `AppScope/app.json5` 中的 `app.bundleName`，作为后续 `--bundle-name` 的精确值；禁止用 `vendor`、`com.example` 或模块目录名猜测。
+
+先探测 faultlogger 近期 `jscrash-*.log`：
+
+```bash
+node "{SKILL_DIR}/scripts/probe-faultlogger.mjs" --bundle-name "{bundleName}" --device-id "{deviceId}" --max-age-minutes "30" --limit "10"
+```
+
+- 若输出 `status: found`：读取 `latest_faultlog` 或 `candidates`，再拉取并解析：
+
+```bash
+node "{SKILL_DIR}/scripts/fetch-faultlog.mjs" --faultlog-name "{latestFaultlog}" --device-id "{deviceId}" --output-dir "{tempDir}"
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{localFaultlogPath}" --bundle-name "{bundleName}" --source file --include-text
+```
+
+- 若输出 `status: not_found` 或 `status: probe_failed`：可按需进入 hilog 兜底采集：
+
+```bash
+node "{SKILL_DIR}/scripts/collect-hilog.mjs" --device-id "{deviceId}" --lines "4000" --output-dir "{tempDir}"
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{hilogPathFromCollect}" --bundle-name "{bundleName}" --source hilog --include-text
+```
+
+## 解析输出字段契约
+
+`jscrash-report.mjs` 和 `parse-jscrash-log.mjs` 首段 `key: value` 行包含：
+
+- `status`: `detected` | `no_crash_signature` | `parse_failed`
+- `source`: `file` | `text` | `hilog` 等
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`: 以 `|` 分隔的帧列表
+- `keywords`: 逗号分隔
+- `next_action`
+
+`--include-text` 会在其后追加人类可读完整报告。
+
+若 `status: no_crash_signature`，须向用户说明证据不足，请求复现或更完整日志后再读代码。
+
+## 常见崩溃签名
+
+| 签名 | 常见原因 | 优先修复方向 |
+|---|---|---|
+| `TypeError` 属性访问 | 渲染 / 生命周期空状态 | 空值保护、提前初始化、调整生命周期 |
+| `ReferenceError` | 作用域 / 导入 / 闭包 | 修正符号、导入路径或回调捕获 |
+| `RangeError` | 下标 / 递归 / 长度 | 边界检查、断环、限制索引 |
+| `BusinessError` / `ParameterError` | API 前置条件 | 校验参数、权限与调用时机 |
+
+## 解释规则
+
+- 应用栈优先于框架噪声；首个具体 `.ets/.ts/.js` 路径是起点而非唯一根因。
+- 若用户给出复现步骤，步骤优先于单纯堆栈推断。
+- 若堆栈指向非入口页，默认视为交互触发路径，除非证据表明仅冷启动。
+- 不做大范围重构，先消除崩溃路径。
+
+## 交互建议
+
+1. 先说明当前已有的证据。
+2. 如果证据不足，再说明是否按需检查 faultlogger 或 hilog。
+3. 一旦拿到锚点，就切换到定向读代码和最小修复。
+
+## 约束
+
+- 不得仅凭推理声称已修复崩溃。
+- 不得用重试、随意延时或大面积防御性改写替代根因修复。
+- 涉及不熟悉的 `@ohos.*` / `@kit.*` API 时，应先查证约束再改代码。
+- 本技能不决定最终的编译 / 运行 / 验证顺序；主 Agent 负责后续验证。

package/skills/arkts-runtime-fix/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "arkts-runtime-fix",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "点击应用就闪退，没有日志",
+      "expected_output": "加载 arkts-runtime-fix；优先从用户现有证据中建立 crash anchor；若缺少可用日志，可选地先 probe-faultlogger，命中则 fetch-faultlog 再 parse-jscrash-log，仍不足时再 collect-hilog；在拿到明确 anchor 前不大范围 Read/Glob 工程",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "这是 jscrash 日志：TypeError ... at entry/src/main/ets/pages/Index.ets:10:5",
+      "expected_output": "直接 node 执行 jscrash-report.mjs（--log-text）或 parse-jscrash-log.mjs（--log-file），基于现有日志建立 anchor，再定向读取 Index.ets 相关入口，不额外拉取设备日志",
+      "files": []
+    }
+  ]
+}

package/skills/arkts-runtime-fix/scripts/collect-hilog.mjs

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2026 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveHdcOrThrow, runHdc, targetArgs } from './shared/hdc.mjs';
+import { printKv, toErrorMessage } from './shared/utils.mjs';
+
+function cleanLines(input) {
+  return input
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0);
+}
+
+function parseArgs(argv) {
+  const map = new Map();
+  const optionalKeys = new Set(['device-id']);
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (!t.startsWith('--')) {
+      continue;
+    }
+    const key = t.slice(2);
+    const val = argv[i + 1];
+    if (!val || val.startsWith('--')) {
+      if (optionalKeys.has(key)) {
+        map.set(key, '');
+        continue;
+      }
+
+      throw new Error(`Missing value for --${key}`);
+    }
+    map.set(key, val);
+    i += 1;
+  }
+
+  const outputDir = map.get('output-dir');
+  if (!outputDir) {
+    throw new Error('Required: --output-dir');
+  }
+
+  return {
+    outputDir,
+    deviceId: map.get('device-id') ?? '',
+    lines: Number(map.get('lines') ?? '4000'),
+  };
+}
+
+function printCollectFailed(nextAction) {
+  printKv({
+    status: 'collect_failed',
+    source: 'device_hilog',
+    log_file: '',
+    log_excerpt: '',
+    next_action: nextAction,
+  });
+}
+
+async function collectHilogText(hdc, deviceId, lines) {
+  const out = await runHdc([hdc, ...targetArgs(deviceId), 'shell', 'hilog', '-x']);
+  if (out.exitCode !== 0) {
+    throw new Error(out.stderr || out.stdout || `hdc hilog -x failed (code=${out.exitCode})`);
+  }
+
+  const all = cleanLines(out.stdout);
+  return all.slice(Math.max(0, all.length - lines)).join('\n');
+}
+
+async function writeHilogSnapshot(outputDir, recent) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  const logFile = path.join(outputDir, `hilog-${Date.now()}.txt`);
+  await fsp.writeFile(logFile, recent, 'utf8');
+  return logFile;
+}
+
+function printCollected(logFile, recent) {
+  printKv({
+    status: 'collected',
+    source: 'device_hilog',
+    log_file: logFile,
+    log_excerpt: recent.slice(0, 800),
+    next_action: `A hilog snapshot is available. Parse it with parse-jscrash-log.mjs --log-file "${logFile}" --source hilog if you want more crash detail.`,
+  });
+}
+
+async function main() {
+  try {
+    const { outputDir, deviceId, lines } = parseArgs(process.argv.slice(2));
+    const hdc = await resolveHdcOrThrow();
+    const recent = await collectHilogText(hdc, deviceId, lines);
+    const logFile = await writeHilogSnapshot(outputDir, recent);
+    printCollected(logFile, recent);
+    process.exit(0);
+  } catch (err) {
+    printCollectFailed(toErrorMessage(err));
+    process.exit(1);
+  }
+}
+
+await main();

package/skills/arkts-runtime-fix/scripts/collect-hilog.ts

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2026 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveHdcOrThrow, runHdc, targetArgs } from './shared/hdc';
+import { printKv, toErrorMessage } from './shared/utils';
+
+function cleanLines(input: string) {
+  return input
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0);
+}
+
+function parseArgs(argv: string[]) {
+  const map = new Map<string, string>();
+  const optionalKeys = new Set(['device-id']);
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (!t.startsWith('--')) {
+      continue;
+    }
+    const key = t.slice(2);
+    const val = argv[i + 1];
+    if (!val || val.startsWith('--')) {
+      if (optionalKeys.has(key)) {
+        map.set(key, '');
+        continue;
+      }
+
+      throw new Error(`Missing value for --${key}`);
+    }
+    map.set(key, val);
+    i += 1;
+  }
+
+  const outputDir = map.get('output-dir');
+  if (!outputDir) {
+    throw new Error('Required: --output-dir');
+  }
+
+  return {
+    outputDir,
+    deviceId: map.get('device-id') ?? '',
+    lines: Number(map.get('lines') ?? '4000'),
+  };
+}
+
+function printCollectFailed(nextAction: string) {
+  printKv({
+    status: 'collect_failed',
+    source: 'device_hilog',
+    log_file: '',
+    log_excerpt: '',
+    next_action: nextAction,
+  });
+}
+
+async function collectHilogText(hdc: string, deviceId: string, lines: number) {
+  const out = await runHdc([hdc, ...targetArgs(deviceId), 'shell', 'hilog', '-x']);
+  if (out.exitCode !== 0) {
+    throw new Error(out.stderr || out.stdout || `hdc hilog -x failed (code=${out.exitCode})`);
+  }
+
+  const all = cleanLines(out.stdout);
+  return all.slice(Math.max(0, all.length - lines)).join('\n');
+}
+
+async function writeHilogSnapshot(outputDir: string, recent: string) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  const logFile = path.join(outputDir, `hilog-${Date.now()}.txt`);
+  await Bun.write(logFile, recent);
+  return logFile;
+}
+
+function printCollected(logFile: string, recent: string) {
+  printKv({
+    status: 'collected',
+    source: 'device_hilog',
+    log_file: logFile,
+    log_excerpt: recent.slice(0, 800),
+    next_action: `A hilog snapshot is available. Parse it with parse-jscrash-log.ts --log-file "${logFile}" --source hilog if you want more crash detail.`,
+  });
+}
+
+async function main() {
+  try {
+    const { outputDir, deviceId, lines } = parseArgs(process.argv.slice(2));
+    const hdc = await resolveHdcOrThrow();
+    const recent = await collectHilogText(hdc, deviceId, lines);
+    const logFile = await writeHilogSnapshot(outputDir, recent);
+    printCollected(logFile, recent);
+    process.exit(0);
+  } catch (err) {
+    printCollectFailed(toErrorMessage(err));
+    process.exit(1);
+  }
+}
+
+await main();

package/skills/arkts-runtime-fix/scripts/fetch-faultlog.mjs

@@ -0,0 +1,117 @@
+/*
+ * Copyright (c) 2026 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import fsp from 'node:fs/promises';
+import { resolveHdcOrThrow, runHdc, targetArgs } from './shared/hdc.mjs';
+import { printKv, toErrorMessage } from './shared/utils.mjs';
+
+function parseArgs(argv) {
+  const map = new Map();
+  const optionalKeys = new Set(['device-id']);
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const t = argv[i];
+    if (!t.startsWith('--')) {
+      continue;
+    }
+    const key = t.slice(2);
+    const val = argv[i + 1];
+    if (!val || val.startsWith('--')) {
+      if (optionalKeys.has(key)) {
+        map.set(key, '');
+        continue;
+      }
+
+      throw new Error(`Missing value for --${key}`);
+    }
+    map.set(key, val);
+    i += 1;
+  }
+
+  const faultlogName = map.get('faultlog-name');
+  const outputDir = map.get('output-dir');
+  if (!faultlogName || !outputDir) {
+    throw new Error('Required: --faultlog-name and --output-dir');
+  }
+
+  return {
+    faultlogName,
+    outputDir,
+    deviceId: map.get('device-id') ?? '',
+  };
+}
+
+function normalizeRemoteName(name) {
+  return name.endsWith('.log') ? name : `${name}.log`;
+}
+
+function printFetchFailed(faultlogName, remotePath, nextAction) {
+  printKv({
+    status: 'fetch_failed',
+    faultlog_name: faultlogName,
+    remote_path: remotePath,
+    local_path: '',
+    next_action: nextAction,
+  });
+}
+
+async function recvFaultlog(hdc, deviceId, remotePath, localPath) {
+  const args = [hdc, ...targetArgs(deviceId), 'file', 'recv', remotePath, localPath];
+  const out = await runHdc(args);
+  if (out.exitCode !== 0) {
+    throw new Error(out.stderr || out.stdout || `hdc file recv failed (code=${out.exitCode})`);
+  }
+
+  await fsp.access(localPath).catch(() => {
+    throw new Error('Local file missing after recv.');
+  });
+}
+
+function printFetched(faultlogName, remotePath, localPath) {
+  printKv({
+    status: 'fetched',
+    faultlog_name: faultlogName,
+    remote_path: remotePath,
+    local_path: localPath,
+    next_action: `parse-jscrash-log.mjs --log-file "${localPath}"`,
+  });
+}
+
+async function main() {
+  let faultlogName = '';
+  let remotePath = '';
+
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const base = normalizeRemoteName(path.basename(args.faultlogName.trim()));
+    faultlogName = base;
+    remotePath = `/data/log/faultlog/faultlogger/${base}`;
+    const hdc = await resolveHdcOrThrow();
+
+    fs.mkdirSync(args.outputDir, { recursive: true });
+    const localPath = path.join(args.outputDir, base);
+    await recvFaultlog(hdc, args.deviceId, remotePath, localPath);
+    printFetched(base, remotePath, localPath);
+    process.exit(0);
+  } catch (err) {
+    printFetchFailed(faultlogName, remotePath, toErrorMessage(err));
+    process.exit(1);
+  }
+}
+
+await main();