codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/cli/main.py

@@ -0,0 +1,28 @@
+import argparse
+import sys
+from collections.abc import Sequence
+
+from pydantic import ValidationError
+
+from codealmanac.app import create_app
+from codealmanac.cli.dispatch.root import dispatch as dispatch_app
+from codealmanac.cli.parser.root import build_parser
+from codealmanac.core.errors import CodeAlmanacError
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return dispatch(args)
+    except (CodeAlmanacError, ValidationError) as error:
+        print(f"codealmanac: {error}", file=sys.stderr)
+        return 1
+
+
+def dispatch(args: argparse.Namespace) -> int:
+    return dispatch_app(args, create_app())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codealmanac/cli/parser/admin.py

@@ -0,0 +1,81 @@
+import argparse
+
+from codealmanac.services.automation.models import AutomationTask
+
+
+def add_admin_commands(subcommands: argparse._SubParsersAction) -> None:
+    doctor = subcommands.add_parser("doctor", help="check local install and wiki")
+    doctor.add_argument("--wiki")
+    doctor.add_argument("--json", action="store_true")
+
+    update = subcommands.add_parser("update", help="update the local CLI")
+    update.add_argument("--check", action="store_true")
+    update.add_argument("--json", action="store_true")
+
+    jobs = subcommands.add_parser("jobs", help="inspect local lifecycle jobs")
+    jobs.add_argument("--wiki")
+    jobs.add_argument("--limit", type=int)
+    jobs.add_argument("--json", action="store_true")
+    job_subcommands = jobs.add_subparsers(dest="jobs_command")
+    jobs_show = job_subcommands.add_parser("show", help="show one job record")
+    jobs_show.add_argument("run_id")
+    jobs_show.add_argument("--json", action="store_true")
+    jobs_logs = job_subcommands.add_parser("logs", help="show one job log")
+    jobs_logs.add_argument("run_id")
+    jobs_logs.add_argument("--json", action="store_true")
+
+    automation = subcommands.add_parser(
+        "automation",
+        help="manage local scheduled automation",
+    )
+    automation_subcommands = automation.add_subparsers(
+        dest="automation_command",
+        required=True,
+    )
+    automation_install = automation_subcommands.add_parser(
+        "install",
+        help="install scheduled sync and garden jobs",
+    )
+    automation_install.add_argument(
+        "tasks",
+        nargs="*",
+        choices=tuple(task.value for task in AutomationTask),
+    )
+    automation_install.add_argument(
+        "--every",
+        help="run interval for sync or one selected task",
+    )
+    automation_install.add_argument(
+        "--quiet",
+        help="minimum quiet time before sync",
+    )
+    automation_install.add_argument(
+        "--garden-every",
+        help="Garden run interval (default: 4h)",
+    )
+    automation_install.add_argument(
+        "--garden-off",
+        action="store_true",
+        help="disable scheduled Garden automation",
+    )
+    automation_install.add_argument("--json", action="store_true")
+    automation_uninstall = automation_subcommands.add_parser(
+        "uninstall",
+        help="remove scheduled jobs",
+    )
+    automation_uninstall.add_argument(
+        "tasks",
+        nargs="*",
+        choices=tuple(task.value for task in AutomationTask),
+    )
+    automation_uninstall.add_argument("--json", action="store_true")
+    automation_status = automation_subcommands.add_parser(
+        "status",
+        help="show scheduled automation status",
+    )
+    automation_status.add_argument(
+        "tasks",
+        nargs="*",
+        choices=tuple(task.value for task in AutomationTask),
+    )
+    automation_status.add_argument("--json", action="store_true")

codealmanac/cli/parser/lifecycle.py

