rote-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{rote_cli-0.1.0 → rote_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rote-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Graduate fuzzy AI skills into deterministic, reliable workflows
 Project-URL: Homepage, https://github.com/trevhud/rote
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -242,9 +242,43 @@ agent-driven — so the same IR always produces byte-identical output.
 
 ## Quickstart
 
-### Install
+### Use from Claude Code (recommended)
 
-`rote` is not on PyPI yet. Clone and install in editable mode:
+`rote` ships as a Claude Code plugin, so you can graduate a skill
+without leaving Claude or touching Python tooling:
+
+```
+/plugin marketplace add trevhud/rote
+/plugin install rote@rote
+```
+
+Then say "graduate this skill" (or run `/rote:graduate` directly).
+The plugin confirms the source skill directory, asks which runtime you
+want (Temporal, Cloudflare Workflows, or DBOS), runs the CLI via
+[uv](https://docs.astral.sh/uv/) in the background, and reports the
+emitted pipeline. A second skill, `/rote:serve`, wires graduated
+pipelines up as MCP tools so Claude can trigger the deployed workflows.
+
+Prefer a terminal? The same thing is one `uvx` command:
+
+```sh
+uvx --from rote-cli rote graduate ./my-skill --runtime dbos --out ./graduated
+
+# or straight from GitHub for unreleased changes:
+uvx --from git+https://github.com/trevhud/rote rote graduate \
+  ./my-skill --runtime dbos --out ./graduated
+```
+
+> **Naming note:** the `rote` package on PyPI is an unrelated
+> memoization library that also installs `import rote`, so the two
+> can't share an environment. This project's distribution is
+> `rote-cli` while the CLI command and import name stay `rote` —
+> hence `uvx --from rote-cli rote ...`. See
+> [docs/releasing.md](docs/releasing.md).
+
+### Install from source (development)
+
+Clone and install in editable mode:
 
 ```sh
 git clone https://github.com/trevhud/rote.git

{rote_cli-0.1.0 → rote_cli-0.3.0}/README.md

@@ -196,9 +196,43 @@ agent-driven — so the same IR always produces byte-identical output.
 
 ## Quickstart
 
-### Install
+### Use from Claude Code (recommended)
 
-`rote` is not on PyPI yet. Clone and install in editable mode:
+`rote` ships as a Claude Code plugin, so you can graduate a skill
+without leaving Claude or touching Python tooling:
+
+```
+/plugin marketplace add trevhud/rote
+/plugin install rote@rote
+```
+
+Then say "graduate this skill" (or run `/rote:graduate` directly).
+The plugin confirms the source skill directory, asks which runtime you
+want (Temporal, Cloudflare Workflows, or DBOS), runs the CLI via
+[uv](https://docs.astral.sh/uv/) in the background, and reports the
+emitted pipeline. A second skill, `/rote:serve`, wires graduated
+pipelines up as MCP tools so Claude can trigger the deployed workflows.
+
+Prefer a terminal? The same thing is one `uvx` command:
+
+```sh
+uvx --from rote-cli rote graduate ./my-skill --runtime dbos --out ./graduated
+
+# or straight from GitHub for unreleased changes:
+uvx --from git+https://github.com/trevhud/rote rote graduate \
+  ./my-skill --runtime dbos --out ./graduated
+```
+
+> **Naming note:** the `rote` package on PyPI is an unrelated
+> memoization library that also installs `import rote`, so the two
+> can't share an environment. This project's distribution is
+> `rote-cli` while the CLI command and import name stay `rote` —
+> hence `uvx --from rote-cli rote ...`. See
+> [docs/releasing.md](docs/releasing.md).
+
+### Install from source (development)
+
+Clone and install in editable mode:
 
 ```sh
 git clone https://github.com/trevhud/rote.git

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/__init__.py

@@ -1,3 +1,3 @@
 """rote — graduate fuzzy AI skills into deterministic workflows."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/adapters/_common.py

@@ -42,7 +42,10 @@ def _pipeline_hash(pipeline: Pipeline) -> str:
     name) so a regenerated pipeline becomes a new type. Old in-flight
     workflows continue on the old code; new workflows use the new code.
     """
-    payload = f"{pipeline.name}|{pipeline.version}|{len(pipeline.nodes)}|{len(pipeline.edges)}"
+    # Hash the full validated contents: node wiring, inputs, retries, and
+    # edges all participate, so any regeneration that changes behavior gets
+    # a new workflow type — name/version/counts alone miss rewires.
+    payload = pipeline.model_dump_json(by_alias=True, exclude_none=True)
     return hashlib.sha256(payload.encode()).hexdigest()[:8]
 
 

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/adapters/cloudflare.py

@@ -551,7 +551,15 @@ function interpolate(template: string, vars: Record<string, unknown>): string {
                     : undefined,
             vars,
         );
-        if (value === undefined) return "";
+        if (value === undefined) {
+            // A hole in a judge prompt produces confident garbage that is
+            // far harder to debug than an error naming the missing field.
+            throw new Error(
+                `prompt template references {{ ${key} }} but the input has no ` +
+                    `such field; available top-level keys: ${Object.keys(vars).sort().join(", ")}`,
+            );
+        }
+        if (value === null) return "";
         return typeof value === "string" ? value : JSON.stringify(value);
     });
 }
