fh_tool-cli 0.2.3__tar.gz → 0.2.4__tar.gz

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fh_tool-cli
-Version: 0.2.3
+Version: 0.2.4
 Summary: 用于本地管理 FiberHome fh_tool 接口的 Python CLI
 Author: Gxxk
 License-Expression: AGPL-3.0-or-later
@@ -151,6 +151,18 @@ fh-tool wan list --backend local-vm
 
 `local-vm` 只是在本机 proot VM 内执行厂商 `cfg_cmd`。`--vm-root` 必须指向 VM 工作区目录，也就是包含 `bin/proot-shell` 和 `rootfs-vm/fhrom/bin/cfg_cmd` 的目录；默认是 `/mnt/dev-cold/HG5143F-ONU-vm`。不要把它指到里面的 `rootfs-vm/`。
 
+也可以从 HG5143F 原始 MTD dump 构建同类 userspace VM。`collect` 默认只输出 dry-run 计划，不读 flash；真正采集必须加 `--confirm`，自动开启 Telnet 也必须显式加 `--auto-enable-telnet --confirm`：
+
+```bash
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps --auto-enable-telnet --confirm
+fh-tool vm build --dump-dir ./hg5143f-dumps --output ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm --with-fhapi --with-http
+```
+
+`vm build` 需要 `ubireader_extract_images`、`ubireader_extract_files`、`unsquashfs`、`jefferson`、`qemu-arm-static` 和 `proot`。输出目录会包含 `rootfs-vm/`、`source/`、`logs/`、`bin/`、`build-manifest.json`、`verify-manifest.json` 和 `events.ndjson`。生成的 VM 是 32-bit ARM userspace under `qemu-arm-static`/`proot -0`，不是完整板级 QEMU 启动；默认不会运行完整 `/etc/rc.d/rcS`。
+
 Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；cfg 来源需要 Telnet 时会默认使用 HG5143F 派生 Telnet 凭据 fallback，可用 `--no-derived-credentials` 关闭。失败不会阻塞只读抓取，并会在结果里返回脱敏 login summary。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
@@ -346,3 +358,7 @@ fh-tool telnet disable --confirm
 ## License
 
 AGPL-3.0-or-later
+
+## 其它
+
+[认可 LINUX DO](https://linux.do)

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.4}/README.md

@@ -135,6 +135,18 @@ fh-tool wan list --backend local-vm
 
 `local-vm` 只是在本机 proot VM 内执行厂商 `cfg_cmd`。`--vm-root` 必须指向 VM 工作区目录，也就是包含 `bin/proot-shell` 和 `rootfs-vm/fhrom/bin/cfg_cmd` 的目录；默认是 `/mnt/dev-cold/HG5143F-ONU-vm`。不要把它指到里面的 `rootfs-vm/`。
 
+也可以从 HG5143F 原始 MTD dump 构建同类 userspace VM。`collect` 默认只输出 dry-run 计划，不读 flash；真正采集必须加 `--confirm`，自动开启 Telnet 也必须显式加 `--auto-enable-telnet --confirm`：
+
+```bash
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps
+fh-tool vm collect --ip 192.168.1.1 --output ./hg5143f-dumps --auto-enable-telnet --confirm
+fh-tool vm build --dump-dir ./hg5143f-dumps --output ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm
+fh-tool vm verify --vm-root ./HG5143F-ONU-vm --with-fhapi --with-http
+```
+
+`vm build` 需要 `ubireader_extract_images`、`ubireader_extract_files`、`unsquashfs`、`jefferson`、`qemu-arm-static` 和 `proot`。输出目录会包含 `rootfs-vm/`、`source/`、`logs/`、`bin/`、`build-manifest.json`、`verify-manifest.json` 和 `events.ndjson`。生成的 VM 是 32-bit ARM userspace under `qemu-arm-static`/`proot -0`，不是完整板级 QEMU 启动；默认不会运行完整 `/etc/rc.d/rcS`。
+
 Web AJAX 读取命令只读。需要复用已有 Web session 时加 `--sessionid`；需要登录时可显式传 `--password-stdin` 或 `--password`。未显式提供密码时默认 `--username useradmin --password-source auto`，会依次尝试 `GetAdminAccount` 和 cfg 路径读取 Web superadmin 密码；cfg 来源需要 Telnet 时会默认使用 HG5143F 派生 Telnet 凭据 fallback，可用 `--no-derived-credentials` 关闭。失败不会阻塞只读抓取，并会在结果里返回脱敏 login summary。sessionid、密码、LOID、PPPoE 等敏感字段默认会脱敏；只有显式加 `--reveal-secrets` 才输出明文。
 
 后台 AJAX 接口发现以 live discovery 为主路径，不需要 HAR，也不需要 rootfs：
