@otto-assistant/otto 0.1.1 → 0.7.15

package/skills/event-sourcing-state/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: event-sourcing-state
+description: >
+  Event-sourced application state pattern for TypeScript apps. Prefer bounded
+  event logs plus pure derivation functions over mirrored mutable lifecycle
+  flags. Use when state transitions are driven by events and bugs can be
+  reproduced from a saved event stream.
+version: 0.2.0
+---
+
+<!-- Skill for event-sourced state and fixture-driven debugging. -->
+
+# Event-Sourcing State
+
+Use this skill when an app keeps adding mutable fields to track lifecycle,
+phase, status, or UI state that could instead be derived from an event log.
+
+## Core idea
+
+Do not store the answer when you can store the evidence.
+
+Coding agents overproduce state. Every bug looks like it wants one more flag,
+one more cached answer, one more special case. Every field feels locally
+justified. Globally you are building a machine nobody can hold in their head.
+
+Every boolean you add:
+
+1. doubles your app's possible states
+2. doubles your bugs
+3. doubles the coverage you need in the worst case
+
+The fix is not a better set of flags. The fix is deleting the flags.
+
+Stop storing conclusions and store evidence instead. If a decision depends on
+what actually happened, keep the events and derive the answer from them.
+
+## Anti-pattern: mirrored flags
+
+To answer one yes/no UI question ("should the footer show?"), an agent will
+mirror facts into state:
+
+```ts
+type ThreadState = {
+  wasInterrupted: boolean
+  didAssistantFinish: boolean
+  didAssistantError: boolean
+  wasToolCallOnly: boolean
+}
+
+function shouldShowFooter(state: ThreadState): boolean {
+  return state.didAssistantFinish
+    && !state.wasInterrupted
+    && !state.didAssistantError
+    && !state.wasToolCallOnly
+}
+```
+
+Four flags to answer one question. Each flag caches a fact already present in
+the event that produced it. Then a function recombines them back into one
+boolean. None of these fields looks insane on its own — that is the trap.
+
+## Pattern: derive from events
+
+Keep the raw events and compute the answer when needed:
+
+```ts
+type SessionEvent =
+  | { type: 'session.status'; status: 'busy' | 'idle' }
+  | { type: 'session.aborted' }
+  | {
+      type: 'message.updated'
+      role: 'assistant'
+      completed: boolean
+      error: boolean
+      finish: 'stop' | 'tool-calls'
+    }
+
+function getLatestAssistantMessage(events: SessionEvent[]) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i]
+    if (event?.type === 'message.updated' && event.role === 'assistant') {
+      return event
+    }
+  }
+  return undefined
+}
+
+function isNaturalCompletion(message: {
+  completed: boolean
+  error: boolean
+  finish: 'stop' | 'tool-calls'
+}): boolean {
+  if (!message.completed) {
+    return false
+  }
+  if (message.error) {
+    return false
+  }
+  return message.finish !== 'tool-calls'
+}
+
+function shouldShowFooter(events: SessionEvent[]): boolean {
+  const msg = getLatestAssistantMessage(events)
+  if (!msg) {
+    return false
+  }
+  return isNaturalCompletion(msg)
+}
+```
+
+Notice what disappeared:
+
+1. no interruption flag
+2. no finished flag
+3. no special footer state
+4. no extra state machine to explain another state machine
+
+You keep the raw thing that happened, then compute the answer when needed.
+
+## Rules
+
+1. Keep events immutable and versioned.
+2. Prefer one bounded event buffer over many mirrored flags.
+3. Derive lifecycle state with pure functions.
+4. Persist the event stream when it helps reproduce bugs.
+5. Write tests against fixtures, not against live mutable runtime state.
+
+## Good fit
+
+- session lifecycle state
+- workflow engines
+- chat or agent runtimes
+- typing/idle/footer decisions
+- retry and interruption logic
+
+## Bad fit
+
+- raw high-volume telemetry that is never read back
+- tiny local state better kept inside a closure
+- data that is already a stable source of truth elsewhere
+
+## Testing workflow
+
+1. Export a failing event stream from production or local runtime.
+2. Save it as a fixture (jsonl file).
+3. Write a pure test around the derivation function.
+4. Fix the derivation code.
+5. Keep the fixture so the bug stays dead.
+
+Any model can one-shot these problems because the feedback loop is obvious:
+events in, answer out.
+
+```ts
+import fs from 'node:fs'
+
+function loadEvents(file: string): SessionEvent[] {
+  return fs
+    .readFileSync(file, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      return JSON.parse(line) as SessionEvent
+    })
+}
+
+test('footer is hidden for aborted runs', () => {
+  const events = loadEvents('./fixtures/aborted-session.jsonl')
+  expect(shouldShowFooter(events)).toBe(false)
+})
+```
+
+The reproduction artifact is just data:
+
+1. no mocking the runtime
+2. no mocking timers
+3. no begging the runtime to reproduce the exact bad interleaving again
+4. just events in, answer out
+
+## Persistency
+
+If you want persistence you just store the events. Events are easily versioned
+and type-safe.
+
+The trade is this:
+
+- **Storing cached state**: if a user hits a broken state and you persist it,
+  the project is gone. Opening it crashes the app. To fix it you need migration
+  code that patches the corrupted state. Tedious and fragile.
+- **Storing the event stream**: you fix the derivation functions, release a new
+  version, the user opens the project, and it works again. What matters is
+  keeping events immutable and versioned so derivation functions are guaranteed
+  to process events from older app versions and return valid state.
+
+State is cached conclusions. Events are stored evidence. Evidence ages better.
+
+If you can derive it, don't store it.
+
+## State encapsulation
+
+The next best thing after no state is state you don't care about because it is
+encapsulated.
+
+Not everything needs event sourcing. The second-best option is state you
+successfully hide. A good example is React `useState`: state can only be
+written in event handlers within the component subtree and can only be read in
+the current component. It is local and easy to reason about.
+
+The same applies to backend code. Instead of promoting a timer or counter into
+a class field visible to all methods, encapsulate it in a closure:
+
+```ts
+// bad: timer is a class field, visible to all methods, agents will touch it
+class MessageWriter {
+  private debounceTimeout: ReturnType<typeof setTimeout> | null = null
+
+  queueSend(text: string): void {
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout)
+    }
+    this.debounceTimeout = setTimeout(() => {
+      this.write(text)
+    }, 300)
+  }
+}
+
+// good: timer is trapped in a tiny box, no other consumer can touch it
+function createDebouncedAction(callback: () => void, delayMs = 300) {
+  let timeout: ReturnType<typeof setTimeout> | null = null
+
+  function clear(): void {
+    if (!timeout) {
+      return
+    }
+    clearTimeout(timeout)
+    timeout = null
+  }
+
+  function trigger(): void {
+    clear()
+    timeout = setTimeout(() => {
+      timeout = null
+      callback()
+    }, delayMs)
+  }
+
+  return { trigger, clear }
+}
+```
+
+A global variable has the potential of doubling your app state. An encapsulated
+closure can only double the states of that tiny function. Given it is so small
+you don't care — spotting a bug inside it is easy for you and agents.