@@ -902,6 +910,168 @@ def emit_tsconfig() -> str:
     return json.dumps(obj, indent=2) + "\n"
 
 
+# ───────── README.md + .dev.vars.example emission ─────────
+
+# "Deploy to Cloudflare" button spec, per
+# https://developers.cloudflare.com/workers/platform/deploy-buttons/:
+# a markdown image link whose target is the deploy service with the
+# public GitHub/GitLab repo URL passed via the ``url`` query parameter.
+# The repo URL is unknowable at emission time, so the emitted README
+# carries an explicit placeholder for the user to substitute.
+_DEPLOY_BUTTON_IMAGE = "https://deploy.workers.cloudflare.com/button"
+_DEPLOY_BUTTON_BASE = "https://deploy.workers.cloudflare.com/?url="
+_REPO_URL_PLACEHOLDER = "REPLACE-WITH-YOUR-REPO-URL"
+
+
+def _llm_clients(pipeline: Pipeline) -> set[str]:
+    """Vendor clients used by the pipeline's llm_judge signature specs."""
+    return {
+        node.signature_spec.client
+        for node in pipeline.nodes
+        if node.kind is NodeKind.LLM_JUDGE and node.signature_spec is not None
+    }
+
+
+def _secret_names(pipeline: Pipeline) -> list[str]:
+    """Secrets the emitted worker reads, in emission order.
+
+    ``ANTHROPIC_API_KEY`` is always present (the emitted ``Env``
+    interface requires it); ``OPENAI_API_KEY`` joins when any signature
+    targets the OpenAI client.
+    """
+    secrets = ["ANTHROPIC_API_KEY"]
+    if "openai" in _llm_clients(pipeline):
+        secrets.append("OPENAI_API_KEY")
+    return secrets
+
+
+def emit_dev_vars_example(pipeline: Pipeline) -> str:
+    """Emit ``.dev.vars.example`` — dotenv-format secret declarations.
+
+    The Deploy to Cloudflare flow reads this file to know which secrets
+    to prompt for during one-click setup (per the deploy-buttons docs);
+    ``wrangler dev`` users copy it to ``.dev.vars`` for local runs.
+    """
+    lines = [
+        "# Copy to .dev.vars for local `wrangler dev`; the Deploy to Cloudflare",
+        "# flow reads this file to prompt for secrets during one-click setup.",
+        "# For a manual deploy, set each with `npx wrangler secret put <NAME>`.",
+    ]
+    lines.extend(f"{name}=" for name in _secret_names(pipeline))
+    return "\n".join(lines) + "\n"
+
+
+def emit_readme(pipeline: Pipeline, cfg: CloudflareAdapterConfig) -> str:
+    deploy_url = f"{_DEPLOY_BUTTON_BASE}{_REPO_URL_PLACEHOLDER}"
+    button = f"[![Deploy to Cloudflare]({_DEPLOY_BUTTON_IMAGE})]({deploy_url})"
+
+    description = pipeline.description.strip()
+    description_block = f"\n{description}\n" if description else ""
+
+    secrets = _secret_names(pipeline)
+    secret_puts = "\n".join(f"npx wrangler secret put {name}" for name in secrets)
+
+    gates = [n for n in pipeline.nodes if n.kind is NodeKind.HITL_GATE]
+    first_signal = gates[0].signal if gates and gates[0].signal else "example_signal"
+    gate_lines = "\n".join(
+        f"| `{g.id}` | `{g.signal}` | {_ir_duration_to_cf(g.timeout or cfg.default_hitl_timeout)} |"
+        for g in gates
+    )
+
+    # Built flush-left (not textwrap.dedent) because interpolated
+    # multi-line values — the pipeline description, gate table rows —
+    # contain unindented lines that would defeat dedent's common-prefix
+    # detection.
+    return f"""\
+# {pipeline.name} — Cloudflare Workflows runtime
+
+Auto-generated by `rote emit --runtime cloudflare`. Do not edit
+generated files by hand; re-run the emitter to regenerate.
+{description_block}
+## Deploy to Cloudflare
+
+{button}
+
+Push this directory to a **public GitHub or GitLab repository**,
+then replace `{_REPO_URL_PLACEHOLDER}` in the button link above with
+the repo URL (a subdirectory path works too). One click clones the
+repo into the visitor's account, provisions the workflow, and
+prompts for the secrets declared in `.dev.vars.example`.
+
+## Layout
+
+- `src/workflow.ts` — the `WorkflowEntrypoint` class: one `step.do`
+  per node, `step.waitForEvent` per HITL gate
+- `src/index.ts` — fetch handler that creates a workflow instance
+  from the POST body
+- `src/extracted/` — stubs for deterministic nodes; fill these in
+  with direct vendor API calls (they throw until you do)
+- `src/signatures/` — typed LLM judges generated from the pipeline
+  IR (Zod schemas + direct vendor SDK calls)
+- `wrangler.jsonc` / `package.json` / `tsconfig.json` — deploy-ready
+  Workers project config
+
+## Deploy from this machine
+
+```sh
+npm install
+{secret_puts}
+npx wrangler deploy
+```
+
+## Trigger a run
+
+POST the pipeline input to the deployed worker; it responds with
+the new instance's id and status:
+
+```sh
+curl -X POST https://{pipeline.name}.<your-subdomain>.workers.dev \\
+    -H 'content-type: application/json' \\
+    -d '{{"your": "input"}}'
+```
+
+Or trigger directly through wrangler:
+
+```sh
+npx wrangler workflows trigger {pipeline.name} '{{"your": "input"}}'
+```
+
+## HITL gates
+
+The workflow parks durably at each gate until an event of the
+gate's type arrives:
+
+| Gate | Event type | Timeout |
+| --- | --- | --- |
+{gate_lines}
+
+Resume a parked instance by sending the event (`latest` targets the
+most recent instance):
+
+```sh
+npx wrangler workflows instances send-event {pipeline.name} latest \\
+    --type {first_signal} --payload '{{"approved": true}}'
+```
+
+A gate that times out fails the run — silence is not approval.
+
+## Trigger from Claude (MCP)
+
+`rote` can expose this deployed pipeline as an MCP tool so any MCP
+client triggers the deterministic workflow instead of re-running
+the fuzzy skill:
+
+```sh
+rote register <graduated-output-dir> \\
+    --runtime cloudflare \\
+    --url https://{pipeline.name}.<your-subdomain>.workers.dev
+rote serve
+```
+
+See `docs/mcp-trigger.md` in the rote repository for the full flow.
+"""
+
+
 # ───────── Adapter facade ─────────
 
 