@@ -0,0 +1,57 @@
+import argparse
+
+from codealmanac.services.harnesses.models import HarnessKind
+
+
+def add_lifecycle_commands(subcommands: argparse._SubParsersAction) -> None:
+    init = subcommands.add_parser("init", help="initialize a local Almanac wiki")
+    init.add_argument("path", nargs="?", default=".")
+    init.add_argument("--root")
+    init.add_argument("--name")
+    init.add_argument("--description", default="")
+
+    build = subcommands.add_parser("build", help="build or refresh a local wiki")
+    build.add_argument("path", nargs="?", default=".")
+    build.add_argument("--root")
+    build.add_argument("--name")
+    build.add_argument("--description", default="")
+
+    ingest = subcommands.add_parser("ingest", help="ingest local material")
+    ingest.add_argument("inputs", nargs="+")
+    ingest.add_argument("--wiki")
+    ingest.add_argument(
+        "--using",
+        choices=tuple(kind.value for kind in HarnessKind),
+    )
+    ingest.add_argument("--title")
+    ingest.add_argument("--guidance")
+
+    garden = subcommands.add_parser("garden", help="garden the local wiki")
+    garden.add_argument("--wiki")
+    garden.add_argument(
+        "--using",
+        choices=tuple(kind.value for kind in HarnessKind),
+    )
+    garden.add_argument("--title")
+    garden.add_argument("--guidance")
+
+    sync = subcommands.add_parser("sync", help="sync quiet local transcripts")
+    sync.add_argument("--wiki")
+    sync.add_argument("--from", dest="source_apps")
+    sync.add_argument("--quiet")
+    sync.add_argument("--pending-timeout")
+    sync.add_argument("--max-failed-attempts", type=int)
+    sync.add_argument("--claim-owner")
+    sync.add_argument(
+        "--using",
+        choices=tuple(kind.value for kind in HarnessKind),
+    )
+    sync.add_argument("--json", action="store_true")
+    sync_subcommands = sync.add_subparsers(dest="sync_command")
+    sync_status = sync_subcommands.add_parser("status", help="show sync readiness")
+    sync_status.add_argument("--wiki")
+    sync_status.add_argument("--from", dest="source_apps")
+    sync_status.add_argument("--quiet")
+    sync_status.add_argument("--pending-timeout")
+    sync_status.add_argument("--max-failed-attempts", type=int)
+    sync_status.add_argument("--json", action="store_true")

codealmanac/cli/parser/root.py

@@ -0,0 +1,19 @@
+import argparse
+
+from codealmanac import __version__
+from codealmanac.cli.parser.admin import add_admin_commands
+from codealmanac.cli.parser.lifecycle import add_lifecycle_commands
+from codealmanac.cli.parser.wiki import add_wiki_commands
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codealmanac",
+        description="Maintain a local Almanac wiki for a codebase.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    add_lifecycle_commands(subcommands)
+    add_wiki_commands(subcommands)
+    add_admin_commands(subcommands)
+    return parser

codealmanac/cli/parser/wiki.py

