spectackl 0.0.1__py3-none-any.whl

spectackl/__init__.py

@@ -0,0 +1,3 @@
+"""Spectackl CLI — public REST API client for AI agents and operators."""
+
+__version__ = "0.0.1"

spectackl/auth.py

@@ -0,0 +1,74 @@
+"""API key resolution for the Spectackl CLI.
+
+Resolution order (highest to lowest priority):
+1. --api-key CLI flag
+2. SPECTACKL_API_KEY environment variable
+3. api_key field in .spectackl/settings.yaml (repo root, walked up from CWD)
+4. api_key field in ~/.config/spectackl/settings.yaml
+5. Error if none found (exit code 10)
+
+Any of the file-based values may be a ${VAR} reference resolved from the named
+scalars in ~/.config/spectackl/settings.yaml (see spectackl.config.load_config).
+"""
+
+from __future__ import annotations
+
+import typer
+
+from spectackl import exit_codes
+from spectackl.config import SpectacklConfig
+
+
+def resolve_api_key(config: SpectacklConfig) -> str:
+    """Return the API key or exit with code 10.
+
+    Raises:
+        typer.Exit: with code 10 (AUTH_REQUIRED) if no API key is found.
+    """
+    if config.api_key:
+        return config.api_key
+
+    typer.echo(
+        "Error: API key not found.\n"
+        "  Run 'spectackl init' to create the config files, or\n"
+        "  set --api-key, the SPECTACKL_API_KEY env var,\n"
+        "  or api_key in .spectackl/settings.yaml (repo root) / ~/.config/spectackl/settings.yaml.\n"
+        "  api_key may be a ${VAR} reference resolved from ~/.config/spectackl/settings.yaml.",
+        err=True,
+    )
+    raise typer.Exit(code=exit_codes.AUTH_REQUIRED)
+
+
+def resolve_project_id(config: SpectacklConfig) -> str:
+    """Return the project ID or exit with code 2 (usage error).
+
+    Resolution order is already applied by load_config:
+      --project flag > SPECTACKL_PROJECT_ID env > .spectackl/settings.yaml > global config.
+
+    Raises:
+        typer.Exit: with code 2 (USAGE_ERROR) if no project_id is found.
+    """
+    if config.project_id:
+        return config.project_id
+
+    typer.echo(
+        "Error: project_id not found.\n"
+        "  Run 'spectackl init --project <key>', or\n"
+        "  set --project, the SPECTACKL_PROJECT_ID env var,\n"
+        "  or add project_id (or project_key) to .spectackl/settings.yaml in the repo root.",
+        err=True,
+    )
+    raise typer.Exit(code=exit_codes.USAGE_ERROR)
+
+
+def validate_api_key_format(api_key: str) -> bool:
+    """Return True if the key matches the spc_<64hex> format.
+
+    Does not contact the server. Used for local pre-flight validation only.
+    """
+    if not api_key.startswith("spc_"):
+        return False
+    suffix = api_key[4:]
+    if len(suffix) != 64:
+        return False
+    return all(c in "0123456789abcdefABCDEF" for c in suffix)

spectackl/cli.py

