tpmjs/sprites_skill.md

Sprites Tools Development & Testing Guide

This document covers how to build, publish, flush caches, and test the TPMJS sprites tools.

Credentials

TPMJS API Key

<your-tpmjs-api-key>

SPRITES_TOKEN (set in collection env vars)

<your-sprites-token>

CRON_SECRET (for triggering syncs)

<your-cron-secret>

MCP Endpoint

The sprites collection MCP endpoint:

https://tpmjs.com/api/mcp/ajax/sprites/http

Available Sprites Tools

Tool	Package	Description
sprites-list	@tpmjs/tools-sprites-list	List all sprites with status
sprites-get	@tpmjs/tools-sprites-get	Get a specific sprite's details
sprites-create	@tpmjs/tools-sprites-create	Create a new sprite
sprites-delete	@tpmjs/tools-sprites-delete	Delete a sprite
sprites-exec	@tpmjs/tools-sprites-exec	Execute commands in a sprite
sprites-sessions	@tpmjs/tools-sprites-sessions	List active sessions
sprites-policy-get	@tpmjs/tools-sprites-policy-get	Get sprite policy
sprites-checkpoint-list	@tpmjs/tools-sprites-checkpoint-list	List checkpoints
sprites-checkpoint-create	@tpmjs/tools-sprites-checkpoint-create	Create a checkpoint
sprites-checkpoint-restore	@tpmjs/tools-sprites-checkpoint-restore	Restore from checkpoint

Building a Sprites Tool

1. Navigate to the tool directory:

cd packages/tools/official/sprites-exec

2. Build:

pnpm build

3. Type-check:

pnpm type-check

Publishing a Sprites Tool

1. Bump version in package.json:

"version": "0.1.5"

2. Build and publish:

cd packages/tools/official/sprites-exec
pnpm build
npm publish

3. Commit the version bump:

git add package.json
git commit -m "chore: bump sprites-exec to 0.1.5"
git push

Syncing to Database

After publishing, sync the package to the TPMJS database:

Changes Feed Sync (fast, picks up recent npm changes)

curl -s -X POST "https://tpmjs.com/api/sync/changes" \
  -H "Authorization: Bearer <your-cron-secret>" \
  -H "Content-Type: application/json"

Keyword Sync (comprehensive, searches for all tpmjs packages)

curl -s -X POST "https://tpmjs.com/api/sync/keyword" \
  -H "Authorization: Bearer <your-cron-secret>" \
  -H "Content-Type: application/json"

Check version in database

curl -s "https://tpmjs.com/api/tools?q=sprites-exec" | jq '.data[] | select(.package.npmPackageName == "@tpmjs/tools-sprites-exec") | {name: .name, version: .package.npmVersion}'

Flushing Executor Caches

CRITICAL: The executor caches npm packages. After publishing a new version, you MUST flush the cache.

Flush Primary Executor (executor.tpmjs.com)

curl -s -X POST "https://executor.tpmjs.com/cache/clear" | jq .

Flush Railway Executor (backup)

curl -s -X POST "https://endearing-commitment-production.up.railway.app/cache/clear" | jq .

Check Cache Stats

curl -s "https://executor.tpmjs.com/cache/stats" | jq .

Testing via MCP Endpoint

List All Tools

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq '.result.tools[] | {name: .name}'

Test sprites-list

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-list--spritesListTool","arguments":{}}}' | jq '.result'

Test sprites-exec (simple command)

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-exec--spritesExecTool","arguments":{"name":"hello-script-sprite","cmd":"echo hello"}}}' | jq '.result'

Test sprites-exec (shell operators)

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-exec--spritesExecTool","arguments":{"name":"hello-script-sprite","cmd":"echo foo && echo bar"}}}' | jq '.result'

Test sprites-get

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-get--spritesGetTool","arguments":{"name":"hello-script-sprite"}}}' | jq '.result'

Test sprites-create

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-create--spritesCreateTool","arguments":{"name":"test-sprite-123"}}}' | jq '.result'

Test sprites-delete

curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-delete--spritesDeleteTool","arguments":{"name":"test-sprite-123"}}}' | jq '.result'

Testing via Agent Conversation

curl -s -X POST "https://tpmjs.com/api/ajax/agents/sprites/conversation/test-conv?format=json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"message":"List all sprites"}'

Complete Workflow: Publish + Sync + Flush + Test

# 1. Build and publish
cd packages/tools/official/sprites-exec
pnpm build && npm publish

# 2. Trigger sync
curl -s -X POST "https://tpmjs.com/api/sync/changes" \
  -H "Authorization: Bearer <your-cron-secret>"

# 3. Flush caches
curl -s -X POST "https://executor.tpmjs.com/cache/clear"
curl -s -X POST "https://endearing-commitment-production.up.railway.app/cache/clear"

# 4. Test
curl -s -X POST "https://tpmjs.com/api/mcp/ajax/sprites/http" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-tpmjs-api-key>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tpmjs-tools-sprites-exec--spritesExecTool","arguments":{"name":"hello-script-sprite","cmd":"echo test"}}}' | jq .

Known Issues & Fixes

Issue: "Failed to parse response from Sprites API"

Cause: Sprites API returns JSON error {"error":"..."} with HTTP 200 instead of proper error codes. Fix: Added JSON error detection in sprites-exec v0.1.4.

Issue: "Invalid sprite status: cold"

Cause: Sprites API returns "cold" status for idle sprites, which wasn't recognized. Fix: Added "cold" to valid statuses in sprites-list v0.1.3.

Issue: "The update command takes no arguments"

Cause: Commands with shell operators (&&, ||, |, etc.) were being parsed incorrectly. Fix: Added shell operator detection and sh -c wrapping in sprites-exec v0.1.5.

Issue: Old version still being used after publish

Cause: Deno HTTP import cache + executor module cache. Fix:

1. Pass explicit version from database (deployed to web app)
2. Flush executor caches after publishing