@reunionstudio/airlock-mcp 0.1.0

package/src/airlock_mcp/manage.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .jsonio import read_json, write_json
+from .specs import retitle_spec, spec_name
+from .summary import workspace_summary
+from .validation import check_workspace
+
+
+ARCHIVE_DIRNAME = "_archive"
+WORKSPACE_MARKERS = ("spec.config.json", "sample.records.json")
+DECISION_PROMPTS = (
+    "One row is:",
+    "- Observe:",
+    "- Orient:",
+    "- Decide:",
+    "- Act:",
+    "Stable ids and retry-safe keys:",
+    "Event, observed, captured, effective, or transaction timestamps:",
+    "Fields people will filter, join, audit, aggregate, or report on:",
+    "Optional context that may evolve:",
+    "Attachments and evidence metadata:",
+    "Submitter, reviewer, reader, owner, and delegation model:",
+    "States, pushback, due dates, order, or cadence:",
+)
+
+
+@dataclass(frozen=True)
+class WorkspaceInfo:
+    name: str
+    path: Path
+    spec_name: str
+    spec_alias: str
+    records: int
+    errors: int
+    warnings: int
+    archived: bool = False
+
+
+def is_workspace(path: Path) -> bool:
+    return path.is_dir() and all((path / marker).exists() for marker in WORKSPACE_MARKERS)
+
+
+def _spec_label(spec: Any, key: str, fallback: str) -> str:
+    if isinstance(spec, dict):
+        core = spec.get("core_config")
+        if isinstance(core, dict) and isinstance(core.get(key), str) and core[key]:
+            return core[key]
+    return fallback
+
+
+def workspace_info(path: Path, *, archived: bool = False) -> WorkspaceInfo:
+    spec = read_json(path / "spec.config.json")
+    sample = read_json(path / "sample.records.json")
+    records = sample.get("records") if isinstance(sample, dict) else []
+    result = check_workspace(path)
+    return WorkspaceInfo(
+        name=path.name,
+        path=path,
+        spec_name=_spec_label(spec, "spec_name", "unknown"),
+        spec_alias=_spec_label(spec, "spec_alias", "Unknown"),
+        records=len(records) if isinstance(records, list) else 0,
+        errors=len(result.errors),
+        warnings=len(result.warnings),
+        archived=archived,
+    )
+
+
+def discover_workspaces(root: Path, *, include_archived: bool = False) -> list[WorkspaceInfo]:
+    if not root.exists():
+        return []
+
+    infos: list[WorkspaceInfo] = []
+    for path in sorted(root.iterdir(), key=lambda item: item.name.lower()):
+        if path.name.startswith(".") or path.name.startswith("_"):
+            continue
+        if is_workspace(path):
+            infos.append(workspace_info(path))
+
+    archive_root = root / ARCHIVE_DIRNAME
+    if include_archived and archive_root.exists():
+        for path in sorted(archive_root.iterdir(), key=lambda item: item.name.lower()):
+            if is_workspace(path):
+                infos.append(workspace_info(path, archived=True))
+    return infos
+
+
+def format_workspace_table(infos: list[WorkspaceInfo]) -> str:
+    if not infos:
+        return "no workspaces found"
+    rows = [
+        (
+            info.name,
+            info.spec_name,
+            str(info.records),
+            "archived" if info.archived else "active",
+            f"{info.errors}/{info.warnings}",
+            str(info.path),
+        )
+        for info in infos
+    ]
+    headers = ("workspace", "spec", "records", "state", "errors/warnings", "path")
+    widths = [
+        max(len(headers[index]), *(len(row[index]) for row in rows))
+        for index in range(len(headers))
+    ]
+    lines = [
+        "  ".join(headers[index].ljust(widths[index]) for index in range(len(headers))),
+        "  ".join("-" * width for width in widths),
+    ]
+    lines.extend("  ".join(row[index].ljust(widths[index]) for index in range(len(row))) for row in rows)
+    return "\n".join(lines)
+
+
+def format_workspace_paths(infos: list[WorkspaceInfo]) -> str:
+    return "\n".join(str(info.path) for info in infos)
+
+
+def archive_workspace(source: Path, *, archive_root: Path | None = None) -> Path:
+    if not is_workspace(source):
+        raise FileNotFoundError(source)
+    target_root = archive_root or source.parent / ARCHIVE_DIRNAME
+    target = target_root / source.name
+    if target.exists():
+        raise FileExistsError(target)
+    target_root.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(source), str(target))
+    return target
+
+
+def restore_workspace(source: Path, *, output_root: Path | None = None) -> Path:
+    if not is_workspace(source):
+        raise FileNotFoundError(source)
+    if output_root is None and source.parent.name != ARCHIVE_DIRNAME:
+        raise ValueError("restore source must be under _archive or --output must be provided")
+    target_root = output_root or source.parent.parent
+    target = target_root / source.name
+    if target.exists():
+        raise FileExistsError(target)
+    target_root.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(source), str(target))
+    return target
+
+
+def rename_workspace(
+    source: Path,
+    new_name: str,
+    *,
+    output_root: Path | None = None,
+    retitle: bool = True,
+) -> Path:
+    if not is_workspace(source):
+        raise FileNotFoundError(source)
+    target_root = output_root or source.parent
+    target = target_root / new_name
+    if target.exists():
+        raise FileExistsError(target)
+
+    spec = read_json(source / "spec.config.json")
+    sample = read_json(source / "sample.records.json")
+    old_spec_name = spec_name(spec) if isinstance(spec, dict) else None
+
+    target_root.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(source), str(target))
+
+    if retitle and isinstance(spec, dict):
+        updated = retitle_spec(spec, new_name)
+        new_spec_name = spec_name(updated)
+        write_json(target / "spec.config.json", updated, force=True)
+        if isinstance(sample, dict):
+            sample["spec_name"] = new_spec_name
+            if sample.get("filename") in {None, "", f"{old_spec_name}_001"}:
+                sample["filename"] = f"{new_spec_name}_001"
+            write_json(target / "sample.records.json", sample, force=True)
+    return target
+
+
+def _line_answers_prompt(line: str, prompt: str) -> bool:
+    stripped = line.strip()
+    return stripped.startswith(prompt) and stripped != prompt
+
+
+def _is_prompt_line(line: str) -> bool:
+    stripped = line.strip()
+    return any(stripped.startswith(prompt) for prompt in DECISION_PROMPTS)
+
+
+def _has_following_answer(lines: list[str], index: int) -> bool:
+    for line in lines[index + 1 :]:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("## ") or _is_prompt_line(stripped):
+            return False
+        return True
+    return False
+
+
+def _text_has_open_placeholders(path: Path) -> bool:
+    if not path.exists():
+        return True
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return True
+    lines = text.splitlines()
+    seen_prompt = False
+    for index, line in enumerate(lines):
+        for prompt in DECISION_PROMPTS:
+            if line.strip().startswith(prompt):
+                seen_prompt = True
+                if not _line_answers_prompt(line, prompt) and not _has_following_answer(lines, index):
+                    return True
+    return not seen_prompt
+
+
+def next_steps(workspace: Path) -> str:
+    spec = read_json(workspace / "spec.config.json")
+    sample = read_json(workspace / "sample.records.json")
+    result = check_workspace(workspace)
+    lines = [workspace_summary(workspace, spec if isinstance(spec, dict) else {}, sample if isinstance(sample, dict) else {}, result)]
+    lines.append("")
+    lines.append("next:")
+    if result.errors:
+        lines.append("1. Fix local check errors before exporting CSV or rendering SQL.")
+        lines.append(f"2. Run `airlock-mcp check {workspace}` again.")
+        return "\n".join(lines)
+    if result.warnings:
+        lines.append("1. Review local warnings and either fix them or record the deliberate exception in review.md.")
+        lines.append(f"2. Run `airlock-mcp summary {workspace}` to confirm the shape.")
+        return "\n".join(lines)
+    if _text_has_open_placeholders(workspace / "decisions.md"):
+        lines.append("1. Fill in decisions.md for row grain, identifiers, time, evidence, access, and OODA.")
+        lines.append(f"2. Run `airlock-mcp next {workspace}` when the design notes are current.")
+        return "\n".join(lines)
+    records = sample.get("records") if isinstance(sample, dict) else []
+    if not records:
+        lines.append("1. Add at least one realistic sample record.")
+        lines.append(f"2. Run `airlock-mcp check {workspace}`.")
+        return "\n".join(lines)
+    lines.append(f"1. Export sample CSV: `airlock-mcp export-csv {workspace}`.")
+    lines.append(f"2. Render validate-only SQL: `airlock-mcp render-sql {workspace}`.")
+    lines.append("3. Run installed Airlock validation before any mutating create or alter call.")
+    return "\n".join(lines)

