shotfable 0.1.0a1__py3-none-any.whl

shotfable/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: shotfable
+description: Make short films from one sentence with the ShotFable API through the `shotfable` CLI — quote, create, wait, approve checkpoints (humans only), retake shots, and download the clean video + SRT. Use when a user asks to generate a ShotFable film, check a film's status, recover an interrupted run, or call any ShotFable API operation from a terminal.
+---
+
+# ShotFable CLI (`shotfable`)
+
+`shotfable` is the official client of the ShotFable API: one command per API operation, the same API key,
+the same Idempotency-Key rules. Locate this file with `shotfable skill path`; list every command with
+`shotfable commands` (machine-readable: command → operationId, method, path, args).
+
+## Output contract
+
+- **stdout = exactly one JSON envelope.** Never merge stdout and stderr (`2>&1`).
+  `{"ok": bool, "code": 0 | "<error_type>", "message": str, "request_id": str|null, "data": {...},
+    "error": {"type", "retryable", "user_action_required", "hint"}}` — `error` only when `ok` is false.
+- **stderr = events**, one per line: `[HH:MM:SS] shotfable_event={json}`. Types include
+  `idempotency_key`, `film_created`, `film_status`, `film_event`, `job_status`, `file_ready`, `poll_retry`.
+  Recovery handles (film id, Idempotency-Key, a `recover`/`retry` command) are written **before** the
+  long part starts. If you persist logs, save stderr separately.
+- The envelope is authoritative; stderr events never replace it.
+
+## Exit codes
+
+| exit | code(s) | what to do |
+|---|---|---|
+| 0 | ok | continue |
+| 1 | internal, film_cancelled | keep `request_id`; do not loop |
+| 2 | invalid_request (also usage errors, Idempotency-Key conflict) | fix the request; unknown fields are rejected |
+| 3 | auth_required | ask the user to set a key (see Auth) |
+| 4 | not_found | check the id (`shotfable film list`) |
+| 5 | policy_violation, review_failed | revise the idea/media with the user; not billed |
+| 6 | budget_exceeded, quota_exceeded, region_not_supported | needs the user (top up, wait, region); `shotfable account` |
+| 7 | upstream_unavailable, network_error | retryable — same command, **same Idempotency-Key** |
+| 8 | wait_timeout | only the local wait stopped; run the `hint` command (`shotfable film wait <id>`) |
+| 9 | checkpoint_waiting | **stop**: a human must review and approve |
+| 130 | interrupted | the backend may still run; run the `hint` command |
+
+Rules: `error.retryable=true` → retry/recover the same operation. `error.user_action_required` set →
+stop automatic handling and tell the user exactly that action. Always keep `request_id`.
+
+## Typical flow
+
+```bash
+shotfable account                                  # region + credits before spending
+shotfable film quote --idea "…" --duration 60 --style cinematic-real --quality draft
+shotfable film create --idea "…" --duration 60 --style cinematic-real --quality draft \
+  --wait --timeout 3600 --download ./out           # clean video + SRT (no burned subtitles)
+```
+
+- `film create` without `--wait` returns at once (202) with the film id; follow with `shotfable film wait <id>`.
+- Multiple deliveries: repeat `--aspect` (`--aspect 16:9 --aspect 9:16`).
+- Burned-in subtitles are a billed add-on: only pass `--burn-subtitles` when the user asked for it.
+- Voice: `--voice-source auto|expressive|standard` (product aliases; `expressive` is not offered in `cn`).
+- Full request bodies: `--body req.json` or `--body -`; explicit flags override body fields.
+- Atomic stages (`script|storyboard|review|character|keyframes|shot|music|compose|qa create`,
+  `voice lines`, `lipsync create`) return a job; add `--wait` or use `shotfable job wait <job_id>`.
+- Anything else: `shotfable api <METHOD> <path> [--body file] [--query k=v]`.
+
+## Idempotency and recovery (never create duplicates)
+
+- Every write prints its `Idempotency-Key` to stderr **before** sending. On `network_error`, a 5xx, or
+  an interruption during a write, the result is unknown: rerun **the same command with
+  `--idempotency-key <that key>`** (the `retry` field of the event / the error hint). Same key + same body
+  returns the original response; never retry a write with a fresh key.
+- Exactly one process polls a film. While a `--wait` process is alive, do not start a second
+  `film wait` or `film events` for the same film; do not re-create the film because it is slow.
+- After exit 8 or 130, run the hint (`shotfable film wait <id>`); after a lost process, `shotfable film get <id>`.
+
+## Checkpoints are human decisions
+
+With `--mode checkpoint` the film pauses at `storyboard`, `bible` and `final`; the wait exits 9 with
+`data.checkpoint`. Show the user the artifacts (`shotfable film artifacts <id>`), and only after the
+user's explicit decision run `shotfable film approve <id> <checkpoint> [--comment …] --wait`. Never
+approve on the user's behalf, and never treat "the user said continue earlier" as approval of a later checkpoint.
+
+## Auth and secrets
+
+- Key precedence: `--api-key` > `SHOTFABLE_API_KEY` > stored profile key.
+- Store a key: `printf '%s\n' "$SHOTFABLE_API_KEY" | shotfable auth login` (stdin; avoid `--token` on argv).
+  `shotfable auth status` shows only a masked key (`rs_live_…abcd`), region and balance.
+- Keys live in `${XDG_CONFIG_HOME:-~/.config}/shotfable/credentials.json` (0600). **Never print, echo,
+  log, or paste the API key**, never put it in a file you create, and never send it anywhere but the
+  API base (the CLI refuses to send it to other hosts, including media download hosts).
+
+## Downloads
+
+`shotfable film download <id> --dir D [--aspect 16:9] [--what video,srt,burned,all]` writes
+`<id>_<aspect>.mp4`, `.srt`, `_burned.mp4`, checks every file is non-empty and matches `sha256` when the
+API provides it, and lists absolute paths in `data.files`. Hand the files to the user once.

