campfire-cli 0.1.0__py3-none-any.whl

campfire_cli/app/decision/service/decision_service.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import re
+from uuid import uuid4
+
+from campfire_cli.app.decision.repository.decision_repository import SqliteDecisionRepository
+from campfire_cli.app.decision.schema.decision_schema import (
+    DecisionListResult,
+    DecisionResult,
+    DecisionSyncResult,
+)
+from campfire_cli.app.decision.service.decision_projection_service import (
+    DecisionProjectionService,
+)
+from campfire_cli.common.exceptions import ConfigurationError
+
+KEY_RE = re.compile(r"[a-z0-9][a-z0-9-]{0,159}")
+STATUSES = {"pending", "answered", "closed", "cancelled"}
+
+
+class DecisionService:
+    def __init__(
+        self,
+        repository: SqliteDecisionRepository,
+        projection: DecisionProjectionService,
+    ) -> None:
+        self._repository = repository
+        self._projection = projection
+
+    def create(
+        self,
+        *,
+        key: str,
+        question: str,
+        context: str = "",
+        recommendation: str = "",
+        options: list[str] | None = None,
+        related_documents: list[str] | None = None,
+        source_type: str,
+        source_id: str | None = None,
+        session_provider: str | None = None,
+        session_id: str | None = None,
+        actor: str | None = None,
+    ) -> DecisionResult:
+        if not KEY_RE.fullmatch(key):
+            raise ConfigurationError("Decision key 只能使用小写字母、数字和连字符")
+        if not question.strip() or not source_type.strip():
+            raise ConfigurationError("Decision question 和 source-type 不能为空")
+        decision = self._repository.create_or_refresh(
+            str(uuid4()),
+            {
+                "dedupe_key": key,
+                "question": question.strip(),
+                "context": context.strip(),
+                "recommendation": recommendation.strip(),
+                "options": [item.strip() for item in options or [] if item.strip()],
+                "related_documents": list(dict.fromkeys(related_documents or [])),
+                "source_type": source_type.strip(),
+                "source_id": source_id,
+                "session_provider": session_provider,
+                "session_id": session_id,
+            },
+            actor,
+        )
+        projection = self._sync_projection()
+        events = self._repository.events(decision.id)
+        return DecisionResult(
+            status="created" if len(events) == 1 else "refreshed",
+            decision=decision,
+            events=events,
+            projection_operations=projection.operations,
+        )
+
+    def list(self, status: str | None = None) -> DecisionListResult:
+        if status is not None and status not in STATUSES:
+            raise ConfigurationError(f"未知 Decision 状态：{status}")
+        return DecisionListResult(decisions=self._repository.list(status))
+
+    def show(self, decision_id: str) -> DecisionResult:
+        return DecisionResult(
+            status="ok",
+            decision=self._repository.get(decision_id),
+            events=self._repository.events(decision_id),
+        )
+
+    def answer(self, decision_id: str, answer: str, answered_by: str) -> DecisionResult:
+        if not answer.strip() or not answered_by.strip():
+            raise ConfigurationError("Decision answer 和 answered-by 不能为空")
+        decision = self._repository.answer(decision_id, answer.strip(), answered_by.strip())
+        projection = self._sync_projection()
+        return DecisionResult(
+            status="answered",
+            decision=decision,
+            events=self._repository.events(decision_id),
+            projection_operations=projection.operations,
+        )
+
+    def close(self, decision_id: str, actor: str | None = None) -> DecisionResult:
+        decision = self._repository.close(decision_id, actor)
+        projection = self._sync_projection()
+        return DecisionResult(
+            status="closed",
+            decision=decision,
+            events=self._repository.events(decision_id),
+            projection_operations=projection.operations,
+        )
+
+    def cancel(self, decision_id: str, reason: str, actor: str | None = None) -> DecisionResult:
+        if not reason.strip():
+            raise ConfigurationError("Decision cancellation reason 不能为空")
+        decision = self._repository.cancel(decision_id, reason.strip(), actor)
+        projection = self._sync_projection()
+        return DecisionResult(
+            status="cancelled",
+            decision=decision,
+            events=self._repository.events(decision_id),
+            projection_operations=projection.operations,
+        )
+
+    def sync(self) -> DecisionSyncResult:
+        return self._sync_projection()
+
+    def _sync_projection(self) -> DecisionSyncResult:
+        return self._projection.sync(self._repository.list())