package/skills/goke/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: goke
+description: >
+  goke is a zero-dependency, type-safe CLI framework for TypeScript. CAC replacement
+  with Standard Schema support (Zod, Valibot, ArkType). Use goke when building CLI
+  tools — it handles commands, subcommands, options, type coercion, help generation,
+  and more. Schema-based options give you automatic type inference, coercion from
+  strings, and help text generation. ALWAYS read this skill when a repo uses goke
+  for its CLI.
+version: 0.0.1
+---
+
+# goke
+
+Fetch the full README from GitHub and read it before using goke:
+
+```bash
+curl -L https://raw.githubusercontent.com/remorses/goke/main/README.md
+```
+
+> Read the README in full every time you use goke.
+>
+> Important: never use `head` or `tail` to truncate it. Read the full README instead.
+
+## Install
+
+```bash
+npm install goke # or bun, pnpm, etc
+```
+
+## Quick Notes
+
+- Core APIs: `cli.option`, `cli.use`, `cli.version`, `cli.help`, `cli.parse`
+- Prefer injected `{ fs, console, process }` over globals
+- Use relative paths with injected `fs`; if a helper needs current-cwd semantics, pass injected `process.cwd` into that helper
+- For JustBash compatibility tests, import the existing CLI from app code instead of defining a new CLI inside the test
+
+The README is the source of truth for rules, examples, testing patterns, JustBash integration, and API details.

package/skills/jitter/EDITOR.md