shotfable/__init__.py

@@ -0,0 +1,7 @@
+"""shotfable — the official command-line client for the ShotFable API (preview).
+
+One command per API operation, the same API key, the same Idempotency-Key semantics.
+Python 3 standard library only.
+"""
+__version__ = "0.1.0a1"
+API_VERSION = "v1"

shotfable/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

shotfable/config.py

@@ -0,0 +1,158 @@
+"""Local state: profiles (config.json) and API keys (credentials.json).
+
+Location: ${XDG_CONFIG_HOME:-~/.config}/shotfable/   directory 0700, credentials.json 0600.
+Key precedence: --api-key  >  SHOTFABLE_API_KEY  >  the profile's entry in credentials.json.
+Base precedence: --api-base > SHOTFABLE_API_BASE > the profile's api_base > DEFAULT_API_BASE.
+"""
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+from .envelope import CliError
+
+DEFAULT_API_BASE = "https://api.shotfable.com/v1"  # matches openapi servers[0]; production API not serving yet
+DEFAULT_PROFILE = "default"
+KEY_RE = re.compile(r"^rs_(live|test)_[A-Za-z0-9]{8,128}$")
+PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return Path(base) / "shotfable"
+
+
+def mask_key(key):
+    """rs_live_…abcd — never more than the prefix and the last four characters."""
+    if not key:
+        return None
+    m = re.match(r"^(rs_(?:live|test)_)", key)
+    prefix = m.group(1) if m else ""
+    tail = key[-4:] if len(key) >= len(prefix) + 8 else ""
+    return f"{prefix}…{tail}"
+
+
+def _read_json(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        raise CliError("internal", f"cannot read {path.name} in the shotfable config directory (corrupt JSON?)",
+                       hint=f"Inspect or remove {path}")
+
+
+def _write_json_private(path: Path, data):
+    d = path.parent
+    d.mkdir(parents=True, exist_ok=True)
+    os.chmod(d, 0o700)
+    fd, tmp = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(d))
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2, sort_keys=True)
+            fh.write("\n")
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+    os.chmod(path, 0o600)
+
+
+class Store:
+    def __init__(self, root: Path = None):
+        self.root = root or config_dir()
+        self.config_path = self.root / "config.json"
+        self.cred_path = self.root / "credentials.json"
+
+    # ---------------------------------------------------------------- config
+    def config(self):
+        c = _read_json(self.config_path)
+        c.setdefault("current_profile", DEFAULT_PROFILE)
+        c.setdefault("profiles", {})
+        return c
+
+    def save_config(self, c):
+        _write_json_private(self.config_path, c)
+
+    def current_profile(self, override=None):
+        name = override or os.environ.get("SHOTFABLE_PROFILE") or self.config().get("current_profile") or DEFAULT_PROFILE
+        if not PROFILE_RE.match(name):
+            raise CliError("invalid_request", f"invalid profile name {name!r}",
+                           hint="Profile names: letters, digits, '.', '_' or '-' (max 64).")
+        return name
+
+    def profile_settings(self, name):
+        return dict(self.config()["profiles"].get(name, {}))
+
+    def set_profile(self, name, api_base=None):
+        c = self.config()
+        p = c["profiles"].setdefault(name, {})
+        if api_base:
+            p["api_base"] = api_base
+        self.save_config(c)
+
+    def use_profile(self, name):
+        c = self.config()
+        c["current_profile"] = name
+        c["profiles"].setdefault(name, {})
+        self.save_config(c)
+
+    def remove_profile(self, name):
+        c = self.config()
+        existed = c["profiles"].pop(name, None) is not None
+        if c.get("current_profile") == name:
+            c["current_profile"] = DEFAULT_PROFILE
+        self.save_config(c)
+        removed_key = self.delete_key(name)
+        return existed or removed_key
+
+    # ---------------------------------------------------------------- credentials
+    def stored_key(self, profile):
+        if not self.cred_path.exists():
+            return None
+        return (_read_json(self.cred_path).get("profiles", {}).get(profile) or {}).get("api_key")
+
+    def save_key(self, profile, key):
+        creds = _read_json(self.cred_path) if self.cred_path.exists() else {}
+        creds.setdefault("profiles", {})[profile] = {"api_key": key}
+        _write_json_private(self.cred_path, creds)
+
+    def delete_key(self, profile):
+        if not self.cred_path.exists():
+            return False
+        creds = _read_json(self.cred_path)
+        existed = creds.get("profiles", {}).pop(profile, None) is not None
+        _write_json_private(self.cred_path, creds)
+        return existed
+
+
+def resolve_api_base(store: Store, profile, flag=None):
+    base = flag or os.environ.get("SHOTFABLE_API_BASE") or store.profile_settings(profile).get("api_base") or DEFAULT_API_BASE
+    base = base.rstrip("/")
+    if not re.match(r"^https?://[^\s/]+", base):
+        raise CliError("invalid_request", "api base must be an http(s) URL", hint="e.g. --api-base https://api.shotfable.com/v1")
+    return base
+
+
+def resolve_api_key(store: Store, profile, flag=None):
+    """Returns (key, source) — source is 'flag' | 'env' | 'profile' | None."""
+    if flag:
+        return flag, "flag"
+    env = os.environ.get("SHOTFABLE_API_KEY")
+    if env:
+        return env.strip(), "env"
+    k = store.stored_key(profile)
+    if k:
+        return k, "profile"
+    return None, None
+
+
+def validate_key_shape(key):
+    if not KEY_RE.match(key or ""):
+        raise CliError("invalid_request", "that does not look like a ShotFable API key (expected rs_live_… or rs_test_…)",
+                       hint="Paste the key exactly as issued; it is never printed back.")

