spectackl 0.0.1__tar.gz

spectackl-0.0.1/MANIFEST.in

@@ -0,0 +1,27 @@
+# Source-distribution contents.
+#
+# The wheel is controlled by [tool.setuptools.packages.find] in pyproject.toml, but an
+# sdist defaults to sweeping in far more than that — so anything that must not be
+# published has to be excluded here as well.
+
+# The generated OpenAPI client is repo-only: it exists for the CI drift check
+# (scripts/regenerate-client.sh) and nothing in the CLI imports it. Keeping it out of
+# the sdist matches the wheel, so both distributions carry the same code.
+prune src/spectackl_client
+
+# Credentials must never reach a published artifact. .env.local holds real PyPI tokens
+# and is gitignored; the sdist defaults happen not to pick up dotfiles today, and this
+# makes that a rule rather than a coincidence. A token published inside an sdist cannot
+# be recalled — only revoked, after it is already public.
+#
+# These are three exact patterns, deliberately NOT a `.env*` glob: `.env.example` is
+# committed and must keep working. Nothing here matches it — `.env.*.local` requires the
+# `.local` suffix. Add new patterns one at a time for the same reason.
+global-exclude .env .env.local .env.*.local
+
+# Build and tooling noise.
+global-exclude *.pyc
+prune **/__pycache__
+prune .mypy_cache
+prune .pytest_cache
+prune .ruff_cache

