@meistrari/tela-cli 0.1.0

package/src/diagnostics.ts

@@ -0,0 +1,578 @@
+import { accessSync, constants, existsSync, statSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { inspectSavedConfig, redactApiKey } from './config.ts'
+import {
+    findRepositoryRoot,
+    getCurrentBranch,
+    getHeadShortSha,
+    getOriginUrl,
+    getShortStatus,
+    getStatusCounts,
+    getUpstreamBranch,
+} from './git.ts'
+import { commandExists } from './process.ts'
+
+export type DiagnosticStatus = 'pass' | 'warn' | 'fail'
+export type AgentApiReachabilityCategory = 'invalid_url' | 'tls_error' | 'network_error' | 'http_response'
+
+export interface AgentApiReachability {
+    reachable: boolean
+    category: AgentApiReachabilityCategory
+    statusCode?: number
+    detail: string
+}
+
+export interface RepoSnapshot {
+    cwd: string
+    inRepository: boolean
+    repoRoot?: string
+    branch?: string
+    upstream?: string | null
+    detached: boolean
+    dirty: boolean
+    originUrl?: string | null
+    shortStatus?: string
+    head?: string
+    statusCounts?: {
+        staged: number
+        unstaged: number
+        untracked: number
+        total: number
+    }
+}
+
+export interface StatusReport {
+    ok: boolean
+    config: {
+        present: boolean
+        valid: boolean
+        path: string
+        agentApiUrl?: string
+        cloneRoot?: string
+        apiKey?: string
+        error?: string
+    }
+    repo: RepoSnapshot
+    tools: {
+        git: boolean
+        claude: boolean
+        agentApiReachable: boolean | null
+        agentApiCategory?: AgentApiReachabilityCategory
+        agentApiStatus?: number
+        agentApiDetail?: string
+    }
+    warnings: string[]
+    nextActions: string[]
+}
+
+export interface DoctorCheck {
+    id: string
+    group: string
+    status: DiagnosticStatus
+    summary: string
+    fixes: string[]
+    evidence?: string[]
+}
+
+export interface DoctorReport {
+    ok: boolean
+    checks: DoctorCheck[]
+    nextActions: string[]
+}
+
+function isDetachedHeadError(error: unknown): boolean {
+    return error instanceof Error && error.message.includes('Detached HEAD')
+}
+
+function classifyAgentApiReachabilityError(message: string): AgentApiReachabilityCategory {
+    return /tls|ssl|certificate|hostname|subject name/i.test(message)
+        ? 'tls_error'
+        : 'network_error'
+}
+
+export async function checkAgentApiReachability(url: string, fetchFn: typeof fetch = fetch): Promise<AgentApiReachability> {
+    try {
+        new URL(url)
+    }
+    catch {
+        return {
+            reachable: false,
+            category: 'invalid_url',
+            detail: 'Agent API origin URL must be a valid URL',
+        }
+    }
+
+    try {
+        const response = await fetchFn(url, {
+            method: 'GET',
+            signal: AbortSignal.timeout(5_000),
+        })
+
+        const detail = response.statusText
+            ? `HTTP ${response.status} ${response.statusText}`
+            : `HTTP ${response.status}`
+
+        return {
+            reachable: true,
+            category: 'http_response',
+            statusCode: response.status,
+            detail,
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error)
+        return {
+            reachable: false,
+            category: classifyAgentApiReachabilityError(detail),
+            detail,
+        }
+    }
+}
+
+export function getAgentApiOriginCheckStatus(reachability: AgentApiReachability): string {
+    switch (reachability.category) {
+        case 'http_response':
+            return 'responded'
+        case 'invalid_url':
+            return 'invalid-url'
+        case 'tls_error':
+            return 'tls-error'
+        case 'network_error':
+            return 'network-error'
+    }
+}
+
+export function getAgentApiOriginWarning(reachability: AgentApiReachability): string | undefined {
+    switch (reachability.category) {
+        case 'http_response':
+            return undefined
+        case 'invalid_url':
+            return `Agent API origin URL is invalid: ${reachability.detail}`
+        case 'tls_error':
+            return `Agent API origin TLS check failed: ${reachability.detail}`
+        case 'network_error':
+            return `Agent API origin is unreachable: ${reachability.detail}`
+    }
+}
+
+export function getAgentApiOriginFixes(reachability: AgentApiReachability): string[] {
+    switch (reachability.category) {
+        case 'http_response':
+            return ['No action required.']
+        case 'invalid_url':
+            return ['Run `tela setup` and choose production, staging, or a valid custom Agent API origin URL.']
+        case 'tls_error':
+            return ['Check the configured hostname and TLS certificate, or choose the correct Agent API target in `tela setup`.']
+        case 'network_error':
+            return ['Check your network connection, VPN, or the configured Agent API origin in `tela setup`.']
+    }
+}
+
+export function getAgentApiOriginSummary(url: string, reachability: AgentApiReachability): string {
+    switch (reachability.category) {
+        case 'http_response':
+            return `Agent API origin responded at ${url} (${reachability.detail})`
+        case 'invalid_url':
+            return `Agent API origin URL is invalid: ${url}`
+        case 'tls_error':
+            return `Agent API origin TLS check failed at ${url}`
+        case 'network_error':
+            return `Agent API origin is unreachable at ${url}`
+    }
+}
+
+export async function inspectCurrentRepository(cwd = process.cwd()): Promise<RepoSnapshot> {
+    const repoRoot = await findRepositoryRoot(cwd)
+    if (!repoRoot) {
+        return {
+            cwd,
+            inRepository: false,
+            detached: false,
+            dirty: false,
+        }
+    }
+
+    const shortStatus = await getShortStatus(repoRoot)
+    const dirty = Boolean(shortStatus.trim())
+    const statusCounts = await getStatusCounts(repoRoot)
+    const head = await getHeadShortSha(repoRoot)
+
+    let branch: string | undefined
+    let detached = false
+    try {
+        branch = await getCurrentBranch(repoRoot)
+    }
+    catch (error) {
+        if (!isDetachedHeadError(error)) {
+            throw error
+        }
+
+        detached = true
+    }
+
+    let upstream: string | null | undefined
+    if (!detached) {
+        upstream = await getUpstreamBranch(repoRoot)
+    }
+
+    let originUrl: string | null = null
+    try {
+        originUrl = await getOriginUrl(repoRoot)
+    }
+    catch {
+        originUrl = null
+    }
+
+    return {
+        cwd,
+        inRepository: true,
+        repoRoot,
+        branch,
+        upstream,
+        detached,
+        dirty,
+        originUrl,
+        shortStatus: shortStatus.trim() || undefined,
+        head,
+        statusCounts,
+    }
+}
+
+function buildStatusNextActions(warnings: string[], repo: RepoSnapshot, hasConfig: boolean): string[] {
+    const actions: string[] = []
+
+    if (!hasConfig) {
+        actions.push('Run `tela setup` to configure the CLI.')
+    }
+
+    if (!repo.inRepository) {
+        actions.push('Run `tela sync <repo>` or change into a cloned repository before mutating commands.')
+    }
+
+    if (repo.detached) {
+        actions.push('Check out a branch before syncing or pushing.')
+    }
+
+    if (repo.dirty) {
+        actions.push('Review local changes before syncing, or use `tela push` to stage and commit them.')
+    }
+
+    if (warnings.length === 0) {
+        actions.push('Run `tela sync --current`, `tela run`, or `tela push` when you are ready.')
+    }
+
+    return Array.from(new Set(actions))
+}
+
+export async function createStatusReport(
+    cwd = process.cwd(),
+    fetchFn: typeof fetch = fetch,
+): Promise<StatusReport> {
+    const [configInspection, gitAvailable, claudeAvailable, repo] = await Promise.all([
+        Promise.resolve(inspectSavedConfig()),
+        commandExists('git'),
+        commandExists('claude'),
+        inspectCurrentRepository(cwd),
+    ])
+
+    const warnings: string[] = []
+    let reachability: AgentApiReachability | undefined
+
+    if (!configInspection.exists) {
+        warnings.push('Tela CLI is not configured yet.')
+    }
+    else if (!configInspection.valid) {
+        warnings.push(`Tela CLI config is invalid: ${configInspection.error ?? 'unknown error'}`)
+    }
+
+    if (!gitAvailable) {
+        warnings.push('`git` is not available on PATH.')
+    }
+
+    if (!claudeAvailable) {
+        warnings.push('`claude` is not available on PATH.')
+    }
+
+    if (repo.detached) {
+        warnings.push('The current repository is on a detached HEAD.')
+    }
+
+    if (repo.dirty) {
+        warnings.push('The current repository has local changes.')
+    }
+
+    if (configInspection.valid && configInspection.config) {
+        reachability = await checkAgentApiReachability(configInspection.config.agentApiUrl, fetchFn)
+        const warning = getAgentApiOriginWarning(reachability)
+        if (warning) {
+            warnings.push(warning)
+        }
+    }
+
+    const nextActions = buildStatusNextActions(warnings, repo, Boolean(configInspection.valid))
+
+    return {
+        ok: warnings.length === 0,
+        config: {
+            present: configInspection.exists,
+            valid: configInspection.valid,
+            path: configInspection.path,
+            agentApiUrl: configInspection.config?.agentApiUrl,
+            cloneRoot: configInspection.config?.cloneRoot,
+            apiKey: configInspection.config ? redactApiKey(configInspection.config.apiKey) : undefined,
+            error: configInspection.error,
+        },
+        repo,
+        tools: {
+            git: gitAvailable,
+            claude: claudeAvailable,
+            agentApiReachable: reachability?.reachable ?? null,
+            agentApiCategory: reachability?.category,
+            agentApiStatus: reachability?.statusCode,
+            agentApiDetail: reachability?.detail,
+        },
+        warnings,
+        nextActions,
+    }
+}
+
+function buildCloneRootCheck(cloneRoot: string | undefined): DoctorCheck {
+    if (!cloneRoot) {
+        return {
+            id: 'clone-root',
+            group: 'filesystem',
+            status: 'warn',
+            summary: 'Clone root is unavailable because config is missing or invalid.',
+            fixes: ['Run `tela setup` to configure a clone root.'],
+        }
+    }
+
+    if (existsSync(cloneRoot)) {
+        const stats = statSync(cloneRoot)
+        if (!stats.isDirectory()) {
+            return {
+                id: 'clone-root',
+                group: 'filesystem',
+                status: 'fail',
+                summary: `Clone root exists but is not a directory: ${cloneRoot}`,
+                fixes: [
+                    `Move or remove \`${cloneRoot}\`, then rerun \`tela setup\`.`,
+                ],
+            }
+        }
+
+        try {
+            accessSync(cloneRoot, constants.R_OK | constants.W_OK | constants.X_OK)
+            return {
+                id: 'clone-root',
+                group: 'filesystem',
+                status: 'pass',
+                summary: `Clone root is ready: ${cloneRoot}`,
+                fixes: ['No action required.'],
+            }
+        }
+        catch (error) {
+            return {
+                id: 'clone-root',
+                group: 'filesystem',
+                status: 'fail',
+                summary: `Clone root is not writable: ${cloneRoot}`,
+                fixes: [
+                    `Fix permissions for \`${cloneRoot}\` or choose another clone root in \`tela setup\`.`,
+                ],
+                evidence: [error instanceof Error ? error.message : String(error)],
+            }
+        }
+    }
+
+    const parentDir = dirname(cloneRoot)
+    try {
+        accessSync(parentDir, constants.W_OK | constants.X_OK)
+        return {
+            id: 'clone-root',
+            group: 'filesystem',
+            status: 'warn',
+            summary: `Clone root does not exist yet: ${cloneRoot}`,
+            fixes: [
+                `Create it with \`mkdir -p ${cloneRoot}\` or rerun \`tela setup\`.`,
+            ],
+        }
+    }
+    catch (error) {
+        return {
+            id: 'clone-root',
+            group: 'filesystem',
+            status: 'fail',
+            summary: `Clone root parent is not writable: ${parentDir}`,
+            fixes: [
+                `Fix permissions for \`${parentDir}\` or choose another clone root in \`tela setup\`.`,
+            ],
+            evidence: [error instanceof Error ? error.message : String(error)],
+        }
+    }
+}
+
+function buildRepoChecks(repo: RepoSnapshot): DoctorCheck[] {
+    if (!repo.inRepository) {
+        return [
+            {
+                id: 'repo-context',
+                group: 'repository',
+                status: 'warn',
+                summary: 'Current directory is not inside a git repository.',
+                fixes: [
+                    'Change into a Tela repository or run `tela sync <repo>` first.',
+                ],
+            },
+        ]
+    }
+
+    const checks: DoctorCheck[] = [
+        {
+            id: 'repo-context',
+            group: 'repository',
+            status: 'pass',
+            summary: `Inside git repository: ${repo.repoRoot}`,
+            fixes: ['No action required.'],
+        },
+    ]
+
+    checks.push({
+        id: 'repo-head',
+        group: 'repository',
+        status: repo.detached ? 'fail' : 'pass',
+        summary: repo.detached
+            ? 'Repository is on a detached HEAD.'
+            : `Current branch is ${repo.branch}.`,
+        fixes: repo.detached
+            ? ['Check out a branch before syncing or pushing.']
+            : ['No action required.'],
+    })
+
+    checks.push({
+        id: 'repo-worktree',
+        group: 'repository',
+        status: repo.dirty ? 'warn' : 'pass',
+        summary: repo.dirty
+            ? 'Repository has local changes.'
+            : 'Repository worktree is clean.',
+        fixes: repo.dirty
+            ? ['Review the local diff before syncing, or use `tela push` to stage and commit changes.']
+            : ['No action required.'],
+        evidence: repo.shortStatus ? [repo.shortStatus] : undefined,
+    })
+
+    checks.push({
+        id: 'repo-upstream',
+        group: 'repository',
+        status: repo.detached ? 'warn' : (repo.upstream ? 'pass' : 'warn'),
+        summary: repo.detached
+            ? 'Upstream check skipped because HEAD is detached.'
+            : (repo.upstream
+                ? `Upstream branch is ${repo.upstream}.`
+                : 'Current branch does not track an upstream.'),
+        fixes: repo.detached
+            ? ['Check out a branch before configuring tracking.']
+            : (repo.upstream
+                ? ['No action required.']
+                : ['Push the branch once or run `git branch --set-upstream-to origin/<branch>` after creating the remote branch.']),
+    })
+
+    checks.push({
+        id: 'repo-origin',
+        group: 'repository',
+        status: repo.originUrl ? 'pass' : 'warn',
+        summary: repo.originUrl
+            ? `Origin remote: ${repo.originUrl}`
+            : 'Origin remote is missing.',
+        fixes: repo.originUrl
+            ? ['No action required.']
+            : ['Add an origin remote or run `tela sync <repo>` to clone a fresh checkout.'],
+    })
+
+    return checks
+}
+
+function buildNextActions(checks: DoctorCheck[]): string[] {
+    const failing = checks.filter(check => check.status !== 'pass')
+    if (failing.length === 0) {
+        return ['Environment looks healthy. Run `tela status`, `tela sync`, `tela run`, or `tela push` as needed.']
+    }
+
+    return Array.from(new Set(failing.flatMap(check => check.fixes))).slice(0, 5)
+}
+
+export async function createDoctorReport(
+    cwd = process.cwd(),
+    fetchFn: typeof fetch = fetch,
+): Promise<DoctorReport> {
+    const [configInspection, gitAvailable, claudeAvailable, repo] = await Promise.all([
+        Promise.resolve(inspectSavedConfig()),
+        commandExists('git'),
+        commandExists('claude'),
+        inspectCurrentRepository(cwd),
+    ])
+
+    const checks: DoctorCheck[] = [
+        configInspection.exists
+            ? (configInspection.valid
+                ? {
+                    id: 'config',
+                    group: 'config',
+                    status: 'pass',
+                    summary: `Config loaded from ${configInspection.path}`,
+                    fixes: ['No action required.'],
+                }
+                : {
+                    id: 'config',
+                    group: 'config',
+                    status: 'fail',
+                    summary: `Config file is invalid: ${configInspection.path}`,
+                    fixes: ['Run `tela setup` to rewrite the config file.'],
+                    evidence: configInspection.error ? [configInspection.error] : undefined,
+                })
+            : {
+                id: 'config',
+                group: 'config',
+                status: 'fail',
+                summary: 'Tela CLI config file is missing.',
+                fixes: ['Run `tela setup` to create the config file.'],
+            },
+        buildCloneRootCheck(configInspection.config?.cloneRoot),
+        {
+            id: 'tool-git',
+            group: 'tools',
+            status: gitAvailable ? 'pass' : 'fail',
+            summary: gitAvailable ? '`git` is available.' : '`git` is missing from PATH.',
+            fixes: gitAvailable ? ['No action required.'] : ['Install `git` and make sure it is available on PATH.'],
+        },
+        {
+            id: 'tool-claude',
+            group: 'tools',
+            status: claudeAvailable ? 'pass' : 'warn',
+            summary: claudeAvailable ? '`claude` is available.' : '`claude` is not available on PATH.',
+            fixes: claudeAvailable ? ['No action required.'] : ['Install the Claude CLI before using `tela run`, `tela push --claude`, or `tela feedback`.'],
+        },
+        ...buildRepoChecks(repo),
+    ]
+
+    if (configInspection.valid && configInspection.config) {
+        const reachability = await checkAgentApiReachability(configInspection.config.agentApiUrl, fetchFn)
+        checks.push({
+            id: 'agent-api-origin',
+            group: 'network',
+            status: reachability.reachable ? 'pass' : 'warn',
+            summary: getAgentApiOriginSummary(configInspection.config.agentApiUrl, reachability),
+            fixes: getAgentApiOriginFixes(reachability),
+            evidence: reachability.reachable ? undefined : [reachability.detail],
+        })
+    }
+
+    const nextActions = buildNextActions(checks)
+
+    return {
+        ok: checks.every(check => check.status === 'pass'),
+        checks,
+        nextActions,
+    }
+}

package/src/errors.ts

@@ -0,0 +1,122 @@
+import { CommandError } from './process.ts'
+import { errorCard, type RenderOptions } from './ui.ts'
+
+export interface UserFacingErrorInput {
+    code: string
+    summary: string
+    details?: string
+    fixes?: string[]
+    evidence?: string[]
+    exitCode?: number
+    cause?: unknown
+}
+
+export class UserFacingError extends Error {
+    public readonly code: string
+    public readonly summary: string
+    public readonly details?: string
+    public readonly fixes: string[]
+    public readonly evidence: string[]
+    public readonly exitCode: number
+    public readonly cause?: unknown
+
+    constructor(input: UserFacingErrorInput) {
+        super(input.summary)
+        this.name = 'UserFacingError'
+        this.code = input.code
+        this.summary = input.summary
+        this.details = input.details
+        this.fixes = input.fixes ?? []
+        this.evidence = input.evidence ?? []
+        this.exitCode = input.exitCode ?? 1
+        this.cause = input.cause
+    }
+}
+
+export function createUserFacingError(input: UserFacingErrorInput): UserFacingError {
+    return new UserFacingError(input)
+}
+
+export function isUserFacingError(error: unknown): error is UserFacingError {
+    return error instanceof UserFacingError
+}
+
+export function toUserFacingError(error: unknown): UserFacingError {
+    if (isUserFacingError(error)) {
+        return error
+    }
+
+    if (error instanceof CommandError) {
+        const stdout = error.result.stdout.trim()
+        const stderr = error.result.stderr.trim()
+        const evidence = [
+            `Command: ${error.result.command.join(' ')}`,
+            stdout ? `stdout: ${stdout}` : '',
+            stderr ? `stderr: ${stderr}` : '',
+        ].filter(Boolean)
+
+        return new UserFacingError({
+            code: 'command_failed',
+            summary: 'A local command failed.',
+            details: error.message,
+            evidence,
+            exitCode: 1,
+            cause: error,
+        })
+    }
+
+    if (error instanceof Error) {
+        return new UserFacingError({
+            code: 'unexpected_error',
+            summary: error.message,
+            exitCode: 1,
+            cause: error,
+        })
+    }
+
+    return new UserFacingError({
+        code: 'unexpected_error',
+        summary: String(error),
+        exitCode: 1,
+        cause: error,
+    })
+}
+
+export function renderUserFacingError(
+    error: unknown,
+    options: RenderOptions & { verbose?: boolean } = {},
+): string {
+    const userError = toUserFacingError(error)
+    const evidence = options.verbose ? userError.evidence : []
+
+    return errorCard({
+        summary: userError.summary,
+        details: userError.details,
+        fixes: userError.fixes,
+        evidence,
+    }, options)
+}
+
+export function serializeError(error: unknown): {
+    ok: false
+    error: {
+        code: string
+        summary: string
+        details?: string
+        fixes: string[]
+        evidence: string[]
+    }
+} {
+    const userError = toUserFacingError(error)
+
+    return {
+        ok: false,
+        error: {
+            code: userError.code,
+            summary: userError.summary,
+            details: userError.details,
+            fixes: userError.fixes,
+            evidence: userError.evidence,
+        },
+    }
+}