campfire-cli 0.1.0__py3-none-any.whl

campfire_cli/common/documents/document_types.py

@@ -0,0 +1,119 @@
+"""Shared helpers for the Vault-wide single-select document type contract."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+FRONTMATTER_KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*):(?:\s*(.*))?$")
+
+
+def safe_path(root: Path, relative: str) -> Path:
+    root = root.resolve()
+    path = (root / relative).resolve()
+    path.relative_to(root)
+    return path
+
+
+def frontmatter_bounds(text: str) -> tuple[int, int] | None:
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    return (4, end) if end >= 0 else None
+
+
+def frontmatter_value(text: str, key: str) -> tuple[str | None, bool]:
+    """Return scalar value and whether the key is represented as a YAML sequence."""
+    bounds = frontmatter_bounds(text)
+    if not bounds:
+        return None, False
+    lines = text[bounds[0] : bounds[1]].splitlines()
+    for index, line in enumerate(lines):
+        match = FRONTMATTER_KEY_RE.match(line)
+        if not match or match.group(1) != key:
+            continue
+        value = (match.group(2) or "").strip().strip('"').strip("'")
+        sequence = value.startswith("[")
+        if not value:
+            for following in lines[index + 1 :]:
+                if FRONTMATTER_KEY_RE.match(following):
+                    break
+                if re.match(r"^\s+-\s+", following):
+                    sequence = True
+                    break
+        return value or None, sequence
+    return None, False
+
+
+def set_frontmatter_scalar(text: str, key: str, value: str) -> str:
+    bounds = frontmatter_bounds(text)
+    if not bounds:
+        return f"---\n{key}: {value}\n---\n\n{text}"
+    lines = text[bounds[0] : bounds[1]].splitlines()
+    output: list[str] = []
+    replaced = False
+    skipping_sequence = False
+    for line in lines:
+        match = FRONTMATTER_KEY_RE.match(line)
+        if match:
+            skipping_sequence = False
+            if match.group(1) == key:
+                if not replaced:
+                    output.append(f"{key}: {value}")
+                    replaced = True
+                skipping_sequence = not (match.group(2) or "").strip()
+                continue
+        if skipping_sequence and re.match(r"^\s+-\s+", line):
+            continue
+        output.append(line)
+    if not replaced:
+        output.append(f"{key}: {value}")
+    return "---\n" + "\n".join(output) + text[bounds[1] :]
+
+
+def prefix_type(filename: str, config: dict[str, Any]) -> str | None:
+    matches = [
+        name for name, item in config["types"].items() if filename.startswith(item["prefix"])
+    ]
+    return matches[0] if len(matches) == 1 else None
+
+
+def prefixed_name(filename: str, doc_type: str, config: dict[str, Any]) -> str:
+    prefix = config["types"][doc_type]["prefix"]
+    known = sorted((item["prefix"] for item in config["types"].values()), key=len, reverse=True)
+    stem = filename
+    for existing in known:
+        if stem.startswith(existing):
+            stem = stem[len(existing) :]
+            break
+    result = prefix + stem
+    if config.get("filename_rules", {}).get("flatten_leading_bracket_categories", False):
+        result = flatten_leading_bracket_categories(result, prefix)
+    return result
+
+
+def flatten_leading_bracket_categories(filename: str, prefix: str) -> str:
+    """Convert PREFIX-【A】【B】Title.md to PREFIX-A-B-Title.md."""
+    if not filename.startswith(prefix):
+        return filename
+    remainder = filename[len(prefix) :]
+    categories: list[str] = []
+    while True:
+        match = re.match(r"^【([^】]+)】\s*", remainder)
+        if not match:
+            break
+        category = match.group(1).strip().strip("-_")
+        if category:
+            categories.append(category)
+        remainder = remainder[match.end() :]
+    if not categories:
+        return filename
+    remainder = remainder.lstrip(" -_")
+    parts = [*categories, remainder] if remainder else categories
+    return prefix + "-".join(parts)
+
+
+def profile_mapping(config: dict[str, Any], profile: str) -> dict[str, str]:
+    names = config.get("profiles", {}).get(profile, [])
+    return {name: config["types"][name]["prefix"] for name in names if name in config["types"]}

campfire_cli/common/documents/frontmatter_schema.py

@@ -0,0 +1,42 @@
+"""Shared helpers for layered Vault frontmatter schemas."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from campfire_cli.common.documents.document_types import frontmatter_bounds
+
+KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*):(?:\s*(.*))?$")
+DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def parse_shape(text: str) -> tuple[dict[str, str], dict[str, str]]:
+    bounds = frontmatter_bounds(text)
+    if not bounds:
+        return {}, {}
+    lines = text[bounds[0] : bounds[1]].splitlines()
+    values: dict[str, str] = {}
+    kinds: dict[str, str] = {}
+    current: str | None = None
+    for line in lines:
+        match = KEY_RE.match(line)
+        if match:
+            current = match.group(1)
+            value = (match.group(2) or "").strip().strip('"').strip("'")
+            values[current] = value
+            kinds[current] = "list" if value.startswith("[") else "scalar"
+        elif current and re.match(r"^\s+-\s+", line):
+            kinds[current] = "list"
+    return values, kinds
+
+
+def is_project_context(path: Path | None) -> bool:
+    if path is None:
+        return False
+    for parent in [path.parent, *path.parents]:
+        marker = parent / "_领域.md"
+        if marker.is_file():
+            marker_values, _ = parse_shape(marker.read_text(encoding="utf-8"))
+            return marker_values.get("governance") == "project-docs"
+    return False