shotfable/envelope.py

@@ -0,0 +1,169 @@
+"""Output contract: exactly one JSON envelope on stdout; events and recovery handles on stderr.
+
+Envelope:
+  {"ok": bool, "code": 0 | "<error_type>", "message": str, "request_id": str | null,
+   "data": {...}, "error": {"type", "retryable", "user_action_required", "hint"}}   # error only on failure
+Event (stderr, one line):  [HH:MM:SS] shotfable_event={json}
+"""
+import json
+import sys
+import time
+
+# Stable, documented exit codes. Never renumber; only append.
+EXIT_CODES = {
+    "ok": 0,
+    "internal": 1,
+    "film_cancelled": 1,
+    "invalid_request": 2,
+    "auth_required": 3,
+    "not_found": 4,
+    "policy_violation": 5,
+    "review_failed": 5,
+    "budget_exceeded": 6,
+    "quota_exceeded": 6,
+    "region_not_supported": 6,
+    "upstream_unavailable": 7,
+    "network_error": 7,
+    "wait_timeout": 8,
+    "checkpoint_waiting": 9,
+    "interrupted": 130,
+}
+
+# The eight server error types (PRODUCT_SPEC §7.1) + the CLI-local ones.
+SERVER_ERROR_TYPES = ("invalid_request", "policy_violation", "review_failed", "budget_exceeded",
+                      "quota_exceeded", "region_not_supported", "upstream_unavailable", "internal")
+LOCAL_ERROR_TYPES = ("auth_required", "not_found", "network_error", "wait_timeout",
+                     "checkpoint_waiting", "interrupted", "film_cancelled")
+
+RETRYABLE = {"quota_exceeded", "upstream_unavailable", "network_error", "wait_timeout", "interrupted"}
+
+USER_ACTION = {
+    "auth_required": "provide_api_key",
+    "policy_violation": "revise_input",
+    "review_failed": "revise_input",
+    "budget_exceeded": "top_up_credits",
+    "region_not_supported": "change_request_for_region",
+    "checkpoint_waiting": "approve_checkpoint",
+}
+
+DEFAULT_HINTS = {
+    "internal": "Unexpected error. Keep the request_id for support.",
+    "invalid_request": "Fix the request (see message); the server runs in strict mode and rejects unknown fields.",
+    "auth_required": "Set an API key: `shotfable auth login` (reads the key from stdin), SHOTFABLE_API_KEY, or --api-key.",
+    "not_found": "No such resource for this account. List films with `shotfable film list`.",
+    "policy_violation": "The input was refused by content policy and was not billed. Change the idea or media and try again.",
+    "review_failed": "The script/storyboard did not pass review. Revise the input and create again.",
+    "budget_exceeded": "Not enough credits or over budget_cap. Check `shotfable account`, then top up or raise --budget-cap.",
+    "quota_exceeded": "Rate or concurrency limit reached. Wait (Retry-After) and retry the same command.",
+    "region_not_supported": "Your account region cannot serve this request. Check `shotfable account` for your region.",
+    "upstream_unavailable": "Generation is temporarily unavailable; nothing was billed. Retry later with the same Idempotency-Key.",
+    "network_error": "Network problem. Reads can simply be retried; for writes the result is unknown — retry with the same Idempotency-Key, never a new one.",
+    "wait_timeout": "Only the local wait stopped; the film keeps running. Resume waiting with `shotfable film wait <id>`.",
+    "checkpoint_waiting": "A human must review and approve the checkpoint before the film continues.",
+    "interrupted": "Interrupted locally; the backend may still be running. Recover with the hint command.",
+    "film_cancelled": "The film was cancelled. Create a new film if you still need it.",
+}
+
+
+def exit_code_for(code):
+    if code == 0:
+        return 0
+    return EXIT_CODES.get(code, 1)
+
+
+class CliError(Exception):
+    """Any failure that should become an error envelope."""
+
+    def __init__(self, code, message, *, hint=None, retryable=None, user_action_required=None,
+                 request_id=None, data=None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint or DEFAULT_HINTS.get(code, DEFAULT_HINTS["internal"])
+        self.retryable = (code in RETRYABLE) if retryable is None else retryable
+        self.user_action_required = (user_action_required if user_action_required is not None
+                                     else USER_ACTION.get(code))
+        self.request_id = request_id
+        self.data = data or {}
+
+
+def success(data, message="ok", request_id=None):
+    return {"ok": True, "code": 0, "message": message, "request_id": request_id, "data": data}
+
+
+def failure(err: CliError):
+    return {
+        "ok": False,
+        "code": err.code,
+        "message": err.message,
+        "request_id": err.request_id,
+        "data": err.data,
+        "error": {
+            "type": err.code,
+            "retryable": bool(err.retryable),
+            "user_action_required": err.user_action_required,
+            "hint": err.hint,
+        },
+    }
+
+
+class Output:
+    """Owns stdout (one envelope) and stderr (events). Redacts known secrets from everything it writes."""
+
+    def __init__(self, stdout=None, stderr=None):
+        self.stdout = stdout or sys.stdout
+        self.stderr = stderr or sys.stderr
+        self.pretty = False
+        self._secrets = []
+        self._emitted = False
+
+    def add_secret(self, value):
+        if value and value not in self._secrets:
+            self._secrets.append(value)
+
+    def redact(self, text):
+        for s in self._secrets:
+            if s and s in text:
+                text = text.replace(s, "[redacted]")
+        return text
+
+    def event(self, kind, **fields):
+        payload = {"type": kind, **fields}
+        line = (f"[{time.strftime('%H:%M:%S')}] shotfable_event="
+                + json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
+        self._err(line)
+
+    def note(self, text):
+        """Free-text stderr line for humans (warnings). Never parsed."""
+        self._err(f"[{time.strftime('%H:%M:%S')}] {text}")
+
+    def _err(self, line):
+        try:
+            self.stderr.write(self.redact(line) + "\n")
+            self.stderr.flush()
+        except (BrokenPipeError, ValueError):
+            pass
+
+    @property
+    def emitted(self):
+        return self._emitted
+
+    def envelope(self, env):
+        if self._emitted:  # the contract: exactly one envelope per invocation
+            return
+        self._emitted = True
+        text = json.dumps(env, ensure_ascii=False, indent=2 if self.pretty else None)
+        self._out(text)
+
+    def text(self, body):
+        if self._emitted:
+            return
+        self._emitted = True
+        self._out(body.rstrip("\n"))
+
+    def _out(self, text):
+        try:
+            self.stdout.write(self.redact(text) + "\n")
+            self.stdout.flush()
+        except BrokenPipeError:
+            pass