arqux 0.3.0__py3-none-any.whl

arqux/__init__.py

@@ -0,0 +1,28 @@
+"""
+Arqux — Minimum-viable governance framework for AI agent teams.
+
+Public API surface:
+    - `cli.main()` — entry point for the `arqux` console script.
+    - `server.serve()` — start the MCP server.
+    - `__version__` — package version string.
+
+The framework exposes 24 MCP handlers grouped in 6 modules:
+    workspace, project, cycle, task, evidence, protocol.
+
+See `AGENTS.md` for the single-entry-point documentation.
+"""
+
+from .constants import (
+    ARQUX_DIR,
+    ARQUX_VERSION,
+    PRODUCT_NAME,
+)
+
+__version__ = ARQUX_VERSION
+
+__all__ = [
+    "PRODUCT_NAME",
+    "ARQUX_DIR",
+    "ARQUX_VERSION",
+    "__version__",
+]

arqux/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m arqux`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

arqux/cli.py

@@ -0,0 +1,196 @@
+"""CLI entry point.
+
+Commands:
+    arqux serve              — start the MCP server on stdio.
+    arqux init               — initialize .arqux/ in the current directory.
+    arqux status             — print workspace/project/cycle status.
+    arqux call <handler>     — call any handler directly (no MCP required).
+    arqux setup-plantuml     — download plantuml.jar.
+    arqux serve-plantuml     — start PlantUML render server.
+    arqux --version
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+import click
+
+from . import __version__
+from .constants import PRODUCT_NAME, PRODUCT_NAME_TITLE
+
+
+
+
+def _call_handler(name: str, raw_args: list[str]) -> str:
+    """Dispatch a handler by name with key=value arguments.
+
+    Returns the handler's CORTEX-OUT message as a string.
+    """
+    from .handlers import REGISTRY
+    from .permissions import PermissionContext
+
+    if name not in REGISTRY:
+        # Try MCP-safe name (underscores → dots)
+        dotted = name.replace("_", ".")
+        if dotted in REGISTRY:
+            name = dotted
+        else:
+            available = "\n".join(f"  {n}" for n in sorted(REGISTRY.keys()))
+            return f"ERROR: unknown handler '{name}'. Available:\n{available}"
+
+    spec = REGISTRY[name]
+    ctx = PermissionContext.from_env()
+
+    # Parse key=value arguments
+    kwargs: dict[str, Any] = {}
+    for arg in raw_args:
+        if "=" in arg:
+            key, val = arg.split("=", 1)
+            # Try JSON parsing for complex values
+            try:
+                kwargs[key] = json.loads(val)
+            except (json.JSONDecodeError, ValueError):
+                kwargs[key] = val
+        else:
+            # Positional: use as first required param's value
+            req = spec.input_schema.get("required", [])
+            if req:
+                kwargs[req[0]] = arg
+
+    # Add path if not provided
+    if "path" not in kwargs:
+        kwargs["path"] = str(Path.cwd())
+
+    # Call handler
+    try:
+        result = spec.fn(**kwargs, ctx=ctx)
+    except TypeError as e:
+        return f"ERROR: {e}. Expected params: {list(spec.input_schema.get('properties', {}).keys())}"
+
+    if hasattr(result, "to_text"):
+        return result.to_text()
+    if hasattr(result, "message"):
+        return str(result.message)
+    return str(result)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name=PRODUCT_NAME, message="%(prog)s %(version)s")
+def main():
+    """Arqux — governance framework for AI agent teams."""
+    pass
+
+@main.command("init")
+@click.option("--path", default=None, help="Path to initialize.")
+@click.option("--verbose", is_flag=True, help="Use OUT-AUDIT profile.")
+def cmd_init(path: str | None, verbose: bool):
+    """Initialize .arqux/ in the current directory."""
+    from .handlers.workspace import init_workspace
+
+    result = init_workspace(path=path, verbose=verbose)
+    click.echo(result.to_text())
+
+@main.command("status")
+@click.option("--path", default=None, help="Path to check.")
+@click.option("--verbose", is_flag=True, help="Verbose output.")
+def cmd_status(path: str | None, verbose: bool):
+    """Print workspace + project + cycle status."""
+    from .handlers.workspace import status as ws_status
+    from .handlers.project import status as pr_status
+    from .handlers.cycle import current_cycle
+
+    ws = ws_status(verbose=verbose, path=path)
+    click.echo(ws.to_text())
+
+    try:
+        pr = pr_status(verbose=verbose, path=path)
+        click.echo(pr.to_text())
+    except Exception:
+        pass
+
+    try:
+        cy = current_cycle(path=path)
+        click.echo(cy.to_text())
+    except Exception:
+        pass
+
+
+@main.command("serve")
+@click.option("--verbose", is_flag=True, help="Verbose startup.")
+def cmd_serve(verbose: bool):
+    """Start the MCP server on stdio."""
+    from .server import run_server
+    run_server(verbose=verbose)
+
+
+@main.command("call")
+@click.argument("handler")
+@click.argument("args", nargs=-1)
+def cmd_call(handler: str, args: tuple[str, ...]):
+    """Call any Arqux handler directly (no MCP required).
+
+    Examples:
+        arqux call workspace.status
+        arqux call blueprint.create obj="OAuth2 endpoint" cycle=CYCLE-01
+        arqux call identity.record lesson="Always verify P0" kind=behavioral
+        arqux call blueprint.list status=done cycle=CYCLE-01
+    """
+    result = _call_handler(handler, list(args))
+    click.echo(result)
+
+
+@main.command("setup-plantuml")
+@click.option("--force", is_flag=True, help="Force re-download.")
+def cmd_setup_plantuml(force: bool):
+    """Install plantuml.jar to ~/.arqux/bin/."""
+    from .plantuml import setup_plantuml as sp
+
+    ok, msg = sp(force=force)
+    click.echo(msg)
+    sys.exit(0 if ok else 1)
+
+
+@main.command("serve-plantuml")
+@click.option("--port", type=int, default=9876, help="Port to listen on.")
+def cmd_serve_plantuml(port: int):
+    """Start PlantUML rendering server."""
+    from .plantuml_server import start_server
+
+    srv = start_server(port=port)
+    import time
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        srv.shutdown()
+
+
+@main.command("render-diagram")
+@click.argument("puml_file")
+@click.option("--format", "fmt", default="svg", type=click.Choice(["svg", "png"]))
+@click.option("--output", "-o", default=None, help="Output directory.")
+def cmd_render_diagram(puml_file: str, fmt: str, output: str | None):
+    """Render a PUML file to SVG/PNG."""
+    from pathlib import Path
+
+    from .plantuml import render_puml
+
+    source = Path(puml_file).read_text(encoding="utf-8")
+    out_dir = Path(output) if output else None
+    ok, result = render_puml(source, format=fmt, output_dir=out_dir)
+    click.echo(result)
+    sys.exit(0 if ok else 1)
+
+
+@main.command("handlers")
+def cmd_handlers():
+    """List all available handlers."""
+    from .handlers import list_handlers
+
+    for name in sorted(list_handlers()):
+        click.echo(name)

arqux/constants.py

@@ -0,0 +1,185 @@
+"""Module-level constants for Arqux.
+
+All placeholder-derived identifiers live here so the rename script has a single
+canonical surface to swap. After running `scripts/rename-product.py <name>`:
+
+    arqux            -> <name>           (lowercase, package/cli/paths)
+    ARQUX      -> <NAME>           (uppercase, constants/markers)
+    Arqux      -> <Name>           (title case, display names)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# --- Identity --------------------------------------------------------------
+
+#: Lowercase product name. Used as the package name, CLI command, and the
+#: governance directory name (e.g. `.<product>/`).
+PRODUCT_NAME: str = "arqux"
+
+#: Uppercase product name. Used for environment variables and constants.
+PRODUCT_NAME_UPPER: str = "ARQUX"
+
+#: Title-case product name. Used in human-readable documentation.
+PRODUCT_NAME_TITLE: str = "Arqux"
+
+#: Version string — single source of truth.
+ARQUX_VERSION: str = "1.0.0"
+
+# --- Filesystem layout -----------------------------------------------------
+
+#: Name of the governance directory created inside a workspace or project.
+ARQUX_DIR: str = f".{PRODUCT_NAME}"
+
+#: Environment variable prefix for runtime configuration.
+ARQUX_ENV_PREFIX: str = f"{PRODUCT_NAME_UPPER}_"
+
+#: Default workspace manifest file (machine-readable).
+MANIFEST_CORTEX: str = "manifest.cortex"
+
+#: Default workspace manifest file (human-readable).
+MANIFEST_HCORTEX: str = "manifest.md"
+
+#: Workspace-level projects index (machine-readable).
+PROJECTS_CORTEX: str = "projects.cortex"
+
+#: Workspace-level projects index (human-readable).
+PROJECTS_HCORTEX: str = "projects.md"
+
+#: Project-level brain (machine-readable).
+BRAIN_CORTEX: str = "brain.cortex"
+
+#: Project-level brain (human-readable).
+BRAIN_HCORTEX: str = "brain.md"
+
+#: Workspace-level meta-brain (machine-readable).
+META_BRAIN_CORTEX: str = "meta-brain.cortex"
+
+#: Workspace-level meta-brain (human-readable).
+META_BRAIN_HCORTEX: str = "meta-brain.md"
+
+#: Per-cycle tasks directory.
+TASKS_DIR: str = "tasks"
+
+#: Per-project cycles directory.
+CYCLES_DIR: str = "cycles"
+BLUEPRINTS_DIR: str = "blueprints"
+
+# --- Brain sections (the project brain is the single shared mind) -----------
+#
+# The brain.cortex is the shared project mind. All handoffs, pulses,
+# sessions, lessons, focus, and active context live HERE — not in separate
+# files. This guarantees that every agent bound to the project shares the
+# same mental state.
+
+BRAIN_SECTION_FOCUS: str = "FOCUS"
+BRAIN_SECTION_OBJECTIVES: str = "OBJECTIVES"
+BRAIN_SECTION_SESSIONS: str = "SESSIONS"
+BRAIN_SECTION_HANDOFFS: str = "HANDOFFS"
+BRAIN_SECTION_PULSE: str = "PULSE"
+BRAIN_SECTION_LESSONS: str = "LESSONS"
+BRAIN_SECTION_ACTIVE_CONTEXT: str = "ACTIVE_CONTEXT"
+BRAIN_SECTION_RISKS: str = "RISKS"
+BRAIN_SECTION_CONCURRENCY: str = "CONCURRENCY"
+
+#: All canonical brain sections (used for validation).
+ALL_BRAIN_SECTIONS: tuple[str, ...] = (
+    BRAIN_SECTION_FOCUS,
+    BRAIN_SECTION_OBJECTIVES,
+    BRAIN_SECTION_SESSIONS,
+    BRAIN_SECTION_HANDOFFS,
+    BRAIN_SECTION_PULSE,
+    BRAIN_SECTION_LESSONS,
+    BRAIN_SECTION_ACTIVE_CONTEXT,
+    BRAIN_SECTION_RISKS,
+    BRAIN_SECTION_CONCURRENCY,
+)
+
+# --- Roles and permissions -------------------------------------------------
+
+ROLE_GOVERNOR: str = "governor"
+ROLE_EXECUTOR: str = "executor"
+ROLE_AUDITOR: str = "auditor"
+
+ALL_ROLES: tuple[str, ...] = (ROLE_GOVERNOR, ROLE_EXECUTOR, ROLE_AUDITOR)
+
+# --- Task state machine ----------------------------------------------------
+
+TASK_DRAFT: str = "draft"
+TASK_OPEN: str = "open"
+TASK_IN_PROGRESS: str = "in_progress"
+TASK_REVIEW: str = "review"
+TASK_DONE: str = "done"
+TASK_BLOCKED: str = "blocked"
+TASK_CANCELLED: str = "cancelled"
+
+TASK_ACTIVE_STATES: tuple[str, ...] = (
+    TASK_DRAFT,
+    TASK_OPEN,
+    TASK_IN_PROGRESS,
+    TASK_REVIEW,
+    TASK_BLOCKED,
+)
+
+TASK_TERMINAL_STATES: tuple[str, ...] = (TASK_DONE, TASK_CANCELLED)
+
+TASK_TRANSITIONS: dict[str, tuple[str, ...]] = {
+    TASK_DRAFT: (TASK_OPEN, TASK_CANCELLED),
+    TASK_OPEN: (TASK_IN_PROGRESS, TASK_CANCELLED),
+    TASK_IN_PROGRESS: (TASK_REVIEW, TASK_BLOCKED, TASK_DONE, TASK_CANCELLED),
+    TASK_REVIEW: (TASK_DONE, TASK_IN_PROGRESS, TASK_BLOCKED, TASK_CANCELLED),
+    TASK_BLOCKED: (TASK_IN_PROGRESS, TASK_CANCELLED),
+    TASK_DONE: (),
+    TASK_CANCELLED: (),
+}
+
+# --- Cycle state machine ---------------------------------------------------
+
+CYCLE_OPEN: str = "open"
+CYCLE_CLOSED: str = "closed"
+
+CYCLE_TRANSITIONS: dict[str, tuple[str, ...]] = {
+    CYCLE_OPEN: (CYCLE_CLOSED,),
+    CYCLE_CLOSED: (),
+}
+
+# --- CORTEX-OUT profiles ---------------------------------------------------
+
+OUT_MIN: str = "OUT-MIN"
+OUT_WORK: str = "OUT-WORK"
+OUT_AUDIT: str = "OUT-AUDIT"
+OUT_FULL: str = "OUT-FULL"
+OUT_ERROR: str = "OUT-ERROR"
+
+ALL_OUT_PROFILES: tuple[str, ...] = (
+    OUT_MIN,
+    OUT_WORK,
+    OUT_AUDIT,
+    OUT_FULL,
+    OUT_ERROR,
+)
+
+DEFAULT_OUT_PROFILE: str = OUT_WORK
+
+# --- Error codes -----------------------------------------------------------
+
+PERMISSION_DENIED: str = "PERMISSION_DENIED"
+NOT_FOUND: str = "NOT_FOUND"
+INVALID_STATE: str = "INVALID_STATE"
+INVALID_ARGUMENT: str = "INVALID_ARGUMENT"
+ALREADY_EXISTS: str = "ALREADY_EXISTS"
+INTERNAL_ERROR: str = "INTERNAL_ERROR"
+
+# --- Paths -----------------------------------------------------------------
+
+PACKAGE_ROOT: Path = Path(__file__).resolve().parent
+TEMPLATES_DIR: Path = PACKAGE_ROOT / "templates"
+IDENTITIES_DIR: Path = PACKAGE_ROOT / "identities"
+
+# --- Environment overrides -------------------------------------------------
+
+def env(var: str, default: str | None = None) -> str | None:
+    """Read an environment variable prefixed with the product name."""
+    return os.environ.get(f"{ARQUX_ENV_PREFIX}{var}", default)

arqux/cortex_out.py

@@ -0,0 +1,124 @@
+"""CORTEX-OUT output protocol.
+
+Five profiles, picked by context:
+
+    OUT-MIN     — quick acks, no detail.
+    OUT-WORK    — work updates, deliverables, evidence of progress.
+    OUT-AUDIT   — architecture reviews, decision logs.
+    OUT-FULL    — full prose, no compression (for humans).
+    OUT-ERROR   — failures, blockers, permission denials.
+
+Format: <PROFILE> <key=value>... [message]
+
+Examples:
+    OUT-MIN ok T-001 in_progress
+    OUT-WORK done T-001 evidence=E-007 coverage=87%
+    OUT-AUDIT review cycle=CYCLE-01 risk=low rationale="..."
+    OUT-ERROR code=PERMISSION_DENIED handler=task.create reason=executor_role
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .constants import (
+    DEFAULT_OUT_PROFILE,
+    OUT_AUDIT,
+    OUT_ERROR,
+    OUT_FULL,
+    OUT_MIN,
+    OUT_WORK,
+)
+
+
+@dataclass
+class CortexOUT:
+    """A structured CORTEX-OUT response."""
+
+    profile: str
+    fields: dict[str, Any] = field(default_factory=dict)
+    message: str = ""
+
+    @classmethod
+    def profile(cls, profile: str, message: str = "", **fields: Any) -> "CortexOUT":
+        """Build a CORTEX-OUT response with the given profile."""
+        return cls(profile=profile, fields=dict(fields), message=message)
+
+    @classmethod
+    def min(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_MIN, fields=dict(fields), message=message)
+
+    @classmethod
+    def work(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_WORK, fields=dict(fields), message=message)
+
+    @classmethod
+    def audit(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_AUDIT, fields=dict(fields), message=message)
+
+    @classmethod
+    def full(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_FULL, fields=dict(fields), message=message)
+
+    @classmethod
+    def error(cls, message: str = "", **fields: Any) -> "CortexOUT":
+        return cls(profile=OUT_ERROR, fields=dict(fields), message=message)
+
+    def to_text(self) -> str:
+        """Render as a single text line (or multi-line for OUT-FULL)."""
+        if self.profile == OUT_FULL:
+            # OUT-FULL: just the message, no key=value compression.
+            return self.message
+
+        parts: list[str] = [self.profile]
+        for key, value in self.fields.items():
+            parts.append(f"{key}={self._format_value(value)}")
+        if self.message:
+            parts.append(self.message)
+        return " ".join(parts)
+
+    @staticmethod
+    def _format_value(value: Any) -> str:
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, (list, tuple)):
+            return ",".join(str(v) for v in value)
+        if isinstance(value, dict):
+            return ";".join(f"{k}:{v}" for k, v in value.items())
+        return str(value)
+
+
+def format_status(workspace_root: Any, profile: str = DEFAULT_OUT_PROFILE) -> str:
+    """Format a workspace status report using the requested CORTEX-OUT profile."""
+    from pathlib import Path
+
+    root: Path = workspace_root
+
+    if profile == OUT_MIN:
+        return f"OUT-MIN workspace={root.name} projects=? cycles=? tasks=?"
+
+    if profile == OUT_WORK:
+        return (
+            f"OUT-WORK workspace={root.name} "
+            f"manifest={'yes' if (root / 'manifest.cortex').exists() else 'no'} "
+            f"projects={'yes' if (root / 'projects.cortex').exists() else 'no'}"
+        )
+
+    if profile == OUT_AUDIT:
+        lines = [f"OUT-AUDIT workspace={root.name}"]
+        for child in sorted(root.iterdir()):
+            if child.is_dir():
+                lines.append(f"  dir={child.name}")
+            elif child.is_file():
+                lines.append(f"  file={child.name}")
+        return "\n".join(lines)
+
+    if profile == OUT_FULL:
+        return (
+            f"Workspace at {root}\n\n"
+            f"This workspace is governed by the framework. The manifest "
+            f"and projects index live in this directory."
+        )
+
+    return CortexOUT.error(message="unknown profile").to_text()