campfire_cli/common/documents/markdown.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+from yaml import YAMLError
+
+
+@dataclass(frozen=True)
+class MarkdownDocument:
+    frontmatter: dict[str, Any]
+    body: str
+    has_frontmatter: bool
+
+
+def parse_document(text: str) -> MarkdownDocument:
+    if not text.startswith("---\n"):
+        return MarkdownDocument({}, text, False)
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        return MarkdownDocument({}, text, False)
+    raw = text[4:end]
+    try:
+        value = yaml.safe_load(raw) or {}
+    except YAMLError:
+        value = _parse_lenient_scalars(raw)
+    if not isinstance(value, dict):
+        return MarkdownDocument({}, text, False)
+    return MarkdownDocument(value, text[end + 5 :], True)
+
+
+def _parse_lenient_scalars(raw: str) -> dict[str, Any]:
+    """Recover top-level fields so malformed legacy YAML cannot abort a Vault scan."""
+    result: dict[str, Any] = {}
+    current_list: str | None = None
+    for line in raw.splitlines():
+        if line.startswith("  - ") and current_list:
+            result[current_list].append(line[4:].strip().strip('"'))
+            continue
+        current_list = None
+        if not line or line[0].isspace() or ":" not in line:
+            continue
+        key, raw_value = line.split(":", 1)
+        key = key.strip()
+        value = raw_value.strip()
+        if not key:
+            continue
+        if value == "[]":
+            result[key] = []
+        elif not value:
+            result[key] = []
+            current_list = key
+        elif value in {"true", "false"}:
+            result[key] = value == "true"
+        else:
+            result[key] = value.strip('"')
+    return result
+
+
+def render_document(frontmatter: dict[str, Any], body: str, field_order: list[str]) -> str:
+    known = [key for key in field_order if key in frontmatter]
+    unknown = [key for key in frontmatter if key not in field_order]
+    ordered = {key: frontmatter[key] for key in [*known, *unknown]}
+    header = yaml.safe_dump(ordered, allow_unicode=True, sort_keys=False).rstrip()
+    return f"---\n{header}\n---\n{body.lstrip()}"

campfire_cli/common/exceptions/__init__.py

@@ -0,0 +1,7 @@
+from campfire_cli.common.exceptions.base import (
+    AppError,
+    ConfigurationError,
+    GovernanceBlockedError,
+)
+
+__all__ = ["AppError", "ConfigurationError", "GovernanceBlockedError"]

campfire_cli/common/exceptions/base.py

@@ -0,0 +1,19 @@
+"""Protocol-neutral application exceptions."""
+
+
+class AppError(Exception):
+    """Base error translated by delivery adapters."""
+
+    exit_code = 1
+
+
+class ConfigurationError(AppError):
+    """Raised when a Vault cannot be located or configured."""
+
+    exit_code = 2
+
+
+class GovernanceBlockedError(AppError):
+    """Raised when a write is blocked by governance safety rules."""
+
+    exit_code = 3