@@ -330,3 +342,7 @@ fh-tool telnet disable --confirm
 ## License
 
 AGPL-3.0-or-later
+
+## 其它
+
+[认可 LINUX DO](https://linux.do)

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fh_tool-cli"
-version = "0.2.3"
+version = "0.2.4"
 description = "用于本地管理 FiberHome fh_tool 接口的 Python CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.4}/src/fh_tool_cli/cli.py

@@ -101,6 +101,9 @@ from .upload import (
     upload_workflow_plan,
 )
 from .output import emit
+from .vm_build import build_vm
+from .vm_collect import collect_vm_dumps
+from .vm_verify import verify_vm
 
 
 SENSITIVE_PLAN_KEY_RE = re.compile(
@@ -294,6 +297,42 @@ def command_backup_verify(args: argparse.Namespace) -> dict[str, Any]:
     return verify_backup(Path(args.path).expanduser())
 
 
+def command_vm_collect(args: argparse.Namespace) -> dict[str, Any]:
+    confirmed = is_confirmed(args)
+    result_prefix: dict[str, Any] = {}
+    if confirmed and args.auto_enable_telnet:
+        result_prefix["auto_enable_telnet"] = call_method(args, "TelnetEnable", {"telnet": "1"})
+    result = collect_vm_dumps(
+        shell_runner=_telnet_root_shell_runner_from_args(args) if confirmed else (lambda _command: ""),
+        output_dir=Path(args.output).expanduser(),
+        confirmed=confirmed,
+        all_mtd=args.all_mtd,
+        requested_partitions=args.partition,
+        chunk_size=args.chunk_size,
+        retries=args.retries,
+    )
+    if result_prefix:
+        result.update(result_prefix)
+    return result
+
+
+def command_vm_build(args: argparse.Namespace) -> dict[str, Any]:
+    return build_vm(
+        dump_dir=Path(args.dump_dir).expanduser(),
+        output_dir=Path(args.output).expanduser(),
+        rootfs_slot=args.rootfs_slot,
+        force=args.force,
+    )
+
+
+def command_vm_verify(args: argparse.Namespace) -> dict[str, Any]:
+    return verify_vm(
+        vm_root=Path(args.vm_root).expanduser(),
+        with_fhapi=args.with_fhapi,
+        with_http=args.with_http,
+    )
+
+
 def command_restore_backup(args: argparse.Namespace) -> dict[str, Any]:
     dry_run = not is_confirmed(args)
     if args.target == "device":
@@ -981,6 +1020,9 @@ def _command_handlers() -> dict[str, Any]:
         "command_config_decrypt": command_config_decrypt,
         "command_backup_create": command_backup_create,
         "command_backup_verify": command_backup_verify,
+        "command_vm_collect": command_vm_collect,
+        "command_vm_build": command_vm_build,
+        "command_vm_verify": command_vm_verify,
         "command_restore_backup": command_restore_backup,
         "command_credentials_derive": command_credentials_derive,
         "command_cfg_get": command_cfg_get,

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.4}/src/fh_tool_cli/click_cli.py

@@ -257,6 +257,14 @@ def _parameter_from_action(action: argparse.Action) -> click.Parameter | None:
 
 
 def _option_from_action(action: argparse.Action) -> click.Option:
+    option_strings = list(action.option_strings)
+    inferred_names = {
+        option.lstrip("-").replace("-", "_")
+        for option in option_strings
+        if option.startswith("--")
+    }
+    if action.dest not in inferred_names:
+        option_strings.append(action.dest)
     kwargs: dict[str, Any] = {
         "help": None if action.help is argparse.SUPPRESS else action.help,
         "hidden": action.help is argparse.SUPPRESS,
@@ -279,7 +287,7 @@ def _option_from_action(action: argparse.Action) -> click.Option:
             type=_type_from_action(action),
         )
 
-    return click.Option(list(action.option_strings), **kwargs)
+    return click.Option(option_strings, **kwargs)
 
 
 def _argument_from_action(action: argparse.Action) -> click.Argument:

{fh_tool_cli-0.2.3 → fh_tool_cli-0.2.4}/src/fh_tool_cli/parser.py

@@ -217,6 +217,42 @@ def build_parser(handlers: HandlerMap) -> argparse.ArgumentParser:
     backup_verify.add_argument("--json", action="store_true", help="输出 machine-readable JSON")
     backup_verify.set_defaults(handler=_handler(handlers, "command_backup_verify"))
 
+    vm = subparsers.add_parser("vm", help="采集、构建和验证 HG5143F userspace VM")
+    vm_subparsers = vm.add_subparsers(
+        dest="vm_command",
+        required=True,
+        metavar="SUBCOMMAND",
+        title="vm commands",
+    )
+    vm_collect = vm_subparsers.add_parser("collect", help="通过 Telnet 安全采集 VM 所需 MTD dump")
+    add_telnet_options(vm_collect)
+    for action in vm_collect._actions:
+        if action.dest == "timeout":
+            action.default = 60.0
+            action.help = "Telnet command timeout 秒数，默认 60"
+            break
+    add_write_confirmation(vm_collect)
+    vm_collect.add_argument("--output", required=True, help="写入 dump 目录")
+    vm_collect.add_argument("--auto-enable-telnet", action="store_true", help="确认后先调用 TelnetEnable=1")
+    vm_collect.add_argument("--all-mtd", action="store_true", help="采集 mtd0-mtd7 物理分区")
+    vm_collect.add_argument("--partition", action="append", default=[], help="只采集指定 mtdN/name，可重复")
+    vm_collect.add_argument("--chunk-size", type=int, default=262144, help="nanddump/base64 chunk bytes，默认 262144")
+    vm_collect.add_argument("--retries", type=int, default=3, help="chunk decode/长度不匹配重试次数，默认 3")
+    vm_collect.set_defaults(handler=_handler(handlers, "command_vm_collect"))
+    vm_build = vm_subparsers.add_parser("build", help="从 dump 构建本地 proot/qemu-arm-static VM")
+    vm_build.add_argument("--dump-dir", required=True, help="包含 MTD dump 的目录")
+    vm_build.add_argument("--output", required=True, help="写入 VM 工作区目录")
+    vm_build.add_argument("--rootfs-slot", choices=["active", "A", "B"], default="active", help="rootfs slot，默认 active")
+    vm_build.add_argument("--force", action="store_true", help="覆盖已有输出目录")
+    vm_build.add_argument("--json", action="store_true", help="输出 machine-readable JSON")
+    vm_build.set_defaults(handler=_handler(handlers, "command_vm_build"))
+    vm_verify = vm_subparsers.add_parser("verify", help="验证本地 VM 工作区")
+    vm_verify.add_argument("--vm-root", required=True, help="VM 工作区目录，不是 rootfs-vm 子目录")
+    vm_verify.add_argument("--with-fhapi", action="store_true", help="启动 ubusd + cfgmgr 并验证 cfg_cmd read")
+    vm_verify.add_argument("--with-http", action="store_true", help="端口空闲时启动并验证 HTTP stack")
+    vm_verify.add_argument("--json", action="store_true", help="输出 machine-readable JSON")
+    vm_verify.set_defaults(handler=_handler(handlers, "command_vm_verify"))
+
     restore_backup = subparsers.add_parser("restore", help="从 backup archive 安全恢复 allowlist 配置")
     add_telnet_options(restore_backup)
     restore_backup.add_argument("backup", help="fh-tool backup 生成的 backup.tgz")

fh_tool_cli-0.2.4/src/fh_tool_cli/vm_build.py

@@ -0,0 +1,458 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .errors import FHToolError
+from .vm_common import (
+    VM_SCHEMA_VERSION,
+    append_event,
+    copy_tree_contents,
+    require_empty_or_force,
+    require_host_tools,
+    run_command,
+    sha256_file,
+    utc_now,
+    write_json,
+)
+
+
+BUILD_TOOLS = [
+    "ubireader_extract_images",
+    "ubireader_extract_files",
+    "unsquashfs",
+    "jefferson",
+    "qemu-arm-static",
+    "proot",
+]
+
+FACTORY_JFFS2_OFFSET = 0x380000
+
+
+def build_vm(
+    *,
+    dump_dir: Path,
+    output_dir: Path,
+    rootfs_slot: str,
+    force: bool,
+) -> dict[str, Any]:
+    dump_dir = dump_dir.resolve()
+    if not dump_dir.is_dir():
+        raise FHToolError(f"dump dir is not a directory: {dump_dir}")
+    if rootfs_slot not in {"active", "A", "B"}:
+        raise FHToolError("--rootfs-slot must be active, A, or B")
+    require_empty_or_force(output_dir, force=force)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    rootfs_dir = output_dir / "rootfs-vm"
+    source_dir = output_dir / "source"
+    logs_dir = output_dir / "logs"
+    bin_dir = output_dir / "bin"
+    for directory in (rootfs_dir, source_dir, logs_dir, bin_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+
+    events_path = output_dir / "events.ndjson"
+    append_event(events_path, "build.start", dump_dir=str(dump_dir), output_dir=str(output_dir))
+    tools = require_host_tools(BUILD_TOOLS)
+
+    manifest = _load_dump_manifest(dump_dir)
+    selected_slot, slot_warning = select_rootfs_slot(rootfs_slot, manifest=manifest)
+    warnings: list[str] = []
+    if slot_warning:
+        warnings.append(slot_warning)
+    rootfs_dump = find_dump(dump_dir, index=0 if selected_slot == "A" else 1, name_contains=f"rootfs{selected_slot}")
+    data_dump = find_dump(dump_dir, index=2, name_contains="data", prefer_contains="padbad")
+    factory_dump = find_dump(dump_dir, index=6, name_contains="factory")
+    append_event(
+        events_path,
+        "build.dumps.selected",
+        rootfs=str(rootfs_dump),
+        data=str(data_dump),
+        factory=str(factory_dump),
+        slot=selected_slot,
+    )
+
+    rootfs_image = _extract_rootfs_image(rootfs_dump, logs_dir, events_path)
+    _extract_squashfs_root(rootfs_image, rootfs_dir, logs_dir, events_path)
+    _extract_data_volumes(data_dump, rootfs_dir, logs_dir, events_path)
+    _extract_factory(factory_dump, source_dir, rootfs_dir, logs_dir, events_path)
+    _normalize_runtime(rootfs_dir)
+    _write_scripts(bin_dir)
+    _write_workspace_readme(output_dir)
+
+    outputs = {
+        "rootfs": str(rootfs_dir),
+        "source": str(source_dir),
+        "logs": str(logs_dir),
+        "bin": str(bin_dir),
+        "manifest": str(output_dir / "build-manifest.json"),
+        "events": str(events_path),
+    }
+    source_sha = {
+        "rootfs": sha256_file(rootfs_dump),
+        "data": sha256_file(data_dump),
+        "factory": sha256_file(factory_dump),
+    }
+    result: dict[str, Any] = {
+        "schema_version": VM_SCHEMA_VERSION,
+        "command": "vm build",
+        "created_at": utc_now(),
+        "ok": True,
+        "dump_dir": str(dump_dir),
+        "output_dir": str(output_dir),
+        "rootfs_slot": selected_slot,
+        "host_tools": tools,
+        "source_dumps": {
+            "rootfs": str(rootfs_dump),
+            "data": str(data_dump),
+            "factory": str(factory_dump),
+        },
+        "source_sha256": source_sha,
+        "outputs": outputs,
+        "warnings": warnings,
+        "limitations": [
+            "This is a userspace proot/qemu-arm-static VM, not a full board-level QEMU boot.",
+            "Full /etc/rc.d/rcS is intentionally not used by default.",
+            "mtd3 nvram is not merged into the VM rootfs.",
+        ],
+    }
+    write_json(output_dir / "build-manifest.json", result)
+    append_event(events_path, "build.done", ok=True)
+    return result
+
+
+def select_rootfs_slot(rootfs_slot: str, *, manifest: dict[str, Any] | None = None) -> tuple[str, str | None]:
+    if rootfs_slot in {"A", "B"}:
+        return rootfs_slot, None
+    text = json.dumps(manifest or {}, ensure_ascii=False)
+    lowered = text.lower()
+    if "rootfsb" in lowered or "rootfs_b" in lowered or "active_flag=b" in lowered or '"active_flag": "b"' in lowered:
+        return "B", None
+    if "rootfsa" in lowered or "rootfs_a" in lowered or "active_flag=a" in lowered or '"active_flag": "a"' in lowered:
+        return "A", None
+    return "A", "active rootfs slot was not found in dump metadata; defaulting to rootfsA"
+
+
+def find_dump(dump_dir: Path, *, index: int, name_contains: str, prefer_contains: str | None = None) -> Path:
+    candidates = [
+        path
+        for path in dump_dir.rglob("*.bin")
+        if path.is_file()
+        and (path.name.startswith(f"mtd{index}_") or path.name.startswith(f"mtd{index:02d}_"))
+        and name_contains.lower() in path.name.lower()
+    ]
+    if not candidates:
+        raise FHToolError(f"missing mtd{index} {name_contains} dump in {dump_dir}")
+    if prefer_contains:
+        preferred = [path for path in candidates if prefer_contains.lower() in path.name.lower()]
+        if preferred:
+            return sorted(preferred, key=lambda item: (len(str(item)), str(item)))[0]
+    return sorted(candidates, key=lambda item: (len(str(item)), str(item)))[0]
+
+
+def _load_dump_manifest(dump_dir: Path) -> dict[str, Any] | None:
+    for name in ("dump-manifest.json", "manifest.json"):
+        path = dump_dir / name
+        if path.is_file():
+            try:
+                return json.loads(path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                return None
+    return None
+
+
+def _extract_rootfs_image(rootfs_dump: Path, logs_dir: Path, events_path: Path) -> Path:
+    output = logs_dir / "rootfs_ubi_images"
+    output.mkdir(parents=True, exist_ok=True)
+    run_command(
+        ["ubireader_extract_images", "-o", str(output), str(rootfs_dump)],
+        log_path=logs_dir / "ubireader-rootfs-images.log",
+    )
+    images = sorted(output.rglob("*vol-rootfs_ubifs*.ubifs"))
+    if not images:
+        raise FHToolError("rootfs_ubifs volume image was not extracted")
+    append_event(events_path, "build.rootfs_image.extracted", image=str(images[0]))
+    return images[0]
+
+
+def _extract_squashfs_root(rootfs_image: Path, rootfs_dir: Path, logs_dir: Path, events_path: Path) -> None:
+    run_command(
+        ["unsquashfs", "-f", "-d", str(rootfs_dir), str(rootfs_image)],
+        log_path=logs_dir / "unsquashfs-rootfs.log",
+    )
+    append_event(events_path, "build.rootfs.extracted", rootfs=str(rootfs_dir))
+
+
+def _extract_data_volumes(data_dump: Path, rootfs_dir: Path, logs_dir: Path, events_path: Path) -> None:
+    output = logs_dir / "data_ubi_files"
+    output.mkdir(parents=True, exist_ok=True)
+    run_command(
+        ["ubireader_extract_files", "-o", str(output), str(data_dump)],
+        log_path=logs_dir / "ubireader-data-files.log",
+    )
+    apps = _find_extracted_volume(output, "apps")
+    userdata = _find_extracted_volume(output, "userdata")
+    copy_tree_contents(apps, rootfs_dir / "opt" / "upt" / "apps")
+    copy_tree_contents(userdata, rootfs_dir / "fhconf")
+    append_event(events_path, "build.data.extracted", apps=str(apps), userdata=str(userdata))
+
+
+def _extract_factory(factory_dump: Path, source_dir: Path, rootfs_dir: Path, logs_dir: Path, events_path: Path) -> None:
+    factory_jffs2 = source_dir / "mtd6_factory_0x380000.jffs2"
+    with factory_dump.open("rb") as source, factory_jffs2.open("wb") as target:
+        source.seek(FACTORY_JFFS2_OFFSET)
+        shutil.copyfileobj(source, target)
+    factory_out = source_dir / "factory_jffs2"
+    run_command(
+        ["jefferson", "-f", "-d", str(factory_out), str(factory_jffs2)],
+        log_path=logs_dir / "jefferson-factory.log",
+    )
+    copy_tree_contents(factory_out, rootfs_dir / "fhdata")
+    append_event(events_path, "build.factory.extracted", factory=str(factory_out))
+
+
+def _find_extracted_volume(root: Path, name: str) -> Path:
+    matches = sorted(path for path in root.rglob(name) if path.is_dir() and path.name == name)
+    if not matches:
+        raise FHToolError(f"UBI volume was not extracted: {name}")
+    return matches[0]
+
+
+def _normalize_runtime(rootfs_dir: Path) -> None:
+    for directory in (
+        rootfs_dir / "tmp",
+        rootfs_dir / "var" / "run",
+        rootfs_dir / "var" / "log",
+        rootfs_dir / "opt" / "upt" / "apps",
+        rootfs_dir / "fhconf",
+        rootfs_dir / "fhdata",
+    ):
+        directory.mkdir(parents=True, exist_ok=True)
+    busybox = rootfs_dir / "bin" / "busybox"
+    if busybox.exists():
+        for relative in (
+            "bin/sh",
+            "bin/ash",
+            "bin/cat",
+            "bin/chmod",
+            "bin/cp",
+            "bin/grep",
+            "bin/ln",
+            "bin/ls",
+            "bin/mkdir",
+            "bin/mount",
+            "bin/rm",
+            "bin/sleep",
+            "bin/test",
+            "usr/bin/env",
+            "usr/bin/awk",
+            "usr/bin/head",
+            "sbin/ifconfig",
+        ):
+            path = rootfs_dir / relative
+            if path.exists() and (path.is_symlink() or path.stat().st_size > 0):
+                continue
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if path.exists():
+                path.unlink()
+            target = os.path.relpath(busybox, start=path.parent)
+            path.symlink_to(target)
+    for preserved in ("passwd_old", "shadow_old", "group_old"):
+        path = rootfs_dir / "etc" / preserved
+        if not path.exists() and (rootfs_dir / "etc" / preserved.removesuffix("_old")).exists():
+            shutil.copy2(rootfs_dir / "etc" / preserved.removesuffix("_old"), path)
+
+
+def _write_scripts(bin_dir: Path) -> None:
+    scripts = {
+        "qemu-exec": QEMU_EXEC_SCRIPT,
+        "prepare-runtime": PREPARE_RUNTIME_SCRIPT,
+        "proot-shell": PROOT_SHELL_SCRIPT,
+        "start-fhapi-proot": START_FHAPI_SCRIPT,
+        "stop-fhapi-proot": STOP_FHAPI_SCRIPT,
+        "start-http-stack-proot": START_HTTP_SCRIPT,
+        "verify": VERIFY_SCRIPT,
+    }
+    for name, content in scripts.items():
+        path = bin_dir / name
+        path.write_text(content, encoding="utf-8")
+        path.chmod(0o755)
+
+
+def _write_workspace_readme(output_dir: Path) -> None:
+    (output_dir / "README.md").write_text(
+        "# HG5143F userspace VM\n\n"
+        "Run `./bin/verify` for local checks. Use `./bin/proot-shell` for a root shell in the extracted firmware.\n"
+        "This workspace is a proot/qemu-arm-static userspace VM, not a full board-level QEMU boot.\n",
+        encoding="utf-8",
+    )
+
+
+QEMU_EXEC_SCRIPT = """#!/usr/bin/env sh
+set -eu
+BASE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+ROOTFS="$BASE_DIR/rootfs-vm"
+QEMU=${QEMU:-qemu-arm-static}
+command -v "$QEMU" >/dev/null 2>&1 || { echo "missing $QEMU" >&2; exit 127; }
+[ "$#" -gt 0 ] || set -- /bin/busybox --help
+case "$1" in /*) guest_path=$1 ;; *) guest_path="/$1" ;; esac
+shift
+exec "$QEMU" -L "$ROOTFS" \
+  -E PATH=/fhrom/fhshell:/usr/bin:/usr/sbin:/bin:/sbin:/fhrom/bin \
+  -E LD_LIBRARY_PATH=/lib:/usr/lib:/fhrom/lib:/usr/lib/glib-2.0:/opt/upt/apps/lib:/opt/upt/apps/usr/lib \
+  "$ROOTFS$guest_path" "$@"
+"""
+
+PREPARE_RUNTIME_SCRIPT = """#!/usr/bin/env sh
+set -eu
+BASE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+ROOTFS="$BASE_DIR/rootfs-vm"
+mkdir -p "$ROOTFS/tmp" "$ROOTFS/var/run" "$ROOTFS/var/log"
+[ ! -f "$ROOTFS/etc/passwd_old" ] || cp -f "$ROOTFS/etc/passwd_old" "$ROOTFS/tmp/passwd"
+[ ! -f "$ROOTFS/etc/shadow_old" ] || cp -f "$ROOTFS/etc/shadow_old" "$ROOTFS/tmp/shadow"
+[ ! -f "$ROOTFS/etc/group_old" ] || cp -f "$ROOTFS/etc/group_old" "$ROOTFS/tmp/group"
+if [ ! -f "$ROOTFS/tmp/InternetGatewayDevice/DeviceInfo/property.conf" ] && [ -x "$ROOTFS/fhrom/bin/cfg_tool" ]; then
+  proot -0 -q "${QEMU:-qemu-arm-static}" -r "$ROOTFS" -w / \
+    -b /dev/null:/dev/null -b /dev/zero:/dev/zero -b /dev/random:/dev/random -b /dev/urandom:/dev/urandom \
+    /usr/bin/env PATH=/fhrom/fhshell:/usr/bin:/usr/sbin:/bin:/sbin:/fhrom/bin \
+    LD_LIBRARY_PATH=/lib:/usr/lib:/fhrom/lib:/usr/lib/glib-2.0:/opt/upt/apps/lib:/opt/upt/apps/usr/lib \
+    /fhrom/bin/cfg_tool /fhrom/fhconf/param.tar.gz.enc >/dev/null 2>&1 || true
+fi
+"""
+
+PROOT_SHELL_SCRIPT = """#!/usr/bin/env sh
+set -eu
+BASE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+ROOTFS="$BASE_DIR/rootfs-vm"
+QEMU=${QEMU:-qemu-arm-static}
+command -v proot >/dev/null 2>&1 || { echo "missing proot" >&2; exit 127; }
+command -v "$QEMU" >/dev/null 2>&1 || { echo "missing $QEMU" >&2; exit 127; }
+"$BASE_DIR/bin/prepare-runtime"
+exec proot -0 -q "$QEMU" -r "$ROOTFS" -w / \
+  -b /dev/null:/dev/null -b /dev/zero:/dev/zero -b /dev/random:/dev/random -b /dev/urandom:/dev/urandom \
+  -b /proc:/proc -b /sys:/sys /bin/busybox sh -l "$@"
+"""
+
+START_FHAPI_SCRIPT = """#!/usr/bin/env sh
+set -eu
+BASE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+LOG_DIR="$BASE_DIR/logs"
+mkdir -p "$LOG_DIR"
+"$BASE_DIR/bin/prepare-runtime"
+if pgrep -f 'qemu-arm-static .* /fhrom/bin/cfgmgr' >/dev/null 2>&1; then
+  echo "cfgmgr already appears to be running"
+  exit 0
+fi
+exec "$BASE_DIR/bin/proot-shell" -c '
+set -eu
+export PATH=/fhrom/fhshell:/usr/bin:/usr/sbin:/bin:/sbin:/fhrom/bin
+export LD_LIBRARY_PATH=/lib:/usr/lib:/fhrom/lib:/usr/lib/glib-2.0:/opt/upt/apps/lib:/opt/upt/apps/usr/lib
+mkdir -p /var/run /var/log /tmp
+rm -f /var/run/ubus.sock
+/fhrom/bin/ubusd >/tmp/ubusd.log 2>&1 &
+sleep 1
+/fhrom/bin/cfgmgr >/tmp/cfgmgr.log 2>&1 &
+sleep 3
+echo "FHAPI runtime started: ubusd + cfgmgr"
+while :; do sleep 3600; done
+'
+"""
+
+STOP_FHAPI_SCRIPT = """#!/usr/bin/env sh
+set -eu
+FOUND=0
+stop_pattern() {
+  pids=$(pgrep -f "$1" || true)
+  [ -n "$pids" ] || return 0
+  FOUND=1
+  kill $pids 2>/dev/null || true
+}
+stop_pattern 'qemu-arm-static .* /fhrom/bin/cfgmgr'
+stop_pattern 'qemu-arm-static .* /fhrom/bin/ubusd'
+stop_pattern 'qemu-arm-static .* sleep /bin/sleep 3600'
+sleep 1
+if [ "$FOUND" = 1 ]; then echo "FHAPI runtime stopped"; else echo "FHAPI runtime was not running"; fi
+"""
+
+START_HTTP_SCRIPT = """#!/usr/bin/env sh
+set -eu
+BASE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+if command -v ss >/dev/null 2>&1; then
+  ss -ltn '( sport = :8840 )' | grep -q ':8840' && { echo "port 8840 is already in use" >&2; exit 1; }
+  ss -ltn '( sport = :8080 )' | grep -q ':8080' && { echo "port 8080 is already in use" >&2; exit 1; }
+fi
+exec "$BASE_DIR/bin/proot-shell" -c '
+set -eu
+export PATH=/fhrom/fhshell:/usr/bin:/usr/sbin:/bin:/sbin:/fhrom/bin
+export LD_LIBRARY_PATH=/lib:/usr/lib:/fhrom/lib:/usr/lib/glib-2.0:/opt/upt/apps/lib:/opt/upt/apps/usr/lib
+mkdir -p /var/run /tmp /var/log
+/fhrom/bin/thttpd -C /fhrom/fhconf/thttpd_nginx.conf
+sleep 1
+exec /fhrom/bin/nginx -c /fhconf/nginx.conf
+'
+"""
+
+VERIFY_SCRIPT = """#!/usr/bin/env sh
+set -eu
+BASE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+ROOTFS="$BASE_DIR/rootfs-vm"
+
+echo "[1/7] host tools"
+command -v qemu-arm-static >/dev/null
+command -v unsquashfs >/dev/null
+command -v ubireader_extract_images >/dev/null
+command -v proot >/dev/null
+command -v jefferson >/dev/null
+
+echo "[2/7] rootfs files"
+test -x "$ROOTFS/bin/busybox"
+test -x "$ROOTFS/sbin/uci"
+test -f "$ROOTFS/lib/ld-linux.so.3"
+test -x "$ROOTFS/fhrom/bin/cfg_cmd"
+test -f "$ROOTFS/fhconf/sysinfo_conf"
+test -f "$ROOTFS/fhconf/usrconfig_conf"
+test -f "$ROOTFS/fhconf/attrconfig_conf"
+test -d "$ROOTFS/opt/upt/apps"
+test -f "$ROOTFS/fhdata/factory_conf"
+test -f "$ROOTFS/fhdata/pre_usrconfig_conf"
+test -f "$ROOTFS/fhdata/pre_attrconfig_conf"
+
+echo "[3/7] ARM busybox executes"
+"$BASE_DIR/bin/qemu-exec" /bin/busybox --help >/dev/null
+
+echo "[4/7] proot runtime paths work"
+"$BASE_DIR/bin/prepare-runtime"
+"$BASE_DIR/bin/proot-shell" -c '/bin/busybox test "$(id -u)" = "0"'
+"$BASE_DIR/bin/proot-shell" -c '/sbin/uci -c /fhconf get sysinfo_conf.area_code.value >/dev/null'
+"$BASE_DIR/bin/proot-shell" -c '/sbin/uci -c /fhdata get factory_conf.SerialNumber.value >/dev/null'
+
+echo "[5/7] vendor cfg_cmd status"
+if pgrep -f 'qemu-arm-static .* /fhrom/bin/cfgmgr' >/dev/null 2>&1; then
+  "$BASE_DIR/bin/proot-shell" -c 'cfg_cmd get InternetGatewayDevice.DeviceInfo.Manufacturer' >/tmp/hg5143f-cfg_cmd.out
+  grep -Eq 'FiberHome|get success' /tmp/hg5143f-cfg_cmd.out
+else
+  if "$BASE_DIR/bin/qemu-exec" /fhrom/bin/cfg_cmd get InternetGatewayDevice.DeviceInfo.Manufacturer >/tmp/hg5143f-cfg_cmd.out 2>/tmp/hg5143f-cfg_cmd.err; then
+    echo "cfg_cmd returned successfully without a detected cfgmgr runtime"
+  elif grep -q 'FHAPI_INIT Error' /tmp/hg5143f-cfg_cmd.err /tmp/hg5143f-cfg_cmd.out; then
+    echo "cfg_cmd binary loads; start FHAPI with ./bin/start-fhapi-proot for live cfg_cmd reads"
+  else
+    cat /tmp/hg5143f-cfg_cmd.out >&2
+    cat /tmp/hg5143f-cfg_cmd.err >&2
+    exit 1
+  fi
+fi
+
+echo "[6/7] nginx config parses under proot"
+"$BASE_DIR/bin/proot-shell" -c '/fhrom/bin/nginx -t -c /fhconf/nginx.conf >/dev/null'
+
+echo "[7/7] optional HTTP stack probe"
+if command -v curl >/dev/null 2>&1 && curl -fsS --max-time 2 http://127.0.0.1:8080/ >/dev/null 2>&1; then
+  echo "HTTP stack is running at http://127.0.0.1:8080/"
+else
+  echo "HTTP stack is not running; start it with ./bin/start-http-stack-proot"
+fi
+
+echo "verify ok"
+"""