spectackl-0.0.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: spectackl
+Version: 0.0.1
+Summary: CLI for the Spectackl Public REST API — for AI agents and operators
+Author-email: Spectackl Engineering <engineering@spectackl.ai>
+License: MIT
+Project-URL: Homepage, https://spectackl.ai
+Project-URL: Documentation, https://docs.spectackl.ai
+Keywords: spectackl,cli,ai,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# spectackl
+
+Command-line interface to the [Spectackl](https://spectackl.ai) Public REST API — built
+for AI agents and operators who need programmatic access to artifacts, scenes and task
+executions without going through the web UI.
+
+```bash
+pip install spectackl
+```
+
+## Quick start
+
+```bash
+spectackl init --api-key spc_… --backend-url https://api.spectackl.ai --project my-project
+spectackl artifact list --json
+```
+
+API keys are managed in the Spectackl Admin Console. `init` writes
+`.spectackl/settings.yaml` in the current directory and a user-global
+`~/.config/spectackl/settings.yaml`; both are created `0600` and neither should be
+committed.
+
+## What it does
+
+| Command | Purpose |
+|---|---|
+| `spectackl search <query>` | Hybrid full-text + semantic search across a project's content |
+| `spectackl artifact` | Get, list, create and update artifacts |
+| `spectackl relation` | Manage the artifact graph (`INCLUDES`, `DOCUMENTS`, `DEPENDS_ON`, …) |
+| `spectackl context` | Inspect scenes (work contexts) and the artifacts they scope |
+| `spectackl task` | Claim, progress and complete task executions |
+| `spectackl assets sync` | Materialize the project's agents and skills into `./.claude/` |
+| `spectackl rsync` | Reconcile artifact content with local files, in both directions |
+| `spectackl daemon` | Run agent sessions on this machine |
+
+Every command accepts `--json` for machine-readable output, and every command returns a
+documented exit code — `0` success, `10` auth required, `20` validation, `30` not found,
+`40` upstream unavailable, and so on — so scripts can branch on failures precisely
+rather than parsing text.
+
+## Designed for agents
+
+Output is stable and parseable, errors are structured, and the exit-code scheme is part
+of the public contract. `spectackl assets sync` writes agent and skill definitions in the
+exact layout Claude Code reads, built from the same artifacts the platform provisions
+into a sandbox — so an agent invoked on a workstation is the one that runs in production.
+
+## Requirements
+
+- Python 3.10+
+- A Spectackl tenant and an API key (`spc_` prefix)
+
+## Documentation
+
+Full guide: **https://docs.spectackl.ai**
+
+## License
+
+MIT

spectackl-0.0.1/README.md

@@ -0,0 +1,59 @@
+# spectackl
+
+Command-line interface to the [Spectackl](https://spectackl.ai) Public REST API — built
+for AI agents and operators who need programmatic access to artifacts, scenes and task
+executions without going through the web UI.
+
+```bash
+pip install spectackl
+```
+
+## Quick start
+
+```bash
+spectackl init --api-key spc_… --backend-url https://api.spectackl.ai --project my-project
+spectackl artifact list --json
+```
+
+API keys are managed in the Spectackl Admin Console. `init` writes
+`.spectackl/settings.yaml` in the current directory and a user-global
+`~/.config/spectackl/settings.yaml`; both are created `0600` and neither should be
+committed.
+
+## What it does
+
+| Command | Purpose |
+|---|---|
+| `spectackl search <query>` | Hybrid full-text + semantic search across a project's content |
+| `spectackl artifact` | Get, list, create and update artifacts |
+| `spectackl relation` | Manage the artifact graph (`INCLUDES`, `DOCUMENTS`, `DEPENDS_ON`, …) |
+| `spectackl context` | Inspect scenes (work contexts) and the artifacts they scope |
+| `spectackl task` | Claim, progress and complete task executions |
+| `spectackl assets sync` | Materialize the project's agents and skills into `./.claude/` |
+| `spectackl rsync` | Reconcile artifact content with local files, in both directions |
+| `spectackl daemon` | Run agent sessions on this machine |
+
+Every command accepts `--json` for machine-readable output, and every command returns a
+documented exit code — `0` success, `10` auth required, `20` validation, `30` not found,
+`40` upstream unavailable, and so on — so scripts can branch on failures precisely
+rather than parsing text.
+
+## Designed for agents
+
+Output is stable and parseable, errors are structured, and the exit-code scheme is part
+of the public contract. `spectackl assets sync` writes agent and skill definitions in the
+exact layout Claude Code reads, built from the same artifacts the platform provisions
+into a sandbox — so an agent invoked on a workstation is the one that runs in production.
+
+## Requirements
+
+- Python 3.10+
+- A Spectackl tenant and an API key (`spc_` prefix)
+
+## Documentation
+
+Full guide: **https://docs.spectackl.ai**
+
+## License
+
+MIT

spectackl-0.0.1/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spectackl"
+# Single-sourced from spectackl.__version__ so the package metadata and the
+# `spectackl --version` output can never disagree. Bump it in src/spectackl/__init__.py.
+dynamic = ["version"]
+description = "CLI for the Spectackl Public REST API — for AI agents and operators"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+  {name = "Spectackl Engineering", email = "engineering@spectackl.ai"},
+]
+keywords = ["spectackl", "cli", "ai", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+# Every entry here is imported by src/spectackl. pydantic used to be listed for the
+# generated OpenAPI client, which is no longer distributed — the CLI itself never
+# imported it, and it is a compiled dependency, so carrying it taxed every install.
+dependencies = [
+  "typer>=0.12",
+  "httpx>=0.27",
+  "rich>=13.0",
+  "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://spectackl.ai"
+Documentation = "https://docs.spectackl.ai"
+
+[project.scripts]
+spectackl = "spectackl.cli:app"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-httpx>=0.30",
+  "mypy>=1.10",
+  "ruff>=0.5",
+  "build>=1.0",
+  "twine>=5.0",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "spectackl.__version__"}
+
+# Ship ONLY the CLI package. `src/spectackl_client/` is a separate, generated
+# OpenAPI client kept in the repo for the CI drift check (scripts/regenerate-client.sh)
+# — nothing in the CLI imports it; every request goes through httpx directly. Shipping
+# it put two unused top-level packages (`spectackl_client`, `spectackl_public_api_client`)
+# into the site-packages of everyone who installs us, one of them twice.
+#
+# The explicit include is what keeps it out: a bare `where = ["src"]` would pick up
+# `spectackl_client` again, and a glob like "spectackl*" would match it too.
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["spectackl", "spectackl.*"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
+ignore = [
+  "E501",
+  # B904: typer.Exit is not a re-raise; it is a flow-control mechanism, not a chained exception
+  "B904",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = false
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = ["-v"]

spectackl-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spectackl-0.0.1/src/spectackl/__init__.py

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

spectackl-0.0.1/src/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-0.0.1/src/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-0.0.1/src/spectackl/commands/__init__.py

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