campfire_cli/common/filesystem/__init__.py

@@ -0,0 +1,6 @@
+"""Safe filesystem primitives shared by application modules."""
+
+from campfire_cli.common.filesystem.atomic import atomic_write, safe_path
+from campfire_cli.common.filesystem.locking import workspace_write_lock
+
+__all__ = ["atomic_write", "safe_path", "workspace_write_lock"]

campfire_cli/common/filesystem/atomic.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from campfire_cli.common.exceptions import GovernanceBlockedError
+
+
+def safe_path(root: Path, relative: str) -> Path:
+    candidate = (root / relative).resolve()
+    if candidate != root and root not in candidate.parents:
+        raise GovernanceBlockedError(f"路径超出 Vault：{relative}")
+    return candidate
+
+
+def atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        # newline="\n" 阻止 Windows 文本模式把 \n 翻译为 \r\n；
+        # 生成文件的哈希校验（file_sha256）依赖写入与读取的换行口径一致。
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)

campfire_cli/common/filesystem/locking.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from campfire_cli.common.exceptions import GovernanceBlockedError
+
+
+@contextmanager
+def workspace_write_lock(scope_root: Path) -> Iterator[None]:
+    """对 scope_root 范围内的治理写入互斥。
+
+    锁的粒度由传入的根目录决定，锁文件位于 <scope_root>/locks/write.lock：
+
+    - Workspace 的 state_root（~/.campfire/workspaces/<id>/）：
+      互斥该 Workspace 的 Vault 写入与状态刷新；
+    - campfire_home（~/.campfire/）：互斥跨 Workspace 的全局资源，
+      包括注册库写入和全局 Skill 同步。
+    """
+    lock = scope_root / "locks" / "write.lock"
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = _acquire(lock)
+    try:
+        with os.fdopen(descriptor, "w") as stream:
+            stream.write(str(os.getpid()))
+        yield
+    finally:
+        lock.unlink(missing_ok=True)
+
+
+def _acquire(lock: Path) -> int:
+    try:
+        return os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError as exc:
+        try:
+            pid = int(lock.read_text(encoding="utf-8").strip())
+        except (OSError, ValueError):
+            raise GovernanceBlockedError(f"已有治理写操作且锁内容无法确认：{lock}") from exc
+        try:
+            os.kill(pid, 0)
+        except PermissionError:
+            raise GovernanceBlockedError(f"已有治理写操作（PID {pid}）：{lock}") from exc
+        except OSError:
+            # 进程不存在：POSIX 抛 ProcessLookupError，Windows 抛 WinError 87，
+            # 两者都是 OSError 子类，统一按死进程清理后重试。
+            pass
+        else:
+            raise GovernanceBlockedError(f"已有治理写操作（PID {pid}）：{lock}") from exc
+        lock.unlink(missing_ok=True)
+        try:
+            return os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError as retry_exc:
+            raise GovernanceBlockedError(f"已有治理写操作：{lock}") from retry_exc

campfire_cli/common/governance/__init__.py

@@ -0,0 +1,13 @@
+"""Shared governance diagnostics and optimistic concurrency helpers."""
+
+from campfire_cli.common.governance.issues import enrich_issue, filter_issues
+from campfire_cli.common.governance.locking import optimistic_write_lock
+from campfire_cli.common.governance.snapshots import capture_snapshot, snapshot_changes
+
+__all__ = [
+    "capture_snapshot",
+    "enrich_issue",
+    "filter_issues",
+    "optimistic_write_lock",
+    "snapshot_changes",
+]

campfire_cli/common/governance/issues.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from campfire_cli.config.defaults import config_section
+
+
+def enrich_issue(issue: dict[str, Any]) -> dict[str, Any]:
+    result = dict(issue)
+    code = str(result.get("code"))
+    policy = config_section("issues")
+    fallback = next(
+        (content for prefix, content in policy["categories"].items() if code.startswith(prefix)),
+        (policy["default"]["message"], policy["default"]["suggestion"]),
+    )
+    message, suggestion = policy["catalog"].get(code, fallback)
+    result.setdefault("message", message)
+    result.setdefault("suggestion", suggestion)
+    result.setdefault("severity", "warning" if code in policy["warning_codes"] else "error")
+    return result
+
+
+def filter_issues(
+    issues: Iterable[dict[str, Any]],
+    *,
+    scope: str | None = None,
+    code: str | None = None,
+    severity: str | None = None,
+) -> list[dict[str, Any]]:
+    prefix = scope.strip("/") if scope else None
+    return [
+        issue
+        for issue in issues
+        if (prefix is None or str(issue.get("path", "")).strip("/").startswith(prefix))
+        and (code is None or issue.get("code") == code)
+        and (severity is None or issue.get("severity", "error") == severity)
+    ]

