@meistrari/tela-skills 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# @meistrari/tela-skills
+
+Tela API skills for [Claude Code](https://claude.ai/claude-code). Enables Claude to interact with Tela canvas/prompts directly.
+
+## Installation
+
+```bash
+bunx @meistrari/tela-skills
+```
+
+The installer will:
+- Copy skill files to `~/.claude/skills/tela/`
+- Optionally set up your Tela API key
+
+## Usage
+
+Once installed, Claude Code can use the Tela skills via bun preload:
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listProjects())"
+```
+
+## Available Functions
+
+### Projects
+- `tela.listProjects()` - List projects in workspace
+- `tela.createProject({ title })` - Create a new project
+
+### Canvas (Prompts)
+- `tela.listPrompts(options?)` - List canvas/prompts
+- `tela.getPrompt(promptId)` - Get a prompt by ID
+- `tela.createCanvas(payload)` - Create a new canvas
+- `tela.getCanvas(canvasId)` - Get canvas + latest version
+- `tela.updateCanvas(canvasId, payload)` - Update canvas (merges config by default)
+
+### Helpers
+- `tela.createStructuredOutput(properties)` - Create structured output schema
+- `tela.createVariable(name, type, options?)` - Create a variable definition
+- `tela.createMessage(role, content, index)` - Create a message with proper formatting
+- `tela.markdownToHtml(markdown)` - Convert markdown to Tela HTML format
+
+## Authentication
+
+The API key is stored at `~/.tela/session`. You can set it up during installation or manually:
+
+```bash
+mkdir -p ~/.tela && echo "YOUR_API_KEY" > ~/.tela/session
+```
+
+## Example: Create Canvas with Structured Output
+
+```typescript
+const canvas = await tela.createCanvas({
+  title: 'My Canvas',
+  projectId: 'PROJECT_ID',
+  workspaceId: 'WORKSPACE_ID',
+  version: {
+    title: 'v1',
+    configuration: {
+      model: 'gpt-5',
+      type: 'chat',
+      temperature: 0,
+      structuredOutput: tela.createStructuredOutput({
+        summary: { type: 'string', description: 'Brief summary' },
+        keyPoints: { type: 'array', items: { type: 'string' } }
+      })
+    },
+    messages: [
+      tela.createMessage('system', '## Task\n\nAnalyze the document.', 0)
+    ],
+    variables: [
+      tela.createVariable('document', 'file', { allowMultimodal: true })
+    ]
+  }
+})
+```
+
+## License
+
+MIT

package/cli.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+import * as p from '@clack/prompts'
+import { existsSync, mkdirSync, cpSync, writeFileSync, readdirSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILLS_DIR = join(homedir(), '.claude', 'skills', 'tela')
+const SESSION_DIR = join(homedir(), '.tela')
+const SESSION_PATH = join(SESSION_DIR, 'session')
+
+async function main() {
+  p.intro('Tela Skills for Claude Code')
+
+  const skillsExist = existsSync(SKILLS_DIR)
+
+  if (skillsExist) {
+    const update = await p.confirm({
+      message: 'Tela skills already installed. Update to latest version?',
+      initialValue: true,
+    })
+
+    if (p.isCancel(update) || !update) {
+      p.cancel('Installation cancelled.')
+      process.exit(0)
+    }
+  } else {
+    const install = await p.confirm({
+      message: 'Install Tela skills to ~/.claude/skills/tela/?',
+      initialValue: true,
+    })
+
+    if (p.isCancel(install) || !install) {
+      p.cancel('Installation cancelled.')
+      process.exit(0)
+    }
+  }
+
+  const spinner = p.spinner()
+  spinner.start('Installing skill files...')
+
+  try {
+    mkdirSync(SKILLS_DIR, { recursive: true })
+
+    const sourceDir = join(__dirname, 'skill')
+    const files = readdirSync(sourceDir)
+
+    for (const file of files) {
+      cpSync(join(sourceDir, file), join(SKILLS_DIR, file))
+    }
+
+    spinner.stop(`Installed ${files.length} files to ${SKILLS_DIR}`)
+  } catch (error) {
+    spinner.stop('Installation failed')
+    p.log.error(String(error))
+    process.exit(1)
+  }
+
+  const sessionExists = existsSync(SESSION_PATH)
+
+  if (!sessionExists) {
+    const setupKey = await p.confirm({
+      message: 'Set up Tela API key now?',
+      initialValue: true,
+    })
+
+    if (!p.isCancel(setupKey) && setupKey) {
+      const apiKey = await p.text({
+        message: 'Enter your Tela API key:',
+        placeholder: 'tela_...',
+        validate: (value) => {
+          if (!value) return 'API key is required'
+          if (value.length < 10) return 'API key seems too short'
+        },
+      })
+
+      if (!p.isCancel(apiKey) && apiKey) {
+        mkdirSync(SESSION_DIR, { recursive: true })
+        writeFileSync(SESSION_PATH, apiKey, { mode: 0o600 })
+        p.log.success('API key saved to ~/.tela/session')
+      }
+    } else {
+      p.log.info('You can set up your API key later by running:')
+      p.log.message('mkdir -p ~/.tela && echo "YOUR_KEY" > ~/.tela/session')
+    }
+  } else {
+    p.log.info('API key already configured at ~/.tela/session')
+  }
+
+  p.note(
+    `Use in Claude Code with bun --preload:
+
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+  console.log(await tela.listProjects())
+"`,
+    'Usage'
+  )
+
+  p.outro('Tela skills installed successfully!')
+}
+
+main().catch(console.error)

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@meistrari/tela-skills",
+  "version": "1.0.0",
+  "description": "Tela API skills for Claude Code",
+  "type": "module",
+  "bin": {
+    "tela-skills": "./cli.ts"
+  },
+  "files": [
+    "cli.ts",
+    "skill/**/*"
+  ],
+  "keywords": [
+    "tela",
+    "claude",
+    "claude-code",
+    "skills",
+    "ai"
+  ],
+  "author": "Meistrari",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.9.1"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: tela
+description: Skills for interacting with Tela - view, create, and update prompts/canvas. Use this skill when user shares a Tela URL (app.tela.com) or asks about canvas/prompts. Do NOT use WebFetch for Tela URLs.
+---
+
+# Tela API Skills
+
+Skills for interacting with the Tela API. Note: Prompts are called "Canvas" in Tela.
+
+**IMPORTANT**: When the user shares a Tela URL like `https://app.tela.com/prompt/{id}/craft`, use these skills to fetch and modify the canvas - do NOT use WebFetch.
+
+## Installation
+
+```bash
+bunx @meistrari/tela-skills
+```
+
+## Authentication
+
+The API uses Bearer token authentication. The token is stored at `~/.tela/session`.
+
+## Using These Skills
+
+Use `bun` with `--preload` to make the `tela` object globally available:
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listProjects())"
+```
+
+## Available Functions
+
+### Projects & Prompts
+
+- `tela.listProjects()` - List all projects in the workspace
+- `tela.createProject({ title })` - Create a new project
+- `tela.listPrompts(options?)` - List prompts/canvas with optional filtering
+- `tela.getPrompt(promptId)` - Get a single prompt by ID
+- `tela.getPromotedVersion(promptId)` - Get the promoted version of a prompt
+
+### Canvas Operations
+
+- `tela.createCanvas(payload)` - Create a new canvas with optional initial version
+- `tela.getCanvas(canvasId)` - Get canvas + latest version by canvas ID
+- `tela.updateCanvas(canvasId, payload, { merge: true })` - Update canvas (merges config by default)
+- `tela.updateCanvasVersion(versionId, payload)` - Low-level: update by version ID
+- `tela.createCanvasVersion(canvasId, payload)` - Create a new version for existing canvas
+- `tela.getCanvasVersion(versionId)` - Get a canvas version by version ID
+
+### Helper Functions
+
+- `tela.createStructuredOutput(properties, options?)` - Create structured output schema
+- `tela.createVariable(name, type, options?)` - Create a variable definition
+- `tela.createMessage(role, content, index)` - Create a message with proper HTML/markdown formatting
+- `tela.markdownToHtml(markdown)` - Convert markdown to HTML with variable formatting
+- `tela.getProjectUrl(projectId)` - Get URL to view project in Tela app
+- `tela.getCanvasUrl(canvasId)` - Get URL to view canvas in Tela app
+
+## Defaults
+
+- **Model**: Always use `gpt-5`
+- **Temperature**: Always use `0`
+- **Prompts**: Use markdown with `## Headings` for readability
+- **Output format**: Use `structuredOutput` config, NEVER put format templates in the prompt text
+
+## Quick Examples
+
+### List Projects (returns max 10 by default)
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(JSON.stringify(await tela.listProjects(), null, 2))"
+```
+
+### Create Canvas with Structured Output
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const canvas = await tela.createCanvas({
+  title: 'My Canvas',
+  projectId: 'PROJECT_ID',
+  workspaceId: 'WORKSPACE_ID',
+  version: {
+    title: 'v1',
+    configuration: {
+      model: 'gpt-5',
+      type: 'chat',
+      temperature: 0,
+      structuredOutput: tela.createStructuredOutput({
+        summary: { type: 'string', description: 'Brief summary' },
+        keyPoints: { type: 'array', items: { type: 'string' } }
+      })
+    },
+    messages: [
+      tela.createMessage('system', '## Task\n\nAnalyze the document.\n\n## Input\n\n{document}', 0)
+    ],
+    variables: [tela.createVariable('document', 'file', { allowMultimodal: true })]
+  }
+})
+console.log('Created:', canvas.id, tela.getCanvasUrl(canvas.id))
+"
+```
+
+**IMPORTANT**: Define output format in `structuredOutput`, not in the prompt text!
+
+### Update Canvas (merges config by default)
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const updated = await tela.updateCanvas('CANVAS_ID', {
+  configuration: { model: 'gpt-5' },
+  variables: [tela.createVariable('input', 'file', { allowMultimodal: true })]
+})
+console.log('Updated:', updated.id)
+"
+```
+
+### Get Canvas Info
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const { canvas, version } = await tela.getCanvas('CANVAS_ID')
+console.log('Title:', canvas.title)
+console.log('Model:', version?.configuration?.model)
+console.log('Variables:', version?.variables?.map(v => v.name))
+"
+```
+
+## Data Structures
+
+### Variables
+```typescript
+{ name: 'input', type: 'text' | 'file' | 'mixed', required: true, description?: 'Description' }
+```
+Referenced in content as `{variableName}` (single braces)
+
+### Structured Output
+```typescript
+{
+  enabled: true,
+  schema: {
+    properties: {
+      fieldName: { type: 'string', description: 'Field description' }
+    },
+    title: 'defaultOutput',
+    description: 'Schema description',
+    type: 'object',
+    required: ['fieldName']
+  }
+}
+```
+
+### Messages
+```typescript
+{ role: 'system' | 'user' | 'assistant', content: 'Message content', index: 0 }
+```
+
+## Environment Variables
+
+- `TELA_API_URL` - Override the API base URL (default: `https://api.tela.com`)
+- `TELA_APP_URL` - Override the app base URL (default: `https://app.tela.com`)
+
+## File Structure
+
+```
+~/.claude/skills/tela/
+├── SKILL.md          # This file
+├── preload.ts        # Preload script - makes `tela` globally available
+├── index.ts          # Barrel export
+├── common.ts         # Shared utilities (loadApiKey, apiRequest)
+├── projects.ts       # Project functions
+├── prompts.ts        # Prompt/Canvas list functions
+└── canvas.ts         # Canvas create/update functions
+```