campfire-cli 0.1.0__py3-none-any.whl

campfire_cli/app/maintenance/cli/maintenance_cli.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+HELP_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+maintenance_cli = typer.Typer(help="后续增量文档维护", context_settings=HELP_SETTINGS)
+archive_cli = typer.Typer(help="项目文档两阶段归档", context_settings=HELP_SETTINGS)
+maintenance_cli.add_typer(archive_cli, name="archive")
+
+
+def emit(result: object) -> None:
+    typer.echo(json.dumps(result.model_dump(mode="json"), ensure_ascii=False, indent=2))
+
+
+@maintenance_cli.command("check")
+def check(
+    ctx: typer.Context,
+    scope: str | None = typer.Option(None, "--scope", help="只显示指定 Vault 相对路径下的问题"),
+    code: str | None = typer.Option(None, "--code", help="只显示指定错误代码"),
+    severity: str | None = typer.Option(None, "--severity", help="只显示指定严重级别"),
+    summary: bool = typer.Option(False, "--summary", help="只输出统计，不展开问题列表"),
+) -> None:
+    """检查当前受管文档并刷新 SQLite 当前状态。"""
+    emit(ctx.obj.maintenance.check(scope=scope, code=code, severity=severity, summary=summary))
+
+
+@maintenance_cli.command("plan")
+def plan(
+    ctx: typer.Context,
+    plan_id: str = typer.Option(..., "--id", help="稳定的维护计划 ID"),
+    scope: str | None = typer.Option(None, "--scope", help="只规划指定 Vault 相对路径"),
+    spec: Path | None = typer.Option(None, "--spec", help="Agent 或人类提供的语义治理 YAML/JSON"),
+) -> None:
+    """生成带稳定 ID、默认未审批的维护计划。"""
+    emit(ctx.obj.maintenance.plan(plan_id, scope=scope, spec_path=spec))
+
+
+@maintenance_cli.command("show")
+def show(ctx: typer.Context, plan_id: str = typer.Option(..., "--plan")) -> None:
+    """查看一个稳定 ID 标识的维护计划。"""
+    emit(ctx.obj.maintenance.show_plan(plan_id))
+
+
+@maintenance_cli.command("apply")
+def apply(
+    ctx: typer.Context,
+    plan_id: str = typer.Option(..., "--plan"),
+    confirm: bool = typer.Option(False, "--confirm"),
+) -> None:
+    """预检或执行指定维护计划中的已审批项。"""
+    emit(ctx.obj.maintenance.apply(plan_id, confirm))
+
+
+@maintenance_cli.command("verify")
+def verify(ctx: typer.Context, plan_id: str = typer.Option(..., "--plan")) -> None:
+    """只验证指定维护计划涉及的文档。"""
+    emit(ctx.obj.maintenance.verify(plan_id))
+
+
+@maintenance_cli.command("sync")
+def sync(
+    ctx: typer.Context,
+    dry_run: bool = typer.Option(False, "--dry-run"),
+    scope: str | None = typer.Option(None, "--scope", help="只同步指定领域或治理根目录"),
+) -> None:
+    """同步 MOC 等确定性派生内容。"""
+    emit(ctx.obj.maintenance.sync(dry_run, scope))
+
+
+@maintenance_cli.command("run")
+def run(
+    ctx: typer.Context,
+    scope: str | None = typer.Option(None, "--scope", help="只同步并显示指定范围"),
+) -> None:
+    """执行同步和最终只读检查。"""
+    sync_result = ctx.obj.maintenance.sync(False, scope)
+    if sync_result.issue_count:
+        emit(sync_result)
+        raise typer.Exit(3)
+    emit(ctx.obj.maintenance.check(scope=scope))
+
+
+@archive_cli.command("check")
+def archive_check(
+    ctx: typer.Context,
+    scope: str | None = typer.Option(None, "--scope", help="只检查指定 Vault 相对路径"),
+) -> None:
+    """只读检查归档候选。"""
+    emit(ctx.obj.maintenance.archive(False, scope))
+
+
+@archive_cli.command("apply")
+def archive_apply(
+    ctx: typer.Context,
+    confirm: bool = typer.Option(False, "--confirm"),
+    scope: str | None = typer.Option(None, "--scope", help="只归档指定 Vault 相对路径"),
+) -> None:
+    """执行已经标记并通过检查的归档请求。"""
+    emit(ctx.obj.maintenance.archive(confirm, scope))

