@meistrari/tela-cli 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# Tela CLI
+
+Tela CLI is a one-shot terminal tool for syncing Tela repositories, running local agents, preparing pushes, and applying commit feedback with Claude.
+
+## Commands
+
+### `setup`
+
+Configure Tela CLI, choose an Agent API target, 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.
+
+Examples:
+- `tela setup` — Choose production, staging, or a custom API origin and run post-setup checks
+
+### `sync [repo]`
+
+Clone or update a Tela repository, or refresh the current checkout
+
+When to use: Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root.
+
+Examples:
+- `tela sync agent-api` — Clone or update a specific repository under the clone root
+- `tela sync --current` — Sync the repository for the current working directory
+- `tela sync --all` — Refresh every repository directly under the clone root
+
+### `run`
+
+Run the local agent repository with Claude
+
+When to use: Use this from inside an agent repository when you want Claude to follow the local contract files, show its progress live, and produce the expected result artifact.
+
+Examples:
+- `tela run` — Run the current agent repository with the live viewer
+- `tela run --plain` — Force scrollback-first text output
+- `tela run --json` — Emit the final execution and artifact envelope as JSON
+
+### `push`
+
+Preview, commit, and push the current repository
+
+When to use: Use this after reviewing local changes when you want Tela to stage everything, produce a commit message, and push the branch.
+
+Examples:
+- `tela push` — Choose the commit-message flow interactively
+- `tela push --claude` — Generate a commit message from the current worktree
+- `tela push --message "Update feedback flow"` — Skip prompts and use an explicit commit message
+
+### `feedback`
+
+Guided review of commit feedback with optional Claude handoff
+
+When to use: Use this after pushing or after a feedback-producing commit when you want a guided review of the feedback, a prompt preview before launch, and an outcome summary after Claude exits.
+
+Examples:
+- `tela feedback --list` — Open the guided review flow without launching Claude
+- `tela feedback --apply all` — Preview and launch Claude against every actionable suggestion
+- `tela feedback --apply select` — Choose specific actionable suggestions before launching Claude
+
+### `status`
+
+Show Tela config, tool availability, repo state, and Agent API origin reachability
+
+When to use: Use this for a quick snapshot of whether the local environment is ready before running mutating commands.
+
+Examples:
+- `tela status` — Render a human-readable environment summary
+- `tela status --json` — Emit a machine-readable status report
+
+### `doctor`
+
+Diagnose config, tools, filesystem state, repo health, and Agent API origin reachability
+
+When to use: Use this when Tela fails or behaves unexpectedly and you need exact remediation steps.
+
+Aliases: `diag`
+
+Examples:
+- `tela doctor` — Run the full diagnostic suite with remediation guidance
+- `tela doctor --json` — Emit structured diagnostic output for scripts
+
+## Output modes
+
+- 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
+
+1. `tela setup`
+2. `tela status`
+3. `tela sync <repo>` or `tela sync --current`
+4. `tela run`
+5. `tela push`
+6. `tela feedback --list`

package/cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+
+import { renderUserFacingError, serializeError, toUserFacingError } from './src/errors.ts'
+import { main } from './src/program.ts'
+
+function hasFlag(argv: string[], flag: string): boolean {
+    return argv.includes(flag)
+}
+
+try {
+    await main(process.argv)
+}
+catch (error) {
+    if (hasFlag(process.argv, '--json')) {
+        process.stderr.write(`${JSON.stringify(serializeError(error), null, 2)}\n`)
+    }
+    else {
+        process.stderr.write(`${renderUserFacingError(error, {
+            decorate: Boolean(process.stderr.isTTY),
+            verbose: hasFlag(process.argv, '--verbose'),
+        })}\n`)
+    }
+
+    process.exitCode = toUserFacingError(error).exitCode
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@meistrari/tela-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "tela": "cli.ts"
+  },
+  "files": [
+    "cli.ts",
+    "src/**/*"
+  ],
+  "scripts": {
+    "build": "bun build --compile ./cli.ts --outfile ./dist/tela",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "13.1.0",
+    "ink": "6.2.3",
+    "react": "19"
+  },
+  "devDependencies": {
+    "@types/react": "19",
+    "bun-types": "1.3.4",
+    "ink-testing-library": "4.0.0"
+  },
+  "patchedDependencies": {
+    "ink@6.2.3": "patches/ink@6.2.3.patch"
+  }
+}

package/src/agent-api.ts

