@meistrari/tela-cli 0.7.0 → 0.7.5

package/dist/output.d.ts

@@ -0,0 +1,13 @@
+import type { Writable } from 'node:stream';
+export type CliIo = {
+    stdout: Pick<Writable, 'write'>;
+    stderr: Pick<Writable, 'write'>;
+};
+export type GlobalOptions = {
+    json: boolean;
+    verbose?: boolean;
+};
+export declare function writeJson(io: CliIo, value: unknown): void;
+export declare function writeLine(io: CliIo, line?: string): void;
+export declare function writeError(io: CliIo, message: string): void;
+export declare function formatBool(value: boolean): string;

package/dist/program.d.ts

@@ -0,0 +1,2 @@
+import type { CliIo } from './output';
+export declare function runCli(argv: string[], io: CliIo): Promise<number>;

package/package.json

@@ -1,34 +1,27 @@
 {
   "name": "@meistrari/tela-cli",
-  "version": "0.7.0",
-  "type": "module",
+  "version": "0.7.5",
+  "description": "Tela command line tools for local state and agent workflows.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meistrari/tela-dock.git",
+    "directory": "apps/tela-cli"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
-    "tela": "cli.ts"
+    "tela": "dist/index.js"
   },
   "files": [
-    "cli.ts",
-    "postinstall.sh",
-    "src/**/*"
+    "dist",
+    "scripts/install-skills.cjs",
+    "skills"
   ],
   "scripts": {
-    "build": "bun build --compile ./cli.ts --outfile ./dist/tela",
-    "postinstall": "bash ./postinstall.sh",
-    "test": "bun test",
-    "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"
-  },
-  "devDependencies": {
-    "@types/react": "19",
-    "bun-types": "1.3.4",
-    "ink-testing-library": "4.0.0"
+    "postinstall": "node scripts/install-skills.cjs --quiet"
   },
-  "patchedDependencies": {
-    "ink@6.2.3": "patches/ink@6.2.3.patch"
+  "publishConfig": {
+    "access": "public"
   }
 }

package/scripts/install-skills.cjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const skillName = 'tela-cli'
+const metadataFile = '.tela-cli-skill.json'
+const managedSource = '@meistrari/tela-cli'
+const sourceDir = path.resolve(__dirname, '..', 'skills', skillName)
+const quiet = process.argv.includes('--quiet')
+const json = process.argv.includes('--json')
+
+function homeDir() {
+  return process.env.HOME || os.homedir()
+}
+
+function targetRoots() {
+  return [
+    path.join(homeDir(), '.agents', 'skills'),
+    path.join(homeDir(), '.claude', 'skills'),
+  ]
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function isManagedInstall(targetDir) {
+  const metadata = readJson(path.join(targetDir, metadataFile))
+  return metadata?.managedBy === managedSource && metadata?.skillName === skillName
+}
+
+function copySkill(targetDir) {
+  const parentDir = path.dirname(targetDir)
+  fs.mkdirSync(parentDir, { recursive: true })
+
+  const tempDir = fs.mkdtempSync(path.join(parentDir, `.${skillName}-tmp-`))
+  const backupDir = path.join(parentDir, `.${skillName}-backup-${process.pid}-${Date.now()}`)
+  let movedExisting = false
+
+  try {
+    fs.cpSync(sourceDir, tempDir, { recursive: true })
+    fs.writeFileSync(path.join(tempDir, metadataFile), `${JSON.stringify({
+      managedBy: managedSource,
+      skillName,
+      installedAt: new Date().toISOString(),
+      sourceDir,
+    }, null, 2)}\n`)
+
+    if (fs.existsSync(targetDir)) {
+      fs.renameSync(targetDir, backupDir)
+      movedExisting = true
+    }
+    fs.renameSync(tempDir, targetDir)
+    fs.rmSync(backupDir, { recursive: true, force: true })
+  } catch (error) {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+    if (movedExisting && !fs.existsSync(targetDir) && fs.existsSync(backupDir)) {
+      fs.renameSync(backupDir, targetDir)
+    }
+    throw error
+  }
+}
+
+function install() {
+  if (process.env.TELA_CLI_SKIP_SKILL_INSTALL === '1') {
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'TELA_CLI_SKIP_SKILL_INSTALL=1',
+      targets: [],
+    }
+  }
+
+  if (!fs.existsSync(path.join(sourceDir, 'SKILL.md'))) {
+    return {
+      ok: false,
+      error: `Bundled skill source is missing: ${sourceDir}`,
+      targets: [],
+    }
+  }
+
+  const targets = targetRoots().map((root) => {
+    const targetDir = path.join(root, skillName)
+    const exists = fs.existsSync(targetDir)
+
+    if (exists && !isManagedInstall(targetDir)) {
+      return {
+        targetDir,
+        status: 'skipped',
+        reason: 'existing unmanaged skill folder',
+      }
+    }
+
+    copySkill(targetDir)
+    return {
+      targetDir,
+      status: exists ? 'updated' : 'installed',
+    }
+  })
+
+  return {
+    ok: true,
+    skillName,
+    targets,
+  }
+}
+
+const result = install()
+
+if (json) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+} else if (!quiet) {
+  for (const target of result.targets || []) {
+    process.stdout.write(`${target.status}: ${target.targetDir}${target.reason ? ` (${target.reason})` : ''}\n`)
+  }
+}
+
+if (!result.ok) {
+  if (!quiet && result.error) process.stderr.write(`${result.error}\n`)
+  process.exitCode = 1
+}

package/skills/tela-cli/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: tela-cli
+description: Use when a coding agent needs to operate Tela Agent repositories through the local `tela` CLI with non-interactive, flag-driven commands and JSON output.
+---
+
+# Tela CLI
+
+Use the local `tela` binary for Tela Agent repository workflows. Prefer explicit
+flags and `--json` so commands are safe in non-interactive agent sessions.
+
+## Subpaths
+
+- Agent workflows: read `references/agent.md` before running `tela agent ...`.
+
+## Core Rules
+
+- Use `tela agent ...` commands, not legacy top-level `sync`, `run`, `push`, or `feedback`.
+- Prefer `--json` for machine-readable output and errors.
+- Do not rely on prompts in coding-agent sessions; pass every required value by flag.
+- Do not print token material. Use `tela auth token --json` for metadata and `--raw` only when a shell command explicitly needs the token.

package/skills/tela-cli/references/agent.md

@@ -0,0 +1,111 @@
+# Tela Agent CLI
+
+Use these commands from a repository checkout unless the command says otherwise.
+Add `--json` whenever you need structured output.
+
+## Setup
+
+Inspect valid setup choices:
+
+```bash
+tela agent setup --list-options --context production/foundation --json
+```
+
+Validate setup without provisioning or writing config:
+
+```bash
+tela agent setup \
+  --context production/foundation \
+  --organization acme \
+  --clone-root "$HOME/tela-agents" \
+  --ssh-public-key "$HOME/.ssh/id_ed25519.pub" \
+  --ssh-private-key "$HOME/.ssh/id_ed25519" \
+  --dry-run \
+  --json
+```
+
+Complete setup by removing `--dry-run`. This provisions the Forgejo user and
+saves Agent setup metadata in the shared Tela local config.
+
+## Sync
+
+Preview repository sync:
+
+```bash
+tela agent sync agent-api --dry-run --json
+tela agent sync --current --dry-run --json
+tela agent sync --all --dry-run --json
+```
+
+Run without `--dry-run` only after checking the plan. `--current` must be run
+inside a git checkout. `--all` operates on the configured clone root.
+
+## Run
+
+Run one-shot, non-interactively:
+
+```bash
+tela agent run \
+  --mode one-shot \
+  --input caderno_teses=./brief.docx \
+  --input-conflict fail \
+  --json
+```
+
+Input assignment format is `variable=path`, where `variable` is a first-level
+folder under `input/`. Conflict modes:
+
+- `fail`: default; exits before running Claude if the destination exists.
+- `overwrite`: replaces the existing staged input.
+- `rename`: uses the CLI suggested destination name.
+
+Avoid `--mode chat` in coding-agent sessions because chat mode requires an
+interactive terminal and cannot be combined with `--json`.
+
+## Push
+
+Preview commit and push:
+
+```bash
+tela agent push --message "feat: update agent behavior" --dry-run --json
+```
+
+Push after checking the dry run:
+
+```bash
+tela agent push --message "feat: update agent behavior" --json
+```
+
+Use `--message` for agent sessions. `--claude` asks the local Claude CLI to
+write a message, and `--manual` relies on fallback behavior.
+
+## Feedback
+
+List feedback for the current commit:
+
+```bash
+tela agent feedback --list --json
+```
+
+Apply all actionable feedback:
+
+```bash
+tela agent feedback --apply all --json
+```
+
+Apply selected actionable feedback ids without prompts:
+
+```bash
+tela agent feedback --apply select --feedback-id 1 --feedback-id 3 --json
+```
+
+Only use ids where the `feedbacks[].actionable` value from `--list --json` is
+`true`.
+
+## Guardrails
+
+- Run `tela doctor auth --json` before agent workflows if credentials look stale.
+- Use `tela context current --json` and `tela context list --json` to inspect the active context.
+- Use `tela context use <context-id> --json` only when you intentionally want to mutate the active context.
+- Treat non-JSON output as human display text; parse JSON only.
+- Stop on `ok: false` or a non-zero exit code and inspect `error.code`, `error.summary`, and `error.fixes`.

