@meistrari/tela-cli 0.1.1 → 0.3.0

package/README.md

@@ -18,12 +18,12 @@ source ~/.zshrc
 
 ### `setup`
 
-Configure Tela CLI, choose an Agent API target, and verify the local environment
+Configure Tela CLI, sign in with device flow, choose the workspace organization, provision Forgejo access, and verify the local environment
 
-When to use: Run this first on a new machine, or any time your Agent API target/origin, clone root, or key changes.
+When to use: Run this first on a new machine, or any time your environment target, clone root, Tela session, or SSH key changes.
 
 Examples:
-- `tela setup` — Choose production, staging, or a custom API origin and run post-setup checks
+- `tela setup` — Choose production, staging, or a custom environment, complete browser-based sign-in, select the workspace organization, and provision Forgejo access with an SSH key
 
 ### `sync [repo]`
 
@@ -71,7 +71,7 @@ Examples:
 
 ### `status`
 
-Show Tela config, tool availability, repo state, and Agent API origin reachability
+Show Tela config, session state, tool availability, repo state, and Agent API reachability
 
 When to use: Use this for a quick snapshot of whether the local environment is ready before running mutating commands.
 
@@ -81,7 +81,7 @@ Examples:
 
 ### `doctor`
 
-Diagnose config, tools, filesystem state, repo health, and Agent API origin reachability
+Diagnose config, auth session, tools, filesystem state, repo health, and Agent API reachability
 
 When to use: Use this when Tela fails or behaves unexpectedly and you need exact remediation steps.
 
@@ -95,7 +95,6 @@ Examples:
 
 - Human output is structured for terminal use with grouped summaries and next actions.
 - `--json` is available on read-heavy flows and on `tela run` for the final execution envelope.
-- `--silent-bark` disables bark audio during interactive Ink startup while keeping the visual intro.
 
 ## First run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "tela": "cli.ts"
@@ -17,6 +17,8 @@
     "typecheck": "bunx tsc --noEmit"
   },
   "dependencies": {
+    "@meistrari/auth-cli": "^1.0.1",
+    "better-auth": "^1.6.3",
     "commander": "13.1.0",
     "ink": "6.2.3",
     "react": "19"
@@ -29,4 +31,4 @@
   "patchedDependencies": {
     "ink@6.2.3": "patches/ink@6.2.3.patch"
   }
-}
+}

package/src/agent-api.ts

@@ -2,8 +2,12 @@ import { buildAgentApiHeaders, type FetchLike } from './auth.ts'
 import type {
     AgentFeedbackItem,
     AgentFeedbackListResponse,
+    ForgejoUserCreateResponse,
+    ForgejoUserSshKeyInput,
+    OrganizationListResponse,
     RepositoryLookupResponse,
     TelaCliConfig,
+    TelaCliForgejoOrganization,
 } from './types.ts'
 
 const DEFAULT_TIMEOUT_MS = 10_000
@@ -32,6 +36,15 @@ function isFeedbackItem(value: unknown): value is AgentFeedbackItem {
         && typeof candidate.suggestion === 'string'
 }
 