campfire_cli/app/maintenance/repository/maintenance_repository.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy import delete
+from sqlalchemy.orm import Session
+
+from campfire_cli.app.maintenance.schema.maintenance_schema import (
+    DocumentState,
+    DomainState,
+    Issue,
+    MaintenancePlan,
+    MaintenanceRunRecord,
+    SpaceState,
+)
+from campfire_cli.common.database.models import (
+    Document,
+    GovernanceIssue,
+    MaintenanceRun,
+    WorkspaceDomain,
+    WorkspaceSpace,
+)
+from campfire_cli.common.exceptions import GovernanceBlockedError
+from campfire_cli.common.filesystem import atomic_write
+
+
+class SqliteMaintenanceRepository:
+    def __init__(self, session: Session, workspace_id: str, state_root: Path) -> None:
+        self._session = session
+        self._workspace_id = workspace_id
+        self._state_root = state_root
+
+    def replace_current_state(
+        self,
+        documents: list[DocumentState],
+        issues: list[Issue],
+        spaces: list[SpaceState],
+        domains: list[DomainState],
+    ) -> None:
+        self._session.execute(delete(Document).where(Document.workspace_id == self._workspace_id))
+        self._session.execute(
+            delete(GovernanceIssue).where(GovernanceIssue.workspace_id == self._workspace_id)
+        )
+        self._session.execute(
+            delete(WorkspaceDomain).where(WorkspaceDomain.workspace_id == self._workspace_id)
+        )
+        self._session.execute(
+            delete(WorkspaceSpace).where(WorkspaceSpace.workspace_id == self._workspace_id)
+        )
+        self._session.add_all(
+            [
+                WorkspaceSpace(workspace_id=self._workspace_id, **item.model_dump())
+                for item in spaces
+            ]
+        )
+        self._session.add_all(
+            [
+                WorkspaceDomain(workspace_id=self._workspace_id, **item.model_dump())
+                for item in domains
+            ]
+        )
+        self._session.add_all(
+            [
+                Document(
+                    workspace_id=self._workspace_id,
+                    path=item.path,
+                    content_hash=item.content_hash,
+                    document_type=item.document_type,
+                    domain_id=item.domain_id,
+                    status=item.status,
+                )
+                for item in documents
+            ]
+        )
+        self._session.add_all(
+            [
+                GovernanceIssue(
+                    workspace_id=self._workspace_id,
+                    path=item.path,
+                    code=item.code,
+                    detail=item.detail,
+                    severity=item.severity,
+                )
+                for item in issues
+            ]
+        )
+        self._session.commit()
+
+    def save_run(self, run: MaintenanceRunRecord) -> None:
+        self._session.add(
+            MaintenanceRun(
+                workspace_id=self._workspace_id,
+                run_id=run.run_id,
+                status=run.status,
+                scanned_count=run.scanned_count,
+                issue_count=run.issue_count,
+                started_at=run.started_at,
+                finished_at=run.finished_at,
+            )
+        )
+        self._session.commit()
+
+    def save_plan(self, plan: MaintenancePlan) -> None:
+        atomic_write(self._plan_path(plan.plan_id), plan.model_dump_json(indent=2) + "\n")
+
+    def load_plan(self, plan_id: str) -> MaintenancePlan:
+        path = self._plan_path(plan_id)
+        if not path.is_file():
+            raise GovernanceBlockedError(f"Maintenance Plan 不存在：{plan_id}")
+        return MaintenancePlan.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def _plan_path(self, plan_id: str) -> Path:
+        if not plan_id or Path(plan_id).name != plan_id:
+            raise GovernanceBlockedError(f"Maintenance Plan id 非法：{plan_id}")
+        return self._state_root / "maintenance" / "plans" / plan_id / "plan.json"