@@ -0,0 +1,87 @@
+import argparse
+
+DEFAULT_VIEWER_HOST = "127.0.0.1"
+DEFAULT_VIEWER_PORT = 3927
+
+
+def add_wiki_commands(subcommands: argparse._SubParsersAction) -> None:
+    list_parser = subcommands.add_parser("list", help="list registered local wikis")
+    list_parser.add_argument("--json", action="store_true")
+    list_actions = list_parser.add_mutually_exclusive_group()
+    list_actions.add_argument("--drop")
+    list_actions.add_argument("--drop-missing", action="store_true")
+
+    search = subcommands.add_parser("search", help="search the local wiki")
+    search.add_argument("query", nargs="?")
+    search.add_argument("--wiki")
+    search.add_argument("--topic", action="append", default=[])
+    search.add_argument("--mentions")
+    search.add_argument("--include-archive", action="store_true")
+    search.add_argument("--archived", action="store_true")
+    search.add_argument("--limit", type=int)
+    search.add_argument("--json", action="store_true")
+
+    show = subcommands.add_parser("show", help="show a wiki page")
+    show.add_argument("slug")
+    show.add_argument("--wiki")
+    show.add_argument("--json", action="store_true")
+    show.add_argument("--body", action="store_true")
+    show.add_argument("--meta", action="store_true")
+    show.add_argument("--lead", action="store_true")
+    show.add_argument("--links", action="store_true")
+    show.add_argument("--backlinks", action="store_true")
+    show.add_argument("--files", action="store_true")
+    show.add_argument("--topics", action="store_true")
+
+    topics = subcommands.add_parser("topics", help="list or inspect topics")
+    topics.add_argument("--wiki")
+    topic_subcommands = topics.add_subparsers(dest="topic_command")
+    topic_show = topic_subcommands.add_parser("show", help="show a topic")
+    topic_show.add_argument("slug")
+    topic_show.add_argument("--descendants", action="store_true")
+    topic_create = topic_subcommands.add_parser("create", help="create a topic")
+    topic_create.add_argument("name")
+    topic_create.add_argument("--parent", action="append", default=[])
+    topic_describe = topic_subcommands.add_parser(
+        "describe",
+        help="set a topic description",
+    )
+    topic_describe.add_argument("slug")
+    topic_describe.add_argument("description")
+    topic_link = topic_subcommands.add_parser("link", help="link topic to parent")
+    topic_link.add_argument("child")
+    topic_link.add_argument("parent")
+    topic_unlink = topic_subcommands.add_parser(
+        "unlink",
+        help="unlink topic from parent",
+    )
+    topic_unlink.add_argument("child")
+    topic_unlink.add_argument("parent")
+    topic_rename = topic_subcommands.add_parser("rename", help="rename a topic")
+    topic_rename.add_argument("old_slug")
+    topic_rename.add_argument("new_slug")
+    topic_delete = topic_subcommands.add_parser("delete", help="delete a topic")
+    topic_delete.add_argument("slug")
+
+    health = subcommands.add_parser("health", help="check wiki health")
+    health.add_argument("--wiki")
+    health.add_argument("--json", action="store_true")
+
+    reindex = subcommands.add_parser("reindex", help="force a full index rebuild")
+    reindex.add_argument("--wiki")
+    reindex.add_argument("--json", action="store_true")
+
+    serve = subcommands.add_parser("serve", help="serve the local wiki viewer")
+    serve.add_argument("--wiki")
+    serve.add_argument("--host", default=DEFAULT_VIEWER_HOST)
+    serve.add_argument("--port", type=int, default=DEFAULT_VIEWER_PORT)
+
+    tag = subcommands.add_parser("tag", help="add topics to a page")
+    tag.add_argument("slug")
+    tag.add_argument("topics", nargs="+")
+    tag.add_argument("--wiki")
+
+    untag = subcommands.add_parser("untag", help="remove topics from a page")
+    untag.add_argument("slug")
+    untag.add_argument("topics", nargs="+")
+    untag.add_argument("--wiki")

codealmanac/cli/render/admin.py

