chatglance 0.0.1__tar.gz

chatglance-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChatArch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chatglance-0.0.1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: chatglance
+Version: 0.0.1
+Summary: ChatArch Glance dashboard generation CLI.
+Author-email: ChatArch <1073853456@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ChatArch/chatglance
+Project-URL: Repository, https://github.com/ChatArch/chatglance
+Keywords: chatglance,chatarch,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: PyYAML<7.0,>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+    <a href="https://pypi.python.org/pypi/chatglance">
+        <img src="https://img.shields.io/pypi/v/chatglance.svg" alt="PyPI version" />
+    </a>
+    <a href="https://github.com/ChatArch/chatglance/actions/workflows/ci.yml">
+        <img src="https://github.com/ChatArch/chatglance/actions/workflows/ci.yml/badge.svg" alt="Tests" />
+    </a>
+</div>
+
+<div align="center">
+
+[English](README.en.md) | [简体中文](README.md)
+</div>
+
+# chatglance
+
+`chatglance` 是 ChatArch/WZHECNU Glance dashboard 的 Python 生成与运维 CLI。
+
+它不是 NPM 项目，也不是重新实现 Glance 后端：上游 Glance 仍然是 Go 单二进制 dashboard server；`chatglance` 负责把 ChatArch 项目清单、Glance YAML 页面、inline HTML 表格和安全运维补丁组织成可复用的 Python 包/CLI。
+
+## 当前能力
+
+- 从 repository inventory JSON 生成 Glance `项目` page。
+- 当前 page tabs 固定为：`最近提交`、`待处理 PR / Issue`、`分类`、`一览表`。
+- `待处理 PR / Issue` 只显示 PR/Issue 非 0 的仓库，并按 `(PR, Issue, 最近提交)` 降序。
+- 生成 config 副本时清理 legacy generated pages：`Projects`、`ChatArch Projects`、`ChatArch Projects List`。
+- 为 Glance `server-stats` 写入 root-only Disk 配置：`hide-mountpoints-by-default: true` + `mountpoints: /`，避免 snap/loop mount 出现在 Disk popover。
+- 维护 durable runtime：一次性 `runtime maintain` 可原子更新 live config、备份、校验，并在内容变化时可选重启 systemd user service。
+- 渲染 systemd user units：主服务仍直接启动 upstream Glance Go binary；维护任务是独立 oneshot/timer，不是 Python wrapper。
+
+## 快速开始
+
+```bash
+pip install -e ".[dev]"
+chatglance --help
+chatglance --tree
+chatglance --version
+python -m pytest -q
+python -m build
+```
+
+## CLI 示例
+
+只生成 `项目` page YAML：
+
+```bash
+chatglance projects render-page \
+  --data /path/to/chatarch-projects.json \
+  --output playground/projects-page.yml
+```
+
+把生成页写入一个 Glance config 副本：
+
+```bash
+chatglance projects update-config \
+  --data /path/to/chatarch-projects.json \
+  --config /path/to/glance.yml \
+  --output playground/glance.with-projects.yml
+```
+
+把 `server-stats` Disk 改成只显示 root 分区，写入 config 副本：
+
+```bash
+chatglance disks root-only \
+  --config /path/to/glance.yml \
+  --output playground/glance.root-disk.yml
+```
+
+维护一个 durable Glance runtime（默认 `~/.chatarch/glance`）：
+
+```bash
+chatglance runtime maintain \
+  --runtime-home ~/.chatarch/glance \
+  --restart-service chatarch-glance.service
+```
+
+生成推荐 systemd user units：
+
+```bash
+chatglance runtime render-systemd \
+  --runtime-home ~/.chatarch/glance \
+  --chatglance-bin ~/.chatarch/venv/bin/chatglance \
+  --output-dir playground/systemd
+```
+
+## 运行态边界
+
+推荐拓扑是 **systemd 直接运行 Glance，chatglance 只做维护**：
+
+- 主服务：`chatarch-glance.service` 直接执行 `~/.chatarch/glance/bin/glance -config ~/.chatarch/glance/config/glance.yml`。
+- 内容数据：repository inventory JSON、缓存和生成快照放在 `~/.chatarch/glance/data/` 或 `~/.chatarch/glance/cache/`。
+- live config：`~/.chatarch/glance/config/glance.yml`；更新前写备份到 `~/.chatarch/glance/config/backups/`。
+- 维护：`chatglance runtime maintain` 是 oneshot，可由 `chatarch-glance-maintenance.timer` 周期触发。
+- 不建议加 Python 长驻 wrapper：wrapper 会把 server 生命周期和内容生成耦合，反而不利于 systemd 重启、日志、健康检查和回滚。
+
+## 安全边界
+
+- CLI 默认写 output file，不默认覆盖 live `glance.yml`。
+- 不保存或输出 Glance auth、password hash、GitHub token、proxy credential。
+- live runtime、logs、backups、全量实时 JSON 快照默认不进源码仓库。
+- 后续如需动态表格、搜索、中英文切换，再考虑增加小型静态前端层；当前 Python CLI 是基础层。