@@ -0,0 +1,108 @@
+"""Spectackl CLI entry point.
+
+The Spectackl CLI provides commands for AI agents and operators to interact
+with the Spectackl Public REST API.
+
+Usage:
+    spectackl init            # create the config files, first thing on a new machine
+    spectackl assets sync     # pull the project's agents and skills into ./.claude/
+    spectackl --help
+    spectackl search "SSO login"   # hybrid content search over the project
+    spectackl artifact --help
+    spectackl context --help
+    spectackl task --help
+
+Global flags (available on all commands):
+    --api-key TEXT         Spectackl API key (spc_<64hex>)
+    --base-url TEXT        API base URL (default: http://localhost:8080/api/v1)
+    --json / --no-json     Output raw JSON (recommended for scripts and agents)
+    --no-color             Disable color output
+    -v / -vv               Increase verbosity
+
+Authentication priority:
+    1. --api-key flag
+    2. SPECTACKL_API_KEY environment variable
+    3. api_key in ~/.config/spectackl/settings.yaml
+
+Exit codes:
+     0  Success
+     1  Generic error
+     2  Usage error (bad flag, missing argument)
+    10  Authentication required or invalid (HTTP 401)
+    11  Authorization denied (HTTP 403)
+    20  Validation error (HTTP 400)
+    30  Not found (HTTP 404)
+    31  Conflict (HTTP 409)
+    40  Upstream unavailable or timeout (HTTP 502/504)
+    50  Internal facade error (HTTP 5xx)
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from spectackl import __version__
+from spectackl.commands import artifact, assets, context, daemon, init, relation
+from spectackl.commands import rsync as rsync_cmd
+from spectackl.commands import search as search_cmd
+from spectackl.commands import task
+
+# Root typer app
+app = typer.Typer(
+    name="spectackl",
+    help=(
+        "Spectackl CLI — interact with the Spectackl Public REST API.\n\n"
+        "Designed for AI agents and operators. Use --json for machine-readable output."
+    ),
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+# Register subcommand groups
+app.add_typer(init.app, name="init")
+app.add_typer(artifact.app, name="artifact")
+app.add_typer(context.app, name="context")
+app.add_typer(assets.app, name="assets")
+app.add_typer(relation.app, name="relation")
+app.add_typer(task.app, name="task")
+app.add_typer(daemon.app, name="daemon")
+
+# Top-level content search command (mirrors GET /api/v1/search)
+app.command(name="search")(search_cmd.search)
+
+# Bi-directional file synchronization. Distinct from `assets sync`, which pulls
+# agent/skill definitions one way.
+app.command(name="rsync")(rsync_cmd.rsync)
+
+# Deprecated: `spectackl sync` was renamed to `spectackl assets sync`. The same
+# function is registered twice so the two entry points cannot drift; it is hidden
+# from --help and warns when invoked, and will be removed in a later release.
+app.command(
+    name=assets.DEPRECATED_ALIAS,
+    hidden=True,
+    help="Deprecated alias for `spectackl assets sync`.",
+)(assets.sync)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"spectackl {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """Spectackl CLI — AI agent and operator interface to the Spectackl platform."""

spectackl/commands/__init__.py

@@ -0,0 +1 @@
+# spectackl.commands package

spectackl/commands/artifact.py

@@ -0,0 +1,335 @@
+"""Artifact commands for the Spectackl CLI.
+
+Commands:
+  spectackl artifact get <key> [--project UUID] [--include-content]
+  spectackl artifact list [--project UUID] [--kind KIND...] [--limit N] [--page-token T]
+  spectackl artifact create [--project UUID] --kind KIND --title TITLE [--content TEXT|@file]
+  spectackl artifact update <key> [--project UUID] [--title TITLE] [--content TEXT|@file]
+
+project_id resolution order:
+  --project flag > SPECTACKL_PROJECT_ID env > project_id in .spectackl/settings.yaml > global config
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Annotated
+
+import httpx
+import typer
+
+from spectackl import exit_codes
+from spectackl.auth import resolve_api_key, resolve_project_id
+from spectackl.config import load_config
+from spectackl.http_client import handle_response, make_client
+from spectackl.output import render, render_error
+
+app = typer.Typer(
+    name="artifact",
+    help="Manage Spectackl artifacts (requirements, designs, implementations, etc.).",
+    no_args_is_help=True,
+)
+
+
+def _resolve_at_file(value: str | None) -> str | None:
+    """If value starts with '@', read the file at the given path and return its contents."""
+    if value is None:
+        return None
+    if value.startswith("@"):
+        path = value[1:]
+        try:
+            with open(path) as f:
+                return f.read()
+        except OSError as e:
+            typer.echo(f"Error: Cannot read file '{path}': {e}", err=True)
+            raise typer.Exit(code=exit_codes.USAGE_ERROR)
+    return value
+
+
+def content_sha256(text: str) -> str:
+    """SHA-256 hex digest of content, matching the server's checksum.
+
+    The backend computes the checksum over the exact UTF-8 bytes of the content
+    you upload (before any server-side frontmatter processing) and returns it as
+    ``artifact.content_checksum``. Hashing identically here lets ``update`` skip
+    re-uploading content that has not changed.
+    """
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _fetch_content_checksum(client: httpx.Client, key: str, project_id: str | None) -> str | None:
+    """Return the artifact's current content_checksum, or None if unavailable.
+
+    Best-effort: any error (network, not-found, missing field) yields None, which
+    makes the caller fall through to a normal upload rather than fail.
+    """
+    try:
+        resp = client.get(f"/artifacts/{key}", params={"project_id": project_id})
+    except httpx.HTTPError:
+        return None
+    if resp.status_code != 200:
+        return None
+    try:
+        data = resp.json()
+    except ValueError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    # GET /artifacts/{key} wraps the object as {"artifact": {...}}; tolerate an
+    # unwrapped object too.
+    artifact = data.get("artifact", data)
+    if not isinstance(artifact, dict):
+        return None
+    return artifact.get("content_checksum") or None
+
+
+@app.command("get")
+def artifact_get(
+    key: Annotated[str, typer.Argument(help="SPC33 artifact key (e.g. REQ-7).")],
+    project: Annotated[str | None, typer.Option("--project", "-p", help="Project UUID. Falls back to SPECTACKL_PROJECT_ID or project_id in .spectackl/settings.yaml.")] = None,
+    include_content: Annotated[
+        bool,
+        typer.Option("--include-content/--no-include-content", help="Include artifact content text."),
+    ] = False,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="Spectackl API key.", envvar="SPECTACKL_API_KEY")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL.", envvar="SPECTACKL_BASE_URL")] = None,
+    json_output: Annotated[bool, typer.Option("--json/--no-json", help="Output raw JSON (for scripts/agents).")] = False,
+    no_color: Annotated[bool, typer.Option("--no-color", help="Disable color output.")] = False,
+    verbose: Annotated[int, typer.Option("--verbose", "-v", count=True, help="Increase verbosity.")] = 0,
+) -> None:
+    """Get a single artifact by its key.
+
+    Example:
+        spectackl artifact get REQ-7
+        spectackl artifact get REQ-7 --include-content --json
+    """
+    config = load_config(api_key_flag=api_key, base_url_flag=base_url, project_id_flag=project)
+    resolved_key = resolve_api_key(config)
+    project_id = resolve_project_id(config)
+
+    params: dict = {"project_id": project_id}
+    if include_content:
+        params["include_content"] = "true"
+
+    with make_client(resolved_key, config.base_url) as client:
+        try:
+            response = client.get(f"/artifacts/{key}", params=params)
+        except httpx.ConnectError as e:
+            render_error(f"Cannot connect to {config.base_url}: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+        except httpx.TimeoutException as e:
+            render_error(f"Request timed out: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+
+    data = handle_response(response, json_mode=json_output, no_color=no_color)
+    render(data, json_mode=json_output, no_color=no_color)
+
+
+@app.command("list")
+def artifact_list(
+    project: Annotated[str | None, typer.Option("--project", "-p", help="Project UUID. Falls back to SPECTACKL_PROJECT_ID or project_id in .spectackl/settings.yaml.")] = None,
+    kind: Annotated[
+        list[str] | None,
+        typer.Option("--kind", help="Filter by artifact kind (may be repeated)."),
+    ] = None,
+    limit: Annotated[int, typer.Option("--limit", help="Maximum results (1-200, default 50).")] = 50,
+    page_token: Annotated[str | None, typer.Option("--page-token", help="Pagination cursor.")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="Spectackl API key.", envvar="SPECTACKL_API_KEY")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL.", envvar="SPECTACKL_BASE_URL")] = None,
+    json_output: Annotated[bool, typer.Option("--json/--no-json", help="Output raw JSON (for scripts/agents).")] = False,
+    no_color: Annotated[bool, typer.Option("--no-color", help="Disable color output.")] = False,
+    verbose: Annotated[int, typer.Option("--verbose", "-v", count=True, help="Increase verbosity.")] = 0,
+) -> None:
+    """List artifacts in a project.
+
+    Example:
+        spectackl artifact list
+        spectackl artifact list --kind requirement --kind design --json
+    """
+    config = load_config(api_key_flag=api_key, base_url_flag=base_url, project_id_flag=project)
+    resolved_key = resolve_api_key(config)
+    project_id = resolve_project_id(config)
+
+    params: dict = {"project_id": project_id, "limit": str(limit)}
+    if kind:
+        params["kind"] = kind
+    if page_token:
+        params["page_token"] = page_token
+
+    with make_client(resolved_key, config.base_url) as client:
+        try:
+            response = client.get("/artifacts", params=params)
+        except httpx.ConnectError as e:
+            render_error(f"Cannot connect to {config.base_url}: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+        except httpx.TimeoutException as e:
+            render_error(f"Request timed out: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+
+    data = handle_response(response, json_mode=json_output, no_color=no_color)
+    render(data, json_mode=json_output, no_color=no_color)
+
+
+@app.command("create")
+def artifact_create(
+    kind: Annotated[str, typer.Option("--kind", "-k", help="Artifact kind code (required).")],
+    title: Annotated[str, typer.Option("--title", "-t", help="Artifact title (required).")],
+    key: Annotated[str | None, typer.Option("--key", help="Explicit artifact key (e.g. my-note). Auto-derived from title if omitted.")] = None,
+    parent: Annotated[str | None, typer.Option("--parent", help="Parent artifact KEY. Binds parent_id so this artifact nests under the parent as a structural partial in the tree.")] = None,
+    context: Annotated[str | None, typer.Option("--context", help="Scene (work context) KEY. Sets the new artifact's home scene (work_context_id) so the Theatre scene view shows it. Distinct from --parent (tree nesting).")] = None,
+    project: Annotated[str | None, typer.Option("--project", "-p", help="Project UUID. Falls back to SPECTACKL_PROJECT_ID or project_id in .spectackl/settings.yaml.")] = None,
+    content: Annotated[
+        str | None,
+        typer.Option("--content", help="Artifact content. Prefix with @ to read from file (e.g. @content.md)."),
+    ] = None,
+    language: Annotated[str | None, typer.Option("--language", "-l", help="Content language tag (e.g. en, cs). Defaults to default_language from settings.yaml.")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="Spectackl API key.", envvar="SPECTACKL_API_KEY")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL.", envvar="SPECTACKL_BASE_URL")] = None,
+    json_output: Annotated[bool, typer.Option("--json/--no-json", help="Output raw JSON (for scripts/agents).")] = False,
+    no_color: Annotated[bool, typer.Option("--no-color", help="Disable color output.")] = False,
+    verbose: Annotated[int, typer.Option("--verbose", "-v", count=True, help="Increase verbosity.")] = 0,
+) -> None:
+    """Create a new artifact.
+
+    Use --context <scene> to also add the new artifact to a scene in one call (so the
+    scene renders it) — the correct way to create an artifact "under a scene". This is
+    distinct from --parent, which only nests it in the tree via parent_id.
+
+    Example:
+        spectackl artifact create --kind requirement --title "User login via SSO"
+        spectackl artifact create --kind requirement --title "Spec" --content @spec.md
+        spectackl artifact create --kind IDEA --title "Bulk import" --context checkout-flow --json
+    """
+    config = load_config(
+        api_key_flag=api_key, base_url_flag=base_url, project_id_flag=project,
+        language_flag=language,
+    )
+    resolved_key = resolve_api_key(config)
+    project_id = resolve_project_id(config)
+
+    resolved_content = _resolve_at_file(content)
+
+    # Always sent, so the stored row records the language explicitly rather than
+    # inheriting whatever the server happens to default to.
+    body: dict = {
+        "project_id": project_id,
+        "kind": kind,
+        "title": title,
+        "language": config.default_language,
+    }
+    if key:
+        body["key"] = key
+    if parent:
+        body["parent"] = parent
+    if context:
+        body["context"] = context
+    if resolved_content is not None:
+        body["content"] = resolved_content
+
+    with make_client(resolved_key, config.base_url) as client:
+        try:
+            response = client.post("/artifacts", content=json.dumps(body))
+        except httpx.ConnectError as e:
+            render_error(f"Cannot connect to {config.base_url}: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+        except httpx.TimeoutException as e:
+            render_error(f"Request timed out: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+
+    data = handle_response(response, json_mode=json_output, no_color=no_color)
+    render(data, json_mode=json_output, no_color=no_color)
+
+
+@app.command("update")
+def artifact_update(
+    key: Annotated[str, typer.Argument(help="SPC33 artifact key (e.g. REQ-7).")],
+    project: Annotated[str | None, typer.Option("--project", "-p", help="Project UUID. Falls back to SPECTACKL_PROJECT_ID or project_id in .spectackl/settings.yaml.")] = None,
+    title: Annotated[str | None, typer.Option("--title", "-t", help="New artifact title.")] = None,
+    content: Annotated[
+        str | None,
+        typer.Option("--content", help="New content. Prefix with @ to read from file."),
+    ] = None,
+    language: Annotated[str | None, typer.Option("--language", "-l", help="Content language tag (e.g. en, cs). Defaults to default_language from settings.yaml.")] = None,
+
+    force: Annotated[
+        bool,
+        typer.Option("--force/--no-force", help="Upload content even when it is unchanged (skip the checksum comparison)."),
+    ] = False,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="Spectackl API key.", envvar="SPECTACKL_API_KEY")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL.", envvar="SPECTACKL_BASE_URL")] = None,
+    json_output: Annotated[bool, typer.Option("--json/--no-json", help="Output raw JSON (for scripts/agents).")] = False,
+    no_color: Annotated[bool, typer.Option("--no-color", help="Disable color output.")] = False,
+    verbose: Annotated[int, typer.Option("--verbose", "-v", count=True, help="Increase verbosity.")] = 0,
+) -> None:
+    """Update an existing artifact (partial update — only provided fields are changed).
+
+    Unchanged content is skipped automatically: the local content's SHA-256 is
+    compared against the artifact's server-side ``content_checksum`` and, when they
+    match, the content is not re-uploaded (no new version is created). Use --force
+    to upload regardless.
+
+    Example:
+        spectackl artifact update REQ-7 --title "Updated title"
+        spectackl artifact update REQ-7 --content @updated-spec.md
+    """
+    config = load_config(
+        api_key_flag=api_key, base_url_flag=base_url, project_id_flag=project,
+        language_flag=language,
+    )
+    resolved_key = resolve_api_key(config)
+    project_id = resolve_project_id(config)
+
+    resolved_content = _resolve_at_file(content)
+
+    body: dict = {}
+    # Only meaningful alongside new content — an update without content creates no
+    # version for the language to apply to.
+    if resolved_content is not None:
+        body["language"] = config.default_language
+    if title is not None:
+        body["title"] = title
+    if resolved_content is not None:
+        body["content"] = resolved_content
+
+    if not body:
+        typer.echo("Error: At least one of --title or --content must be provided.", err=True)
+        raise typer.Exit(code=exit_codes.USAGE_ERROR)
+
+    params = {"project_id": project_id}
+
+    with make_client(resolved_key, config.base_url) as client:
+        # Skip re-uploading unchanged content: compare a local SHA-256 of the
+        # content against the artifact's server-computed content_checksum. On any
+        # doubt (checksum unavailable, --force) we fall through and upload.
+        if resolved_content is not None and not force:
+            local_sum = content_sha256(resolved_content)
+            current_sum = _fetch_content_checksum(client, key, project_id)
+            if current_sum and current_sum == local_sum:
+                body.pop("content", None)
+                # Language describes the content version, so it goes with it. Left
+                # behind, it would make `body` non-empty and defeat the skip —
+                # turning a no-op re-run into a pointless new version.
+                body.pop("language", None)
+                if verbose:
+                    typer.echo(f"content unchanged (sha256 {local_sum[:12]}…) — skipping content upload", err=True)
+                if not body:
+                    # Nothing left to update — don't touch the artifact at all.
+                    render(
+                        {"key": key, "skipped": True, "reason": "content unchanged"},
+                        json_mode=json_output,
+                        no_color=no_color,
+                    )
+                    return
+
+        try:
+            response = client.patch(f"/artifacts/{key}", content=json.dumps(body), params=params)
+        except httpx.ConnectError as e:
+            render_error(f"Cannot connect to {config.base_url}: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+        except httpx.TimeoutException as e:
+            render_error(f"Request timed out: {e}", json_mode=json_output, no_color=no_color)
+            raise typer.Exit(code=exit_codes.UPSTREAM_UNAVAILABLE)
+
+    data = handle_response(response, json_mode=json_output, no_color=no_color)
+    render(data, json_mode=json_output, no_color=no_color)