@@ -0,0 +1,191 @@
+import json
+import shlex
+import sys
+from datetime import timedelta
+
+from codealmanac.services.automation.models import (
+    AutomationInstallResult,
+    AutomationStatusReport,
+    AutomationTask,
+    AutomationUninstallResult,
+    ScheduledJob,
+    ScheduledJobStatus,
+)
+from codealmanac.services.diagnostics.models import DoctorCheck, DoctorReport
+from codealmanac.services.runs.models import RunLogEvent, RunRecord
+from codealmanac.services.updates.models import UpdatePlan, UpdateResult
+
+
+def render_automation_install(
+    result: AutomationInstallResult,
+    json_output: bool,
+) -> None:
+    if json_output:
+        print(json.dumps(result.model_dump(mode="json"), indent=2))
+        return
+    print("automation installed")
+    for job in result.jobs:
+        print_automation_job(job)
+    for job in result.disabled:
+        print(f"  {job.task.value}: disabled")
+
+
+def render_automation_uninstall(
+    result: AutomationUninstallResult,
+    json_output: bool,
+) -> None:
+    if json_output:
+        print(json.dumps(result.model_dump(mode="json"), indent=2))
+        return
+    if len(result.removed) == 0:
+        print("automation not installed")
+        return
+    print("automation removed")
+    for path in result.removed:
+        print(f"  plist: {path}")
+
+
+def render_automation_status(
+    report: AutomationStatusReport,
+    json_output: bool,
+) -> None:
+    if json_output:
+        print(json.dumps(report.model_dump(mode="json"), indent=2))
+        return
+    for status in report.statuses:
+        render_automation_job_status(status)
+
+
+def print_automation_job(job: ScheduledJob) -> None:
+    print(f"  {job.task.value} interval: {duration_label(job.interval)}")
+    if job.task == AutomationTask.SYNC:
+        quiet = job.program_arguments[job.program_arguments.index("--quiet") + 1]
+        print(f"  sync quiet: {quiet}")
+    print(f"  {job.task.value} command: {' '.join(job.program_arguments)}")
+    if job.working_directory is not None:
+        print(f"  {job.task.value} cwd: {job.working_directory}")
+    print(f"  {job.task.value} plist: {job.plist_path}")
+
+
+def render_automation_job_status(status: ScheduledJobStatus) -> None:
+    label = f"{status.task.value} automation"
+    if not status.installed:
+        print(f"{label}: not installed")
+        return
+    print(f"{label}: installed")
+    print(f"  plist: {status.plist_path}")
+    print(f"  launchd loaded: {'yes' if status.loaded else 'no'}")
+    if status.interval is not None:
+        print(f"  interval: {duration_label(status.interval)}")
+    if status.quiet is not None:
+        print(f"  quiet: {duration_label(status.quiet)}")
+
+
+def duration_label(value: timedelta) -> str:
+    seconds = int(value.total_seconds())
+    return f"{seconds}s"
+
+
+def render_doctor(report: DoctorReport, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(report.model_dump(mode="json"), indent=2))
+        return
+    print(f"codealmanac v{report.version}")
+    print("")
+    render_doctor_section("Install", report.install)
+    render_doctor_section("Current wiki", report.wiki)
+
+
+def render_doctor_section(title: str, checks: tuple[DoctorCheck, ...]) -> None:
+    if len(checks) == 0:
+        return
+    print(f"## {title}")
+    for check in checks:
+        print(f"  {check.status.value} {check.message}")
+        if check.fix is not None:
+            print(f"    {check.fix}")
+    print("")
+
+
+def render_update_plan(plan: UpdatePlan, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(plan.model_dump(mode="json"), indent=2))
+        return
+    print(f"codealmanac {plan.installed_version}")
+    print(f"update status: {plan.status.value}")
+    print(f"install method: {plan.method.value}")
+    print(f"message: {plan.message}")
+    if plan.command:
+        print(f"command: {shell_command(plan.command)}")
+    if plan.fix is not None:
+        print(plan.fix)
+
+
+def render_update_result(result: UpdateResult, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(result.model_dump(mode="json"), indent=2))
+        return
+    render_update_plan(result.plan, json_output=False)
+    if result.exit_code is not None:
+        print(f"exit_code: {result.exit_code}")
+    if result.stdout:
+        print(result.stdout, end="" if result.stdout.endswith("\n") else "\n")
+    if result.stderr:
+        print(result.stderr, end="" if result.stderr.endswith("\n") else "\n")
+
+
+def shell_command(command: tuple[str, ...]) -> str:
+    return shlex.join(command)
+
+
+def render_runs(records: tuple[RunRecord, ...], json_output: bool) -> None:
+    if json_output:
+        data = [record.model_dump(mode="json") for record in records]
+        print(json.dumps(data, indent=2))
+        return
+    if len(records) == 0:
+        print("# 0 jobs", file=sys.stderr)
+        return
+    for record in records:
+        title = record.title or ""
+        print(
+            f"{record.run_id}\t{record.status.value}\t"
+            f"{record.operation.value}\t{title}"
+        )
+
+
+def render_run(record: RunRecord, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(record.model_dump(mode="json"), indent=2))
+        return
+    print(f"id: {record.run_id}")
+    print(f"operation: {record.operation.value}")
+    print(f"status: {record.status.value}")
+    if record.title is not None:
+        print(f"title: {record.title}")
+    if record.summary is not None:
+        print(f"summary: {record.summary}")
+    if record.error is not None:
+        print(f"error: {record.error}")
+    if record.harness_transcript is not None:
+        print(
+            "harness_transcript: "
+            f"{record.harness_transcript.kind.value} "
+            f"{record.harness_transcript.session_id}"
+        )
+        if record.harness_transcript.transcript_path is not None:
+            print(
+                "harness_transcript_path: "
+                f"{record.harness_transcript.transcript_path}"
+            )
+    print(f"created_at: {record.created_at.isoformat()}")
+    print(f"updated_at: {record.updated_at.isoformat()}")
+
+
+def render_run_log(events: tuple[RunLogEvent, ...], json_output: bool) -> None:
+    if json_output:
+        data = [event.model_dump(mode="json") for event in events]
+        print(json.dumps(data, indent=2))
+        return
+    for event in events:
+        print(f"{event.sequence}\t{event.kind.value}\t{event.message}")