package/src/airlock_mcp/models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Pattern:
+    name: str
+    title: str
+    summary: str
+    directory: Path
+    spec_config_path: Path
+    sample_records_path: Path
+    readme_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class Finding:
+    level: str
+    path: str
+    message: str
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    findings: tuple[Finding, ...]
+
+    @property
+    def errors(self) -> tuple[Finding, ...]:
+        return tuple(finding for finding in self.findings if finding.level == "error")
+
+    @property
+    def warnings(self) -> tuple[Finding, ...]:
+        return tuple(finding for finding in self.findings if finding.level == "warning")
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+JsonObject = dict[str, Any]

package/src/airlock_mcp/patterns.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .jsonio import read_json
+from .models import Pattern
+from .project import patterns_dir
+
+
+def load_patterns(root: Path | None = None) -> dict[str, Pattern]:
+    base = patterns_dir(root)
+    manifest = read_json(base / "manifest.json")
+    if not isinstance(manifest, dict):
+        raise RuntimeError(f"Pattern manifest not found or invalid: {base / 'manifest.json'}")
+
+    patterns: dict[str, Pattern] = {}
+    for raw in manifest.get("patterns", []):
+        if not isinstance(raw, dict):
+            continue
+        name = str(raw.get("name") or "").strip()
+        directory_name = str(raw.get("directory") or name).strip()
+        if not name:
+            continue
+        directory = base / directory_name
+        pattern = Pattern(
+            name=name,
+            title=str(raw.get("title") or name),
+            summary=str(raw.get("summary") or ""),
+            directory=directory,
+            spec_config_path=directory / "spec.config.json",
+            sample_records_path=directory / "sample.records.json",
+            readme_path=(directory / "README.md") if (directory / "README.md").exists() else None,
+        )
+        patterns[name] = pattern
+    return patterns
+
+
+def load_pattern_spec(pattern: Pattern) -> dict:
+    spec = read_json(pattern.spec_config_path)
+    if not isinstance(spec, dict):
+        raise RuntimeError(f"Pattern spec config is missing or invalid: {pattern.spec_config_path}")
+    return spec
+
+
+def load_pattern_records(pattern: Pattern) -> dict:
+    records = read_json(pattern.sample_records_path)
+    if not isinstance(records, dict):
+        raise RuntimeError(f"Pattern sample records are missing or invalid: {pattern.sample_records_path}")
+    return records