chatglance-0.0.1/README.md

@@ -0,0 +1,101 @@
+<div align="center">
+    <a href="https://pypi.python.org/pypi/chatglance">
+        <img src="https://img.shields.io/pypi/v/chatglance.svg" alt="PyPI version" />
+    </a>
+    <a href="https://github.com/ChatArch/chatglance/actions/workflows/ci.yml">
+        <img src="https://github.com/ChatArch/chatglance/actions/workflows/ci.yml/badge.svg" alt="Tests" />
+    </a>
+</div>
+
+<div align="center">
+
+[English](README.en.md) | [简体中文](README.md)
+</div>
+
+# chatglance
+
+`chatglance` 是 ChatArch/WZHECNU Glance dashboard 的 Python 生成与运维 CLI。
+
+它不是 NPM 项目，也不是重新实现 Glance 后端：上游 Glance 仍然是 Go 单二进制 dashboard server；`chatglance` 负责把 ChatArch 项目清单、Glance YAML 页面、inline HTML 表格和安全运维补丁组织成可复用的 Python 包/CLI。
+
+## 当前能力
+
+- 从 repository inventory JSON 生成 Glance `项目` page。
+- 当前 page tabs 固定为：`最近提交`、`待处理 PR / Issue`、`分类`、`一览表`。
+- `待处理 PR / Issue` 只显示 PR/Issue 非 0 的仓库，并按 `(PR, Issue, 最近提交)` 降序。
+- 生成 config 副本时清理 legacy generated pages：`Projects`、`ChatArch Projects`、`ChatArch Projects List`。
+- 为 Glance `server-stats` 写入 root-only Disk 配置：`hide-mountpoints-by-default: true` + `mountpoints: /`，避免 snap/loop mount 出现在 Disk popover。
+- 维护 durable runtime：一次性 `runtime maintain` 可原子更新 live config、备份、校验，并在内容变化时可选重启 systemd user service。
+- 渲染 systemd user units：主服务仍直接启动 upstream Glance Go binary；维护任务是独立 oneshot/timer，不是 Python wrapper。
+
+## 快速开始
+
+```bash
+pip install -e ".[dev]"
+chatglance --help
+chatglance --tree
+chatglance --version
+python -m pytest -q
+python -m build
+```
+
+## CLI 示例
+
+只生成 `项目` page YAML：
+
+```bash
+chatglance projects render-page \
+  --data /path/to/chatarch-projects.json \
+  --output playground/projects-page.yml
+```
+
+把生成页写入一个 Glance config 副本：
+
+```bash
+chatglance projects update-config \
+  --data /path/to/chatarch-projects.json \
+  --config /path/to/glance.yml \
+  --output playground/glance.with-projects.yml
+```
+
+把 `server-stats` Disk 改成只显示 root 分区，写入 config 副本：
+
+```bash
+chatglance disks root-only \
+  --config /path/to/glance.yml \
+  --output playground/glance.root-disk.yml
+```
+
+维护一个 durable Glance runtime（默认 `~/.chatarch/glance`）：
+
+```bash
+chatglance runtime maintain \
+  --runtime-home ~/.chatarch/glance \
+  --restart-service chatarch-glance.service
+```
+
+生成推荐 systemd user units：
+
+```bash
+chatglance runtime render-systemd \
+  --runtime-home ~/.chatarch/glance \
+  --chatglance-bin ~/.chatarch/venv/bin/chatglance \
+  --output-dir playground/systemd
+```
+
+## 运行态边界
+
+推荐拓扑是 **systemd 直接运行 Glance，chatglance 只做维护**：
+
+- 主服务：`chatarch-glance.service` 直接执行 `~/.chatarch/glance/bin/glance -config ~/.chatarch/glance/config/glance.yml`。
+- 内容数据：repository inventory JSON、缓存和生成快照放在 `~/.chatarch/glance/data/` 或 `~/.chatarch/glance/cache/`。
+- live config：`~/.chatarch/glance/config/glance.yml`；更新前写备份到 `~/.chatarch/glance/config/backups/`。
+- 维护：`chatglance runtime maintain` 是 oneshot，可由 `chatarch-glance-maintenance.timer` 周期触发。
+- 不建议加 Python 长驻 wrapper：wrapper 会把 server 生命周期和内容生成耦合，反而不利于 systemd 重启、日志、健康检查和回滚。
+
+## 安全边界
+
+- CLI 默认写 output file，不默认覆盖 live `glance.yml`。
+- 不保存或输出 Glance auth、password hash、GitHub token、proxy credential。
+- live runtime、logs、backups、全量实时 JSON 快照默认不进源码仓库。
+- 后续如需动态表格、搜索、中英文切换，再考虑增加小型静态前端层；当前 Python CLI 是基础层。