campfire_cli/common/governance/locking.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from campfire_cli.common.filesystem import workspace_write_lock
+from campfire_cli.common.governance.snapshots import snapshot_changes
+
+
+@contextmanager
+def optimistic_write_lock(
+    state_root: Path,
+    snapshot: dict[str, str | None],
+    root: Path | None = None,
+) -> Iterator[list[str]]:
+    """乐观并发控制的治理写锁：取治理写锁，并复核快照哈希后放行写入。
+
+    与悲观互斥的 workspace_write_lock（只防提交瞬间的并发）不同，本锁用于
+    覆盖"计划到执行"的长窗口：yield 变化路径清单，非空表示计划生成后内容
+    被其他会话修改，调用方必须放弃写入（返回 blocked 结果或抛出
+    GovernanceBlockedError）；空清单表示可安全写入，写入动作在 with 块内
+    完成，退出时释放锁。
+
+    快照的期望哈希必须由 file_sha256 产出，与 snapshot_changes 的复核口径
+    一致；不允许各服务手工拼装其他口径的期望哈希。snapshot 的键通常是相对
+    root 的 POSIX 路径，也允许绝对路径键（Vault 之外的同步目标，如全局
+    Skill 目录），此时 root 不参与该键的解析。
+    """
+    with workspace_write_lock(state_root):
+        yield snapshot_changes(root or Path(), snapshot)

campfire_cli/common/governance/snapshots.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from campfire_cli.common.hashing import file_sha256
+
+
+def capture_snapshot(root: Path, paths: Iterable[Path]) -> dict[str, str | None]:
+    root = root.resolve()
+    result: dict[str, str | None] = {}
+    for path in sorted({item.resolve() for item in paths}):
+        relative = path.relative_to(root).as_posix()
+        result[relative] = file_sha256(path) if path.is_file() else None
+    return result
+
+
+def snapshot_changes(root: Path, snapshot: dict[str, str | None]) -> list[str]:
+    changes: list[str] = []
+    for relative, expected in snapshot.items():
+        key = Path(relative)
+        path = key if key.is_absolute() else root / key
+        actual = file_sha256(path) if path.is_file() else None
+        if actual != expected:
+            changes.append(relative)
+    return changes

campfire_cli/common/hashing.py