package/src/airlock_mcp/project.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import os
+import sysconfig
+from pathlib import Path
+
+
+def repo_root() -> Path:
+    """Resolve the Airlock MCP checkout root.
+
+    `AIRLOCK_MCP_HOME` can point the CLI at a different checkout. Otherwise,
+    walk upward from this module and the current directory looking for the
+    pattern manifest. Editable installs use the module path; direct source runs
+    often use the current working directory.
+    """
+
+    override = os.environ.get("AIRLOCK_MCP_HOME") or os.environ.get("AIRLOCK_SMITH_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+
+    candidates = [Path(__file__).resolve(), Path.cwd().resolve()]
+    for start in candidates:
+        for parent in [start, *start.parents]:
+            if (parent / "patterns" / "manifest.json").exists():
+                return parent
+
+    installed_data = Path(sysconfig.get_path("data")) / "airlock_mcp"
+    if (installed_data / "patterns" / "manifest.json").exists():
+        return installed_data
+
+    return Path(__file__).resolve().parents[2]
+
+
+def patterns_dir(root: Path | None = None) -> Path:
+    return (root or repo_root()) / "patterns"
+
+
+def workspace_template_dir(root: Path | None = None) -> Path:
+    return (root or repo_root()) / "workspaces" / "_template"

package/src/airlock_mcp/records.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import csv
+import json
+from io import StringIO
+from typing import Any
+
+
+def column_names(spec_config: dict[str, Any]) -> list[str]:
+    columns = spec_config.get("column_config")
+    if not isinstance(columns, list):
+        return []
+    names: list[str] = []
+    for column in columns:
+        if isinstance(column, dict) and isinstance(column.get("name"), str) and column["name"]:
+            names.append(column["name"])
+    return names
+
+
+def _csv_value(value: Any) -> Any:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, separators=(",", ":"), sort_keys=True)
+    return value
+
+
+def records_to_csv(spec_config: dict[str, Any], sample_records: dict[str, Any]) -> str:
+    """Render sample.records.json records as CSV in spec column order."""
+
+    fields = column_names(spec_config)
+    records = sample_records.get("records")
+    if not isinstance(records, list):
+        records = []
+
+    output = StringIO()
+    writer = csv.DictWriter(output, fieldnames=fields, extrasaction="ignore", lineterminator="\n")
+    writer.writeheader()
+    for raw_record in records:
+        if not isinstance(raw_record, dict):
+            continue
+        writer.writerow({field: _csv_value(raw_record.get(field)) for field in fields})
+    return output.getvalue()