campfire_cli/app/maintenance/schema/maintenance_schema.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Issue(BaseModel):
+    code: str
+    path: str
+    detail: str = ""
+    severity: str = "error"
+    message: str = ""
+    suggestion: str = ""
+    field: str | None = None
+    actual: Any = None
+    allowed: list[Any] = Field(default_factory=list)
+
+
+class DocumentState(BaseModel):
+    path: str
+    content_hash: str
+    document_type: str | None = None
+    domain_id: str | None = None
+    status: str | None = None
+
+
+class SpaceState(BaseModel):
+    space_id: str
+    name: str
+    path: str
+    space_type: str
+    status: str
+    source_hash: str
+
+
+class DomainState(BaseModel):
+    domain_id: str
+    space_id: str
+    parent_domain_id: str | None = None
+    project_id: str | None = None
+    name: str
+    path: str
+    domain_type: str
+    governance: str
+    moc: str
+    status: str
+    source_hash: str
+
+
+class MaintenanceResult(BaseModel):
+    status: str
+    document_count: int
+    issue_count: int
+    total_issue_count: int = 0
+    issues: list[Issue] = Field(default_factory=list)
+    changed_document_count: int = 0
+    generated_file_count: int = 0
+    write_performed: bool = False
+    blocked_phase: str | None = None
+    blocked_scope: str | None = None
+    issue_counts: dict[str, int] = Field(default_factory=dict)
+    operations: list[dict[str, Any]] = Field(default_factory=list)
+    scope: str | None = None
+    workspace_status: str | None = None
+    space_count: int = 0
+    domain_count: int = 0
+
+
+class MaintenanceIntentItem(BaseModel):
+    path: str
+    frontmatter: dict[str, Any] = Field(default_factory=dict)
+    filename: str | None = None
+    format_frontmatter: bool = True
+    reason: str
+    approved: bool = False
+
+
+class MaintenanceIntentSpec(BaseModel):
+    schema_version: int = 1
+    operations: list[MaintenanceIntentItem]
+
+
+class MaintenancePlanItem(BaseModel):
+    source: str
+    target: str
+    source_sha256: str
+    frontmatter: dict[str, Any] = Field(default_factory=dict)
+    format_frontmatter: bool = False
+    reason: str
+    approved: bool = False
+
+
+class MaintenancePlan(BaseModel):
+    schema_version: int = 1
+    plan_id: str
+    scope: str | None = None
+    config_hash: str
+    items: list[MaintenancePlanItem] = Field(default_factory=list)
+
+
+class MaintenanceRunRecord(BaseModel):
+    run_id: str
+    status: str
+    scanned_count: int
+    issue_count: int
+    started_at: datetime
+    finished_at: datetime

campfire_cli/app/maintenance/service/archive_service.py

