chatglance 0.0.1__py3-none-any.whl

chatglance/__init__.py

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

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/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)

chatglance/projects.py

@@ -0,0 +1,224 @@
+"""Build Glance project-dashboard pages from ChatArch repository inventory JSON."""
+
+from __future__ import annotations
+
+import html
+import json
+from pathlib import Path
+from typing import Any
+
+PAGE_NAME = "项目"
+LEGACY_PAGE_NAMES = {"Projects", "ChatArch Projects", "ChatArch Projects List"}
+
+CATEGORY_LABELS = {
+    "python-package": "Python 包",
+    "node-package": "Node / npm 包",
+    "service/app": "服务 / 应用",
+    "docs/site": "文档 / 站点",
+    "template/early": "模板 / 早期包",
+    "other": "其他项目",
+}
+CATEGORY_ORDER = ["python-package", "node-package", "service/app", "docs/site", "template/early", "other"]
+
+
+def load_inventory(path: str | Path) -> dict[str, Any]:
+    """Load a ChatArch repository inventory JSON file."""
+
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("inventory JSON must be an object")
+    repos = data.get("repositories")
+    if not isinstance(repos, list):
+        raise ValueError("inventory JSON must contain a repositories list")
+    return data
+
+
+def safe_date(value: Any) -> str:
+    text = str(value or "").strip()
+    if "T" in text:
+        return text.split("T", 1)[0]
+    return text or "—"
+
+
+def text_value(value: Any, fallback: str = "—") -> str:
+    text = str(value or "").strip()
+    return text or fallback
+
+
+def html_text(value: Any, fallback: str = "—") -> str:
+    return html.escape(text_value(value, fallback), quote=True)
+
+
+def version_display(version: dict[str, Any] | None) -> str:
+    if not isinstance(version, dict):
+        return "—"
+    value = text_value(version.get("value"), "")
+    if not value:
+        return "—"
+    source = text_value(version.get("source"), "")
+    return f"{value} · {source}" if source else value
+
+
+def repositories(data: dict[str, Any]) -> list[dict[str, Any]]:
+    return [item for item in data.get("repositories", []) if isinstance(item, dict)]
+
+
+def sorted_repos(data: dict[str, Any], sort_key: str, limit: int | None = None) -> list[dict[str, Any]]:
+    repos = repositories(data)
+    if sort_key == "recent":
+        rows = sorted(repos, key=lambda item: text_value(item.get("pushed_at") or item.get("updated_at"), ""), reverse=True)
+    elif sort_key == "triage":
+        rows = [item for item in repos if int(item.get("open_prs") or 0) > 0 or int(item.get("open_issues") or 0) > 0]
+        rows = sorted(
+            rows,
+            key=lambda item: (
+                int(item.get("open_prs") or 0),
+                int(item.get("open_issues") or 0),
+                text_value(item.get("pushed_at") or item.get("updated_at"), ""),
+            ),
+            reverse=True,
+        )
+    elif sort_key == "category":
+        order = {name: index for index, name in enumerate(CATEGORY_ORDER)}
+        rows = sorted(repos, key=lambda item: (order.get(text_value(item.get("category"), "other"), 999), text_value(item.get("name"), "")))
+    else:
+        rows = sorted(repos, key=lambda item: text_value(item.get("name"), "").lower())
+    return rows[:limit] if limit else rows
+
+
+def bookmark_link(item: dict[str, Any], *, url_kind: str = "repo") -> dict[str, str]:
+    url = text_value(item.get("html_url"), "https://github.com/ChatArch")
+    if url_kind == "docs":
+        docs = item.get("docs") if isinstance(item.get("docs"), list) else []
+        if docs and isinstance(docs[0], dict):
+            url = text_value(docs[0].get("url"), url)
+    desc_parts = [
+        f"PR {int(item.get('open_prs') or 0)}",
+        f"Issue {int(item.get('open_issues') or 0)}",
+        f"提交 {safe_date(item.get('pushed_at') or item.get('updated_at'))}",
+    ]
+    version = version_display(item.get("version") if isinstance(item.get("version"), dict) else None)
+    if version != "—":
+        desc_parts.append(version)
+    return {
+        "title": text_value(item.get("name"), "unknown"),
+        "url": url,
+        "description": " · ".join(desc_parts),
+        "icon": "si:github",
+    }
+
+
+def make_overview_groups(data: dict[str, Any]) -> list[dict[str, Any]]:
+    counts = data.get("counts") if isinstance(data.get("counts"), dict) else {}
+    triage_count = int(counts.get("with_open_prs") or 0) + int(counts.get("with_open_issues") or 0)
+    return [
+        {
+            "title": "概览",
+            "links": [
+                {"title": "可见仓库", "url": "https://github.com/ChatArch", "description": str(counts.get("visible_repos", len(repositories(data)))), "icon": "si:github"},
+                {"title": "待处理 PR / Issue", "url": "https://github.com/ChatArch", "description": str(triage_count), "icon": "mdi:source-pull"},
+                {"title": "生成数据", "url": "https://github.com/ChatArch", "description": "本地生成快照 · 不含凭据", "icon": "mdi:code-json"},
+            ],
+        }
+    ]
+
+
+def make_sort_widget(data: dict[str, Any], title: str, sort_key: str) -> dict[str, Any]:
+    rows = sorted_repos(data, sort_key)
+    return {
+        "type": "bookmarks",
+        "title": title,
+        "groups": [{"title": f"{title} ({len(rows)})", "links": [bookmark_link(item) for item in rows]}],
+    }
+
+
+def make_category_groups(data: dict[str, Any]) -> list[dict[str, Any]]:
+    groups: list[dict[str, Any]] = []
+    for category in CATEGORY_ORDER:
+        rows = [item for item in sorted_repos(data, "category") if text_value(item.get("category"), "other") == category]
+        if rows:
+            groups.append({"title": CATEGORY_LABELS.get(category, category), "links": [bookmark_link(item) for item in rows]})
+    remainder = [item for item in sorted_repos(data, "category") if text_value(item.get("category"), "other") not in CATEGORY_ORDER]
+    if remainder:
+        groups.append({"title": "其他项目", "links": [bookmark_link(item) for item in remainder]})
+    return groups
+
+
+def make_categories_widget(data: dict[str, Any]) -> dict[str, Any]:
+    return {"type": "bookmarks", "title": "分类", "collapse-after": 12, "groups": make_category_groups(data)}
+
+
+def make_table_widget(data: dict[str, Any]) -> dict[str, Any]:
+    rows: list[str] = []
+    for item in sorted_repos(data, "name"):
+        commands = ((item.get("cli") or {}).get("commands") if isinstance(item.get("cli"), dict) else []) or []
+        cli = ", ".join(str(command) for command in commands[:3])
+        if len(commands) > 3:
+            cli += f" +{len(commands) - 3}"
+        docs = item.get("docs") if isinstance(item.get("docs"), list) else []
+        docs_url = docs[0].get("url") if docs and isinstance(docs[0], dict) else ""
+        docs_cell = f'<a href="{html_text(docs_url)}" target="_blank" rel="noreferrer">文档</a>' if docs_url else "—"
+        rows.append(
+            "<tr>"
+            f'<td><a href="{html_text(item.get("html_url"))}" target="_blank" rel="noreferrer">{html_text(item.get("name"))}</a></td>'
+            f'<td class="num">{int(item.get("open_prs") or 0)}</td>'
+            f'<td class="num">{int(item.get("open_issues") or 0)}</td>'
+            f'<td>{html_text(version_display(item.get("version") if isinstance(item.get("version"), dict) else None))}</td>'
+            f'<td>{html_text(CATEGORY_LABELS.get(text_value(item.get("category"), "other"), text_value(item.get("category"), "other")))}</td>'
+            f'<td>{html_text(cli)}</td>'
+            f'<td>{docs_cell}</td>'
+            f'<td>{html_text(safe_date(item.get("pushed_at") or item.get("updated_at")))}</td>'
+            "</tr>"
+        )
+    source = """
+<style>
+.projects-table-wrap { overflow-x: auto; }
+.projects-table { width: 100%; border-collapse: collapse; font-size: 0.9em; }
+.projects-table th, .projects-table td { padding: 0.38rem 0.5rem; border-bottom: 1px solid var(--color-separator); vertical-align: top; }
+.projects-table th { text-align: left; position: sticky; top: 0; background: var(--color-widget-background); z-index: 1; }
+.projects-table td.num { text-align: right; font-variant-numeric: tabular-nums; }
+.projects-table a { color: inherit; text-decoration: none; }
+.projects-table a:hover { text-decoration: underline; }
+</style>
+<div class="projects-table-wrap">
+<table class="projects-table">
+<thead><tr><th>仓库</th><th>PR</th><th>Issue</th><th>版本</th><th>类型</th><th>CLI</th><th>文档</th><th>最近提交</th></tr></thead>
+<tbody>
+""" + "\n".join(rows) + """
+</tbody>
+</table>
+</div>
+"""
+    return {"type": "html", "title": "一览表", "source": source}
+
+
+def build_projects_page(data: dict[str, Any], *, page_name: str = PAGE_NAME) -> dict[str, Any]:
+    """Build the Glance page object for the ChatArch projects dashboard."""
+
+    page = {
+        "name": page_name,
+        "columns": [
+            {"size": "small", "widgets": [{"type": "bookmarks", "title": "概览", "groups": make_overview_groups(data)}]},
+            {
+                "size": "full",
+                "widgets": [
+                    {
+                        "type": "group",
+                        "widgets": [
+                            make_sort_widget(data, "最近提交", "recent"),
+                            make_sort_widget(data, "待处理 PR / Issue", "triage"),
+                            make_categories_widget(data),
+                            make_table_widget(data),
+                        ],
+                    }
+                ],
+            },
+        ],
+    }
+    return page
+
+
+def dump_yaml(value: Any) -> str:
+    import yaml
+
+    return yaml.safe_dump(value, sort_keys=False, allow_unicode=True, width=120)