package/src/airlock_mcp/specs.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from .jsonio import coerce_json_object
+
+
+def slug_to_snake(value: str) -> str:
+    import re
+
+    cleaned = re.sub(r"[^A-Za-z0-9]+", "_", value).strip("_").lower()
+    return cleaned or "draft_spec"
+
+
+def spec_name(spec_config: dict[str, Any]) -> str:
+    core = spec_config.get("core_config")
+    if isinstance(core, dict):
+        name = core.get("spec_name")
+        if isinstance(name, str) and name.strip():
+            return name.strip()
+    return "draft_spec"
+
+
+def retitle_spec(spec_config: dict[str, Any], workspace_name: str) -> dict[str, Any]:
+    updated = copy.deepcopy(spec_config)
+    core = updated.setdefault("core_config", {})
+    if isinstance(core, dict):
+        new_name = slug_to_snake(workspace_name)
+        core["spec_name"] = new_name
+        core["spec_alias"] = workspace_name.replace("-", " ").replace("_", " ").title()
+    return updated
+
+
+def extract_spec_config(raw: Any) -> dict[str, Any]:
+    """Extract canonical spec config from common Airlock/spec-library shapes."""
+
+    data = coerce_json_object(raw)
+    if not isinstance(data, dict):
+        raise ValueError("Expected a JSON object containing a spec config.")
+
+    for key in ("specConfig", "spec_config", "SPEC_CONFIG"):
+        if key in data:
+            extracted = coerce_json_object(data[key])
+            if isinstance(extracted, dict):
+                return extracted
+
+    if "core_config" in data or "column_config" in data:
+        return data
+
+    specs = data.get("specs")
+    if isinstance(specs, list) and specs:
+        first = specs[0]
+        if isinstance(first, dict):
+            config = first.get("config") or first
+            if isinstance(config, dict):
+                core = {
+                    "spec_name": data.get("specName") or data.get("SPEC_NAME") or config.get("spec_name") or "imported_spec",
+                    "spec_alias": data.get("specAlias") or data.get("SPEC_ALIAS") or data.get("specName") or "Imported Spec",
+                    "description": data.get("summary") or data.get("description") or "",
+                    "owner_role": config.get("owner_role") or "app_admin",
+                    "is_published": False,
+                    "is_archived": False,
+                }
+                return {
+                    "core_config": core,
+                    "column_config": config.get("columns") or config.get("column_config") or [],
+                    "file_rules": {"file_format": config.get("file_format") or {}},
+                    "rules": config.get("rules") or [],
+                    "attachment_policy": config.get("attachment_policy") or {},
+                    "guest_access": data.get("guest_access") or config.get("guest_access") or {},
+                }
+
+    raise ValueError("Could not find specConfig, spec_config, SPEC_CONFIG, or canonical spec keys.")
+
+
+def sample_value_for_column(column: dict[str, Any]) -> Any:
+    column_type = str(column.get("type") or "string").lower()
+    name = str(column.get("name") or "field")
+    if column_type in {"number", "float", "decimal"}:
+        return 1.0
+    if column_type == "integer":
+        return 1
+    if column_type == "boolean":
+        return True
+    if column_type == "date":
+        return "2026-06-13"
+    if column_type == "datetime":
+        return "2026-06-13 09:00:00"
+    if column_type == "variant":
+        return {"source": {"system": "manual"}}
+    if name.endswith("_id"):
+        return f"{name.upper()}-001"
+    return f"example {name.replace('_', ' ')}"
+
+
+def sample_records_for_spec(spec_config: dict[str, Any]) -> dict[str, Any]:
+    columns = spec_config.get("column_config")
+    if not isinstance(columns, list):
+        columns = []
+    record: dict[str, Any] = {}
+    for column in columns:
+        if isinstance(column, dict) and column.get("name"):
+            record[str(column["name"])] = sample_value_for_column(column)
+    current_spec_name = spec_name(spec_config)
+    return {
+        "spec_name": current_spec_name,
+        "filename": f"{current_spec_name}_001",
+        "records": [record],
+    }

package/src/airlock_mcp/sql.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .specs import spec_name
+
+
+def render_admin_sql(spec_config: dict[str, Any], *, app_name: str, operation: str) -> str:
+    body = json.dumps(spec_config, indent=2)
+    current_spec = spec_name(spec_config)
+    if operation == "alter":
+        escaped = current_spec.replace("'", "''")
+        return f"CALL {app_name}.admin.alter_spec('{escaped}', PARSE_JSON($${body}$$), TRUE);"
+    return f"CALL {app_name}.admin.create_spec(PARSE_JSON($${body}$$), TRUE);"