+function isForgejoOrganization(value: unknown): value is TelaCliForgejoOrganization {
+    if (!value || typeof value !== 'object') {
+        return false
+    }
+
+    const candidate = value as Partial<TelaCliForgejoOrganization>
+    return typeof candidate.id === 'string' && typeof candidate.name === 'string'
+}
+
 export class AgentApiError extends Error {
     constructor(
         message: string,
@@ -47,11 +60,12 @@ export async function fetchRepositoryLookup(
     config: TelaCliConfig,
     fetchFn: FetchLike = fetch,
 ): Promise<Required<Pick<RepositoryLookupResponse, 'organization' | 'agentRepo' | 'forgejoRepository'>> & { success: true }> {
+    const headers = await buildAgentApiHeaders(config, { fetchFn })
     const response = await fetchFn(
         joinUrl(config.agentApiUrl, `/v3/agents/repositories/${encodeURIComponent(repository)}`),
         {
             method: 'GET',
-            headers: buildAgentApiHeaders(config),
+            headers,
             signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
         },
     )
@@ -86,6 +100,7 @@ export async function fetchCommitFeedback(
     config: TelaCliConfig,
     fetchFn: FetchLike = fetch,
 ): Promise<AgentFeedbackListResponse> {
+    const headers = await buildAgentApiHeaders(config, { fetchFn })
     const response = await fetchFn(
         joinUrl(
             config.agentApiUrl,
@@ -93,7 +108,7 @@ export async function fetchCommitFeedback(
         ),
         {
             method: 'GET',
-            headers: buildAgentApiHeaders(config),
+            headers,
             signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
         },
     )
@@ -122,3 +137,88 @@ export async function fetchCommitFeedback(
         feedbacks: payload.feedbacks,
     }
 }
+
+export async function listOrganizations(
+    config: TelaCliConfig,
+    fetchFn: FetchLike = fetch,
+): Promise<TelaCliForgejoOrganization[]> {
+    const headers = await buildAgentApiHeaders(config, { fetchFn })
+    const response = await fetchFn(
+        joinUrl(config.agentApiUrl, '/v3/organizations'),
+        {
+            method: 'GET',
+            headers,
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        },
+    )
+
+    const responseText = await response.text()
+    const payload = parseJsonBody(responseText) as OrganizationListResponse | null
+
+    if (!response.ok) {
+        throw new AgentApiError(
+            payload?.error ?? `Agent API organization lookup failed with status ${response.status}`,
+            response.status,
+            responseText,
+        )
+    }
+
+    if (!payload
+        || payload.success !== true
+        || !Array.isArray(payload.organizations)
+        || !payload.organizations.every(isForgejoOrganization)) {
+        throw new AgentApiError('Agent API organization lookup returned an invalid payload', response.status, responseText)
+    }
+
+    return payload.organizations
+}
+
+export async function provisionForgejoUser(
+    input: {
+        organizationName: string
+        sshKey: ForgejoUserSshKeyInput
+    },
+    config: TelaCliConfig,
+    fetchFn: FetchLike = fetch,
+): Promise<ForgejoUserCreateResponse> {
+    const headers = await buildAgentApiHeaders(config, { fetchFn })
+    const response = await fetchFn(
+        joinUrl(config.agentApiUrl, '/v3/forgejo/users'),
+        {
+            method: 'POST',
+            headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                organizationName: input.organizationName,
+                sshKey: input.sshKey,
+            }),
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        },
+    )
+
+    const responseText = await response.text()
+    const payload = parseJsonBody(responseText) as ForgejoUserCreateResponse | null
+
+    if (!response.ok) {
+        throw new AgentApiError(
+            payload?.error ?? `Agent API Forgejo user provisioning failed with status ${response.status}`,
+            response.status,
+            responseText,
+        )
+    }
+
+    if (!payload
+        || payload.success !== true
+        || typeof payload.username !== 'string'
+        || typeof payload.organizationName !== 'string'
+        || typeof payload.teamName !== 'string'
+        || typeof payload.userCreated !== 'boolean'
+        || typeof payload.teamCreated !== 'boolean'
+        || typeof payload.sshKeyCreated !== 'boolean') {
+        throw new AgentApiError('Agent API Forgejo user provisioning returned an invalid payload', response.status, responseText)
+    }
+
+    return payload
+}

package/src/assets.d.ts

@@ -0,0 +1,4 @@
+declare module '*.mp3' {
+    const assetPath: string
+    export default assetPath
+}

package/src/auth.ts

@@ -1,16 +1,432 @@
-import type { TelaCliConfig } from './types.ts'
+import {
+    DeviceAccessDeniedError,
+    DeviceCodeExpiredError,
+    DeviceFlow,
+    DeviceFlowAbortedError,
+    RefreshTokenExpiredError,
+} from '@meistrari/auth-cli'
+import {
+    clearSavedAuth,
+    isPlaceholderApplicationId,
+    saveConfig,
+} from './config.ts'
+import { createUserFacingError } from './errors.ts'
+import { runCommand } from './process.ts'
+import type {
+    TelaCliAuthState,
+    TelaCliConfig,
+    TelaCliUser,
+    TelaCliWorkspace,
+} from './types.ts'
 
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
 
-export function buildAuthorizationHeader(config: Pick<TelaCliConfig, 'apiKey'>): string {
-    return `Bearer ${config.apiKey.trim()}`
+type StoredTokensLike = {
+    accessToken: string
+    refreshToken: string
+    expiresAt: number
+    user: {
+        id: string
+        email: string
+        name?: string | null
+    }
+    organization: {
+        id: string
+        name?: string | null
+        title?: string | null
+        slug?: string | null
+    }
+}
+
+export interface DeviceFlowLike {
+    on(
+        eventName: 'userCode',
+        listener: (payload: {
+            userCode: string
+            verificationUri: string
+            verificationUriComplete: string
+            expiresIn: number
+            interval: number
+        }) => void | Promise<void>,
+    ): unknown
+    on(
+        eventName: 'pending',
+        listener: (payload: { attempt: number, elapsedMs: number }) => void | Promise<void>,
+    ): unknown
+    on(
+        eventName: 'slowDown',
+        listener: (payload: { previousInterval: number, newInterval: number }) => void | Promise<void>,
+    ): unknown
+    on(
+        eventName: 'transientError',
+        listener: (payload: { attempt: number }) => void | Promise<void>,
+    ): unknown
+    authenticate(): Promise<StoredTokensLike>
+    refresh(refreshToken?: string): Promise<StoredTokensLike>
+}
+
+export type DeviceFlowFactory = (input: {
+    apiUrl: string
+    requesterApplicationId: string
+    targetApplicationId: string
+    signal?: AbortSignal
+}) => DeviceFlowLike
+
+export interface SetupAuthEvent {
+    type: 'message' | 'user_code' | 'browser_opened' | 'browser_open_failed' | 'success'
+    message: string
+    title?: string
+    verificationUrl?: string
+    userCode?: string
+    expiresInSeconds?: number
+}
+
+export interface AuthenticateWithDeviceFlowOptions {
+    createDeviceFlow?: DeviceFlowFactory
+    openBrowser?: (url: string) => Promise<boolean>
+    timeoutMs?: number
+    onEvent?: (event: SetupAuthEvent) => void
+}
+
+export interface BuildAgentApiHeadersOptions {
+    clearAuth?: (config: TelaCliConfig) => TelaCliConfig
+    createDeviceFlow?: DeviceFlowFactory
+    fetchFn?: FetchLike
+    nowMs?: number
+    persistConfig?: (config: TelaCliConfig) => void
+}
+
+function defaultDeviceFlowFactory(input: ConstructorParameters<typeof DeviceFlow>[0]): DeviceFlowLike {
+    return new DeviceFlow(input)
+}
+
+function createAuthRequiredError(summary: string): ReturnType<typeof createUserFacingError> {
+    return createUserFacingError({
+        code: 'auth_required',
+        summary,
+        fixes: ['Run `tela setup` in an interactive terminal to sign in again.'],
+    })
+}
+
+function mapUser(user: StoredTokensLike['user']): TelaCliUser {
+    return {
+        id: user.id,
+        email: user.email,
+        name: user.name?.trim() || user.email,
+    }
+}
+
+function mapWorkspace(organization: StoredTokensLike['organization']): TelaCliWorkspace {
+    return {
+        id: organization.id,
+        title: organization.name?.trim()
+            || organization.title?.trim()
+            || organization.slug?.trim()
+            || organization.id,
+    }
+}
+
+function mapTokens(tokens: StoredTokensLike): TelaCliAuthState {
+    return {
+        user: mapUser(tokens.user),
+        workspace: mapWorkspace(tokens.organization),
+        session: {
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: tokens.expiresAt,
+        },
+    }
+}
+
+function buildDashboardVerificationUrl(dashboardUrl: string, userCode: string, fallbackUrl: string): string {
+    try {
+        const url = new URL('/applications/device', dashboardUrl)
+        url.searchParams.set('user_code', userCode)
+        return url.toString()
+    }
+    catch {
+        return fallbackUrl
+    }
+}
+
+async function defaultOpenBrowser(url: string): Promise<boolean> {
+    const command = (() => {
+        switch (process.platform) {
+            case 'darwin':
+                return ['open', url]
+            case 'win32':
+                return ['cmd', '/c', 'start', '', url]
+            default:
+                return ['xdg-open', url]
+        }
+    })()
+
+    try {
+        const result = await runCommand(command, { allowFailure: true })
+        return result.exitCode === 0
+    }
+    catch {
+        return false
+    }
 }
 
-export function buildAgentApiHeaders(
-    config: Pick<TelaCliConfig, 'apiKey'>,
-): Record<string, string> {
+function ensurePresetApplicationIds(input: {
+    environment: TelaCliConfig['environment']
+    requesterApplicationId: string
+    targetApplicationId: string
+}): void {
+    if (input.environment === 'custom') {
+        return
+    }
+
+    if (!isPlaceholderApplicationId(input.requesterApplicationId) && !isPlaceholderApplicationId(input.targetApplicationId)) {
+        return
+    }
+
+    throw createUserFacingError({
+        code: 'setup_preset_incomplete',
+        summary: `The ${input.environment} auth preset is missing the real Tela CLI application IDs.`,
+        fixes: [
+            'Update the production/staging requester and target application IDs in `src/config.ts`, or use the custom setup target.',
+        ],
+    })
+}
+
+export async function authenticateWithDeviceFlow(
+    input: Pick<TelaCliConfig, 'environment' | 'authApiUrl' | 'authDashboardUrl' | 'requesterApplicationId' | 'targetApplicationId'>,
+    options: AuthenticateWithDeviceFlowOptions = {},
+): Promise<TelaCliAuthState> {
+    ensurePresetApplicationIds(input)
+
+    const timeoutMs = options.timeoutMs ?? (15 * 60 * 1000)
+    const signal = AbortSignal.timeout(timeoutMs)
+    const createDeviceFlow = options.createDeviceFlow ?? defaultDeviceFlowFactory
+    const openBrowser = options.openBrowser ?? defaultOpenBrowser
+    const emit = (event: SetupAuthEvent) => {
+        options.onEvent?.(event)
+    }
+
+    const flow = createDeviceFlow({
+        apiUrl: input.authApiUrl,
+        requesterApplicationId: input.requesterApplicationId,
+        targetApplicationId: input.targetApplicationId,
+        signal,
+    })
+
+    flow.on('userCode', async ({ userCode, verificationUriComplete, expiresIn }) => {
+        const verificationUrl = buildDashboardVerificationUrl(
+            input.authDashboardUrl,
+            userCode,
+            verificationUriComplete,
+        )
+
+        emit({
+            type: 'user_code',
+            title: 'Authentication',
+            message: `Open ${verificationUrl}\nUser code: ${userCode}\nCode expires in ${expiresIn}s`,
+            verificationUrl,
+            userCode,
+            expiresInSeconds: expiresIn,
+        })
+
+        const opened = await openBrowser(verificationUrl)
+        emit(opened
+            ? {
+                type: 'browser_opened',
+                title: 'Authentication',
+                message: 'Opened the verification URL in your browser.',
+                verificationUrl,
+            }
+            : {
+                type: 'browser_open_failed',
+                title: 'Authentication',
+                message: 'Could not open the browser automatically. Open the verification URL manually.',
+                verificationUrl,
+            })
+    })
+
+    flow.on('pending', ({ attempt }) => {
+        emit({
+            type: 'message',
+            title: 'Authentication',
+            message: `[poll ${attempt}] Waiting for approval...`,
+        })
+    })
+
+    flow.on('slowDown', ({ newInterval }) => {
+        emit({
+            type: 'message',
+            title: 'Authentication',
+            message: `Server requested a slower polling interval (${newInterval}s).`,
+        })
+    })
+
+    flow.on('transientError', ({ attempt }) => {
+        emit({
+            type: 'message',
+            title: 'Authentication',
+            message: `[poll ${attempt}] Temporary auth server error. Retrying...`,
+        })
+    })
+
+    try {
+        const tokens = await flow.authenticate()
+        const auth = mapTokens(tokens)
+        emit({
+            type: 'success',
+            title: 'Authentication',
+            message: `Signed in as ${auth.user.email} for workspace ${auth.workspace.title}.`,
+        })
+        return auth
+    }
+    catch (error) {
+        if (error instanceof DeviceAccessDeniedError) {
+            throw createUserFacingError({
+                code: 'device_access_denied',
+                summary: 'The device authorization request was denied.',
+                fixes: ['Run `tela setup` again and approve the request in the browser.'],
+            })
+        }
+
+        if (error instanceof DeviceCodeExpiredError) {
+            throw createUserFacingError({
+                code: 'device_code_expired',
+                summary: 'The device authorization expired before approval completed.',
+                fixes: ['Run `tela setup` again and approve the request before the code expires.'],
+            })
+        }
+
+        if (error instanceof DeviceFlowAbortedError) {
+            throw createUserFacingError({
+                code: 'device_flow_timeout',
+                summary: `Timed out waiting for device authorization after ${Math.round(timeoutMs / 60_000)} minutes.`,
+                fixes: ['Run `tela setup` again and complete the browser approval before the timeout.'],
+            })
+        }
+
+        throw error
+    }
+}
+
+async function refreshAuthState(
+    config: TelaCliConfig,
+    options: BuildAgentApiHeadersOptions,
+): Promise<TelaCliAuthState> {
+    if (!config.auth?.session.refreshToken) {
+        throw createAuthRequiredError('Tela CLI is not authenticated.')
+    }
+
+    const createDeviceFlow = options.createDeviceFlow ?? defaultDeviceFlowFactory
+    const flow = createDeviceFlow({
+        apiUrl: config.authApiUrl,
+        requesterApplicationId: config.requesterApplicationId,
+        targetApplicationId: config.targetApplicationId,
+        signal: AbortSignal.timeout(10_000),
+    })
+
+    try {
+        const refreshed = await flow.refresh(config.auth.session.refreshToken)
+        const nextAuth = mapTokens(refreshed)
+        const nextConfig: TelaCliConfig = {
+            ...config,
+            auth: nextAuth,
+        }
+        ;(options.persistConfig ?? saveConfig)(nextConfig)
+        config.auth = nextAuth
+        return nextAuth
+    }
+    catch (error) {
+        if (error instanceof RefreshTokenExpiredError) {
+            ;(options.clearAuth ?? clearSavedAuth)(config)
+            config.auth = null
+            throw createAuthRequiredError('The saved Tela session expired and must be reauthenticated.')
+        }
+
+        throw error
+    }
+}
+
+async function getValidAccessToken(
+    config: TelaCliConfig,
+    options: BuildAgentApiHeadersOptions = {},
+): Promise<string> {
+    if (!config.auth?.session.accessToken) {
+        throw createAuthRequiredError('Tela CLI is not authenticated.')
+    }
+
+    const nowMs = options.nowMs ?? Date.now()
+    if (config.auth.session.expiresAt > nowMs + 30_000) {
+        return config.auth.session.accessToken
+    }
+
+    const nextAuth = await refreshAuthState(config, options)
+    return nextAuth.session.accessToken
+}
+
+type DataTokenResponse = {
+    dataToken?: string
+    error?: string
+}
+
+async function exchangeDataToken(
+    config: TelaCliConfig,
+    accessToken: string,
+    fetchFn: FetchLike,
+): Promise<string> {
+    const dataTokenUrl = new URL('/data-token', config.authApiUrl)
+    dataTokenUrl.searchParams.set('expiresAt', '1d')
+
+    const response = await fetchFn(dataTokenUrl.toString(), {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: 'application/json',
+        },
+        signal: AbortSignal.timeout(10_000),
+    })
+
+    const responseText = await response.text()
+    let payload: DataTokenResponse | null = null
+    try {
+        payload = responseText ? JSON.parse(responseText) as DataTokenResponse : null
+    }
+    catch {
+        payload = null
+    }
+
+    if (!response.ok) {
+        throw createUserFacingError({
+            code: 'data_token_exchange_failed',
+            summary: payload?.error ?? `Tela data-token exchange failed with status ${response.status}.`,
+            fixes: ['Run `tela setup` again if the saved session is stale.'],
+            evidence: responseText ? [responseText] : [],
+        })
+    }
+
+    const headerToken = response.headers.get('x-data-token')?.trim()
+    const dataToken = headerToken || payload?.dataToken?.trim()
+    if (!dataToken) {
+        throw createUserFacingError({
+            code: 'data_token_exchange_invalid',
+            summary: 'Tela data-token exchange returned an invalid response.',
+            fixes: ['Run `tela setup` again if the saved session is stale.'],
+            evidence: responseText ? [responseText] : [],
+        })
+    }
+
+    return dataToken
+}
+
+export async function buildAgentApiHeaders(
+    config: TelaCliConfig,
+    options: BuildAgentApiHeadersOptions = {},
+): Promise<Record<string, string>> {
+    const fetchFn = options.fetchFn ?? fetch
+    const accessToken = await getValidAccessToken(config, options)
+    const dataToken = await exchangeDataToken(config, accessToken, fetchFn)
+
     return {
-        Authorization: buildAuthorizationHeader(config),
+        'x-data-token': dataToken,
         Accept: 'application/json',
     }
 }

package/src/commands/feedback.ts

@@ -540,7 +540,7 @@ export async function runFeedbackCommand(options: RunFeedbackCommandOptions): Pr
     const runInteractiveCommandFn = options.runInteractiveCommand ?? runInteractiveCommand
     const selectionMode = getFeedbackSelectionMode(options)
 
-    const config: TelaCliConfig = await ensureConfig({ prompts })
+    const config: TelaCliConfig = await ensureConfig()
     const data = await loadFeedbackData({
         cwd: repoRoot,
         config,