@meistrari/tela-skills 1.3.5 → 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.5",
+  "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": [

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

package/skill/common.ts

@@ -6,7 +6,11 @@ const SESSION_DIR = join(homedir(), '.tela')
 
 export function getSessionPath(): string {
     const apiUrl = getApiBaseUrl()
-    const env = apiUrl.includes('staging') ? 'staging' : 'production'
+    const env = apiUrl.includes('localhost')
+        ? 'local'
+        : apiUrl.includes('staging')
+          ? 'staging'
+          : 'production'
     return join(SESSION_DIR, `session.${env}`)
 }
 
@@ -34,12 +38,58 @@ export function getCanvasUrl(canvasId: string): string {
     return `${getAppBaseUrl()}/prompt/${canvasId}/craft`
 }
 
+export function isJwtExpired(token: string): boolean {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1]!, 'base64url').toString())
+        return typeof payload.exp === 'number' && payload.exp < Math.floor(Date.now() / 1000)
+    } catch {
+        return false
+    }
+}
+
+export function getJwtWorkspace(token: string): { id: string; title: string } | null {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1]!, 'base64url').toString())
+        return payload.workspace ?? null
+    } catch {
+        return null
+    }
+}
+
+function tryRegenerateLocalhostToken(token: string): string | null {
+    try {
+        const workspace = getJwtWorkspace(token)
+        if (!workspace) return null
+
+        const { readSavedReposPath, parseApiGatewayKeys, signLocalhostJwt, saveLocalhostSession } = require('./localhost-utils') as typeof import('./localhost-utils')
+
+        const reposPath = readSavedReposPath()
+        if (!reposPath) return null
+
+        const keys = parseApiGatewayKeys(reposPath)
+        const newToken = signLocalhostJwt({ workspace, privateKey: keys.privateKey, kid: keys.kid })
+        saveLocalhostSession(newToken)
+        return newToken
+    } catch {
+        return null
+    }
+}
+
 export function loadApiKey(): string {
     const sessionPath = getSessionPath()
     if (!existsSync(sessionPath)) {
         throw new Error(`No session found at ${sessionPath}. Run the installer to authenticate first.`)
     }
-    return readFileSync(sessionPath, 'utf-8').trim()
+    let token = readFileSync(sessionPath, 'utf-8').trim()
+
+    if (getApiBaseUrl().includes('localhost') && isJwtExpired(token)) {
+        const refreshed = tryRegenerateLocalhostToken(token)
+        if (refreshed) {
+            token = refreshed
+        }
+    }
+
+    return token
 }
 
 export function parsePayload(obj: unknown): unknown {

package/skill/localhost-utils.test.ts

@@ -0,0 +1,107 @@
+import { describe, test, expect } from 'bun:test'
+import { generateKeyPairSync, randomUUID } from 'node:crypto'
+import { mkdtempSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+// Generate a test RSA keypair
+const { publicKey: testPublicPem, privateKey: testPrivatePem } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+})
+const testKid = 'test-key-id-123'
+
+describe('localhost-utils', () => {
+    describe('parseApiGatewayKeys', () => {
+        test('parses multiline RSA keys from .env file', async () => {
+            const { parseApiGatewayKeys } = await import('./localhost-utils.ts')
+
+            // Create a temp directory mimicking the repo structure
+            const tmpDir = mkdtempSync(join(tmpdir(), 'tela-test-'))
+            const envDir = join(tmpDir, '.repositories', 'api-gateway')
+            mkdirSync(envDir, { recursive: true })
+
+            const envContent = `CURRENT_KEY_ID='${testKid}'\nCURRENT_KEY_PRIVATE='${testPrivatePem}'\nCURRENT_KEY_PUBLIC='${testPublicPem}'`
+            writeFileSync(join(envDir, '.env'), envContent)
+
+            const keys = parseApiGatewayKeys(tmpDir)
+            expect(keys.kid).toBe(testKid)
+            expect(keys.privateKey).toContain('BEGIN PRIVATE KEY')
+            expect(keys.publicKey).toContain('BEGIN PUBLIC KEY')
+        })
+
+        test('throws when .env file is missing', async () => {
+            const { parseApiGatewayKeys } = await import('./localhost-utils.ts')
+            expect(() => parseApiGatewayKeys('/nonexistent/path')).toThrow('api-gateway .env not found')
+        })
+    })
+
+    describe('signLocalhostJwt', () => {
+        test('produces a valid 3-part JWT', async () => {
+            const { signLocalhostJwt } = await import('./localhost-utils.ts')
+
+            const token = signLocalhostJwt({
+                workspace: { id: randomUUID(), title: 'Test Workspace' },
+                privateKey: testPrivatePem,
+                kid: testKid,
+            })
+
+            const parts = token.split('.')
+            expect(parts).toHaveLength(3)
+
+            // Decode and verify header
+            const header = JSON.parse(Buffer.from(parts[0]!, 'base64url').toString())
+            expect(header.alg).toBe('RS256')
+            expect(header.typ).toBe('JWT')
+            expect(header.kid).toBe(testKid)
+
+            // Decode and verify payload
+            const payload = JSON.parse(Buffer.from(parts[1]!, 'base64url').toString())
+            expect(payload.iss).toBe('api.tela.com')
+            expect(payload.workspace.title).toBe('Test Workspace')
+            expect(payload.requestId).toBeDefined()
+            expect(payload.iat).toBeDefined()
+            expect(payload.exp).toBeGreaterThan(payload.iat)
+        })
+    })
+
+    describe('getDockerPort', () => {
+        test('returns null for non-existent container', async () => {
+            const { getDockerPort } = await import('./localhost-utils.ts')
+            const port = getDockerPort('nonexistent-container-xyz')
+            expect(port).toBeNull()
+        })
+    })
+
+    describe('readAuthApiSecret', () => {
+        test('reads quoted AUTH_API_SECRET from tela-api .env', async () => {
+            const { readAuthApiSecret } = await import('./localhost-utils.ts')
+
+            const tmpDir = mkdtempSync(join(tmpdir(), 'tela-test-'))
+            const envDir = join(tmpDir, 'packages', 'api')
+            mkdirSync(envDir, { recursive: true })
+            writeFileSync(join(envDir, '.env'), "AUTH_API_SECRET='test-secret'\nOTHER=value\n")
+
+            const secret = readAuthApiSecret(tmpDir)
+            expect(secret).toBe('test-secret')
+        })
+
+        test('reads unquoted AUTH_API_SECRET from tela-api .env', async () => {
+            const { readAuthApiSecret } = await import('./localhost-utils.ts')
+
+            const tmpDir = mkdtempSync(join(tmpdir(), 'tela-test-'))
+            const envDir = join(tmpDir, 'packages', 'api')
+            mkdirSync(envDir, { recursive: true })
+            writeFileSync(join(envDir, '.env'), "AUTH_API_SECRET=chefs\nOTHER=value\n")
+
+            const secret = readAuthApiSecret(tmpDir)
+            expect(secret).toBe('chefs')
+        })
+
+        test('throws when .env missing', async () => {
+            const { readAuthApiSecret } = await import('./localhost-utils.ts')
+            expect(() => readAuthApiSecret('/nonexistent')).toThrow('tela-api .env not found')
+        })
+    })
+})