package/src/airlock_mcp/summary.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .models import CheckResult
+
+
+def _core(spec_config: dict[str, Any]) -> dict[str, Any]:
+    core = spec_config.get("core_config")
+    return core if isinstance(core, dict) else {}
+
+
+def _columns(spec_config: dict[str, Any]) -> list[dict[str, Any]]:
+    columns = spec_config.get("column_config")
+    return [column for column in columns if isinstance(column, dict)] if isinstance(columns, list) else []
+
+
+def _variant_shape_fields(spec_config: dict[str, Any]) -> set[str]:
+    rules = spec_config.get("rules")
+    if not isinstance(rules, list):
+        return set()
+    fields: set[str] = set()
+    for rule in rules:
+        if not isinstance(rule, dict) or rule.get("type") != "variant_shape":
+            continue
+        field = rule.get("field", rule.get("column"))
+        if isinstance(field, str) and field:
+            fields.add(field)
+    return fields
+
+
+def _guest_access_summary(spec_config: dict[str, Any]) -> str:
+    guest_access = spec_config.get("guest_access")
+    if not isinstance(guest_access, dict):
+        return "not configured"
+    if guest_access.get("isolated_directories_enabled") is True:
+        return "isolated directories enabled"
+    public_folder = guest_access.get("public_folder")
+    if not isinstance(public_folder, dict) or public_folder.get("enabled") is not True:
+        return "configured without public folder"
+    subfolders = public_folder.get("subfolders")
+    if not isinstance(subfolders, dict):
+        return "shared public folder"
+    enabled = [
+        name
+        for name, value in subfolders.items()
+        if isinstance(value, dict) and value.get("enabled") is True
+    ]
+    return "shared public folder: " + (", ".join(enabled) if enabled else "no enabled subfolders")
+
+
+def _attachment_summary(spec_config: dict[str, Any]) -> str:
+    policy = spec_config.get("attachment_policy")
+    if not isinstance(policy, dict):
+        return "not configured"
+    if policy.get("attachments_enabled") is not True:
+        return "disabled"
+    return "required" if policy.get("attachment_required") is True else "optional"
+
+
+def _text_status(workspace: Path, filename: str) -> str:
+    path = workspace / filename
+    if not path.exists():
+        return f"{filename}: missing"
+    return f"{filename}: filled" if path.read_text(encoding="utf-8").strip() else f"{filename}: empty"
+
+
+def workspace_summary(
+    workspace: Path,
+    spec_config: dict[str, Any],
+    sample_records: dict[str, Any],
+    result: CheckResult,
+) -> str:
+    core = _core(spec_config)
+    columns = _columns(spec_config)
+    required = [
+        str(column.get("name"))
+        for column in columns
+        if isinstance(column.get("tests"), list) and "not_null" in column["tests"]
+    ]
+    variants = [str(column.get("name")) for column in columns if column.get("type") == "variant"]
+    variant_shapes = _variant_shape_fields(spec_config)
+    records = sample_records.get("records")
+    record_count = len(records) if isinstance(records, list) else 0
+    file_rules = spec_config.get("file_rules")
+    file_format = file_rules.get("file_format") if isinstance(file_rules, dict) else None
+    file_type = file_format.get("file_type") if isinstance(file_format, dict) else "unknown"
+
+    lines = [
+        f"workspace: {workspace}",
+        f"spec: {core.get('spec_name', 'unknown')} ({core.get('spec_alias', 'no alias')})",
+        f"owner_role: {core.get('owner_role', 'unknown')}",
+        f"columns: {len(columns)} total, {len(required)} required, {len(variants)} variant",
+        "required_fields: " + (", ".join(required) if required else "none"),
+        "variant_fields: "
+        + (
+            ", ".join(
+                f"{name}{' shaped' if name in variant_shapes else ' unshaped'}" for name in variants
+            )
+            if variants
+            else "none"
+        ),
+        f"sample_records: {record_count}",
+        f"file_type: {file_type}",
+        f"attachments: {_attachment_summary(spec_config)}",
+        f"guest_access: {_guest_access_summary(spec_config)}",
+        "notes: "
+        + "; ".join(
+            _text_status(workspace, filename)
+            for filename in ("brief.md", "decisions.md", "questions.md", "review.md")
+        ),
+        f"check: {len(result.errors)} error(s), {len(result.warnings)} warning(s)",
+    ]
+    return "\n".join(lines)