@@ -0,0 +1,124 @@
+import { buildAgentApiHeaders, type FetchLike } from './auth.ts'
+import type {
+    AgentFeedbackItem,
+    AgentFeedbackListResponse,
+    RepositoryLookupResponse,
+    TelaCliConfig,
+} from './types.ts'
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+function joinUrl(baseUrl: string, path: string): string {
+    return new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString()
+}
+
+function parseJsonBody(responseText: string): unknown {
+    try {
+        return responseText ? JSON.parse(responseText) as unknown : null
+    }
+    catch {
+        return null
+    }
+}
+
+function isFeedbackItem(value: unknown): value is AgentFeedbackItem {
+    if (!value || typeof value !== 'object') {
+        return false
+    }
+
+    const candidate = value as Partial<AgentFeedbackItem>
+    return (candidate.status === 'success' || candidate.status === 'failed')
+        && typeof candidate.reason === 'string'
+        && typeof candidate.suggestion === 'string'
+}
+
+export class AgentApiError extends Error {
+    constructor(
+        message: string,
+        public readonly status: number,
+        public readonly responseBody: string,
+    ) {
+        super(message)
+    }
+}
+
+export async function fetchRepositoryLookup(
+    repository: string,
+    config: TelaCliConfig,
+    fetchFn: FetchLike = fetch,
+): Promise<Required<Pick<RepositoryLookupResponse, 'organization' | 'agentRepo' | 'forgejoRepository'>> & { success: true }> {
+    const response = await fetchFn(
+        joinUrl(config.agentApiUrl, `/v3/agents/repositories/${encodeURIComponent(repository)}`),
+        {
+            method: 'GET',
+            headers: buildAgentApiHeaders(config),
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        },
+    )
+
+    const responseText = await response.text()
+    const payload = parseJsonBody(responseText) as RepositoryLookupResponse | null
+
+    if (!response.ok) {
+        throw new AgentApiError(
+            payload?.error ?? `Agent API lookup failed with status ${response.status}`,
+            response.status,
+            responseText,
+        )
+    }
+
+    if (!payload?.success || !payload.organization || !payload.agentRepo || !payload.forgejoRepository) {
+        throw new AgentApiError('Agent API lookup returned an invalid payload', response.status, responseText)
+    }
+
+    return {
+        success: true,
+        organization: payload.organization,
+        agentRepo: payload.agentRepo,
+        forgejoRepository: payload.forgejoRepository,
+    }
+}
+
+export async function fetchCommitFeedback(
+    organizationName: string,
+    repository: string,
+    commitHash: string,
+    config: TelaCliConfig,
+    fetchFn: FetchLike = fetch,
+): Promise<AgentFeedbackListResponse> {
+    const response = await fetchFn(
+        joinUrl(
+            config.agentApiUrl,
+            `/v3/agents/${encodeURIComponent(organizationName)}/${encodeURIComponent(repository)}/feedback?commitHash=${encodeURIComponent(commitHash)}`,
+        ),
+        {
+            method: 'GET',
+            headers: buildAgentApiHeaders(config),
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        },
+    )
+
+    const responseText = await response.text()
+    const payload = parseJsonBody(responseText) as Partial<AgentFeedbackListResponse> & { error?: string } | null
+
+    if (!response.ok) {
+        throw new AgentApiError(
+            payload?.error ?? `Agent API feedback lookup failed with status ${response.status}`,
+            response.status,
+            responseText,
+        )
+    }
+
+    if (!payload
+        || typeof payload.commitHash !== 'string'
+        || payload.commitHash !== commitHash
+        || !Array.isArray(payload.feedbacks)
+        || !payload.feedbacks.every(isFeedbackItem)) {
+        throw new AgentApiError('Agent API feedback lookup returned an invalid payload', response.status, responseText)
+    }
+
+    return {
+        commitHash: payload.commitHash,
+        feedbacks: payload.feedbacks,
+    }
+}

package/src/auth.ts

@@ -0,0 +1,16 @@
+import type { TelaCliConfig } 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()}`
+}
+
+export function buildAgentApiHeaders(
+    config: Pick<TelaCliConfig, 'apiKey'>,
+): Record<string, string> {
+    return {
+        Authorization: buildAuthorizationHeader(config),
+        Accept: 'application/json',
+    }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,35 @@
+import { createDoctorReport, type DoctorReport } from '../diagnostics.ts'
+import { nextActions, resultCard, section, table, type RenderOptions } from '../ui.ts'
+
+const STATUS_LABEL: Record<'pass' | 'warn' | 'fail', string> = {
+    pass: 'PASS',
+    warn: 'WARN',
+    fail: 'FAIL',
+}
+
+export function renderDoctorReport(report: DoctorReport, options: RenderOptions = {}): string {
+    const rows = report.checks.map(check => [
+        check.group,
+        STATUS_LABEL[check.status],
+        check.summary,
+    ])
+
+    const remediation = report.checks
+        .filter(check => check.status !== 'pass')
+        .map((check) => {
+            const fixes = check.fixes.map(fix => `- ${fix}`).join('\n')
+            const evidence = check.evidence?.length ? `\n\nEvidence\n${check.evidence.map(item => `- ${item}`).join('\n')}` : ''
+            return `${check.summary}\n${fixes}${evidence}`
+        })
+        .join('\n\n')
+
+    return resultCard('Tela doctor', [
+        section('Checks', table(['Group', 'Status', 'Summary'], rows, options), options),
+        remediation ? section('Remediation', remediation, options) : undefined,
+        nextActions(report.nextActions, options),
+    ], options)
+}
+
+export async function getDoctorReport(cwd = process.cwd(), fetchFn: typeof fetch = fetch): Promise<DoctorReport> {
+    return await createDoctorReport(cwd, fetchFn)
+}