chatglance-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chatglance"
+dynamic = ["version"]
+description = "ChatArch Glance dashboard generation CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["click>=8.0", "PyYAML>=6.0,<7.0"]
+authors = [{name = "ChatArch", email = "1073853456@qq.com"}]
+keywords = ["chatglance", "chatarch", "cli"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/ChatArch/chatglance"
+Repository = "https://github.com/ChatArch/chatglance"
+
+[project.scripts]
+chatglance = "chatglance.cli:main"
+
+[project.optional-dependencies]
+dev = ["build", "pytest", "twine"]
+
+[tool.setuptools.dynamic]
+version = {attr = "chatglance.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true

chatglance-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chatglance-0.0.1/src/chatglance/__init__.py

@@ -0,0 +1,5 @@
+"""chatglance package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

chatglance-0.0.1/src/chatglance/cli.py

@@ -0,0 +1,221 @@
+"""CLI entrypoint for chatglance."""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+
+import click
+
+from chatglance import __version__
+from chatglance.glance_config import patch_disks_from_files, update_projects_page_from_files
+from chatglance.projects import PAGE_NAME, build_projects_page, dump_yaml, load_inventory
+from chatglance.runtime import maintain_config, runtime_path
+from chatglance.systemd import render_all_units, write_units
+
+
+def _purpose(command: click.Command) -> str:
+    text = command.short_help or inspect.getdoc(command.callback) or ""
+    return " ".join(text.strip().split()).rstrip(".")
+
+
+def _parameter_piece(parameter: click.Parameter) -> str | None:
+    if getattr(parameter, "hidden", False) or parameter.name == "help":
+        return None
+    if isinstance(parameter, click.Argument):
+        piece = parameter.name.upper().replace("_", "-")
+        if not parameter.required:
+            piece = f"[{piece}]"
+        if parameter.nargs == -1:
+            piece = f"{piece}..."
+        return piece
+    if not isinstance(parameter, click.Option):
+        return None
+    option_names = [name for name in (*parameter.opts, *parameter.secondary_opts) if name.startswith("--")]
+    if not option_names:
+        option_names = [name for name in (*parameter.opts, *parameter.secondary_opts) if name.startswith("-")]
+    if not option_names:
+        return None
+    if parameter.is_flag or parameter.flag_value is not None:
+        piece = "/".join(option_names)
+    else:
+        metavar = parameter.metavar or parameter.name.upper().replace("_", "-")
+        piece = f"{'/'.join(option_names)} {metavar}"
+    if not parameter.required:
+        piece = f"[{piece}]"
+    return piece
+
+
+def _command_signature(name: str, command: click.Command) -> str:
+    pieces = [piece for piece in (_parameter_piece(parameter) for parameter in command.params) if piece]
+    return " ".join([name, *pieces])
+
+
+def _render_command_tree(command: click.Command, name: str, prefix: str, is_last: bool, lines: list[str]) -> None:
+    connector = "└── " if is_last else "├── "
+    line = f"{prefix}{connector}{_command_signature(name, command)}"
+    purpose = _purpose(command)
+    if purpose:
+        line = f"{line}  # {purpose}"
+    lines.append(line)
+    if not isinstance(command, click.Group):
+        return
+    children = [(child_name, child) for child_name, child in command.commands.items() if not child.hidden]
+    child_prefix = prefix + ("    " if is_last else "│   ")
+    for index, (child_name, child) in enumerate(children):
+        _render_command_tree(child, child_name, child_prefix, index == len(children) - 1, lines)
+
+
+def _render_cli_tree(root: click.Group) -> str:
+    children = [(name, command) for name, command in root.commands.items() if not command.hidden]
+    lines = [f"chatglance  # {_purpose(root)}"]
+    root_options = [
+        ("--help", "Show help for the current command."),
+        ("--version", "Show package version."),
+        ("--tree", "Print the registered CLI tree."),
+    ]
+    for index, (option, purpose) in enumerate(root_options):
+        is_last = not children and index == len(root_options) - 1
+        lines.append(f"{'└──' if is_last else '├──'} {option}  # {purpose}")
+    for index, (child_name, child) in enumerate(children):
+        _render_command_tree(child, child_name, "", index == len(children) - 1, lines)
+    return "\n".join(lines)
+
+
+@click.group(invoke_without_command=True, no_args_is_help=True)
+@click.version_option(__version__, prog_name="chatglance")
+@click.option("--tree", "show_tree", is_flag=True, is_eager=True, help="Print the registered CLI tree.")
+@click.pass_context
+def main(ctx: click.Context, show_tree: bool) -> None:
+    """Generate and maintain ChatArch Glance dashboard config."""
+
+    if show_tree:
+        click.echo(_render_cli_tree(ctx.command))
+        ctx.exit()
+
+
+@main.group()
+def projects() -> None:
+    """Generate Glance project dashboard pages."""
+
+
+@projects.command("render-page")
+@click.option("--data", "data_path", type=click.Path(path_type=Path, dir_okay=False, exists=True), required=True, help="Inventory JSON generated from repository metadata.")
+@click.option("--output", "output_path", type=click.Path(path_type=Path, dir_okay=False), required=True, help="YAML file to write the generated Glance page object to.")
+@click.option("--page-name", default=PAGE_NAME, show_default=True, help="Generated Glance page name.")
+def render_projects_page(data_path: Path, output_path: Path, page_name: str) -> None:
+    """Render the `项目` page YAML from inventory JSON."""
+
+    data = load_inventory(data_path)
+    page = build_projects_page(data, page_name=page_name)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(dump_yaml(page), encoding="utf-8")
+    click.echo(f"wrote {output_path}")
+
+
+@projects.command("update-config")
+@click.option("--data", "data_path", type=click.Path(path_type=Path, dir_okay=False, exists=True), required=True, help="Inventory JSON generated from repository metadata.")
+@click.option("--config", "config_path", type=click.Path(path_type=Path, dir_okay=False, exists=True), required=True, help="Existing Glance YAML config.")
+@click.option("--output", "output_path", type=click.Path(path_type=Path, dir_okay=False), required=True, help="Output path for the updated Glance YAML config.")
+@click.option("--page-name", default=PAGE_NAME, show_default=True, help="Generated Glance page name.")
+def update_projects_config(data_path: Path, config_path: Path, output_path: Path, page_name: str) -> None:
+    """Write a config copy with the generated project page replaced."""
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    update_projects_page_from_files(config_path, data_path, output_path, page_name=page_name)
+    click.echo(f"wrote {output_path}")
+
+
+@main.group()
+def disks() -> None:
+    """Patch Glance server-stats disk display."""
+
+
+@disks.command("root-only")
+@click.option("--config", "config_path", type=click.Path(path_type=Path, dir_okay=False, exists=True), required=True, help="Existing Glance YAML config.")
+@click.option("--output", "output_path", type=click.Path(path_type=Path, dir_okay=False), required=True, help="Output path for the patched Glance YAML config.")
+@click.option("--mountpoint", default="/", show_default=True, help="Only mountpoint to display.")
+@click.option("--name", "mount_name", default="根分区", show_default=True, help="Display name for the mountpoint.")
+def root_only_disk(config_path: Path, output_path: Path, mountpoint: str, mount_name: str) -> None:
+    """Write a config copy that hides default snap/loop mountpoints."""
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    patch_disks_from_files(config_path, output_path, mountpoint=mountpoint, name=mount_name)
+    click.echo(f"wrote {output_path}")
+
+
+@main.group()
+def runtime() -> None:
+    """Maintain a durable Glance service runtime."""
+
+
+@runtime.command("maintain")
+@click.option("--runtime-home", type=click.Path(path_type=Path, file_okay=False), default=Path("~/.chatarch/glance"), show_default=True, help="Durable Glance service home.")
+@click.option("--config", "config_path", type=click.Path(path_type=Path, dir_okay=False), default=Path("config/glance.yml"), show_default=True, help="Runtime-relative or absolute Glance YAML config.")
+@click.option("--data", "data_path", type=click.Path(path_type=Path, dir_okay=False), default=Path("data/chatarch-projects.json"), show_default=True, help="Runtime-relative or absolute repository inventory JSON.")
+@click.option("--backup-dir", type=click.Path(path_type=Path, file_okay=False), default=Path("config/backups"), show_default=True, help="Runtime-relative or absolute backup directory for in-place writes.")
+@click.option("--page-name", default=PAGE_NAME, show_default=True, help="Generated Glance page name.")
+@click.option("--validate/--no-validate", default=True, show_default=True, help="Validate the candidate config with the upstream Glance binary before replacing it.")
+@click.option("--glance-bin", type=click.Path(path_type=Path, dir_okay=False), default=Path("bin/glance"), show_default=True, help="Runtime-relative or absolute Glance binary used for config validation.")
+@click.option("--restart-service", default=None, help="systemd user service to restart only if the rendered config changed.")
+def maintain_runtime(runtime_home: Path, config_path: Path, data_path: Path, backup_dir: Path, page_name: str, validate: bool, glance_bin: Path, restart_service: str | None) -> None:
+    """Apply generated project content and root-only Disk config once."""
+
+    runtime_home = runtime_home.expanduser()
+    config = runtime_path(runtime_home, config_path)
+    data = runtime_path(runtime_home, data_path)
+    backups = runtime_path(runtime_home, backup_dir) if backup_dir else None
+    binary = runtime_path(runtime_home, glance_bin) if validate else None
+    result = maintain_config(
+        config_path=config,
+        data_path=data,
+        output_path=config,
+        backup_dir=backups,
+        validate_bin=binary,
+        page_name=page_name,
+        restart_service=restart_service,
+    )
+    click.echo(
+        " ".join(
+            [
+                f"output={result.output_path}",
+                f"changed={str(result.changed).lower()}",
+                f"validated={str(result.validated).lower()}",
+                f"restarted={str(result.restarted).lower()}",
+                f"backup={result.backup_path or '-'}",
+            ]
+        )
+    )
+
+
+@runtime.command("render-systemd")
+@click.option("--runtime-home", type=click.Path(path_type=Path, file_okay=False), default=Path("~/.chatarch/glance"), show_default=True, help="Durable Glance service home.")
+@click.option("--chatglance-bin", type=click.Path(path_type=Path, dir_okay=False), required=True, help="Absolute path to the chatglance executable used by the maintenance oneshot.")
+@click.option("--service-name", default="chatarch-glance.service", show_default=True, help="Main Glance user service name.")
+@click.option("--maintenance-service-name", default="chatarch-glance-maintenance.service", show_default=True, help="Generated oneshot maintenance service name.")
+@click.option("--timer-name", default="chatarch-glance-maintenance.timer", show_default=True, help="Generated maintenance timer name.")
+@click.option("--interval", default="30min", show_default=True, help="systemd OnUnitActiveSec interval for the maintenance timer.")
+@click.option("--output-dir", type=click.Path(path_type=Path, file_okay=False), help="Directory to write unit files. Omit to print them.")
+def render_systemd(runtime_home: Path, chatglance_bin: Path, service_name: str, maintenance_service_name: str, timer_name: str, interval: str, output_dir: Path | None) -> None:
+    """Render direct Glance service plus chatglance maintenance units."""
+
+    units = render_all_units(
+        runtime_home=runtime_home.expanduser(),
+        chatglance_bin=chatglance_bin.expanduser(),
+        service_name=service_name,
+        maintenance_service_name=maintenance_service_name,
+        timer_name=timer_name,
+        interval=interval,
+    )
+    if output_dir:
+        paths = write_units(output_dir.expanduser(), units)
+        for path in paths:
+            click.echo(f"wrote {path}")
+        return
+    click.echo(f"# {units.service_name}\n{units.service}")
+    click.echo(f"# {units.maintenance_service_name}\n{units.maintenance_service}")
+    click.echo(f"# {units.timer_name}\n{units.timer}")
+
+
+if __name__ == "__main__":
+    main()

chatglance-0.0.1/src/chatglance/glance_config.py

@@ -0,0 +1,104 @@
+"""Safe Glance YAML config transformations for chatglance."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Iterator
+
+from .projects import LEGACY_PAGE_NAMES, PAGE_NAME, build_projects_page, dump_yaml, load_inventory
+
+
+def load_yaml(path: str | Path) -> dict[str, Any]:
+    import yaml
+
+    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("Glance config must be a YAML mapping")
+    return data
+
+
+def write_yaml(path: str | Path, data: dict[str, Any]) -> None:
+    Path(path).write_text(dump_yaml(data), encoding="utf-8")
+
+
+def replace_projects_page(config: dict[str, Any], inventory: dict[str, Any], *, page_name: str = PAGE_NAME) -> dict[str, Any]:
+    """Return a config copy where the generated projects page is replaced.
+
+    This function does not mutate the input mapping. It removes old generated page
+    names and then replaces/appends the current `page_name` page.
+    """
+
+    updated = deepcopy(config)
+    pages = updated.setdefault("pages", [])
+    if not isinstance(pages, list):
+        raise ValueError("Glance config `pages` must be a list")
+    legacy_names = set(LEGACY_PAGE_NAMES) | {page_name}
+    pages[:] = [page for page in pages if not (isinstance(page, dict) and page.get("name") in legacy_names)]
+    pages.append(build_projects_page(inventory, page_name=page_name))
+    return updated
+
+
+def iter_widgets(value: Any) -> Iterator[dict[str, Any]]:
+    """Yield Glance widget mappings recursively from pages/columns/groups."""
+
+    if isinstance(value, dict):
+        if "type" in value:
+            yield value
+        for key in ("widgets", "columns"):
+            nested = value.get(key)
+            if isinstance(nested, list):
+                for item in nested:
+                    yield from iter_widgets(item)
+    elif isinstance(value, list):
+        for item in value:
+            yield from iter_widgets(item)
+
+
+def patch_server_stats_root_only(
+    config: dict[str, Any],
+    *,
+    mountpoint: str = "/",
+    name: str = "根分区",
+    hide_swap: bool = True,
+) -> dict[str, Any]:
+    """Return a config copy where all server-stats widgets show only one mountpoint.
+
+    Glance's `mountpoints` entries name configured mountpoints, but without
+    `hide-mountpoints-by-default: true` Glance can still render all default OS
+    mountpoints, including snap/loop mounts. This helper sets both fields.
+    """
+
+    updated = deepcopy(config)
+    for widget in iter_widgets(updated.get("pages", [])):
+        if widget.get("type") != "server-stats":
+            continue
+        widget["hide-mountpoints-by-default"] = True
+        servers = widget.get("servers")
+        if not isinstance(servers, list):
+            # A bare local server-stats widget can exist; keep it safe by adding
+            # a local server entry rather than leaving defaults visible.
+            servers = [{"type": "local", "name": "local"}]
+            widget["servers"] = servers
+        for server in servers:
+            if not isinstance(server, dict):
+                continue
+            server["hide-swap"] = bool(hide_swap)
+            server["hide-mountpoints-by-default"] = True
+            server["mountpoints"] = {mountpoint: {"name": name}}
+    return updated
+
+
+def update_projects_page_from_files(config_path: str | Path, data_path: str | Path, output_path: str | Path, *, page_name: str = PAGE_NAME) -> Path:
+    config = load_yaml(config_path)
+    inventory = load_inventory(data_path)
+    updated = replace_projects_page(config, inventory, page_name=page_name)
+    write_yaml(output_path, updated)
+    return Path(output_path)
+
+
+def patch_disks_from_files(config_path: str | Path, output_path: str | Path, *, mountpoint: str = "/", name: str = "根分区") -> Path:
+    config = load_yaml(config_path)
+    updated = patch_server_stats_root_only(config, mountpoint=mountpoint, name=name)
+    write_yaml(output_path, updated)
+    return Path(output_path)