@@ -911,6 +1081,8 @@ class CloudflareAdapter:
     Output layout::
 
         out/
+            README.md
+            .dev.vars.example
             wrangler.jsonc
             package.json
             tsconfig.json
@@ -975,4 +1147,12 @@ class CloudflareAdapter:
         ts_path.write_text(emit_tsconfig(), encoding="utf-8")
         written["tsconfig.json"] = ts_path
 
+        readme_path = out / "README.md"
+        readme_path.write_text(emit_readme(pipeline, self.config), encoding="utf-8")
+        written["README"] = readme_path
+
+        dev_vars_path = out / ".dev.vars.example"
+        dev_vars_path.write_text(emit_dev_vars_example(pipeline), encoding="utf-8")
+        written[".dev.vars.example"] = dev_vars_path
+
         return written

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/adapters/dbos.py

@@ -523,12 +523,24 @@ def emit_signature_module(node: Node, cfg: DbosAdapterConfig) -> str:
     interpolate_block = textwrap.dedent(
         '''\
         def _interpolate(template: str, variables: dict[str, Any]) -> str:
-            """Resolve ``{{ dotted.path }}`` placeholders against the input dict."""
+            """Resolve ``{{ dotted.path }}`` placeholders against the input dict.
+
+            An unresolvable placeholder raises instead of interpolating "" —
+            a hole in a judge prompt produces confident garbage that is far
+            harder to debug than a KeyError naming the missing variable.
+            """
 
             def _resolve(match: re.Match[str]) -> str:
+                path = match.group(1)
                 value: Any = variables
-                for part in match.group(1).split("."):
-                    value = value.get(part) if isinstance(value, dict) else None
+                for part in path.split("."):
+                    if not isinstance(value, dict) or part not in value:
+                        raise KeyError(
+                            f"prompt template references {{{{ {path} }}}} but the "
+                            f"input has no such field; available top-level keys: "
+                            f"{sorted(variables)}"
+                        )
+                    value = value[part]
                 if value is None:
                     return ""
                 return value if isinstance(value, str) else json.dumps(value, default=str)
@@ -1087,9 +1099,12 @@ def emit_readme(pipeline: Pipeline, cfg: DbosAdapterConfig) -> str:
         for g in gates
     )
     first_signal = gates[0].signal if gates else "example_signal"
-    return textwrap.dedent(
-        f"""\
-        # {pipeline.name} — DBOS runtime
+    # Dedent BEFORE interpolating: a multi-line gate_lines value would put
+    # column-0 lines inside the template, making dedent a no-op and shipping
+    # the whole README indented (Markdown renders that as one code block).
+    template = textwrap.dedent(
+        """\
+        # {pipeline_name} — DBOS runtime
 
         Auto-generated by `rote emit --runtime dbos`. Do not edit generated
         files by hand; re-run the emitter to regenerate.
@@ -1150,6 +1165,11 @@ def emit_readme(pipeline: Pipeline, cfg: DbosAdapterConfig) -> str:
         run — silence is not approval.
         """
     )
+    return template.format(
+        pipeline_name=pipeline.name,
+        gate_lines=gate_lines,
+        first_signal=first_signal,
+    )
 
 
 # ───────── Adapter facade ─────────

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/cli.py

@@ -212,7 +212,15 @@ def _cmd_register(args: argparse.Namespace) -> int:
         return 1
 
     registry_path = Path(args.registry) if args.registry else default_registry_path()
-    registry = Registry.load(registry_path)
+    try:
+        registry = Registry.load(registry_path)
+    except Exception as e:
+        print(
+            f"error: failed to load registry {registry_path}: {e}\n"
+            f"Fix or delete the file and re-run.",
+            file=sys.stderr,
+        )
+        return 1
     replaced = registry.upsert(entry)
     registry.save(registry_path)
 

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/serve/backends.py

@@ -85,12 +85,18 @@ async def _start_temporal(
 ) -> dict[str, Any]:
     client = await _temporal_client(trigger)
     workflow_id = f"{tool_name}-{uuid.uuid4().hex[:12]}"
-    handle = await client.start_workflow(
-        trigger.workflow_name,
-        payload,
-        id=workflow_id,
-        task_queue=trigger.task_queue,
-    )
+    try:
+        handle = await client.start_workflow(
+            trigger.workflow_name,
+            payload,
+            id=workflow_id,
+            task_queue=trigger.task_queue,
+        )
+    except Exception as e:
+        raise BackendError(
+            f"Temporal at {trigger.address} refused to start workflow "
+            f"{trigger.workflow_name!r} on task queue {trigger.task_queue!r}: {e}"
+        ) from e
     return {
         "workflow_id": workflow_id,
         "run_id": handle.first_execution_run_id or "",
@@ -102,7 +108,12 @@ async def _start_temporal(
 async def _status_temporal(trigger: TemporalTrigger, workflow_id: str) -> dict[str, Any]:
     client = await _temporal_client(trigger)
     handle = client.get_workflow_handle(workflow_id)
-    description = await handle.describe()
+    try:
+        description = await handle.describe()
+    except Exception as e:
+        raise BackendError(
+            f"Temporal at {trigger.address} could not describe workflow {workflow_id!r}: {e}"
+        ) from e
     status = description.status.name.lower() if description.status else "unknown"
     return {
         "workflow_id": workflow_id,
@@ -124,10 +135,24 @@ async def _start_cloudflare(trigger: CloudflareTrigger, payload: dict[str, Any])
             data = resp.json()
     except httpx.HTTPError as e:
         raise BackendError(f"Cloudflare worker at {trigger.url} failed: {e}") from e
+    except ValueError as e:
+        raise BackendError(
+            f"Cloudflare worker at {trigger.url} returned a non-JSON response "
+            f"(HTTP {resp.status_code}): {resp.text[:200]!r}"
+        ) from e
 
-    # The emitted src/index.ts responds with {id, status}.
+    # The emitted src/index.ts responds with {id, status}. A 2xx JSON body
+    # without an id means the URL is not the emitted worker (an auth proxy,
+    # a different service) — nothing started, so say so instead of
+    # fabricating success with an empty workflow_id.
+    if not isinstance(data, dict) or not data.get("id"):
+        raise BackendError(
+            f"Cloudflare worker at {trigger.url} did not return a workflow id. "
+            f"Expected the emitted worker's {{id, status}} response, got: "
+            f"{str(data)[:200]}"
+        )
     return {
-        "workflow_id": str(data.get("id", "")),
+        "workflow_id": str(data["id"]),
         "status": "started",
         "runtime": "cloudflare",
         "details": data.get("status"),

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/serve/registry.py

@@ -153,13 +153,11 @@ class Registry(BaseModel):
 def input_schema_for(pipeline_input: PipelineInput) -> dict[str, Any]:
     """Derive the MCP tool's inputSchema from the pipeline's input contract.
 
-    Prefers a structured ``input_schema`` field if the loaded model carries
-    one (being added to :class:`rote.ir.PipelineInput` concurrently — coded
-    defensively via ``getattr`` so this works before and after that lands).
-    Otherwise synthesizes a permissive object schema from the required /
+    Prefers the structured ``input_schema`` field when the pipeline carries
+    one. Otherwise synthesizes a permissive object schema from the required /
     optional name lists, which are untyped in the current IR.
     """
-    explicit = getattr(pipeline_input, "input_schema", None)
+    explicit = pipeline_input.input_schema
     if isinstance(explicit, dict) and explicit:
         return dict(explicit)
 
@@ -191,7 +189,13 @@ def entry_from_pipeline(
     characters replaced by ``-``; description comes from
     ``pipeline.description`` (first paragraph, whitespace-normalized).
     """
-    tool_name = name if name is not None else re.sub(r"[^A-Za-z0-9_-]+", "-", pipeline.name)
+    tool_name = (
+        name
+        if name is not None
+        # Strip leading separators the substitution can leave behind — tool
+        # names must start alphanumeric or RegistryEntry validation raises.
+        else re.sub(r"[^A-Za-z0-9_-]+", "-", pipeline.name).lstrip("-_") or "pipeline"
+    )
     return RegistryEntry(
         name=tool_name,
         description=pipeline.description.strip(),

{rote_cli-0.1.0 → rote_cli-0.3.0}/src/rote/serve/server.py

@@ -162,12 +162,22 @@ class RegistryProvider(Provider):
             return None
 
     def _load_if_changed(self) -> bool:
-        """Reload the registry if the file content changed. Returns True on change."""
+        """Reload the registry if the file content changed. Returns True on change.
+
+        The digest is committed only after a successful parse: a corrupt
+        file (hand-edit typo, non-atomic write by another tool) must not
+        be recorded as "seen", or the server would silently serve the
+        previous tool list forever. Leaving the digest uncommitted means
+        every subsequent poll retries, so fixing the file recovers the
+        server without a restart. `Registry.save` itself is atomic
+        (tmp + rename), so `rote register` can never produce a torn read.
+        """
         digest = self._current_digest()
         if digest == self._digest:
             return False
+        registry = Registry.load(self.registry_path)
         self._digest = digest
-        self._registry = Registry.load(self.registry_path)
+        self._registry = registry
         return True
 
     # ── Provider hooks ──
@@ -187,13 +197,28 @@ class RegistryProvider(Provider):
             yield
         finally:
             watcher.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await watcher
 
     # ── change notification ──
 
     async def _watch_registry(self) -> None:
         while True:
             await asyncio.sleep(self.poll_interval)
-            if self._load_if_changed():
+            try:
+                changed = self._load_if_changed()
+            except Exception:
+                # A corrupt registry or transient filesystem error must not
+                # kill the watcher task — that would silently end
+                # list_changed notifications for the rest of the server's
+                # life. The digest was not committed, so the next poll
+                # retries and a fixed file recovers automatically.
+                logger.warning(
+                    "registry reload failed; still serving the previous tool list",
+                    exc_info=True,
+                )
+                continue
+            if changed:
                 await self._notify_tool_list_changed()
 
     async def _notify_tool_list_changed(self) -> None: