@meistrari/tela-cli 0.1.0

package/src/commands/metadata.ts

@@ -0,0 +1,208 @@
+export interface CommandExample {
+    command: string
+    description: string
+}
+
+export interface CommandMetadata {
+    name: string
+    summary: string
+    argumentHint?: string
+    aliases?: string[]
+    whenToUse: string
+    examples: CommandExample[]
+    supportsJson: boolean
+    relatedCommands: string[]
+}
+
+const COMMANDS: CommandMetadata[] = [
+    {
+        name: 'setup',
+        summary: 'Configure Tela CLI, choose an Agent API target, and verify the local environment',
+        whenToUse: 'Run this first on a new machine, or any time your Agent API target/origin, clone root, or key changes.',
+        examples: [
+            {
+                command: 'tela setup',
+                description: 'Choose production, staging, or a custom API origin and run post-setup checks',
+            },
+        ],
+        supportsJson: false,
+        relatedCommands: ['status', 'doctor', 'sync'],
+    },
+    {
+        name: 'sync',
+        summary: 'Clone or update a Tela repository, or refresh the current checkout',
+        argumentHint: '[repo]',
+        whenToUse: 'Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root.',
+        examples: [
+            {
+                command: 'tela sync agent-api',
+                description: 'Clone or update a specific repository under the clone root',
+            },
+            {
+                command: 'tela sync --current',
+                description: 'Sync the repository for the current working directory',
+            },
+            {
+                command: 'tela sync --all',
+                description: 'Refresh every repository directly under the clone root',
+            },
+        ],
+        supportsJson: true,
+        relatedCommands: ['setup', 'status', 'doctor', 'run', 'push'],
+    },
+    {
+        name: 'run',
+        summary: 'Run the local agent repository with Claude',
+        whenToUse: '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: [
+            {
+                command: 'tela run',
+                description: 'Run the current agent repository with the live viewer',
+            },
+            {
+                command: 'tela run --plain',
+                description: 'Force scrollback-first text output',
+            },
+            {
+                command: 'tela run --json',
+                description: 'Emit the final execution and artifact envelope as JSON',
+            },
+        ],
+        supportsJson: true,
+        relatedCommands: ['sync', 'status', 'doctor'],
+    },
+    {
+        name: 'push',
+        summary: 'Preview, commit, and push the current repository',
+        whenToUse: 'Use this after reviewing local changes when you want Tela to stage everything, produce a commit message, and push the branch.',
+        examples: [
+            {
+                command: 'tela push',
+                description: 'Choose the commit-message flow interactively',
+            },
+            {
+                command: 'tela push --claude',
+                description: 'Generate a commit message from the current worktree',
+            },
+            {
+                command: 'tela push --message "Update feedback flow"',
+                description: 'Skip prompts and use an explicit commit message',
+            },
+        ],
+        supportsJson: true,
+        relatedCommands: ['run', 'status', 'feedback', 'doctor'],
+    },
+    {
+        name: 'feedback',
+        summary: 'Guided review of commit feedback with optional Claude handoff',
+        whenToUse: '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: [
+            {
+                command: 'tela feedback --list',
+                description: 'Open the guided review flow without launching Claude',
+            },
+            {
+                command: 'tela feedback --apply all',
+                description: 'Preview and launch Claude against every actionable suggestion',
+            },
+            {
+                command: 'tela feedback --apply select',
+                description: 'Choose specific actionable suggestions before launching Claude',
+            },
+        ],
+        supportsJson: true,
+        relatedCommands: ['push', 'status', 'doctor'],
+    },
+    {
+        name: 'status',
+        summary: 'Show Tela config, tool availability, repo state, and Agent API origin reachability',
+        whenToUse: 'Use this for a quick snapshot of whether the local environment is ready before running mutating commands.',
+        examples: [
+            {
+                command: 'tela status',
+                description: 'Render a human-readable environment summary',
+            },
+            {
+                command: 'tela status --json',
+                description: 'Emit a machine-readable status report',
+            },
+        ],
+        supportsJson: true,
+        relatedCommands: ['setup', 'doctor', 'sync', 'run', 'push', 'feedback'],
+    },
+    {
+        name: 'doctor',
+        summary: 'Diagnose config, tools, filesystem state, repo health, and Agent API origin reachability',
+        aliases: ['diag'],
+        whenToUse: 'Use this when Tela fails or behaves unexpectedly and you need exact remediation steps.',
+        examples: [
+            {
+                command: 'tela doctor',
+                description: 'Run the full diagnostic suite with remediation guidance',
+            },
+            {
+                command: 'tela doctor --json',
+                description: 'Emit structured diagnostic output for scripts',
+            },
+        ],
+        supportsJson: true,
+        relatedCommands: ['status', 'setup', 'sync', 'run'],
+    },
+]
+
+export function getCommandMetadata(name: string): CommandMetadata | undefined {
+    return COMMANDS.find(command => command.name === name)
+}
+
+export function listCommandMetadata(): CommandMetadata[] {
+    return [...COMMANDS]
+}
+
+export function renderReadmeMarkdown(): string {
+    const lines = [
+        '# 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',
+        '',
+    ]
+
+    for (const command of COMMANDS) {
+        lines.push(`### \`${command.name}${command.argumentHint ? ` ${command.argumentHint}` : ''}\``)
+        lines.push('')
+        lines.push(command.summary)
+        lines.push('')
+        lines.push(`When to use: ${command.whenToUse}`)
+        lines.push('')
+
+        if (command.aliases?.length) {
+            lines.push(`Aliases: ${command.aliases.map(alias => `\`${alias}\``).join(', ')}`)
+            lines.push('')
+        }
+
+        lines.push('Examples:')
+        for (const example of command.examples) {
+            lines.push(`- \`${example.command}\` — ${example.description}`)
+        }
+        lines.push('')
+    }
+
+    lines.push('## Output modes')
+    lines.push('')
+    lines.push('- Human output is structured for terminal use with grouped summaries and next actions.')
+    lines.push('- `--json` is available on read-heavy flows and on `tela run` for the final execution envelope.')
+    lines.push('- `--silent-bark` disables bark audio during interactive Ink startup while keeping the visual intro.')
+    lines.push('')
+    lines.push('## First run')
+    lines.push('')
+    lines.push('1. `tela setup`')
+    lines.push('2. `tela status`')
+    lines.push('3. `tela sync <repo>` or `tela sync --current`')
+    lines.push('4. `tela run`')
+    lines.push('5. `tela push`')
+    lines.push('6. `tela feedback --list`')
+    lines.push('')
+
+    return `${lines.join('\n').trimEnd()}\n`
+}