package/skill/localhost-utils.ts

@@ -0,0 +1,175 @@
+import { execFileSync } from 'node:child_process'
+import { createSign, randomUUID } from 'node:crypto'
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const SESSION_DIR = join(homedir(), '.tela')
+
+// --- Docker Discovery ---
+
+export function getDockerPort(container: string): number | null {
+    try {
+        const output = execFileSync('docker', ['port', container], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        })
+        const match = output.match(/-> [^:]+:(\d+)/)
+        return match ? parseInt(match[1]!, 10) : null
+    } catch {
+        return null
+    }
+}
+
+export function discoverLocalhostServices(): {
+    authApiPort: number | null
+    telaApiPort: number | null
+    telaAppPort: number | null
+} {
+    return {
+        authApiPort: getDockerPort('auth-api'),
+        telaApiPort: getDockerPort('tela-api'),
+        telaAppPort: getDockerPort('tela-app'),
+    }
+}
+
+// --- RSA Key Parsing ---
+
+function parseEnvFile(content: string): Record<string, string> {
+    return Object.fromEntries(
+        content
+            .replace(/\r\n/g, '\n')
+            .split(/\n(?=[A-Za-z_][A-Za-z0-9_]*=)/)
+            .filter((line) => !line.trimStart().startsWith('#'))
+            .map((line) => {
+                const firstEqual = line.indexOf('=')
+                if (firstEqual === -1) return [line, '']
+                const key = line.slice(0, firstEqual)
+                let value = line.slice(firstEqual + 1)
+                // Strip surrounding single or double quotes if present
+                if ((value.startsWith("'") && value.endsWith("'")) ||
+                    (value.startsWith('"') && value.endsWith('"'))) {
+                    value = value.slice(1, -1)
+                }
+                return [key, value]
+            }),
+    )
+}
+
+export function parseApiGatewayKeys(reposPath: string): {
+    kid: string
+    privateKey: string
+    publicKey: string
+} {
+    const envPath = join(reposPath, '.repositories', 'api-gateway', '.env')
+    if (!existsSync(envPath)) {
+        throw new Error(`api-gateway .env not found at ${envPath}`)
+    }
+    const content = readFileSync(envPath, 'utf-8')
+    const env = parseEnvFile(content)
+
+    const kid = env.CURRENT_KEY_ID
+    const privateKey = env.CURRENT_KEY_PRIVATE
+    const publicKey = env.CURRENT_KEY_PUBLIC
+
+    if (!kid || !privateKey || !publicKey) {
+        throw new Error(`Missing RSA key variables in ${envPath}. Expected: CURRENT_KEY_ID, CURRENT_KEY_PRIVATE, CURRENT_KEY_PUBLIC`)
+    }
+
+    return { kid, privateKey, publicKey }
+}
+
+// --- Auth API Secret ---
+
+export function readAuthApiSecret(reposPath: string): string {
+    const envPath = join(reposPath, 'packages', 'api', '.env')
+    if (!existsSync(envPath)) {
+        throw new Error(`tela-api .env not found at ${envPath}. Expected at: ${envPath}`)
+    }
+    const content = readFileSync(envPath, 'utf-8')
+    const env = parseEnvFile(content)
+    const secret = env.AUTH_API_SECRET
+    if (!secret) {
+        throw new Error(`AUTH_API_SECRET not found in ${envPath}`)
+    }
+    return secret
+}
+
+// --- JWT Signing ---
+
+export function signLocalhostJwt(opts: {
+    workspace: { id: string; title: string }
+    privateKey: string
+    kid: string
+}): string {
+    const header = { alg: 'RS256', typ: 'JWT', kid: opts.kid }
+    const b64 = (obj: object) => Buffer.from(JSON.stringify(obj)).toString('base64url')
+
+    const headerB64 = b64(header)
+    const payloadB64 = b64({
+        requestId: randomUUID(),
+        workspace: opts.workspace,
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60,
+        iss: 'api.tela.com',
+    })
+
+    const signature = createSign('RSA-SHA256')
+        .update(`${headerB64}.${payloadB64}`)
+        .sign(opts.privateKey, 'base64url')
+
+    return `${headerB64}.${payloadB64}.${signature}`
+}
+
+// --- Workspace Fetching ---
+
+export type Workspace = {
+    id: string
+    title: string
+    slug: string
+}
+
+export async function fetchWorkspaces(authApiUrl: string, authApiSecret: string): Promise<Workspace[]> {
+    const response = await fetch(`${authApiUrl}/organizations`, {
+        headers: { Authorization: `Bearer ${authApiSecret}` },
+    })
+
+    if (!response.ok) {
+        throw new Error(`Failed to fetch workspaces: ${response.status} ${response.statusText}`)
+    }
+
+    const { data } = await response.json() as { data: Workspace[] }
+    return data
+}
+
+// --- Session Management ---
+
+export function saveLocalhostSession(token: string): void {
+    mkdirSync(SESSION_DIR, { recursive: true })
+    writeFileSync(join(SESSION_DIR, 'session.local'), token, { mode: 0o600 })
+}
+
+export function writeLocalhostEnv(apiPort: number, appPort: number | null): void {
+    mkdirSync(SESSION_DIR, { recursive: true })
+    const apiUrl = `http://localhost:${apiPort}`
+    const appUrl = appPort ? `http://localhost:${appPort}` : `http://localhost:3000`
+    writeFileSync(
+        join(SESSION_DIR, '.env'),
+        `TELA_API_URL=${apiUrl}\nTELA_APP_URL=${appUrl}\n`,
+        { mode: 0o600 },
+    )
+}
+
+export function readSavedReposPath(): string | null {
+    const saved = join(SESSION_DIR, 'tela-repo-path')
+    if (existsSync(saved)) {
+        return readFileSync(saved, 'utf-8').trim() || null
+    }
+    return null
+}
+
+export function saveReposPath(reposPath: string): void {
+    mkdirSync(SESSION_DIR, { recursive: true })
+    writeFileSync(join(SESSION_DIR, 'tela-repo-path'), reposPath, { mode: 0o600 })
+}