chatglance/runtime.py

@@ -0,0 +1,122 @@
+"""Runtime maintenance helpers for a durable Glance service home."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+import shutil
+import subprocess
+from typing import Any
+
+from .glance_config import load_yaml, patch_server_stats_root_only, replace_projects_page, write_yaml
+from .projects import PAGE_NAME, load_inventory
+
+
+@dataclass(frozen=True)
+class MaintainResult:
+    """Result of a runtime maintenance pass."""
+
+    output_path: Path
+    changed: bool
+    backup_path: Path | None
+    validated: bool
+    restarted: bool
+
+
+def build_maintained_config(config: dict[str, Any], inventory: dict[str, Any], *, page_name: str = PAGE_NAME) -> dict[str, Any]:
+    """Apply all chatglance-managed config transformations.
+
+    The runtime boundary is deliberately narrow: this updates generated dashboard
+    content and Glance `server-stats` disk presentation. It does not embed live
+    credentials, run the Glance server, or fetch repository metadata.
+    """
+
+    updated = replace_projects_page(config, inventory, page_name=page_name)
+    updated = patch_server_stats_root_only(updated)
+    return updated
+
+
+def _read_text_if_exists(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    return path.read_text(encoding="utf-8")
+
+
+def _timestamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def validate_glance_config(glance_bin: str | Path, config_path: str | Path) -> None:
+    """Validate a config file with the upstream Glance binary."""
+
+    subprocess.run(
+        [str(glance_bin), "-config", str(config_path), "config:validate"],
+        check=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+
+def maintain_config(
+    *,
+    config_path: str | Path,
+    data_path: str | Path,
+    output_path: str | Path | None = None,
+    backup_dir: str | Path | None = None,
+    validate_bin: str | Path | None = None,
+    page_name: str = PAGE_NAME,
+    restart_service: str | None = None,
+) -> MaintainResult:
+    """Maintain a Glance config using a repository-inventory snapshot.
+
+    If `output_path` is the same as `config_path`, the write is in-place: a
+    backup is created when `backup_dir` is provided, the candidate is validated
+    before replacing the live file, and an optional systemd user service restart
+    runs only when the rendered config actually changed.
+    """
+
+    source = Path(config_path)
+    output = Path(output_path) if output_path is not None else source
+    config = load_yaml(source)
+    inventory = load_inventory(data_path)
+    updated = build_maintained_config(config, inventory, page_name=page_name)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    tmp = output.with_name(f".{output.name}.chatglance.tmp")
+    write_yaml(tmp, updated)
+
+    if validate_bin is not None:
+        validate_glance_config(validate_bin, tmp)
+    validated = validate_bin is not None
+
+    old_text = _read_text_if_exists(output)
+    new_text = tmp.read_text(encoding="utf-8")
+    changed = old_text != new_text
+    backup_path: Path | None = None
+    restarted = False
+
+    if changed:
+        if output.exists() and backup_dir is not None:
+            backup_root = Path(backup_dir)
+            backup_root.mkdir(parents=True, exist_ok=True)
+            backup_path = backup_root / f"{output.name}.{_timestamp()}.bak"
+            shutil.copy2(output, backup_path)
+        tmp.replace(output)
+        if restart_service:
+            subprocess.run(["systemctl", "--user", "restart", restart_service], check=True)
+            restarted = True
+    else:
+        tmp.unlink(missing_ok=True)
+
+    return MaintainResult(output_path=output, changed=changed, backup_path=backup_path, validated=validated, restarted=restarted)
+
+
+def runtime_path(runtime_home: str | Path, relative_or_absolute: str | Path) -> Path:
+    """Resolve a runtime-relative path without forcing callers into cwd tricks."""
+
+    value = Path(relative_or_absolute).expanduser()
+    if value.is_absolute():
+        return value
+    return Path(runtime_home).expanduser() / value

chatglance/systemd.py

@@ -0,0 +1,150 @@
+"""systemd unit rendering for chatglance-managed Glance runtimes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SystemdUnits:
+    """Rendered systemd user units for a Glance runtime."""
+
+    service_name: str
+    service: str
+    maintenance_service_name: str
+    maintenance_service: str
+    timer_name: str
+    timer: str
+
+
+def _path(value: str | Path) -> str:
+    return str(Path(value).expanduser())
+
+
+def render_glance_service(
+    *,
+    runtime_home: str | Path,
+    glance_bin: str | Path = "bin/glance",
+    config_path: str | Path = "config/glance.yml",
+    description: str = "ChatArch Glance dashboard",
+) -> str:
+    """Render the long-running Glance service unit.
+
+    This intentionally starts the upstream Glance binary directly. `chatglance`
+    is not a Python wrapper around the server process.
+    """
+
+    home = Path(runtime_home).expanduser()
+    binary = Path(glance_bin)
+    if not binary.is_absolute():
+        binary = home / binary
+    config = Path(config_path)
+    if not config.is_absolute():
+        config = home / config
+    return f"""[Unit]
+Description={description}
+After=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory={_path(home)}
+ExecStart={_path(binary)} -config {_path(config)}
+Restart=always
+RestartSec=5
+StandardOutput=append:{_path(home / 'logs/glance.stdout.log')}
+StandardError=append:{_path(home / 'logs/glance.stderr.log')}
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def render_maintenance_service(
+    *,
+    runtime_home: str | Path,
+    chatglance_bin: str | Path,
+    restart_service: str = "chatarch-glance.service",
+    description: str = "Maintain ChatArch Glance generated config",
+) -> str:
+    """Render a oneshot maintenance unit that applies generated content.
+
+    The unit calls `chatglance runtime maintain`, validates with the Glance
+    binary, and restarts the Glance user service only when the rendered config
+    changed.
+    """
+
+    home = Path(runtime_home).expanduser()
+    return f"""[Unit]
+Description={description}
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory={_path(home)}
+ExecStart={_path(chatglance_bin)} runtime maintain --runtime-home {_path(home)} --restart-service {restart_service}
+"""
+
+
+def render_timer(
+    *,
+    timer_unit: str = "chatarch-glance-maintenance.service",
+    interval: str = "30min",
+    description: str = "Run ChatArch Glance maintenance periodically",
+) -> str:
+    """Render a periodic systemd user timer for the maintenance oneshot."""
+
+    return f"""[Unit]
+Description={description}
+
+[Timer]
+OnBootSec=5min
+OnUnitActiveSec={interval}
+Persistent=true
+Unit={timer_unit}
+
+[Install]
+WantedBy=timers.target
+"""
+
+
+def render_all_units(
+    *,
+    runtime_home: str | Path,
+    chatglance_bin: str | Path,
+    service_name: str = "chatarch-glance.service",
+    maintenance_service_name: str = "chatarch-glance-maintenance.service",
+    timer_name: str = "chatarch-glance-maintenance.timer",
+    interval: str = "30min",
+) -> SystemdUnits:
+    """Render the recommended user-service topology for a Glance runtime."""
+
+    return SystemdUnits(
+        service_name=service_name,
+        service=render_glance_service(runtime_home=runtime_home),
+        maintenance_service_name=maintenance_service_name,
+        maintenance_service=render_maintenance_service(
+            runtime_home=runtime_home,
+            chatglance_bin=chatglance_bin,
+            restart_service=service_name,
+        ),
+        timer_name=timer_name,
+        timer=render_timer(timer_unit=maintenance_service_name, interval=interval),
+    )
+
+
+def write_units(output_dir: str | Path, units: SystemdUnits) -> list[Path]:
+    """Write rendered units to an output directory."""
+
+    root = Path(output_dir)
+    root.mkdir(parents=True, exist_ok=True)
+    paths = [
+        root / units.service_name,
+        root / units.maintenance_service_name,
+        root / units.timer_name,
+    ]
+    contents = [units.service, units.maintenance_service, units.timer]
+    for path, content in zip(paths, contents, strict=True):
+        path.write_text(content, encoding="utf-8")
+    return paths

chatglance-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+chatglance/__init__.py,sha256=ND9tvpnp2d32-4YjM30dyTYeFnxRE3rt7lESCJcF6O4,76
+chatglance/cli.py,sha256=68aohCN4yrbFsTnO4NaDUChM9MXUkyGwacXNGFNbQiY,11610
+chatglance/glance_config.py,sha256=VxE93rw9oRT8wm752SuXnP93B0OBWxLdPWkwpGgq3RI,4024
+chatglance/projects.py,sha256=9iVHTOpe90ylDOQhehQvrlFShDO5-yPODzsrWXUJBOY,9496
+chatglance/runtime.py,sha256=dghz7YoIdRCshBL9emvMWlJgQALQXsfxaESQwVoFEWQ,4154
+chatglance/systemd.py,sha256=L46G9VrjOxtalSpK9RNfBl6kmGKTLif7Mx2oqVC7jrA,4207
+chatglance-0.0.1.dist-info/licenses/LICENSE,sha256=G-fJLQ4pkXXISE3qeN8J5Cw5VRoNongA0hbsHA9TRe8,1065
+chatglance-0.0.1.dist-info/METADATA,sha256=fe0jp5dHuH1No4n1fBwjQMkya8DEZqnp2TQFXGPRCsU,4732
+chatglance-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+chatglance-0.0.1.dist-info/entry_points.txt,sha256=ywnllmIM7VX8HIypCdYBYxK4wlEMtf06hbplkeNabfs,51
+chatglance-0.0.1.dist-info/top_level.txt,sha256=R41gAv-uBU31IM5_5o5aNW79TCd3f4Eli_c1boRA6bw,11
+chatglance-0.0.1.dist-info/RECORD,,

chatglance-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chatglance-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chatglance = chatglance.cli:main

chatglance-0.0.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+chatglance