alku 0.5.0__py3-none-any.whl

alku/__init__.py

@@ -0,0 +1,3 @@
+"""Alku repository bootstrapper and documentation maintainer."""
+
+__version__ = "0.5.0"

alku/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

alku/agent_configs.py

@@ -0,0 +1,269 @@
+"""Managed project-scoped agent profiles for supported model providers."""
+
+from __future__ import annotations
+
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from .providers import profile_for
+
+
+class AgentConfigSyncError(ValueError):
+    """A managed agent profile cannot be synchronized safely."""
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    name: str
+    description: str
+    model: str
+    effort: str
+    instructions: str
+    read_only: bool = False
+
+
+@dataclass(frozen=True)
+class AgentConfigSyncReport:
+    state: str
+    copied: tuple[str, ...] = ()
+
+
+def _agent_specs(provider: str) -> tuple[AgentSpec, ...]:
+    """Build native agent specs from the packaged model matrix."""
+    profile = profile_for(provider)
+    if provider == "openai":
+        workflow_instructions = (
+            "Read and follow .agents/skills/alku-workflow/SKILL.md. Own one bounded "
+            "feature, retain architecture and documentation context, and return a "
+            "verified result to the parent agent."
+        )
+        research_instructions = (
+            "Read and follow .agents/skills/alku-workflow/references/research.md. "
+            "Stay within the delegated question and return concise, cited evidence."
+        )
+        review_instructions = (
+            "Read and follow .agents/skills/alku-workflow/references/review.md. "
+            "Review the post-generation artifact independently and lead with concrete "
+            "findings."
+        )
+        develop_instructions = (
+            "Read and follow .agents/skills/alku-workflow/references/develop.md. "
+            "Implement only the assigned files and acceptance criteria, preserve "
+            "unrelated changes, and report targeted verification."
+        )
+    else:
+        workflow_instructions = (
+            "Follow the preloaded alku-workflow skill. Own one bounded feature, retain "
+            "architecture and documentation context, and return a verified result to "
+            "the parent agent."
+        )
+        research_instructions = (
+            "Read .claude/skills/alku-workflow/references/research.md. Stay within the "
+            "delegated question and return concise, cited evidence."
+        )
+        review_instructions = (
+            "Read .claude/skills/alku-workflow/references/review.md. Review the "
+            "post-generation artifact independently and lead with concrete findings."
+        )
+        develop_instructions = (
+            "Read .claude/skills/alku-workflow/references/develop.md. Implement only "
+            "the assigned files and acceptance criteria, preserve unrelated changes, "
+            "and report targeted verification."
+        )
+
+    specs = [
+        AgentSpec(
+            "alku-workflow",
+            "Own one bounded Alku feature from approved plan through verification.",
+            profile.model_for("workflow"),
+            profile.effort_for("workflow"),
+            workflow_instructions,
+        ),
+        AgentSpec(
+            "alku-research",
+            "Investigate a bounded question and return evidence without editing code.",
+            profile.model_for("research"),
+            profile.effort_for("research"),
+            research_instructions,
+            True,
+        ),
+        AgentSpec(
+            "alku-review",
+            "Independently review a completed Alku change for material risks.",
+            profile.model_for("review"),
+            profile.effort_for("review"),
+            review_instructions,
+            True,
+        ),
+    ]
+    specs.extend(
+        AgentSpec(
+            f"alku-develop-{effort}",
+            f"Implement bounded Alku work at {effort} reasoning effort.",
+            profile.model_for(f"develop-{effort}"),
+            profile.effort_for(f"develop-{effort}"),
+            develop_instructions,
+        )
+        for effort in ("low", "medium", "high")
+    )
+    return tuple(specs)
+
+
+OPENAI_AGENT_SPECS = _agent_specs("openai")
+ANTHROPIC_AGENT_SPECS = _agent_specs("anthropic")
+
+
+def _kind(path: Path) -> str:
+    try:
+        mode = path.lstat().st_mode
+    except FileNotFoundError:
+        return "missing"
+    except OSError:
+        return "other"
+    if stat.S_ISLNK(mode):
+        return "symlink"
+    if stat.S_ISREG(mode):
+        return "file"
+    if stat.S_ISDIR(mode):
+        return "directory"
+    return "other"
+
+
+def _safe_parent(root: Path, path: Path) -> bool:
+    try:
+        relative = path.parent.relative_to(root)
+    except ValueError:
+        return False
+    current = root
+    for part in relative.parts:
+        current /= part
+        if _kind(current) in {"symlink", "file", "other"}:
+            return False
+    return True
+
+
+def _toml(spec: AgentSpec) -> str:
+    sandbox = 'sandbox_mode = "read-only"\n' if spec.read_only else ""
+    return (
+        "# alku:managed-agent\n"
+        f'name = "{spec.name}"\n'
+        f'description = "{spec.description}"\n'
+        f'model = "{spec.model}"\n'
+        f'model_reasoning_effort = "{spec.effort}"\n'
+        f"{sandbox}"
+        'developer_instructions = """\n'
+        f"{spec.instructions}\n"
+        '"""\n'
+    )
+
+
+def _markdown(spec: AgentSpec) -> str:
+    permission = "\npermissionMode: plan" if spec.read_only else ""
+    skills = "\nskills:\n  - alku-workflow" if spec.name == "alku-workflow" else ""
+    return (
+        "---\n"
+        f"name: {spec.name}\n"
+        f"description: {spec.description}\n"
+        f"model: {spec.model}\n"
+        f"effort: {spec.effort}"
+        f"{permission}{skills}\n"
+        "---\n"
+        "<!-- alku:managed-agent -->\n\n"
+        f"{spec.instructions}\n"
+    )
+
+
+def agent_config_outputs(root: Path) -> tuple[tuple[Path, str], ...]:
+    """Return every provider-native project agent profile."""
+    outputs = [
+        (root / ".codex" / "agents" / f"{spec.name}.toml", _toml(spec))
+        for spec in OPENAI_AGENT_SPECS
+    ]
+    outputs.extend(
+        (root / ".claude" / "agents" / f"{spec.name}.md", _markdown(spec))
+        for spec in ANTHROPIC_AGENT_SPECS
+    )
+    return tuple(outputs)
+
+
+def _managed(path: Path, content: str) -> bool:
+    if path.suffix == ".toml":
+        return content.startswith("# alku:managed-agent\n")
+    if not content.startswith("---\n"):
+        return False
+    end = content.find("\n---\n", 4)
+    return end >= 0 and content[end + 5 :].startswith("<!-- alku:managed-agent -->\n")
+
+
+def sync_agent_configs_report(
+    root: Path, *, dry_run: bool = False
+) -> AgentConfigSyncReport:
+    """Synchronize both provider profile sets with whole-file ownership checks."""
+    planned: list[tuple[Path, str, str | None]] = []
+    for path, content in agent_config_outputs(root):
+        if not _safe_parent(root, path):
+            raise AgentConfigSyncError(f"unsafe managed agent parent: {path.parent}")
+        kind = _kind(path)
+        if kind == "missing":
+            planned.append((path, content, None))
+            continue
+        if kind != "file":
+            raise AgentConfigSyncError(f"unsafe managed agent collision: {path}")
+        try:
+            actual = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as error:
+            raise AgentConfigSyncError(
+                f"cannot read managed agent {path}: {error}"
+            ) from error
+        if actual == content:
+            continue
+        if not _managed(path, actual):
+            raise AgentConfigSyncError(
+                f"fail-closed agent collision: unmarked/user-owned file: {path}"
+            )
+        planned.append((path, content, actual))
+    if not dry_run:
+        for path, content, original in planned:
+            if not _safe_parent(root, path):
+                raise AgentConfigSyncError(
+                    f"concurrent managed agent parent update: {path.parent}"
+                )
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if original is None:
+                if _kind(path) != "missing":
+                    raise AgentConfigSyncError(
+                        f"concurrent managed agent update: {path}"
+                    )
+                with path.open("x", encoding="utf-8", newline="") as stream:
+                    stream.write(content)
+                continue
+            if _kind(path) != "file":
+                raise AgentConfigSyncError(f"concurrent managed agent update: {path}")
+            try:
+                current = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError) as error:
+                raise AgentConfigSyncError(
+                    f"cannot recheck managed agent {path}: {error}"
+                ) from error
+            if current != original or not _managed(path, current):
+                raise AgentConfigSyncError(f"concurrent managed agent update: {path}")
+            temporary = path.with_name(path.name + ".alku-new")
+            if _kind(temporary) == "missing":
+                with temporary.open("x", encoding="utf-8", newline="") as stream:
+                    stream.write(content)
+            elif (
+                _kind(temporary) != "file"
+                or temporary.read_text(encoding="utf-8") != content
+            ):
+                raise AgentConfigSyncError(
+                    f"unsafe managed agent staging collision: {temporary}"
+                )
+            if _kind(path) != "file" or path.read_text(encoding="utf-8") != original:
+                temporary.unlink(missing_ok=True)
+                raise AgentConfigSyncError(f"concurrent managed agent update: {path}")
+            temporary.replace(path)
+    return AgentConfigSyncReport(
+        "copied" if planned else "unchanged",
+        tuple(str(path.relative_to(root)) for path, _, _ in planned),
+    )

