@meistrari/tela-skills 1.3.4 → 1.4.0

package/README.md

@@ -60,6 +60,9 @@ bun run cli.ts
 
 # Verify skill loads correctly
 bun --preload skill/preload.ts -e "console.log(Object.keys(tela))"
+
+# Localhost (API :4000, App :3000)
+bun localhost.ts "console.log(await tela.listProjects())"
 ```
 
 ### File layout after installation

package/cli.ts

@@ -5,60 +5,49 @@ import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import open from 'open'
+import {
+    discoverLocalhostServices,
+    parseApiGatewayKeys,
+    readAuthApiSecret,
+    signLocalhostJwt,
+    fetchWorkspaces,
+    saveLocalhostSession,
+    writeLocalhostEnv,
+    readSavedReposPath,
+    saveReposPath,
+} from './skill/localhost-utils.ts'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const SKILLS_DIR = join(homedir(), '.claude', 'skills', 'tela')
 const OPEN_ISSUE_SKILLS_DIR = join(homedir(), '.claude', 'skills', 'tela-open-issue')
+const LOCALHOST_SKILLS_DIR = join(homedir(), '.claude', 'skills', 'tela-localhost')
 const SESSION_DIR = join(homedir(), '.tela')
 const BACKOFFICE_URL = 'https://backoffice.tela.com'
 const STAGING_BACKOFFICE_URL = 'https://staging-backoffice.tela.com'
 
-async function main() {
-    p.intro('Tela Skills for Claude Code')
-
-    const environment = await p.select({
-        message: 'Which environment do you want to connect to?',
-        options: [
-            { value: 'production', label: 'Production' },
-            { value: 'staging', label: 'Staging' },
-        ],
-    })
-
-    if (p.isCancel(environment)) {
-        p.cancel('Setup cancelled.')
-        process.exit(0)
-    }
-
-    const env = environment as 'production' | 'staging'
-    const sessionPath = join(SESSION_DIR, `session.${env}`)
-    const sessionLabel = `~/.tela/session.${env}`
-    const backofficeUrl = env === 'staging' ? STAGING_BACKOFFICE_URL : BACKOFFICE_URL
-
-    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)
+// --- CLI Flag Parsing ---
+function parseFlags(argv: string[]): Record<string, string | true> {
+    const flags: Record<string, string | true> = {}
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2)
+            const next = argv[i + 1]
+            if (next && !next.startsWith('--')) {
+                flags[key] = next
+                i++
+            } else {
+                flags[key] = true
+            }
         }
     }
-    else {
-        const install = await p.confirm({
-            message: 'Install Tela skills to ~/.claude/skills/tela/?',
-            initialValue: true,
-        })
+    return flags
+}
 
-        if (p.isCancel(install) || !install) {
-            p.cancel('Installation cancelled.')
-            process.exit(0)
-        }
-    }
+const flags = parseFlags(process.argv.slice(2))
+const YES = 'yes' in flags || 'y' in flags
 
+async function installSkills() {
     const spinner = p.spinner()
     spinner.start('Installing skill files...')
 
@@ -68,17 +57,23 @@ async function main() {
         const sourceDir = join(__dirname, 'skill')
         const openIssueSkillFile = 'TELA_OPEN_ISSUE_SKILL.md'
         const telaSkillFile = 'TELA_SKILL.md'
-        const files = readdirSync(sourceDir).filter(f => f !== openIssueSkillFile && f !== telaSkillFile)
+        const localhostSkillFile = 'TELA_LOCALHOST_SKILL.md'
+        const files = readdirSync(sourceDir).filter(f =>
+            f !== openIssueSkillFile && f !== telaSkillFile && f !== localhostSkillFile
+        )
 
         for (const file of files) {
             cpSync(join(sourceDir, file), join(SKILLS_DIR, file))
         }
         cpSync(join(sourceDir, telaSkillFile), join(SKILLS_DIR, 'SKILL.md'))
 
-        // Install open-issue skill to its own directory
         mkdirSync(OPEN_ISSUE_SKILLS_DIR, { recursive: true })
         cpSync(join(sourceDir, openIssueSkillFile), join(OPEN_ISSUE_SKILLS_DIR, 'SKILL.md'))
 
+        // Install localhost skill to its own directory
+        mkdirSync(LOCALHOST_SKILLS_DIR, { recursive: true })
+        cpSync(join(sourceDir, localhostSkillFile), join(LOCALHOST_SKILLS_DIR, 'SKILL.md'))
+
         const agentsSourceDir = join(__dirname, 'agents')
         const agentsDestDir = join(homedir(), '.claude', 'agents')
         if (existsSync(agentsSourceDir)) {
@@ -107,38 +102,296 @@ async function main() {
         }
 
         depSpinner.stop(`Installed ${dependencies.length} dependencies`)
-    }
-    catch (err: unknown) {
+    } catch (err: unknown) {
         spinner.stop('Installation failed')
         p.log.error(err instanceof Error ? err.message : String(err))
         process.exit(1)
     }
+}
 
-    if (existsSync(sessionPath)) {
-        const reconnect = await p.confirm({
-            message: 'Session already configured. Clear and reconnect?',
-            initialValue: false,
+async function handleLocalhostSetup() {
+    // 1. Discover Docker services
+    const discoverSpinner = p.spinner()
+    discoverSpinner.start('Discovering local services via Docker...')
+
+    const services = discoverLocalhostServices()
+
+    if (!services.authApiPort) {
+        discoverSpinner.stop('auth-api container not found')
+        p.log.error('Could not find auth-api Docker container. Make sure local services are running.')
+        process.exit(1)
+    }
+    if (!services.telaApiPort) {
+        discoverSpinner.stop('tela-api container not found')
+        p.log.error('Could not find tela-api Docker container. Make sure local services are running.')
+        process.exit(1)
+    }
+
+    discoverSpinner.stop(`Found services — auth-api :${services.authApiPort}, tela-api :${services.telaApiPort}${services.telaAppPort ? `, tela-app :${services.telaAppPort}` : ''}`)
+
+    // 2. Ask for meistrari repos path
+    const savedPath = readSavedReposPath()
+    const reposPathFlag = typeof flags['repos-path'] === 'string' ? flags['repos-path'] : null
+
+    let reposPath: string
+    if (reposPathFlag) {
+        reposPath = reposPathFlag
+        p.log.info(`Using repos path: ${reposPath}`)
+    } else if (YES && savedPath) {
+        reposPath = savedPath
+        p.log.info(`Using saved repos path: ${reposPath}`)
+    } else {
+        const result = await p.text({
+            message: 'Where is the tela monorepo cloned?',
+            placeholder: '/path/to/tela',
+            ...(savedPath ? { defaultValue: savedPath } : {}),
+            validate(value): string | undefined {
+                if (!value.trim()) return 'Path is required'
+                return undefined
+            },
+        })
+
+        if (p.isCancel(result)) {
+            p.cancel('Setup cancelled.')
+            process.exit(0)
+        }
+        reposPath = result
+    }
+
+    const resolvedPath = reposPath.replace(/^~/, homedir())
+    saveReposPath(resolvedPath)
+
+    // 3. Read RSA keys and auth secret
+    const keysSpinner = p.spinner()
+    keysSpinner.start('Reading RSA keys from api-gateway...')
+
+    let keys: ReturnType<typeof parseApiGatewayKeys>
+    let authApiSecret: string
+    try {
+        keys = parseApiGatewayKeys(resolvedPath)
+        authApiSecret = readAuthApiSecret(resolvedPath)
+        keysSpinner.stop('RSA keys loaded')
+    } catch (err) {
+        keysSpinner.stop('Failed to read keys')
+        p.log.error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+    }
+
+    // 4. Fetch workspaces
+    const authApiUrl = `http://localhost:${services.authApiPort}`
+    const wsSpinner = p.spinner()
+    wsSpinner.start('Fetching workspaces from auth-api...')
+
+    let workspaces: Awaited<ReturnType<typeof fetchWorkspaces>>
+    try {
+        workspaces = await fetchWorkspaces(authApiUrl, authApiSecret)
+        wsSpinner.stop(`Found ${workspaces.length} workspace(s)`)
+    } catch (err) {
+        wsSpinner.stop('Failed to fetch workspaces')
+        p.log.error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+    }
+
+    if (workspaces.length === 0) {
+        p.log.warning('No workspaces found. Create one using auth-api CLI scripts first.')
+        process.exit(1)
+    }
+
+    // 5. Select workspace
+    const workspaceFlag = typeof flags['workspace'] === 'string' ? flags['workspace'] : null
+
+    let workspace: { id: string; title: string; slug: string }
+    if (workspaceFlag) {
+        const match = workspaces.find(ws => ws.id === workspaceFlag || ws.slug === workspaceFlag)
+        if (!match) {
+            p.log.error(`Workspace "${workspaceFlag}" not found. Available: ${workspaces.map(ws => `${ws.slug} (${ws.id})`).join(', ')}`)
+            process.exit(1)
+        }
+        workspace = match
+        p.log.info(`Using workspace: ${workspace.title}`)
+    } else if (YES && workspaces.length === 1) {
+        workspace = workspaces[0]!
+        p.log.info(`Auto-selecting only workspace: ${workspace.title}`)
+    } else {
+        const selectedWorkspace = await p.select({
+            message: 'Which workspace do you want to connect to?',
+            options: workspaces.map(ws => ({
+                value: ws,
+                label: ws.title,
+                hint: ws.slug,
+            })),
+        })
+
+        if (p.isCancel(selectedWorkspace)) {
+            p.cancel('Setup cancelled.')
+            process.exit(0)
+        }
+
+        workspace = selectedWorkspace as { id: string; title: string; slug: string }
+    }
+
+    // 6. Generate JWT and save
+    const tokenSpinner = p.spinner()
+    tokenSpinner.start('Generating authentication token...')
+
+    const token = signLocalhostJwt({
+        workspace: { id: workspace.id, title: workspace.title },
+        privateKey: keys.privateKey,
+        kid: keys.kid,
+    })
+
+    saveLocalhostSession(token)
+    writeLocalhostEnv(services.telaApiPort, services.telaAppPort)
+
+    tokenSpinner.stop('Token generated and saved')
+
+    // 7. Install skills (reuse existing logic)
+    if (YES) {
+        await installSkills()
+    } else {
+        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) {
+                await installSkills()
+            }
+        } else {
+            const install = await p.confirm({
+                message: 'Install Tela skills to ~/.claude/skills/tela/?',
+                initialValue: true,
+            })
+
+            if (!p.isCancel(install) && install) {
+                await installSkills()
+            }
+        }
+    }
+
+    writeFileSync(join(SESSION_DIR, 'environment'), 'localhost', { mode: 0o600 })
+
+    p.log.success(`Connected to workspace "${workspace.title}" on localhost`)
+
+    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('Localhost setup complete!')
+}
+
+async function main() {
+    p.intro('Tela Skills for Claude Code')
+
+    const envFlag = typeof flags['env'] === 'string' ? flags['env'] : null
+    const validEnvs = ['production', 'staging', 'localhost'] as const
+
+    let environment: string
+    if (envFlag) {
+        if (!validEnvs.includes(envFlag as any)) {
+            p.log.error(`Invalid environment: "${envFlag}". Valid: ${validEnvs.join(', ')}`)
+            process.exit(1)
+        }
+        environment = envFlag
+        p.log.info(`Environment: ${environment}`)
+    } else {
+        const selected = await p.select({
+            message: 'Which environment do you want to connect to?',
+            options: [
+                { value: 'production', label: 'Production' },
+                { value: 'staging', label: 'Staging' },
+                { value: 'localhost', label: 'Localhost (internal)' },
+            ],
         })
 
-        if (!p.isCancel(reconnect) && reconnect) {
-            const { unlinkSync } = await import('node:fs')
-            unlinkSync(sessionPath)
-            const envPath = join(SESSION_DIR, 'environment')
-            if (existsSync(envPath)) unlinkSync(envPath)
-            p.log.info('Session cleared. Proceeding to authentication...')
+        if (p.isCancel(selected)) {
+            p.cancel('Setup cancelled.')
+            process.exit(0)
+        }
+        environment = selected as string
+    }
+
+    if (environment === 'localhost') {
+        await handleLocalhostSetup()
+        return
+    }
+
+    const env = environment as 'production' | 'staging'
+    const sessionPath = join(SESSION_DIR, `session.${env}`)
+    const sessionLabel = `~/.tela/session.${env}`
+    const backofficeUrl = env === 'staging' ? STAGING_BACKOFFICE_URL : BACKOFFICE_URL
+
+    if (YES) {
+        await installSkills()
+    } else {
+        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)
+            }
+        }
+
+        await installSkills()
+    }
+
+    if (existsSync(sessionPath)) {
+        if (YES) {
             p.log.info(`Keeping existing session at ${sessionLabel}`)
+        } else {
+            const reconnect = await p.confirm({
+                message: 'Session already configured. Clear and reconnect?',
+                initialValue: false,
+            })
+
+            if (!p.isCancel(reconnect) && reconnect) {
+                const { unlinkSync } = await import('node:fs')
+                unlinkSync(sessionPath)
+                const envPath = join(SESSION_DIR, 'environment')
+                if (existsSync(envPath)) unlinkSync(envPath)
+                p.log.info('Session cleared. Proceeding to authentication...')
+            }
+            else {
+                p.log.info(`Keeping existing session at ${sessionLabel}`)
+            }
         }
     }
 
     if (!existsSync(sessionPath)) {
-        const setupKey = await p.confirm({
-            message: 'Set up Tela authentication now?',
-            initialValue: true,
-        })
+        const shouldAuth = YES || await (async () => {
+            const setupKey = await p.confirm({
+                message: 'Set up Tela authentication now?',
+                initialValue: true,
+            })
+            return !p.isCancel(setupKey) && setupKey
+        })()
 
-        if (!p.isCancel(setupKey) && setupKey) {
+        if (shouldAuth) {
             let resolveToken: (token: string) => void
             let rejectToken: (error: Error) => void
             const tokenPromise = new Promise<string>((resolve, reject) => {
@@ -147,6 +400,7 @@ async function main() {
             })
 
             const server = Bun.serve({
+                hostname: '127.0.0.1',
                 port: 0,
                 fetch(req) {
                     const url = new URL(req.url)

package/list-workspaces.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+/**
+ * List available Tela workspaces from the local auth-api.
+ *
+ * Usage:
+ *   bun list-workspaces.ts
+ *   bunx @meistrari/tela-skills/list-workspaces
+ *
+ * Requires:
+ *   - Docker running with auth-api container
+ *   - Tela monorepo path saved at ~/.tela/tela-repo-path (via CLI setup)
+ */
+import {
+    discoverLocalhostServices,
+    readSavedReposPath,
+    readAuthApiSecret,
+    fetchWorkspaces,
+} from './skill/localhost-utils.ts'
+
+const reposPath = readSavedReposPath()
+if (!reposPath) {
+    console.error('No tela repo path saved. Run CLI setup first: bunx @meistrari/tela-skills → select Localhost')
+    process.exit(1)
+}
+
+const services = discoverLocalhostServices()
+if (!services.authApiPort) {
+    console.error('auth-api Docker container not found. Are local services running?')
+    process.exit(1)
+}
+
+const secret = readAuthApiSecret(reposPath)
+const workspaces = await fetchWorkspaces(`http://localhost:${services.authApiPort}`, secret)
+
+if (workspaces.length === 0) {
+    console.log('No workspaces found.')
+    process.exit(0)
+}
+
+console.log('Available workspaces:')
+for (const ws of workspaces) {
+    console.log(`  - ${ws.title} (${ws.id}) [${ws.slug}]`)
+}

package/localhost.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+/**
+ * Run tela-skills against localhost (discovers ports via Docker).
+ * Usage: bun run localhost -- "console.log(await tela.listProjects())"
+ *    or: bun localhost.ts "console.log(await tela.listProjects())"
+ */
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { discoverLocalhostServices, writeLocalhostEnv } from './skill/localhost-utils.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TELA_PRELOAD = join(__dirname, 'skill', 'preload.ts')
+const SESSION_PATH = join(homedir(), '.tela', 'session.local')
+
+const args = process.argv.slice(2)
+const code = args.join(' ').trim()
+if (!code) {
+    console.error('Usage: bun localhost.ts "console.log(await tela.listProjects())"')
+    process.exit(1)
+}
+
+// Check session.local exists
+if (!existsSync(SESSION_PATH)) {
+    console.error('Error: No localhost session found at ~/.tela/session.local')
+    console.error('Run CLI setup first: bunx @meistrari/tela-skills → select Localhost')
+    process.exit(1)
+}
+
+// Discover ports from Docker
+const services = discoverLocalhostServices()
+if (!services.telaApiPort) {
+    console.error('Error: tela-api Docker container not found. Are local services running?')
+    process.exit(1)
+}
+
+// Write .env with discovered ports
+writeLocalhostEnv(services.telaApiPort, services.telaAppPort)
+
+const proc = Bun.spawn(['bun', '--preload', TELA_PRELOAD, '-e', code], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+})
+process.exit(await proc.exited)

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@meistrari/tela-skills",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Tela API skills for Claude Code",
   "type": "module",
   "bin": {
-    "tela-skills": "./cli.ts"
+    "tela-skills": "./cli.ts",
+    "tela-list-workspaces": "./list-workspaces.ts"
   },
   "scripts": {
+    "prepare": "ln -sf ../../scripts/pre-commit .git/hooks/pre-commit",
     "postinstall": "mise-en-place postinstall",
     "build": "echo \"No build step required, script placeholder for npm publish action compatibility\""
   },
   "files": [
     "cli.ts",
+    "localhost.ts",
+    "list-workspaces.ts",
     "skill/**/*"
   ],
   "keywords": [
@@ -29,7 +33,7 @@
     "open": "^11.0.0"
   },
   "devDependencies": {
-    "@meistrari/mise-en-place": "^2.10.3",
+    "@meistrari/mise-en-place": "^2.10.6",
     "bun-types": "^1.3.4"
   }
 }

package/skill/TELA_LOCALHOST_SKILL.md

@@ -0,0 +1,106 @@
+---
+name: tela-localhost
+description: Manage localhost workspaces for Tela. Switch workspaces, check status, and regenerate tokens for local development.
+---
+
+# Tela Localhost Workspace Manager
+
+Manage your local Tela development environment. Switch between workspaces, check connection status, and regenerate authentication tokens.
+
+## Prerequisites
+
+- Docker running with tela services (auth-api, tela-api)
+- Localhost environment configured via `bunx @meistrari/tela-skills` (select "Localhost")
+- Tela monorepo path saved at `~/.tela/tela-repo-path`
+
+## Commands
+
+### List Workspaces
+
+Show all available workspaces in the local environment.
+
+```bash
+bunx @meistrari/tela-skills/list-workspaces
+```
+
+Or if running from the repo directly:
+
+```bash
+bun list-workspaces.ts
+```
+
+### Switch Workspace
+
+Switch to a different workspace by generating a new JWT token.
+
+Replace `WORKSPACE_ID` and `WORKSPACE_TITLE` with the target workspace values from "List Workspaces".
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const { join } = await import('node:path')
+const { homedir } = await import('node:os')
+const lu = await import(join(homedir(), '.claude', 'skills', 'tela', 'localhost-utils.ts'))
+const reposPath = lu.readSavedReposPath()
+if (!reposPath) { console.error('No tela repo path saved. Run CLI setup first.'); process.exit(1) }
+
+const keys = lu.parseApiGatewayKeys(reposPath)
+const token = lu.signLocalhostJwt({
+    workspace: { id: 'WORKSPACE_ID', title: 'WORKSPACE_TITLE' },
+    privateKey: keys.privateKey,
+    kid: keys.kid,
+})
+lu.saveLocalhostSession(token)
+console.log('Switched to workspace: WORKSPACE_TITLE')
+console.log('New token saved to ~/.tela/session.local')
+"
+```
+
+### Check Status
+
+Verify localhost connection is working and show current workspace.
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const { readFileSync, existsSync } = await import('node:fs')
+const { join } = await import('node:path')
+const { homedir } = await import('node:os')
+
+const envPath = join(homedir(), '.tela', '.env')
+const sessionPath = join(homedir(), '.tela', 'session.local')
+
+if (!existsSync(sessionPath)) {
+    console.log('Status: NOT CONFIGURED')
+    console.log('Run CLI setup: bunx @meistrari/tela-skills → select Localhost')
+    process.exit(0)
+}
+
+// Decode JWT payload
+const token = readFileSync(sessionPath, 'utf-8').trim()
+const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString())
+console.log('Status: CONFIGURED')
+console.log('Workspace:', payload.workspace?.title, '(' + payload.workspace?.id + ')')
+console.log('Token expires:', new Date(payload.exp * 1000).toISOString())
+
+// Check env
+if (existsSync(envPath)) {
+    const env = readFileSync(envPath, 'utf-8')
+    console.log('API URL:', env.match(/TELA_API_URL=(.*)/)?.[1] || 'not set')
+    console.log('App URL:', env.match(/TELA_APP_URL=(.*)/)?.[1] || 'not set')
+}
+
+// Try a test call
+try {
+    const projects = await tela.listProjects()
+    console.log('Connection: OK (' + projects.length + ' projects)')
+} catch (e) {
+    console.log('Connection: FAILED -', e.message)
+}
+"
+```
+
+## Troubleshooting
+
+- **"auth-api not running"**: Start Docker services in the tela monorepo (`make dev`)
+- **"No tela repo path saved"**: Run `bunx @meistrari/tela-skills` and select Localhost to configure
+- **"Connection: FAILED"**: Check that tela-api Docker container is running (`docker ps | grep tela-api`)
+- **Token expired**: Tokens are auto-regenerated when expired. If auto-regeneration fails, use "Switch Workspace" to regenerate manually