@reunionstudio/airlock-mcp 0.1.0

package/src/airlock_mcp/updater.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_SOURCE = "git+https://github.com/reunionstudio/airlock-mcp.git"
+
+
+@dataclass(frozen=True)
+class UpdatePlan:
+    method: str
+    root: Path
+    command: tuple[str, ...]
+    reason: str
+
+
+def _is_git_checkout(root: Path) -> bool:
+    return (root / ".git").exists()
+
+
+def build_update_plan(root: Path, *, method: str = "auto", source: str = DEFAULT_SOURCE) -> UpdatePlan:
+    if method not in {"auto", "git", "pip"}:
+        raise ValueError("method must be auto, git, or pip")
+
+    if method == "git" or (method == "auto" and _is_git_checkout(root)):
+        return UpdatePlan(
+            method="git",
+            root=root,
+            command=("git", "-C", str(root), "pull", "--ff-only"),
+            reason="update checkout with a fast-forward-only pull",
+        )
+
+    return UpdatePlan(
+        method="pip",
+        root=root,
+        command=(sys.executable, "-m", "pip", "install", "--upgrade", source),
+        reason="upgrade installed package from source",
+    )
+
+
+def format_update_plan(plan: UpdatePlan, *, dry_run: bool) -> str:
+    prefix = "dry-run: " if dry_run else ""
+    return "\n".join(
+        (
+            f"{prefix}self-update method: {plan.method}",
+            f"root: {plan.root}",
+            f"reason: {plan.reason}",
+            "command: " + " ".join(plan.command),
+        )
+    )
+
+
+def git_checkout_dirty(root: Path) -> bool:
+    result = subprocess.run(
+        ("git", "-C", str(root), "status", "--porcelain"),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return True
+    return bool(result.stdout.strip())
+
+
+def run_update(plan: UpdatePlan, *, force: bool = False) -> subprocess.CompletedProcess[str]:
+    if plan.method == "git" and git_checkout_dirty(plan.root) and not force:
+        return subprocess.CompletedProcess(
+            plan.command,
+            2,
+            "",
+            "working tree has uncommitted changes; commit, stash, or pass --force\n",
+        )
+    return subprocess.run(plan.command, check=False, capture_output=True, text=True)

package/src/airlock_mcp/validation.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .jsonio import read_json
+from .models import CheckResult, Finding
+
+
+ALLOWED_COLUMN_TYPES = {
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "date",
+    "datetime",
+    "variant",
+}
+
+BANNED_PAYLOAD_FIELDS = {
+    "approval_status",
+    "approved_at",
+    "approved_by",
+    "reviewer_notes",
+    "workflow_state",
+    "workflow_status",
+    "workflow_step",
+}
+
+WORKFLOW_FIELD_PREFIXES = (
+    "approval_",
+    "approved_",
+    "reviewer_",
+    "workflow_",
+    "pushback_",
+)
+
+ALLOWED_ACCESS_LEVELS = {"append_access", "read_access", "full_access"}
+
+REQUIRED_TEXT_FILES = ("brief.md", "decisions.md", "questions.md", "review.md")
+
+
+def require_dict(value: Any, findings: list[Finding], path: str) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        findings.append(Finding("error", path, "Expected object."))
+        return None
+    return value
+
+
+def require_list(value: Any, findings: list[Finding], path: str) -> list[Any] | None:
+    if not isinstance(value, list):
+        findings.append(Finding("error", path, "Expected array."))
+        return None
+    return value
+
+
+def _variant_shape_field(rule: dict[str, Any]) -> str | None:
+    value = rule.get("field", rule.get("column"))
+    return value if isinstance(value, str) and value else None
+
+
+def _looks_like_workflow_state(name: str) -> bool:
+    return name in BANNED_PAYLOAD_FIELDS or name.startswith(WORKFLOW_FIELD_PREFIXES)
+
+
+def _public_access_enabled(guest_access: dict[str, Any], access_level: str) -> bool:
+    public_folder = guest_access.get("public_folder")
+    if not isinstance(public_folder, dict) or public_folder.get("enabled") is not True:
+        return False
+    subfolders = public_folder.get("subfolders")
+    if not isinstance(subfolders, dict):
+        return False
+    target = subfolders.get(access_level)
+    return isinstance(target, dict) and target.get("enabled") is True
+
+
+def validate_guest_access(guest_access: dict[str, Any], findings: list[Finding]) -> None:
+    isolated = guest_access.get("isolated_directories_enabled") is True
+    guest_roles = guest_access.get("guest_roles")
+    if guest_roles is None:
+        return
+
+    roles = require_list(guest_roles, findings, "spec.config.json:guest_access.guest_roles")
+    if not roles:
+        return
+
+    for index, raw_role in enumerate(roles):
+        path = f"spec.config.json:guest_access.guest_roles[{index}]"
+        if isinstance(raw_role, str):
+            continue
+        role = require_dict(raw_role, findings, path)
+        if not role:
+            continue
+
+        role_name = role.get("role_name")
+        if not isinstance(role_name, str) or not role_name:
+            findings.append(Finding("error", f"{path}.role_name", "Guest role name is required."))
+
+        access_level = role.get("access_level")
+        if access_level is None:
+            if not isolated:
+                findings.append(
+                    Finding(
+                        "warning",
+                        path,
+                        "Shared guest role has no access_level; confirm the intended public-folder access.",
+                    )
+                )
+            continue
+
+        if access_level not in ALLOWED_ACCESS_LEVELS:
+            findings.append(
+                Finding(
+                    "error",
+                    f"{path}.access_level",
+                    "Expected append_access, read_access, or full_access.",
+                )
+            )
+            continue
+
+        if not isolated and not _public_access_enabled(guest_access, str(access_level)):
+            findings.append(
+                Finding(
+                    "error",
+                    f"{path}.access_level",
+                    f"`{access_level}` requires the matching public_folder subfolder to be enabled.",
+                )
+            )
+
+
+def validate_spec_config(spec: dict[str, Any], findings: list[Finding]) -> set[str]:
+    core = require_dict(spec.get("core_config"), findings, "spec.config.json:core_config")
+    if core:
+        for key in ("spec_name", "spec_alias", "description", "owner_role"):
+            if not core.get(key):
+                findings.append(
+                    Finding("error", f"spec.config.json:core_config.{key}", "Required value is missing.")
+                )
+
+    columns = require_list(spec.get("column_config"), findings, "spec.config.json:column_config")
+    column_names: set[str] = set()
+    variant_columns: set[str] = set()
+    variant_shape_fields: set[str] = set()
+    if columns:
+        seen: set[str] = set()
+        for index, raw_column in enumerate(columns):
+            path = f"spec.config.json:column_config[{index}]"
+            column = require_dict(raw_column, findings, path)
+            if not column:
+                continue
+
+            name = column.get("name")
+            column_type = column.get("type")
+            tests = column.get("tests")
+
+            if not isinstance(name, str) or not name:
+                findings.append(Finding("error", f"{path}.name", "Column name is required."))
+                continue
+            if name in seen:
+                findings.append(Finding("error", f"{path}.name", f"Duplicate column `{name}`."))
+            seen.add(name)
+            column_names.add(name)
+
+            if _looks_like_workflow_state(name):
+                findings.append(
+                    Finding(
+                        "warning",
+                        f"{path}.name",
+                        f"`{name}` looks like Airlock workflow or review state; keep it only if it is an upstream fact.",
+                    )
+                )
+
+            if column_type not in ALLOWED_COLUMN_TYPES:
+                findings.append(Finding("error", f"{path}.type", f"Unsupported column type `{column_type}`."))
+            if column_type == "variant":
+                variant_columns.add(name)
+            if column_type in {"date", "datetime"}:
+                fmt = column.get("format")
+                if not isinstance(fmt, str) or "%" not in fmt:
+                    findings.append(
+                        Finding(
+                            "error",
+                            f"{path}.format",
+                            "Date and datetime formats must use strftime tokens such as %Y-%m-%d.",
+                        )
+                    )
+            if not isinstance(column.get("description"), str) or not column.get("description"):
+                findings.append(Finding("error", f"{path}.description", "Column description is required."))
+            if not isinstance(tests, list):
+                findings.append(Finding("error", f"{path}.tests", "Column tests must be an array."))
+
+    rules = spec.get("rules", [])
+    if rules is not None:
+        rules_list = require_list(rules, findings, "spec.config.json:rules")
+        if rules_list:
+            for index, raw_rule in enumerate(rules_list):
+                path = f"spec.config.json:rules[{index}]"
+                rule = require_dict(raw_rule, findings, path)
+                if not rule:
+                    continue
+                if rule.get("type") == "variant_shape":
+                    field = _variant_shape_field(rule)
+                    if not field:
+                        findings.append(
+                            Finding("error", f"{path}.field", "variant_shape needs `field` or `column`.")
+                        )
+                    elif field not in variant_columns:
+                        findings.append(
+                            Finding(
+                                "error",
+                                f"{path}.field",
+                                "variant_shape field must reference a declared variant column.",
+                            )
+                        )
+                    else:
+                        variant_shape_fields.add(field)
+                    allowed = rule.get("allowed_root_keys")
+                    if allowed is not None and not isinstance(allowed, list):
+                        findings.append(Finding("error", f"{path}.allowed_root_keys", "Expected array."))
+                    paths = rule.get("paths")
+                    optional_paths = rule.get("optional_paths")
+                    required_paths = rule.get("required_paths")
+                    if paths is not None and not isinstance(paths, list):
+                        findings.append(Finding("error", f"{path}.paths", "Expected array."))
+                    if optional_paths is not None and not isinstance(optional_paths, list):
+                        findings.append(Finding("error", f"{path}.optional_paths", "Expected array."))
+                    if required_paths is not None and not isinstance(required_paths, list):
+                        findings.append(Finding("error", f"{path}.required_paths", "Expected array."))
+
+    for name in sorted(variant_columns - variant_shape_fields):
+        findings.append(
+            Finding(
+                "warning",
+                "spec.config.json:rules",
+                f"Variant column `{name}` has no variant_shape rule.",
+            )
+        )
+
+    file_rules = require_dict(spec.get("file_rules"), findings, "spec.config.json:file_rules")
+    if file_rules:
+        file_format = require_dict(
+            file_rules.get("file_format"), findings, "spec.config.json:file_rules.file_format"
+        )
+        if file_format and file_format.get("file_type") not in {"csv", "excel"}:
+            findings.append(
+                Finding(
+                    "warning",
+                    "spec.config.json:file_rules.file_format.file_type",
+                    "Local records adapter currently checks CSV and Excel-shaped specs best.",
+                )
+            )
+
+    guest_access = spec.get("guest_access")
+    if guest_access is not None and not isinstance(guest_access, dict):
+        findings.append(Finding("error", "spec.config.json:guest_access", "Expected object."))
+    elif isinstance(guest_access, dict):
+        validate_guest_access(guest_access, findings)
+
+    return column_names
+
+
+def validate_sample_records(
+    sample: dict[str, Any], spec: dict[str, Any], columns: set[str], findings: list[Finding]
+) -> None:
+    core = spec.get("core_config") if isinstance(spec.get("core_config"), dict) else {}
+    expected_spec_name = core.get("spec_name")
+    if sample.get("spec_name") != expected_spec_name:
+        findings.append(
+            Finding(
+                "error",
+                "sample.records.json:spec_name",
+                f"Expected `{expected_spec_name}` to match spec.config.json.",
+            )
+        )
+    if not sample.get("filename"):
+        findings.append(Finding("error", "sample.records.json:filename", "Filename is required."))
+
+    records = require_list(sample.get("records"), findings, "sample.records.json:records")
+    if not records:
+        return
+
+    required_fields = {
+        column["name"]
+        for column in spec.get("column_config", [])
+        if isinstance(column, dict)
+        and isinstance(column.get("tests"), list)
+        and "not_null" in column["tests"]
+    }
+    variant_fields = {
+        column["name"]
+        for column in spec.get("column_config", [])
+        if isinstance(column, dict) and column.get("type") == "variant"
+    }
+
+    for index, raw_record in enumerate(records):
+        path = f"sample.records.json:records[{index}]"
+        record = require_dict(raw_record, findings, path)
+        if not record:
+            continue
+        extra = set(record) - columns
+        missing = {field for field in required_fields if record.get(field) in (None, "")}
+        for field in sorted(extra):
+            findings.append(
+                Finding("error", f"{path}.{field}", "Record field is not declared in column_config.")
+            )
+        for field in sorted(missing):
+            findings.append(Finding("error", f"{path}.{field}", "Required sample value is missing."))
+        for field in sorted(variant_fields & set(record)):
+            if record[field] not in (None, "") and not isinstance(record[field], (dict, list)):
+                findings.append(
+                    Finding("error", f"{path}.{field}", "Variant sample values should be objects or arrays.")
+                )
+
+
+def check_workspace(workspace: Path) -> CheckResult:
+    findings: list[Finding] = []
+    if not workspace.exists():
+        return CheckResult((Finding("error", str(workspace), "Workspace not found."),))
+
+    for filename in REQUIRED_TEXT_FILES:
+        path = workspace / filename
+        if not path.exists():
+            findings.append(Finding("error", filename, "Missing workspace file."))
+        elif not path.read_text(encoding="utf-8").strip():
+            findings.append(Finding("warning", filename, "Workspace file is empty."))
+
+    spec = read_json(workspace / "spec.config.json", findings)
+    sample = read_json(workspace / "sample.records.json", findings)
+    if isinstance(spec, dict):
+        columns = validate_spec_config(spec, findings)
+        if isinstance(sample, dict):
+            validate_sample_records(sample, spec, columns, findings)
+
+    return CheckResult(tuple(findings))

package/src/airlock_mcp/workspace.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import copy
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .jsonio import read_json, write_json, write_text
+from .models import Pattern
+from .patterns import load_pattern_records, load_pattern_spec
+from .specs import retitle_spec, sample_records_for_spec, spec_name
+
+
+WORKSPACE_FILES = (
+    "brief.md",
+    "decisions.md",
+    "questions.md",
+    "review.md",
+    "spec.config.json",
+    "sample.records.json",
+)
+
+
+def workspace_markdown(name: str, source_name: str, summary: str, *, mode: str = "create") -> dict[str, str]:
+    if mode == "create":
+        goal = f"Start from the `{source_name}` pattern: {summary}"
+        source_block = f"Mode: create\n\nPattern: {source_name}"
+    else:
+        goal = summary
+        source_block = f"Mode: {mode}\n\nSource: {source_name}"
+
+    return {
+        "brief.md": f"""# Spec Brief
+
+## Goal
+
+{goal}
+
+## Users And Agents
+
+Who submits, reviews, reads, delegates, or acts on this data?
+
+## Systems To Observe
+
+List the systems, files, screenshots, APIs, users, or existing Airlock specs
+that inform the decision.
+
+## First Useful Outcome
+
+What should become possible after the first version lands in Airlock?
+""",
+        "decisions.md": """# Decisions
+
+## Row Grain
+
+One row is:
+
+## OODA Loop
+
+- Observe:
+- Orient:
+- Decide:
+- Act:
+
+## Identifiers
+
+Stable ids and retry-safe keys:
+
+## Business Time
+
+Event, observed, captured, effective, or transaction timestamps:
+
+## Typed Columns
+
+Fields people will filter, join, audit, aggregate, or report on:
+
+## Variant Context
+
+Optional context that may evolve:
+
+## Evidence
+
+Attachments and evidence metadata:
+
+## Access
+
+Submitter, reviewer, reader, owner, and delegation model:
+
+## Workflow And Expectations
+
+States, pushback, due dates, order, or cadence:
+""",
+        "questions.md": """# Questions
+
+Use this file for decisions that change the model.
+
+- What row grain would be expensive to change later?
+- What evidence is required?
+- What business timestamp matters?
+- Which fields must be typed columns?
+- Who can see shared data?
+""",
+        "review.md": f"""# Review
+
+## Local Check
+
+Run:
+
+```bash
+airlock-mcp check .
+```
+
+## Source
+
+{source_block}
+
+Adaptations:
+
+## Airlock Validation
+
+Result:
+
+## Remaining Risk
+
+Human decisions still open:
+""",
+    }
+
+
+def create_workspace_from_pattern(
+    target: Path,
+    pattern: Pattern,
+    *,
+    workspace_name: str,
+    force: bool = False,
+) -> None:
+    if target.exists() and not force:
+        raise FileExistsError(target)
+    target.mkdir(parents=True, exist_ok=True)
+
+    spec_config = copy.deepcopy(load_pattern_spec(pattern))
+    sample_records = copy.deepcopy(load_pattern_records(pattern))
+    if pattern.name == "blank":
+        spec_config = retitle_spec(spec_config, workspace_name)
+        sample_records["spec_name"] = spec_name(spec_config)
+        sample_records["filename"] = f"{sample_records['spec_name']}_001"
+
+    for filename, content in workspace_markdown(workspace_name, pattern.name, pattern.summary).items():
+        write_text(target / filename, content, force=force)
+    write_json(target / "spec.config.json", spec_config, force=force)
+    write_json(target / "sample.records.json", sample_records, force=force)
+
+
+def create_workspace_from_spec_config(
+    target: Path,
+    spec_config: dict[str, Any],
+    *,
+    mode: str,
+    source: str,
+    force: bool = False,
+) -> None:
+    if target.exists() and not force:
+        raise FileExistsError(target)
+    target.mkdir(parents=True, exist_ok=True)
+
+    records = sample_records_for_spec(spec_config)
+    summary = f"Imported canonical spec config from {source}."
+    for filename, content in workspace_markdown(target.name, source, summary, mode=mode).items():
+        write_text(target / filename, content, force=force)
+    write_json(target / "spec.config.json", spec_config, force=force)
+    write_json(target / "sample.records.json", records, force=force)
+
+
+def clone_workspace(source: Path, target: Path, *, workspace_name: str, force: bool = False) -> None:
+    if not source.exists():
+        raise FileNotFoundError(source)
+    if target.exists() and not force:
+        raise FileExistsError(target)
+    target.mkdir(parents=True, exist_ok=True)
+
+    for filename in WORKSPACE_FILES:
+        source_file = source / filename
+        if source_file.exists() and filename not in {"spec.config.json", "sample.records.json", "review.md"}:
+            shutil.copyfile(source_file, target / filename)
+
+    spec_config = read_json(source / "spec.config.json")
+    if not isinstance(spec_config, dict):
+        raise ValueError(f"Source workspace has invalid spec.config.json: {source}")
+
+    cloned_config = retitle_spec(spec_config, workspace_name)
+    records = sample_records_for_spec(cloned_config)
+    write_json(target / "spec.config.json", cloned_config, force=True)
+    write_json(target / "sample.records.json", records, force=True)
+
+    review = f"""# Review
+
+## Local Check
+
+Run:
+
+```bash
+airlock-mcp check .
+```
+
+## Source
+
+Mode: clone
+
+Source workspace: {source}
+
+Original spec: {spec_name(spec_config)}
+
+New spec: {spec_name(cloned_config)}
+
+## Airlock Validation
+
+Result:
+
+## Remaining Risk
+
+Human decisions still open:
+"""
+    write_text(target / "review.md", review, force=True)