campfire_cli/app/document/SPEC.md

@@ -0,0 +1,51 @@
+# Document App SPEC
+
+本模块承载面向用户和 Agent 的文档业务能力，包括单篇检查与格式化、类型契约、Profile 契约、命名和 Frontmatter 治理。
+
+Document App 负责文档自身及其规则；Maintenance App 负责跨文档统一计划、执行、验收和派生内容同步；Workspace Restructure 用例负责存量结构重构。纯解析、序列化和路径安全等无业务状态的原子能力保留在 `common/documents/`。
+
+## 当前能力
+
+```text
+document/
+├── cli/
+│   ├── document_cli.py
+│   ├── profile_cli.py
+│   └── type_cli.py
+├── service/
+│   ├── document_profile_service.py
+│   ├── document_type_service.py
+│   ├── document_service.py
+│   ├── document_rule_service.py
+│   ├── document_scanner.py
+│   ├── profile_registry.py
+│   ├── type_plan.py
+│   ├── type_apply.py
+│   ├── frontmatter_plan.py
+│   ├── frontmatter_apply.py
+│   └── frontmatter_formatter.py
+└── repository/
+    ├── document_profile_repository.py
+    └── document_type_repository.py
+```
+
+- `profile`：定义并解析不同文档的属性契约。
+- `type`：检查、规划和执行单选类型与文件命名治理。
+- `frontmatter`：检查、规划、执行和格式化文档属性。
+- `rule`：统一解释类型、Profile、枚举与跨字段不变量。
+- `inspect`：向 Agent 返回单篇文档的 Domain、类型、有效 Profile 和具体问题。
+- `scanner`：统一解释受管根、忽略目录和豁免文件；Document 与 Maintenance 共用。
+
+Document Service 可以被 Maintenance 和 Workspace Restructure 编排，但不得反向依赖它们。批量计划文件、运行记录、MOC、Base、归档和重构批次不属于 Document App。
+
+包内 `config.yml` 的默认 Profile 与用户级 `~/.campfire/config.yml` 覆盖共同构成当前治理契约。
+
+Profile 只允许一层 `base` 继承。Service 将声明配置编译为完整 `EffectiveProfile`；Validator、Formatter 和 CLI 必须消费同一结果，不得复制字段与枚举。
+
+标准字段用于格式化、补全和校验。默认 `unknown_fields: preserve`：已有业务扩展字段不参与标准排序但必须原样保留，不因尚未建立专属 Profile 而制造全库噪声；确需封闭字段集合的 Profile 可显式设为 `report`。
+
+Document 不维护配置副本，也不提供契约同步命令。升级 Python 包会更新默认契约；用户自定义类型和 Profile 只写入 `~/.campfire/config.yml`，并通过 `workspace config check` 验证。
+
+`_空间.md`、`_领域.md` 等声明文件由 Workspace App 按结构契约校验，不是普通 Document，不得套用 base Profile。Document 的单篇命令遇到豁免文件时返回 `not-applicable` 和对应的 Workspace 检查入口。
+
+Document Rule 必须把属性顺序错误作为正式 Issue 暴露；顺序取自同一个 Effective Profile。`document format --path <文档>` 默认只预览字段顺序变化，追加 `--confirm` 后才写入；它不新增、删除或修改属性值。

campfire_cli/app/document/__init__.py

@@ -0,0 +1 @@
+"""Document application."""

campfire_cli/app/document/cli/__init__.py

@@ -0,0 +1 @@
+"""Document CLI adapters."""