alku/claude.py

@@ -0,0 +1,144 @@
+"""Canonical Claude project-instruction import handling."""
+
+from __future__ import annotations
+
+import re
+import stat
+from pathlib import Path
+
+from .gate import BEGIN, END, _models_for_text, _provider_for_text, gate_template
+
+CLAUDE_IMPORT = "@AGENTS.md\n"
+_IMPORT = re.compile(r"(?<!\S)@AGENTS\.md(?!\S)")
+
+
+class ClaudeReferenceError(ValueError):
+    """CLAUDE.md cannot be converted without risking authored content."""
+
+
+def _without_managed_gate(content: str) -> str:
+    starts, ends = content.count(BEGIN), content.count(END)
+    if not starts and not ends:
+        return content
+    if starts != 1 or ends != 1 or content.index(BEGIN) > content.index(END):
+        raise ClaudeReferenceError("CLAUDE.md contains malformed alku markers")
+    start, end = content.index(BEGIN), content.index(END) + len(END)
+    block = content[start:end]
+    try:
+        provider = _provider_for_text(block)
+    except ValueError as error:
+        raise ClaudeReferenceError(str(error)) from error
+    if provider is None:
+        inferred = [
+            name
+            for name, skill_root in (("openai", ".agents"), ("anthropic", ".claude"))
+            if f"{skill_root}/skills/alku-workflow/SKILL.md" in block
+        ]
+        provider = inferred[0] if len(inferred) == 1 else None
+    historical = (
+        f"{BEGIN}\n"
+        f"<!-- alku:provider {provider} -->\n"
+        "Use the `alku-workflow` skill.\n"
+        f"{END}"
+    )
+    if provider is not None and block.replace("\r\n", "\n") == historical:
+        return content[:start] + content[end:]
+    without_provider_marker = re.sub(
+        r"<!-- alku:provider(?: (?:openai|anthropic))? -->\r?\n?",
+        "",
+        block,
+        count=1,
+    )
+    if provider is not None and without_provider_marker.replace(
+        "\r\n", "\n"
+    ) == gate_template(provider=provider).rstrip("\n"):
+        return content[:start] + content[end:]
+    models = _models_for_text(block)
+    skill_root = ".agents" if provider == "openai" else ".claude"
+    required = (
+        "## Alku workflow",
+        f"{skill_root}/skills/alku-workflow/SKILL.md",
+    )
+    if (
+        provider is None
+        or models is None
+        or any(item not in block for item in required)
+        or (
+            "Before work, run `alku self check`" not in block
+            and "Load the repository workflow skill" not in block
+        )
+    ):
+        raise ClaudeReferenceError(
+            "CLAUDE.md marker block is not a recognized legacy Alku gate"
+        )
+    return content[:start] + content[end:]
+
+
+def claude_reference_content(content: str | None) -> str:
+    """Return CLAUDE.md with the legacy gate removed and AGENTS.md imported."""
+    exterior = _without_managed_gate(content or "")
+    if not exterior.strip():
+        return CLAUDE_IMPORT
+    if _IMPORT.search(exterior):
+        return exterior
+    separator = (
+        ""
+        if exterior.endswith("\n\n")
+        else ("\n" if exterior.endswith("\n") else "\n\n")
+    )
+    return exterior + separator + CLAUDE_IMPORT
+
+
+def claude_reference_diagnostics(path: Path) -> list[dict[str, str]]:
+    """Validate that CLAUDE.md imports AGENTS.md without a legacy Alku gate."""
+    try:
+        mode = path.lstat().st_mode
+    except FileNotFoundError:
+        return [
+            {
+                "code": "missing_claude_reference",
+                "message": "CLAUDE.md must import AGENTS.md; run alku init",
+                "path": path.name,
+                "level": "error",
+            }
+        ]
+    except OSError as error:
+        return [
+            {
+                "code": "claude_reference_error",
+                "message": str(error),
+                "path": path.name,
+                "level": "error",
+            }
+        ]
+    if stat.S_ISLNK(mode) or not stat.S_ISREG(mode):
+        return [
+            {
+                "code": "claude_reference_error",
+                "message": "CLAUDE.md must be a regular file",
+                "path": path.name,
+                "level": "error",
+            }
+        ]
+    try:
+        content = path.read_text(encoding="utf-8")
+        expected = claude_reference_content(content)
+    except (OSError, UnicodeDecodeError, ClaudeReferenceError) as error:
+        return [
+            {
+                "code": "claude_reference_error",
+                "message": str(error),
+                "path": path.name,
+                "level": "error",
+            }
+        ]
+    if content == expected:
+        return []
+    return [
+        {
+            "code": "stale_claude_reference",
+            "message": "CLAUDE.md must import AGENTS.md; run alku init",
+            "path": path.name,
+            "level": "error",
+        }
+    ]