@@ -0,0 +1,219 @@
+# Jitter Editor API Reference
+
+Reference for `window.app` methods and layer types. For utilities, see SKILL.md and use `jitterUtils.*`.
+
+## App Instance Methods
+
+```javascript
+// Playback
+app.play()
+app.stopPlayback()
+app.moveCursor(timeInMs)
+
+// Layer creation (opens picker or adds at cursor)
+app.addArtboard()
+app.addText('toolbar')
+app.addRectShape('toolbar')
+app.addEllipseShape('toolbar')
+app.addMedia('toolbar')
+
+// File operations
+app.renameFile(newName)
+app.deleteFile()
+app.downloadProject()
+app.scheduleSave()
+```
+
+## Dispatch Actions
+
+Use `app.dispatchAction(action)` or `jitterUtils.*` helpers.
+
+### Core Actions
+
+| Action Type         | Purpose                |
+| ------------------- | ---------------------- |
+| `updateObjWithUndo` | Update node properties |
+| `addObjWithUndo`    | Add new node           |
+| `removeObjWithUndo` | Remove nodes           |
+| `setSelection`      | Select nodes           |
+| `emptySelection`    | Clear selection        |
+| `undo` / `redo`     | Undo/redo              |
+| `setCurrentTime`    | Set playhead time      |
+| `zoomToSelection`   | Zoom to selected       |
+
+## Layer Types
+
+### Artboard
+
+```javascript
+{
+  type: "artboard",
+  name: "16:9",
+  width: 1920,
+  height: 1080,
+  duration: 11000,
+  background: true,
+  fillColor: "#ffffff"
+}
+```
+
+### Text
+
+```javascript
+{
+  type: "text",
+  text: "Hello World",
+  fontSize: 48,
+  font: { name: "Poppins", type: "googlefont", weight: 600 },
+  fillColor: "#000000",
+  textAlign: "center",  // "left" | "center" | "right"
+  verticalAlign: "middle"
+}
+```
+
+### Image / SVG / Video / GIF
+
+```javascript
+{
+  type: "image",  // or "svg", "video", "gif"
+  url: "https://example.com/asset.jpg",
+  width: 400,
+  height: 300,
+  cornerRadius: 0
+}
+```
+
+### Shapes
+
+```javascript
+// Rectangle
+{ type: "rect", fillColor: "#3B82F6", cornerRadius: 8 }
+
+// Ellipse
+{ type: "ellipse", fillColor: "#EF4444" }
+
+// Star
+{ type: "star", fillColor: "#F59E0B", points: 5, innerRadius: 50 }
+```
+
+### Group
+
+```javascript
+{
+  type: "layerGrp",
+  name: "Group Name",
+  clipsContent: false,
+  cornerRadius: 0
+}
+```
+
+## Common Properties
+
+All layers support:
+
+| Property          | Type    | Description         |
+| ----------------- | ------- | ------------------- |
+| `x`, `y`          | number  | Position            |
+| `width`, `height` | number  | Size                |
+| `angle`           | number  | Rotation in degrees |
+| `scale`           | number  | Scale factor        |
+| `opacity`         | number  | 0-100               |
+| `shadowEnabled`   | boolean | Drop shadow         |
+| `strokeEnabled`   | boolean | Stroke/border       |
+
+## Fill Colors
+
+```javascript
+// Solid
+fillColor: "#3B82F6"
+
+// Linear gradient
+fillColor: {
+  type: "GRADIENT_LINEAR",
+  stops: [
+    { id: "s1", position: 0, color: "#FF0000" },
+    { id: "s2", position: 1, color: "#0000FF" }
+  ],
+  transform: { angle: 0, sx: 1, tx: 0.5, ty: 0.5 }
+}
+
+// Radial gradient
+fillColor: {
+  type: "GRADIENT_RADIAL",
+  stops: [...],
+  transform: { sx: 1, tx: 0.5, ty: 0.5 }
+}
+```
+
+## Easing Presets
+
+```javascript
+{ name: "smooth:standard:v1", schema: "v1", config: { intensity: 50 } }
+{ name: "smooth:accelerate:v1", schema: "v1", config: { intensity: 50 } }
+{ name: "smooth:decelerate:v1", schema: "v1", config: { intensity: 50 } }
+{ name: "spring", schema: "v1", config: { stiffness: 100, damping: 10 } }
+{ name: "bounce", schema: "v1", config: { bounces: 3 } }
+{ name: "linear", schema: "v1", config: {} }
+```
+
+## Animation Types
+
+### Transform
+
+`scale`, `move`, `rotate`, `opacity`
+
+### Enter/Exit
+
+`fadeIn/Out`, `growIn/Out`, `shrinkIn/Out`, `slideIn/Out`, `spinIn/Out`, `blurIn/Out`, `textIn/Out`
+
+### Mask
+
+`maskRevealIn/Out`, `maskSlideIn/Out`, `maskCenterIn/Out`
+
+### Media
+
+`playVideo`, `playAudio`
+
+## Node Tree Structure
+
+```
+Artboard (type: "artboard")
+├── LayersTree (type: "layersTree")
+│   ├── LayerGrp (type: "layerGrp")
+│   │   ├── Text (type: "text")
+│   │   └── Image (type: "image")
+│   └── SVG (type: "svg")
+└── OperationsTree (type: "operationsTree")
+    └── OpGrp (type: "opGrp")
+        ├── Scale animation
+        └── FadeIn animation
+```
+
+## State Access
+
+```javascript
+// Current selection
+const state = app.props.observableEditorState.getSnapshot()
+const selectedIds = state.selection.nodesIds
+
+// Project config
+const conf = app.props.observableImmutableConf.lastImmutableConf
+
+// File metadata
+const fileMeta = app.props.fileMeta
+// { id, name, bucket, teamId }
+
+// Subscribe to changes
+const unsubscribe = app.props.observableImmutableConf.subscribe(() => {
+  // Config changed
+})
+```
+
+## File Actions
+
+```javascript
+await app.props.fileActions.duplicateFile(fileId) // Returns new ID
+await app.props.fileActions.deleteFile(fileId)
+await app.props.fileActions.renameFile(name)
+await app.props.fileActions.saveFile()
+```