@@ -0,0 +1,10 @@
+import hashlib
+from pathlib import Path
+
+
+def file_sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def text_sha256(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()

campfire_cli/common/reports/__init__.py

@@ -0,0 +1 @@
+"""Stable machine-readable and human-readable report rendering."""

campfire_cli/common/reports/json_report.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def render_json_report(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"

campfire_cli/common/reports/markdown_report.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def render_maintenance_report(payload: dict[str, Any]) -> str:
+    lines = [
+        "# Campfire 当前检查报告",
+        "",
+        f"- 状态：`{payload['status']}`",
+        f"- 文档数：{payload['document_count']}",
+        f"- 问题数：{payload['issue_count']}",
+        f"- 生成时间：{payload['exported_at']}",
+        "",
+        "## 待处理问题",
+        "",
+    ]
+    issues = payload.get("issues", [])
+    if issues:
+        for issue in issues:
+            lines.append(
+                f"- `{issue['severity']}` `{issue['code']}` `{issue['path']}`："
+                f"{issue.get('message') or issue.get('detail', '')}"
+            )
+            if issue.get("suggestion"):
+                lines.append(f"  - 建议：{issue['suggestion']}")
+    else:
+        lines.append("当前没有发现治理问题。")
+    return "\n".join(lines) + "\n"

campfire_cli/config/SPEC.md

@@ -0,0 +1,5 @@
+# Config SPEC
+
+配置和状态统一保存在用户级 `CAMPFIRE_HOME`，默认是 `~/.campfire/`。唯一的 `campfire.db` 注册多个 Workspace 和 Project，并按 `workspace_id` 隔离索引与工作流状态。CLI 不读取或创建 Workspace 内 `.campfire/`。
+
+包内 `resources/defaults/config.yml` 是产品默认值的唯一来源：Workspace 模板、文档类型、Profile、项目状态、归档原因和 Issue 展示规则按顶级分区集中维护。`~/.campfire/config.yml` 只保存用户覆盖项，使用 mapping 深度合并、列表整体替换；运行状态不得写入配置。

campfire_cli/config/defaults.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+from copy import deepcopy
+from functools import cache
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@cache
+def builtin_config() -> dict[str, Any]:
+    """Load the immutable packaged product configuration."""
+    resource = files("campfire_cli.resources.defaults").joinpath("config.yml")
+    value = yaml.safe_load(resource.read_text(encoding="utf-8"))
+    if not isinstance(value, dict) or not isinstance(value.get("version"), int):
+        raise ValueError("内置 config.yml 缺少整数 version")
+    return value
+
+
+def builtin_section(name: str) -> dict[str, Any]:
+    value = builtin_config().get(name)
+    if not isinstance(value, dict):
+        raise ValueError(f"内置 config.yml 缺少配置分区：{name}")
+    return deepcopy(value)
+
+
+def config_section(name: str) -> dict[str, Any]:
+    home = Path(os.environ.get("CAMPFIRE_HOME", "~/.campfire")).expanduser().resolve()
+    value = effective_config(home / "config.yml").get(name)
+    if not isinstance(value, dict):
+        raise ValueError(f"有效 config.yml 缺少配置分区：{name}")
+    return deepcopy(value)
+
+
+def effective_config(user_path: Path) -> dict[str, Any]:
+    """Merge optional user overrides onto packaged defaults."""
+    config = deepcopy(builtin_config())
+    if not user_path.is_file():
+        return config
+    try:
+        override = yaml.safe_load(user_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise ValueError(f"用户 config.yml 不是合法 YAML：{exc}") from exc
+    if not isinstance(override, dict):
+        raise ValueError("用户 config.yml 必须是 YAML mapping")
+    if not isinstance(override.get("version"), int):
+        raise ValueError("用户 config.yml 缺少整数 version")
+    unknown = sorted(set(override) - set(config))
+    if unknown:
+        raise ValueError("用户 config.yml 包含未知顶级分区：" + ", ".join(unknown))
+    return _deep_merge(config, override)
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    result = deepcopy(base)
+    for key, value in override.items():
+        if isinstance(result.get(key), dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+    return result

campfire_cli/config/settings.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.common.exceptions import ConfigurationError
+from campfire_cli.config.defaults import effective_config
+
+
+def campfire_home() -> Path:
+    return Path(os.environ.get("CAMPFIRE_HOME", "~/.campfire")).expanduser().resolve()
+
+
+@dataclass(frozen=True)
+class WorkspaceSettings:
+    workspace_id: str
+    vault_root: Path
+    state_root: Path
+    governance: dict[str, Any]
+    document_types: dict[str, Any]
+    frontmatter_schema: dict[str, Any]
+    skills: dict[str, Any]
+    bases: dict[str, Any]
+
+    def skill_targets(self) -> list[Path]:
+        override = os.environ.get("CAMPFIRE_SKILL_TARGETS")
+        values = override.split(os.pathsep) if override else self.skills.get("targets", [])
+        return [Path(value).expanduser().resolve() for value in values]
+
+    @classmethod
+    def load(cls, workspace_id: str, root: Path) -> WorkspaceSettings:
+        if not root.is_dir():
+            raise ConfigurationError(f"已注册 Workspace 不存在：{root}")
+        state_root = campfire_home() / "workspaces" / workspace_id
+        try:
+            config = effective_config(campfire_home() / "config.yml")
+        except (OSError, ValueError) as exc:
+            raise ConfigurationError(f"无法加载 Campfire config.yml：{exc}") from exc
+        return cls(
+            workspace_id=workspace_id,
+            vault_root=root,
+            state_root=state_root,
+            governance=config["governance"],
+            document_types=config["document_types"],
+            frontmatter_schema=config["frontmatter_schema"],
+            skills=config["skills"],
+            bases=config["bases"],
+        )