package/src/commands/push.ts

@@ -0,0 +1,208 @@
+import type { ClaudeCommitContext } from '../commit-message.ts'
+import {
+    fallbackCommitMessageFromFiles,
+    generateCommitMessageWithClaude,
+} from '../commit-message.ts'
+import {
+    buildFallbackCommitMessage,
+    commitWithMessage,
+    getChangedFilesAgainstHead,
+    getCurrentBranch,
+    getDiffAgainstHead,
+    getRecentLog,
+    getRepositoryRoot,
+    getHeadShortSha,
+    getShortStatus,
+    getStatusCounts,
+    getStagedDiff,
+    getStagedFiles,
+    getUpstreamBranch,
+    pushBranch,
+    stageAll,
+} from '../git.ts'
+import { CommandError } from '../process.ts'
+import type { PushResult } from '../types.ts'
+
+export interface PushRepositoryOptions {
+    cwd?: string
+    mode: 'manual' | 'claude'
+    manualMessage?: string
+    generateCommitMessage?: (context: ClaudeCommitContext) => Promise<string>
+    resolvedMessage?: ResolvedCommitMessage
+}
+
+export interface ResolvedCommitMessage {
+    message: string
+    source: 'manual' | 'claude' | 'fallback'
+    fallbackReason?: string
+}
+
+export interface PushPreview {
+    repoRoot: string
+    branch?: string
+    upstream?: string | null
+    detached: boolean
+    hasChanges: boolean
+    worktreeStatus: string
+    statusCounts: {
+        staged: number
+        unstaged: number
+        untracked: number
+        total: number
+    }
+    suggestedMessage?: string
+    messageSource?: ResolvedCommitMessage['source']
+    fallbackReason?: string
+}
+
+function shouldRetryCommit(error: unknown): boolean {
+    if (!(error instanceof CommandError)) {
+        return false
+    }
+
+    const details = `${error.result.stdout}\n${error.result.stderr}`.toLowerCase()
+    return details.includes('hook')
+        || details.includes('pre-commit')
+        || details.includes('modified')
+        || details.includes('stashed changes conflicted')
+}
+
+async function resolveCommitMessage(
+    repoRoot: string,
+    options: PushRepositoryOptions,
+    mode: 'staged' | 'worktree' = 'staged',
+): Promise<ResolvedCommitMessage> {
+    if (options.mode === 'manual' && options.manualMessage?.trim()) {
+        return {
+            message: options.manualMessage.trim(),
+            source: 'manual',
+        }
+    }
+
+    const [status, diff, log, files] = await Promise.all([
+        getShortStatus(repoRoot),
+        mode === 'staged' ? getStagedDiff(repoRoot) : getDiffAgainstHead(repoRoot),
+        getRecentLog(repoRoot),
+        mode === 'staged' ? getStagedFiles(repoRoot) : getChangedFilesAgainstHead(repoRoot),
+    ])
+
+    const generateCommitMessage = options.generateCommitMessage ?? generateCommitMessageWithClaude
+
+    try {
+        const generatedMessage = await generateCommitMessage({ status, diff, log })
+        if (generatedMessage.trim()) {
+            return {
+                message: generatedMessage.trim(),
+                source: 'claude',
+            }
+        }
+    }
+    catch (error) {
+        const fallbackMessage = fallbackCommitMessageFromFiles(files) || buildFallbackCommitMessage(files)
+        return {
+            message: fallbackMessage,
+            source: 'fallback',
+            fallbackReason: error instanceof Error ? error.message : String(error),
+        }
+    }
+
+    return {
+        message: fallbackCommitMessageFromFiles(files) || buildFallbackCommitMessage(files),
+        source: 'fallback',
+        fallbackReason: 'Claude returned an empty commit message.',
+    }
+}
+
+function isDetachedHeadError(error: unknown): boolean {
+    return error instanceof Error && error.message.includes('Detached HEAD')
+}
+
+export async function previewPush(options: PushRepositoryOptions): Promise<PushPreview> {
+    const repoRoot = await getRepositoryRoot(options.cwd ?? process.cwd())
+    const [worktreeStatus, statusCounts] = await Promise.all([
+        getShortStatus(repoRoot),
+        getStatusCounts(repoRoot),
+    ])
+
+    let branch: string | undefined
+    let detached = false
+    try {
+        branch = await getCurrentBranch(repoRoot)
+    }
+    catch (error) {
+        if (!isDetachedHeadError(error)) {
+            throw error
+        }
+
+        detached = true
+    }
+
+    const upstream = detached ? null : await getUpstreamBranch(repoRoot)
+    const hasChanges = Boolean(worktreeStatus.trim())
+
+    let suggestedMessage: string | undefined
+    let messageSource: ResolvedCommitMessage['source'] | undefined
+    let fallbackReason: string | undefined
+    if (hasChanges) {
+        const resolved = await resolveCommitMessage(repoRoot, options, 'worktree')
+        suggestedMessage = resolved.message
+        messageSource = resolved.source
+        fallbackReason = resolved.fallbackReason
+    }
+
+    return {
+        repoRoot,
+        branch,
+        upstream,
+        detached,
+        hasChanges,
+        worktreeStatus: worktreeStatus.trim(),
+        statusCounts,
+        suggestedMessage,
+        messageSource,
+        fallbackReason,
+    }
+}
+
+export async function pushRepository(options: PushRepositoryOptions): Promise<PushResult> {
+    const repoRoot = await getRepositoryRoot(options.cwd ?? process.cwd())
+    const worktreeStatus = await getShortStatus(repoRoot)
+    if (!worktreeStatus.trim()) {
+        throw new Error('No changes to push.')
+    }
+
+    await stageAll(repoRoot)
+
+    const resolvedMessage = options.resolvedMessage ?? await resolveCommitMessage(repoRoot, options)
+    const message = resolvedMessage.message
+
+    let retriedCommit = false
+    try {
+        await commitWithMessage(repoRoot, message)
+    }
+    catch (error) {
+        if (!shouldRetryCommit(error)) {
+            throw error
+        }
+
+        retriedCommit = true
+        await stageAll(repoRoot)
+        await commitWithMessage(repoRoot, message)
+    }
+
+    const branch = await getCurrentBranch(repoRoot)
+    const upstream = await getUpstreamBranch(repoRoot)
+
+    await pushBranch(repoRoot, branch, !upstream)
+
+    return {
+        repoRoot,
+        branch,
+        message,
+        retriedCommit,
+        commitSha: await getHeadShortSha(repoRoot),
+        upstream: await getUpstreamBranch(repoRoot),
+        messageSource: resolvedMessage.source,
+        fallbackReason: resolvedMessage.fallbackReason,
+    }
+}