@@ -0,0 +1,255 @@
+"""
+SPEC:
+  name: project_archive
+  purpose: 检查并执行项目文档的显式两阶段归档请求
+  default_env_file: none
+  env_override: none
+  idempotent: true
+  behavior:
+    - check 模式只读列出归档请求、路径状态和阻塞问题
+    - apply 模式只移动校验通过的请求到同领域扁平 archive 目录
+    - 完成归档时统一 status、lifecycle、archive_requested 和 archived_at
+  safety:
+    - 不依据更新时间自动归档
+    - 不覆盖同名目标，不删除文档，不处理治理范围外文件
+    - 缺少归档原因或必要替代文档时拒绝执行该文档
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.app.workspace.service.structure_service import (
+    DomainService,
+)
+from campfire_cli.app.workspace.service.structure_service import (
+    parse_marker as parse_frontmatter,
+)
+from campfire_cli.config.defaults import config_section
+
+
+@dataclass(frozen=True)
+class ArchiveItem:
+    source: Path
+    target: Path
+    domain: Path
+    in_archive: bool
+
+
+def is_true(value: str) -> bool:
+    return value.strip().lower() == "true"
+
+
+def list_has_values(value: str) -> bool:
+    compact = value.strip()
+    return bool(compact and compact not in {"[]", "null", "~"})
+
+
+def frontmatter_list_has_values(text: str, key: str, parsed_value: str) -> bool:
+    if list_has_values(parsed_value):
+        return True
+    if not text.startswith("---\n"):
+        return False
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        return False
+    lines = text[4:end].splitlines()
+    for index, line in enumerate(lines):
+        if not re.match(rf"^{re.escape(key)}:\s*$", line):
+            continue
+        for following in lines[index + 1 :]:
+            if re.match(r"^[a-zA-Z_][a-zA-Z0-9_-]*:", following):
+                break
+            if re.match(r"^\s+-\s+\S", following):
+                return True
+    return False
+
+
+def is_under(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def project_domains(vault_root: Path, config: dict[str, Any]) -> list[Path]:
+    domains, _ = DomainService(vault_root, vault_root).discover()
+    return sorted(
+        (item.path for item in domains if item.governance == "project-docs"),
+        key=lambda path: (len(path.parts), str(path)),
+    )
+
+
+def owning_domain(path: Path, domains: list[Path]) -> Path | None:
+    matches = [domain for domain in domains if is_under(path, domain)]
+    return max(matches, key=lambda item: len(item.parts)) if matches else None
+
+
+def collect_items(
+    vault_root: Path, config: dict[str, Any]
+) -> tuple[list[ArchiveItem], list[dict[str, str]]]:
+    domains = project_domains(vault_root, config)
+    policy = config_section("archive")
+    archive_reasons = set(policy["reasons"])
+    reasons_requiring_successor = set(policy["reasons_requiring_successor"])
+    marker_name = config.get("domain_marker", "_领域.md")
+    ignored = set(config.get("ignored_directories", [])) - {"archive", "记录"}
+    items: list[ArchiveItem] = []
+    issues: list[dict[str, str]] = []
+
+    for domain in domains:
+        for doc in domain.rglob("*.md"):
+            if (
+                owning_domain(doc, domains) != domain
+                or doc.name == marker_name
+                or doc.name.startswith("MOC-")
+            ):
+                continue
+            relative_to_domain = doc.relative_to(domain)
+            if any(part in ignored for part in relative_to_domain.parts):
+                continue
+            in_archive = "archive" in relative_to_domain.parts[:-1]
+            meta = parse_frontmatter(doc)
+            requested = is_true(meta.get("archive_requested", "false")) if meta else False
+            if not requested and not in_archive:
+                continue
+            target = doc if in_archive else domain / "archive" / doc.name
+            item = ArchiveItem(doc, target, domain, in_archive)
+            items.append(item)
+            rel = str(doc.relative_to(vault_root))
+
+            if not meta:
+                issues.append({"code": "archive-frontmatter-missing", "path": rel})
+                continue
+            raw_text = doc.read_text(encoding="utf-8")
+            reason = meta.get("archive_reason", "")
+            if not reason:
+                issues.append({"code": "archive-reason-missing", "path": rel})
+            elif reason not in archive_reasons:
+                issues.append({"code": "archive-reason-invalid", "path": rel, "detail": reason})
+            if reason in reasons_requiring_successor and not frontmatter_list_has_values(
+                raw_text, "superseded_by", meta.get("superseded_by", "")
+            ):
+                issues.append({"code": "archive-successor-missing", "path": rel})
+            if not in_archive and target.exists():
+                issues.append(
+                    {
+                        "code": "archive-target-exists",
+                        "path": rel,
+                        "detail": str(target.relative_to(vault_root)),
+                    }
+                )
+            if in_archive:
+                if meta.get("status") != "archived" or meta.get("lifecycle") != "archived":
+                    issues.append({"code": "archive-path-state-mismatch", "path": rel})
+            elif meta.get("status") == "archived" or meta.get("lifecycle") == "archived":
+                issues.append({"code": "archive-request-state-premature", "path": rel})
+    return sorted(items, key=lambda item: str(item.source)), issues
+
+
+def issue_paths(issues: list[dict[str, str]]) -> set[str]:
+    return {item["path"] for item in issues}
+
+
+def replace_frontmatter_fields(text: str, values: dict[str, str]) -> str:
+    if not text.startswith("---\n"):
+        raise ValueError("frontmatter missing")
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        raise ValueError("frontmatter closing marker missing")
+    body = text[4:end]
+    lines = body.splitlines()
+    positions: dict[str, int] = {}
+    for index, line in enumerate(lines):
+        match = re.match(r"^([a-zA-Z_][a-zA-Z0-9_-]*):", line)
+        if match:
+            positions[match.group(1)] = index
+    for key, value in values.items():
+        rendered = f"{key}: {value}"
+        if key in positions:
+            lines[positions[key]] = rendered
+        else:
+            insert_at = positions.get("created", len(lines))
+            lines.insert(insert_at, rendered)
+            positions = {
+                field: index + 1 if index >= insert_at else index
+                for field, index in positions.items()
+            }
+            positions[key] = insert_at
+    return "---\n" + "\n".join(lines) + text[end:]
+
+
+def apply_items(
+    vault_root: Path, items: list[ArchiveItem], issues: list[dict[str, str]], archived_at: str
+) -> list[dict[str, str]]:
+    applied: list[dict[str, str]] = []
+    for item in items:
+        rel = str(item.source.relative_to(vault_root))
+        # A path/state mismatch is repairable after an explicit manual move.
+        # Other issues block the document.
+        item_issues = [issue for issue in issues if issue["path"] == rel]
+        if any(issue["code"] != "archive-path-state-mismatch" for issue in item_issues):
+            continue
+        current_meta = parse_frontmatter(item.source)
+        if (
+            item.in_archive
+            and current_meta.get("status") == "archived"
+            and current_meta.get("lifecycle") == "archived"
+            and not is_true(current_meta.get("archive_requested", "false"))
+            and current_meta.get("archived_at")
+        ):
+            continue
+        effective_archived_at = current_meta.get("archived_at") or archived_at
+        updated = replace_frontmatter_fields(
+            item.source.read_text(encoding="utf-8"),
+            {
+                "status": "archived",
+                "lifecycle": "archived",
+                "archive_requested": "false",
+                "archived_at": effective_archived_at,
+            },
+        )
+        if item.in_archive:
+            item.source.write_text(updated, encoding="utf-8")
+            action = "normalized"
+        else:
+            item.target.parent.mkdir(parents=True, exist_ok=True)
+            item.target.write_text(updated, encoding="utf-8")
+            item.source.unlink()
+            action = "archived"
+        applied.append(
+            {
+                "action": action,
+                "source": rel,
+                "target": str(item.target.relative_to(vault_root)),
+            }
+        )
+    return applied
+
+
+def build_result(
+    vault_root: Path, config: dict[str, Any], apply: bool, archived_at: str
+) -> dict[str, Any]:
+    vault_root = vault_root.resolve()
+    items, issues = collect_items(vault_root, config)
+    applied = apply_items(vault_root, items, issues, archived_at) if apply else []
+    return {
+        "status": "issues-found" if issues else ("applied" if apply else "ok"),
+        "mode": "apply" if apply else "check",
+        "candidate_count": len(items),
+        "applied_count": len(applied),
+        "candidates": [
+            {
+                "source": str(item.source.relative_to(vault_root)),
+                "target": str(item.target.relative_to(vault_root)),
+                "already_in_archive": item.in_archive,
+            }
+            for item in items
+        ],
+        "applied": applied,
+        "issues": issues,
+    }

campfire_cli/app/maintenance/service/link_service.py

@@ -0,0 +1,91 @@
+"""
+SPEC:
+  name: link_service
+  purpose: 只读检查 Vault 或已治理范围的 wikilink、Markdown 链接、嵌入和附件引用
+  default_env_file: none
+  env_override: none
+  idempotent: true
+  behavior:
+    - 支持 managed 和 vault 两种扫描范围
+    - 报告失效、歧义 wikilink 和失效相对链接
+  safety:
+    - 不修改任何文件
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from pathlib import Path
+from urllib.parse import unquote
+
+WIKILINK_RE = re.compile(r"!?\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]")
+MARKDOWN_LINK_RE = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
+FENCED_CODE_RE = re.compile(r"```.*?```|~~~.*?~~~", re.DOTALL)
+INLINE_CODE_RE = re.compile(r"`[^`\n]*`")
+
+
+def vault_markdown_files(vault_root: Path) -> list[Path]:
+    excluded = {".git", ".obsidian", ".campfire"}
+    return sorted(
+        path
+        for path in vault_root.rglob("*.md")
+        if not any(part in excluded for part in path.relative_to(vault_root).parts)
+    )
+
+
+def check_links(vault_root: Path, sources: list[Path]) -> list[dict[str, str]]:
+    by_stem: dict[str, list[Path]] = defaultdict(list)
+    for candidate in vault_root.rglob("*"):
+        if candidate.is_file() and ".git" not in candidate.relative_to(vault_root).parts:
+            by_stem[candidate.stem].append(candidate)
+    issues: list[dict[str, str]] = []
+    for source in sources:
+        text = INLINE_CODE_RE.sub("", FENCED_CODE_RE.sub("", source.read_text(encoding="utf-8")))
+        for raw in WIKILINK_RE.findall(text):
+            target = unquote(raw.strip()).replace("\\", "/")
+            if "/" in target:
+                candidates = [
+                    vault_root / target,
+                    vault_root / f"{target}.md",
+                    source.parent / target,
+                    source.parent / f"{target}.md",
+                ]
+                matches = {item.resolve() for item in candidates if item.is_file()}
+            else:
+                stem = target[:-3] if target.lower().endswith(".md") else target
+                matches = set(by_stem.get(stem, []))
+            if not matches:
+                issues.append(
+                    {
+                        "code": "wikilink-missing",
+                        "path": source.relative_to(vault_root).as_posix(),
+                        "detail": raw,
+                    }
+                )
+            elif len(matches) > 1:
+                issues.append(
+                    {
+                        "code": "wikilink-ambiguous",
+                        "path": source.relative_to(vault_root).as_posix(),
+                        "detail": raw,
+                    }
+                )
+        for raw in MARKDOWN_LINK_RE.findall(text):
+            target = unquote(raw.strip().strip("<>").split("#", 1)[0])
+            if not target or re.match(r"^[A-Za-z][A-Za-z0-9+.-]*:", target):
+                continue
+            candidate = (
+                vault_root / target.lstrip("/")
+                if target.startswith("/")
+                else source.parent / target
+            )
+            if not candidate.exists():
+                issues.append(
+                    {
+                        "code": "markdown-link-missing",
+                        "path": source.relative_to(vault_root).as_posix(),
+                        "detail": raw,
+                    }
+                )
+    return issues

campfire_cli/app/maintenance/service/maintenance_protocol.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from campfire_cli.app.maintenance.schema.maintenance_schema import (
+    DocumentState,
+    DomainState,
+    Issue,
+    MaintenancePlan,
+    MaintenanceRunRecord,
+    SpaceState,
+)
+
+
+class MaintenanceRepositoryProtocol(Protocol):
+    def replace_current_state(
+        self,
+        documents: list[DocumentState],
+        issues: list[Issue],
+        spaces: list[SpaceState],
+        domains: list[DomainState],
+    ) -> None: ...
+    def save_run(self, run: MaintenanceRunRecord) -> None: ...
+    def save_plan(self, plan: MaintenancePlan) -> None: ...
+    def load_plan(self, plan_id: str) -> MaintenancePlan: ...