# Rote Typescript Transformations > Author or debug TypeScript transformations for cached rote responses and TypeScript plays. Use for `FlowOutput` shape, deterministic response handling, `rote deno` execution, and tests before returning to play authoring or workspace work. - Skill: `modiqo/rote-typescript-transformations` (Agent Skill) - Install (CLI): `npx skillmds@latest add modiqo/rote-typescript-transformations` - Raw SKILL.md: https://api.skillmd.com/api/skills/modiqo/rote-typescript-transformations/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: modiqo (https://skillmd.com/u/modiqo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/modiqo/rote-typescript-transformations --- # rote-typescript-transformations All `rote-` references in this document — including every name in the Handoff Contract — are companion **skills**, never CLI commands (`rote-shell` is not `rote shell`). Invoke them through the runtime's skill mechanism; only literal `rote …` commands run in a terminal. Use this skill when cached rote responses need TypeScript transformation or a TypeScript play body is being authored. `rote grammar deno` and `rote guidance typescript essential` remain the source of truth for execution syntax and SDK import forms. This is a helper skill, not a lifecycle owner. Return to the invoking owner after the transformation is implemented and tested: `rote-flow-authoring` when authoring invoked it, `rote-workspace` when workspace invoked it. Do not stop here when release, index/search verification, pending cleanup, or final presentation is still outstanding, and do not hand authoring-owned state back to a substrate skill. ## Browser Boundary If the TypeScript body navigates, snapshots, finds, clicks, types, screenshots, restores browser auth, or controls browser replay, this skill does not own that SDK surface. Run: ```bash rote guidance browser play-authoring ``` Then return to `rote-flow-authoring`. Do not search the installed SDK barrel to discover the common browser API before checking this version-matched runtime guide. ## Execution Rules - Run legacy TypeScript plays, with no frontmatter `steps:` block, through `rote deno run --allow-all`. - Run TypeScript plays with frontmatter `steps:` through `rote play run`. Raw `deno` skips the effect plane and provides no presentation input; `rote deno run` reroutes `steps:` plays to the play runner, but do not rely on the reroute — use `rote play run` directly. - Run play files from outside the active workspace. - Do not call system `deno` directly. - Do not prefix the binary with `~/.rote/bin/`; use `rote` on `PATH`. Typical execution: ```bash rote deno run --allow-all /absolute/path/to/main.ts [args] ``` Use SDK imports exactly as shown by live rote guidance. Avoid npm-style package assumptions unless the current rote version explicitly supports them. For `steps_with_presentation`, do not import `sdk/ts/mod.ts` or construct `Rote`. Import `__ROTE_PRESENTATION_SDK__`, then use `loadPresentationContext()`, literal `stepName("...")` references, `isProcessExecBody`, `isBrowserBody`, and `FlowOutput`. The context's `ctx.params` (`Readonly>`, declared defaults applied) carries the play's invocation parameters — read plain inputs there instead of echoing them through a step's stdout or touching `Deno.args`. Template/export also creates or merges the sibling `deno.json` import mapping for editor type-checking. The `main.ts` source stays machine-agnostic by importing the virtual specifier. The editor map may use a relative target in the standard plays layout or an absolute `file://` URL to the local bundled presentation SDK for an arbitrary/workspace export. That machine-local resolution belongs only in `deno.json`; the runner supplies its own sandbox import map at execution time. Never hard-code the SDK path or file URL in `main.ts`. Before adding package-relative imports or process-payload references, run `rote guidance typescript play-creation`. Follow that authoritative package contract instead of inferring module imports or resource addressing from a file's location. ## Normalize Presentation Observations Treat the presentation body as a schema-agnostic normalizer over recorded facts, not as a second effect runner. Preserve the SDK's `single`, `fan_out`, and `empty_fan_out` distinction. Normalize each fan-out item independently; an observed empty fan-out is `[]`, while an absent optional value stays absent rather than becoming `""`, `0`, `false`, or `[]`. If a step can be restored, failed, skipped, or blocked, inspect `ctx.step(stepName("literal")).outcome.status`. A checkpoint-restored step has status `restored`. It does not have status `skipped`. When the play runs with `rote play run --resume`, handle `restored` in every status switch. Use `requireAvailable` when the step must provide output. It accepts completed, partial, and restored steps. It throws for condition-skipped, failed, and blocked steps. Branch on `outcome.status` when partial diagnostics or restored provenance affect the rendered result. For skipped, failed, or blocked steps, return a typed warning or error. Do not create a successful payload from an unavailable result. For play inputs, narrow `ctx.params` values explicitly (`typeof ctx.params.owner === "string"`) rather than coercing absent parameters into fabricated defaults. Normalize completed bodies by substrate: - Narrow `process.exec` with `isProcessExecBody`; validate `status.exit` before consuming optional `stdout.text`, `stderr.text`, or file observations. - Narrow browser bodies with `isBrowserBody`; switch on `op` and retain bounded page/element facts. - Treat other bodies as adapter observations. Accept direct JSON, plain text, JSON encoded in one text block, and the narrowly recognized legacy `{result:{content:[{type:"text",text}]}}` residue. Preserve zero or many valid text blocks as an `adapter_text_blocks` observation without joining or dropping them. Only non-text/malformed blocks or unexpected values become malformed observations with a reason; never guess a payload. The full concrete normalization pattern lives in `rote guidance typescript play-creation`; copy it and specialize only the final domain projection. ## Transform Cached Responses When a transformation can be expressed clearly with jq, prefer `rote query @N '' -r` and return to `rote-workspace`. Use TypeScript when the task needs richer validation, grouping, date handling, joins, cross-response merging, or formatting than jq should carry. Keep transformations deterministic: - Treat missing fields explicitly instead of fabricating zero, empty string, or default dates. - Keep user-provided parameters separate from constants. - Return structured data plus a concise summary when useful. - Avoid reading rote workspace files directly; use response IDs, exported fixtures, or SDK helpers. - Preserve raw adapter responses only when the user or play contract needs them. ## FlowOutput Guidance Design `FlowOutput` for future agents as well as humans: - `summary` for the short answer. - `data` or domain-specific fields for machine-readable results. - `warnings` for partial, skipped, or best-effort outcomes. - No secrets, local paths, transient workspace IDs, or one-off response IDs unless requested. - Stable field names that match documented frontmatter output expectations. If the transformation is part of a reusable play, return the proposed `FlowOutput` shape to `rote-flow-authoring` before release. ## Testing Expectations Test with representative cached data or fixture input before release. Cover no-result, partial-result, malformed/optional fields, and at least one user-provided edge case. After changes, rerun legacy TypeScript through `rote deno run --allow-all` and plays with frontmatter `steps:` through `rote play run`, rather than a standalone TypeScript runner. If a cached response query fails, inspect the cached response first. If the response is an adapter error, fix the upstream call, auth, base URL, or arguments before adding transformation workaround code. ## Return Fields Return these fields to the invoking owner (`rote-flow-authoring` or `rote-workspace`): - Input response IDs or fixture sources. - Transformation path: jq, TypeScript helper, play body, or blocker. - `FlowOutput` shape and warnings contract. - Test commands and representative cases covered. - Remaining assumptions, missing fields, or upstream adapter fixes needed. ## Handoff Contract - Use when: TypeScript play logic or cached-response transformation is needed for workspace output or reusable play authoring. - Preconditions: input response IDs, fixture data, or play parameters are available; live `rote grammar deno` guidance can be checked or its blocker is known. - Owns: TypeScript execution rules, SDK import guidance, deterministic transformation design, `FlowOutput` shape, and transformation-specific test expectations. - Hands off to: live `rote guidance browser play-authoring` for browser TypeScript; `rote-flow-authoring` for play lifecycle/release; `rote-workspace` for additional adapter calls or cached response queries; `rote-command-patterns` for command syntax; `rote-troubleshooting` after repeated unchanged failures. - Returns to: the invoking owner (`rote-flow-authoring` or `rote-workspace`) with transformation path, output shape, tests, and blockers. - Stop when: transformation is tested, jq is sufficient and the owner can continue, required data is missing, or troubleshooting becomes the correct owner. - Completion signal: tested transformation or explicit blocker plus the owner skill to resume.