campfire_cli/app/document/cli/document_cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from campfire_cli.app.document.cli.profile_cli import profile_cli
+from campfire_cli.app.document.cli.type_cli import type_cli
+from campfire_cli.app.document.service.document_service import DocumentService
+from campfire_cli.app.workspace.repository.workspace_repository import SqliteWorkspaceRepository
+from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
+from campfire_cli.common.exceptions import AppError
+from campfire_cli.config.settings import WorkspaceSettings, campfire_home
+
+document_cli = typer.Typer(
+    help="创建、检查和维护文档及其规则",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+document_cli.add_typer(profile_cli, name="profile")
+document_cli.add_typer(type_cli, name="type")
+
+
+def service(ctx: typer.Context) -> DocumentService:
+    selector = ctx.find_root().params.get("workspace")
+    root = campfire_home()
+    resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
+        selector, Path.cwd()
+    )
+    settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
+    return DocumentService(settings)
+
+
+def invoke(operation: Callable[[], dict[str, Any]]) -> None:
+    try:
+        typer.echo(json.dumps(operation(), ensure_ascii=False, indent=2))
+    except AppError as exc:
+        typer.echo(json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False))
+        raise typer.Exit(exc.exit_code) from exc
+
+
+@document_cli.command("check")
+def check(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
+    """检查一篇 Markdown 文档是否符合当前类型与 Profile 契约。"""
+    invoke(lambda: service(ctx).check(path))
+
+
+@document_cli.command("inspect")
+def inspect(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
+    """返回 Agent 治理单篇文档所需的类型、Profile、领域和问题上下文。"""
+    invoke(lambda: service(ctx).inspect(path))
+
+
+@document_cli.command("format")
+def format_document(
+    ctx: typer.Context,
+    path: str = typer.Option(..., "--path"),
+    confirm: bool = typer.Option(False, "--confirm"),
+) -> None:
+    """预览或执行一篇文档的 Frontmatter 字段排序。"""
+    invoke(lambda: service(ctx).format(path, confirm))

campfire_cli/app/document/cli/profile_cli.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from campfire_cli.app.document.repository.document_profile_repository import (
+    DocumentProfileRepository,
+)
+from campfire_cli.app.document.service.document_profile_service import (
+    DocumentProfileService,
+)
+from campfire_cli.app.workspace.repository.workspace_repository import SqliteWorkspaceRepository
+from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
+from campfire_cli.common.exceptions import AppError
+from campfire_cli.config.settings import WorkspaceSettings, campfire_home
+
+profile_cli = typer.Typer(
+    help="查看和解析文档 Profile 契约",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def service(ctx: typer.Context) -> DocumentProfileService:
+    selector = ctx.find_root().params.get("workspace")
+    root = campfire_home()
+    resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
+        selector, Path.cwd()
+    )
+    settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
+    return DocumentProfileService(
+        settings.workspace_id,
+        settings.vault_root,
+        settings.document_types,
+        DocumentProfileRepository(settings.state_root),
+    )
+
+
+def invoke(operation: Callable[[], dict[str, Any]]) -> None:
+    try:
+        typer.echo(json.dumps(operation(), ensure_ascii=False, indent=2))
+    except AppError as exc:
+        typer.echo(json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False))
+        raise typer.Exit(exc.exit_code) from exc
+
+
+@profile_cli.command("list")
+def list_profiles(ctx: typer.Context) -> None:
+    """列出所有有效 Profile。"""
+    invoke(lambda: service(ctx).list_profiles())
+
+
+@profile_cli.command("show")
+def show_profile(ctx: typer.Context, name: str) -> None:
+    """显示继承合并后的完整 Profile。"""
+    invoke(lambda: service(ctx).show_profile(name))
+
+
+@profile_cli.command("resolve")
+def resolve(ctx: typer.Context, path: str = typer.Option(..., "--path")) -> None:
+    """解析一篇文档最终使用的 Profile。"""
+    invoke(lambda: service(ctx).resolve(path))

campfire_cli/app/document/cli/type_cli.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from campfire_cli.app.document.repository.document_type_repository import (
+    DocumentTypeRepository,
+)
+from campfire_cli.app.document.service.document_type_service import DocumentTypeService
+from campfire_cli.app.workspace.repository.workspace_repository import SqliteWorkspaceRepository
+from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
+from campfire_cli.common.exceptions import AppError
+from campfire_cli.config.settings import WorkspaceSettings, campfire_home
+
+type_cli = typer.Typer(
+    help="查看文档类型与文件名前缀契约",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def service(ctx: typer.Context) -> DocumentTypeService:
+    selector = ctx.find_root().params.get("workspace")
+    root = campfire_home()
+    resolution = WorkspaceService(root, SqliteWorkspaceRepository(root)).resolve(
+        selector, Path.cwd()
+    )
+    settings = WorkspaceSettings.load(resolution.workspace_id, Path(resolution.workspace))
+    return DocumentTypeService(
+        settings.workspace_id,
+        DocumentTypeRepository(settings.state_root),
+    )
+
+
+def invoke(operation: Callable[[], dict[str, Any]]) -> None:
+    try:
+        typer.echo(json.dumps(operation(), ensure_ascii=False, indent=2))
+    except AppError as exc:
+        typer.echo(json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False))
+        raise typer.Exit(exc.exit_code) from exc
+
+
+@type_cli.command("list")
+def list_types(ctx: typer.Context) -> None:
+    """列出当前 Workspace 的单选文档类型和文件名前缀。"""
+    invoke(lambda: service(ctx).list_types())

campfire_cli/app/document/repository/__init__.py

@@ -0,0 +1 @@
+"""Document repositories."""

campfire_cli/app/document/repository/document_profile_repository.py

@@ -0,0 +1,17 @@
+"""Persistence for the active Workspace document Profile contract."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.config.defaults import effective_config
+
+
+class DocumentProfileRepository:
+    def __init__(self, state_root: Path) -> None:
+        self._path = state_root.parents[1] / "config.yml"
+
+    def load(self) -> dict[str, Any]:
+        return deepcopy(effective_config(self._path)["frontmatter_schema"])

campfire_cli/app/document/repository/document_type_repository.py

@@ -0,0 +1,17 @@
+"""Persistence for the active Workspace document type contract."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.config.defaults import effective_config
+
+
+class DocumentTypeRepository:
+    def __init__(self, state_root: Path) -> None:
+        self._path = state_root.parents[1] / "config.yml"
+
+    def load(self) -> dict[str, Any]:
+        return deepcopy(effective_config(self._path)["document_types"])

campfire_cli/app/document/service/__init__.py

@@ -0,0 +1 @@
+"""Document application services."""

campfire_cli/app/document/service/document_profile_service.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from campfire_cli.app.document.repository.document_profile_repository import (
+    DocumentProfileRepository,
+)
+from campfire_cli.app.document.service.profile_registry import ProfileRegistry
+from campfire_cli.common.documents.markdown import parse_document
+from campfire_cli.common.exceptions import ConfigurationError
+
+
+class DocumentProfileService:
+    def __init__(
+        self,
+        workspace_id: str,
+        vault_root: Path,
+        type_config: dict[str, Any],
+        repository: DocumentProfileRepository,
+    ) -> None:
+        self._workspace_id = workspace_id
+        self._vault_root = vault_root
+        self._type_config = type_config
+        self._repository = repository
+
+    def list_profiles(self) -> dict[str, Any]:
+        profiles = self._profiles()
+        return {
+            "status": "ok",
+            "workspace_id": self._workspace_id,
+            "profiles": [
+                {
+                    "name": profile.name,
+                    "field_count": len(profile.field_order),
+                    "required_count": len(profile.required),
+                }
+                for profile in profiles.list()
+            ],
+        }
+
+    def show_profile(self, name: str) -> dict[str, Any]:
+        return {
+            "status": "ok",
+            "workspace_id": self._workspace_id,
+            "profile": self._profiles().get(name).model_dump(),
+        }
+
+    def resolve(self, relative_path: str) -> dict[str, Any]:
+        path = (self._vault_root / relative_path).resolve()
+        if self._vault_root != path and self._vault_root not in path.parents:
+            raise ConfigurationError("path 必须位于当前 Workspace 内")
+        if not path.is_file():
+            raise ConfigurationError(f"文档不存在：{relative_path}")
+        frontmatter = parse_document(path.read_text(encoding="utf-8")).frontmatter
+        profile = self._profiles().resolve(frontmatter.get("type"), frontmatter, path)
+        return {
+            "status": "ok",
+            "workspace_id": self._workspace_id,
+            "path": path.relative_to(self._vault_root).as_posix(),
+            "type": frontmatter.get("type"),
+            "profile": profile.model_dump(),
+        }
+
+    def _profiles(self) -> ProfileRegistry:
+        return ProfileRegistry(self._type_config, self._repository.load())