package/cli.ts

@@ -1,25 +0,0 @@
-#!/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/postinstall.sh

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-set -e
-
-ZSHRC="$HOME/.zshrc"
-PKG_DIR="$(cd "$(dirname "$0")" && pwd)"
-ALIAS_LINE="alias tela='bun run $PKG_DIR/cli.ts'"
-MARKER="# tela-cli"
-
-if [ ! -f "$ZSHRC" ]; then
-  touch "$ZSHRC"
-fi
-
-# Remove any previous tela-cli entry
-sed -i '' "/$MARKER/d" "$ZSHRC" 2>/dev/null || sed -i "/$MARKER/d" "$ZSHRC" 2>/dev/null || true
-
-echo "$ALIAS_LINE $MARKER" >> "$ZSHRC"
-
-echo "tela command added to $ZSHRC"
-echo "Run 'source ~/.zshrc' or open a new terminal to use 'tela'"

package/src/agent-api.ts

@@ -1,300 +0,0 @@
-import { buildAgentApiHeaders, type FetchLike } from './auth.ts'
-import type {
-    AgentRepoSummary,
-    AvailableRepositorySummary,
-    AgentFeedbackItem,
-    AgentFeedbackListResponse,
-    ForgejoUserCreateResponse,
-    ForgejoUserSshKeyInput,
-    OrganizationListResponse,
-    OrganizationSummary,
-    RepositoryListItemResponse,
-    RepositoryListResponse,
-    RepositoryLookupResponse,
-    TelaCliConfig,
-    TelaCliForgejoOrganization,
-} 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'
-}
-
-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'
-}
-
-function isOrganizationSummary(value: unknown): value is OrganizationSummary {
-    if (!value || typeof value !== 'object') {
-        return false
-    }
-
-    const candidate = value as Partial<OrganizationSummary>
-    return typeof candidate.id === 'string'
-        && typeof candidate.workspaceId === 'string'
-        && typeof candidate.name === 'string'
-}
-
-function isAgentRepoSummary(value: unknown): value is AgentRepoSummary {
-    if (!value || typeof value !== 'object') {
-        return false
-    }
-
-    const candidate = value as Partial<AgentRepoSummary>
-    return typeof candidate.id === 'string'
-        && typeof candidate.workspaceId === 'string'
-        && typeof candidate.organizationId === 'string'
-        && typeof candidate.repository === 'string'
-}
-
-function isRepositoryListItemResponse(value: unknown): value is RepositoryListItemResponse {
-    if (!value || typeof value !== 'object') {
-        return false
-    }
-
-    const candidate = value as Partial<RepositoryListItemResponse>
-    return isOrganizationSummary(candidate.organization)
-        && isAgentRepoSummary(candidate.agentRepo)
-}
-
-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 headers = await buildAgentApiHeaders(config, { fetchFn })
-    const response = await fetchFn(
-        joinUrl(config.agentApiUrl, `/v3/agents/repositories/${encodeURIComponent(repository)}`),
-        {
-            method: 'GET',
-            headers,
-            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 headers = await buildAgentApiHeaders(config, { fetchFn })
-    const response = await fetchFn(
-        joinUrl(
-            config.agentApiUrl,
-            `/v3/agents/${encodeURIComponent(organizationName)}/${encodeURIComponent(repository)}/feedback?commitHash=${encodeURIComponent(commitHash)}`,
-        ),
-        {
-            method: 'GET',
-            headers,
-            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,
-    }
-}
-
-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 listAvailableRepositories(
-    config: TelaCliConfig,
-    fetchFn: FetchLike = fetch,
-): Promise<AvailableRepositorySummary[]> {
-    const headers = await buildAgentApiHeaders(config, { fetchFn })
-    const response = await fetchFn(
-        joinUrl(config.agentApiUrl, '/v3/agents/repositories'),
-        {
-            method: 'GET',
-            headers,
-            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
-        },
-    )
-
-    const responseText = await response.text()
-    const payload = parseJsonBody(responseText) as RepositoryListResponse | null
-
-    if (!response.ok) {
-        throw new AgentApiError(
-            payload?.error ?? `Agent API repository listing failed with status ${response.status}`,
-            response.status,
-            responseText,
-        )
-    }
-
-    if (!payload
-        || payload.success !== true
-        || !Array.isArray(payload.repositories)
-        || !payload.repositories.every(isRepositoryListItemResponse)) {
-        throw new AgentApiError('Agent API repository listing returned an invalid payload', response.status, responseText)
-    }
-
-    return payload.repositories.map(repository => ({
-        ...repository,
-        syncStatus: 'available' as const,
-    }))
-}
-
-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

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