alku/cli.py

@@ -0,0 +1,35 @@
+"""Top-level command assembly for Alku."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .commands.docs import docs
+from .commands.init import init_command
+from .commands.self import self_group
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="alku")
+@click.option(
+    "--root",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="repository root (default: current working directory)",
+)
+@click.option(
+    "--json", "as_json", is_flag=True, default=False, help="emit structured JSON only"
+)
+@click.pass_context
+def cli(ctx: click.Context, root: Path | None, as_json: bool) -> None:
+    """Initialize projects, maintain documentation, and manage Alku itself."""
+    ctx.ensure_object(dict)
+    ctx.obj.update(root=root if root is not None else Path.cwd(), json=as_json)
+
+
+cli.add_command(init_command)
+cli.add_command(docs)
+cli.add_command(self_group)

alku/codebase_memory.py

@@ -0,0 +1,51 @@
+"""Best-effort codebase-memory installation and version discovery."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable
+
+
+def codebase_memory_status(
+    *,
+    which: Callable[[str], str | None] = shutil.which,
+    runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+) -> dict[str, object]:
+    """Detect codebase-memory-mcp and return a non-mutating recommendation."""
+    executable = which("codebase-memory-mcp")
+    if executable is None:
+        command = (
+            "Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/"
+            "codebase-memory-mcp/main/install.ps1 -OutFile install.ps1; "
+            ".\\install.ps1"
+            if os.name == "nt"
+            else "curl -fsSL https://raw.githubusercontent.com/DeusData/"
+            "codebase-memory-mcp/main/install.sh | bash"
+        )
+        return {
+            "installed": False,
+            "version": None,
+            "recommendation": "Install codebase-memory-mcp for structural code discovery.",
+            "command": command,
+        }
+    version = None
+    try:
+        completed = runner(
+            [executable, "--version"],
+            text=True,
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        if completed.returncode == 0:
+            version = (completed.stdout or completed.stderr).strip() or None
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return {
+        "installed": True,
+        "version": version,
+        "recommendation": "Keep codebase-memory-mcp current before large code changes.",
+        "command": "codebase-memory-mcp update",
+    }

alku/commands/__init__.py

@@ -0,0 +1 @@
+"""Click command groups exposed by :mod:`alku.cli`."""

alku/commands/common.py

@@ -0,0 +1,144 @@
+"""Shared Click options, output rendering, and repository resolution."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import click
+
+from ..repository import scan_features
+from ..validation import validate_query_metadata
+
+
+def common_options(
+    query: bool = False,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    def decorate(command: Callable[..., Any]) -> Callable[..., Any]:
+        command = click.option(
+            "--root",
+            type=click.Path(path_type=Path),
+            default=None,
+            help="repository root; may also precede the command",
+        )(command)
+        command = click.option(
+            "--json",
+            "as_json",
+            is_flag=True,
+            default=False,
+            help="emit structured JSON only",
+        )(command)
+        if query:
+            command = click.option(
+                "--offset", type=click.IntRange(min=0), default=0, show_default=True
+            )(command)
+            command = click.option(
+                "--limit", type=click.IntRange(min=1), default=20, show_default=True
+            )(command)
+        return command
+
+    return decorate
+
+
+def filters(command: Callable[..., Any]) -> Callable[..., Any]:
+    for option in ("work", "delivery", "decision", "area"):
+        command = click.option(f"--{option}")(command)
+    return click.option("--depends-on")(command)
+
+
+def emit(value: object, as_json: bool) -> None:
+    if as_json:
+        click.echo(json.dumps(value, indent=2, sort_keys=True))
+    elif isinstance(value, dict) and value.get("command") == "init":
+        steps = value.get("steps")
+        counts: dict[str, int] = {}
+        if isinstance(steps, list):
+            for step in steps:
+                if not isinstance(step, dict) or not isinstance(
+                    step.get("status"), str
+                ):
+                    continue
+                status = str(step["status"])
+                counts[status] = counts.get(status, 0) + 1
+        summary = ", ".join(
+            f"{counts[status]} {status}"
+            for status in ("done", "skipped", "blocked", "error")
+            if counts.get(status)
+        )
+        glyph = "✓" if value.get("ok") else "×"
+        label = "Initialized" if value.get("ok") else "Initialization failed"
+        click.echo(f"\n{glyph} {label}" + (f" · {summary}" if summary else ""))
+        recommendations = value.get("recommendations")
+        if isinstance(recommendations, list):
+            if recommendations:
+                click.echo("\nNext steps:")
+            for recommendation in recommendations:
+                if not isinstance(recommendation, dict):
+                    continue
+                if recommendation.get("message"):
+                    click.echo(str(recommendation["message"]))
+                if recommendation.get("cwd"):
+                    click.echo(f"Working directory: {recommendation['cwd']}")
+                argv = recommendation.get("argv")
+                if isinstance(argv, list) and all(
+                    isinstance(argument, str) for argument in argv
+                ):
+                    click.echo(
+                        "Argument vector (execute without a shell): "
+                        + json.dumps(argv, ensure_ascii=False)
+                    )
+    elif isinstance(value, dict) and "items" in value:
+        for item in value["items"]:
+            click.echo(
+                f"{item.get('id', item.get('path'))}: {item.get('title', item.get('heading', ''))}"
+            )
+        click.echo(
+            f"total={value['total']} has_more={value['has_more']} truncated={value['truncated']}"
+        )
+    elif isinstance(value, dict) and "text" in value:
+        click.echo(value["text"])
+    elif isinstance(value, dict) and "diagnostics" in value:
+        for item in value["diagnostics"]:
+            click.echo(
+                f"{item['level']}: {item.get('path', '')}: {item['code']}: {item['message']}",
+                err=True,
+            )
+    else:
+        click.echo(str(value))
+
+
+def resolved_options(
+    ctx: click.Context, local_root: Path | None, local_json: bool
+) -> tuple[Path, bool]:
+    root = (local_root or ctx.find_root().obj["root"]).resolve()
+    if not root.is_dir():
+        raise click.UsageError(f"--root is not a directory: {root}")
+    return root, local_json or bool(ctx.find_root().obj["json"])
+
+
+def query_features(root: Path) -> tuple[list[Any], list[Any]]:
+    features, diagnostics = scan_features(root)
+    errors = validate_query_metadata(features) + diagnostics
+    return features, errors
+
+
+def report(
+    ctx: click.Context,
+    root: Path | None,
+    as_json: bool,
+    action: Callable[[Path], tuple[Any, list[Any]]],
+    name: str,
+) -> None:
+    selected_root, selected_json = resolved_options(ctx, root, as_json)
+    records, diagnostics = action(selected_root)
+    payload = {
+        "command": name,
+        "diagnostics": [item.json() for item in diagnostics],
+        "ok": not any(item.level == "error" for item in diagnostics),
+    }
+    payload.update({f"{kind}s": len(items) for kind, items in records.items()})
+    emit(payload, selected_json)
+    if not payload["ok"]:
+        raise click.exceptions.Exit(1)