@meistrari/tela-cli 0.6.0 → 0.7.4

package/README.md

@@ -1,129 +1,79 @@
 # 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.
+`@meistrari/tela-cli` owns the local `tela` binary for scriptable access to
+Tela Local state and agent workflows.
 
-## Installation
+The CLI reads and writes the same `~/.tela/config.json` state as Tela Dock
+through `@meistrari/tela-local-config`. It should not parse local config files
+directly, and normal output must not print token material.
 
-```bash
-bun install -g @meistrari/tela-cli
-```
+## Commands
 
-This installs the package globally and adds a `tela` alias to your `~/.zshrc`. After installing, either open a new terminal or run:
+Current first-slice commands:
 
 ```bash
-source ~/.zshrc
+tela auth token --json
+tela auth token --raw
+tela context current --json
+tela context list --json
+tela context show <context-id> --json
+tela context use <context-id>
+tela env list --json
+tela doctor auth --json
+tela agent sync [repo] --current --all --dry-run --json --verbose
+tela agent run --input <name=path>... --plain --json --verbose
+tela agent push --message <text> --claude --manual --dry-run --json --verbose
+tela agent feedback --list --apply <all|select> --json --verbose
 ```
 
-## Default command
-
-### `tela`
-
-List workspace repositories that are available to sync locally.
-
-When to use: Run this with no subcommand when you want to see which workspace repositories are available before using `tela sync <repo>`.
-
-Examples:
-- `tela` — Render the available repositories in a human-readable table
-- `tela --json` — Emit the available repositories as JSON
-
-## Version
-
-Examples:
-- `tela --version` — Print the current Tela CLI version
-- `tela -v` — Print the current Tela CLI version
-
-## Commands
-
-### `setup`
-
-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 environment target, clone root, Tela session, or SSH key changes.
-
-Examples:
-- `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]`
-
-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. SSH-backed sync automatically accepts first-seen host keys during clone and update flows.
-
-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`
+`context use` is the only normal config mutation in this slice. `auth token`
+may refresh a user-session credential in Keychain before returning metadata or
+printing a raw token. Creating, removing, editing, and repairing contexts are
+Dock-first workflows.
 
-Run the local agent repository with project-scoped Claude
+## Development
 
-When to use: Use this from inside an agent repository when you want Claude to follow the repo-local contract files, ignore user/global Claude config by default, show its progress live, and produce the expected result artifact.
+From the repository root:
 
-Examples:
-- `tela run` — Run the current agent repository with project-scoped Claude and the live viewer
-- `tela run --plain` — Force project-scoped execution with scrollback-first text output
-- `tela run --json` — Emit the final project-scoped 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, 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.
-
-Examples:
-- `tela status` — Render a human-readable environment summary
-- `tela status --json` — Emit a machine-readable status report
+```bash
+pnpm cli:build
+pnpm cli:test
+pnpm --filter @meistrari/tela-cli run typecheck
+```
 
-### `doctor`
+Run the built binary directly during development:
 
-Diagnose config, auth session, tools, filesystem state, repo health, and Agent API reachability
+```bash
+node apps/tela-cli/dist/index.js context current --json
+node apps/tela-cli/dist/index.js auth token --json
+```
 
-When to use: Use this when Tela fails or behaves unexpectedly and you need exact remediation steps.
+Use `TELA_HOME` to point the CLI at an isolated config directory:
 
-Aliases: `diag`
+```bash
+TELA_HOME=/tmp/tela-home node apps/tela-cli/dist/index.js env list --json
+```
 
-Examples:
-- `tela doctor` — Run the full diagnostic suite with remediation guidance
-- `tela doctor --json` — Emit structured diagnostic output for scripts
+## Credential Behavior
 
-## Output modes
+The CLI uses the credential adapter contract from `local-config`.
 
-- 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.
+- `env` credentials read `TELA_ACCESS_TOKEN`, `TELA_REFRESH_TOKEN`, or `TELA_DATA_TOKEN`.
+- macOS `keychain` credentials use the system `security` command.
+- expired user-session access tokens with a refresh token are reported as
+  `refreshable`, not as a hard auth failure.
+- `auth token` refreshes expired user-session access tokens when a refresh token
+  is available.
+- unsupported providers report diagnostic status instead of exposing secrets.
 
-## `tela run` scope
+`auth token --raw` is the explicit token-export escape hatch for shell scripts.
+Default and `--json` output stay redacted.
 
-- `tela run` loads project-scoped Claude settings by default and excludes user/global Claude config.
-- Remaining external inputs are explicit: Claude's built-in system prompt, managed enterprise settings, auth/provider credentials, minimal shell runtime environment, and the default model when `agent.config.json` does not set one.
+## Tests
 
-## First run
+Tests are black-box `node --test` cases that execute the compiled CLI with an
+isolated `TELA_HOME`.
 
-1. `tela setup`
-2. `tela status`
-3. `tela sync <repo>` or `tela sync --current`
-4. `tela run`
-5. `tela push`
-6. `tela feedback --list`
+```bash
+pnpm --filter @meistrari/tela-cli run test
+```

package/dist/commands/auth.d.ts

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

package/dist/commands/context.d.ts

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

package/dist/commands/doctor-auth.d.ts

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

package/dist/commands/env.d.ts

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

package/dist/credentials.d.ts

@@ -0,0 +1,2 @@
+import { type CredentialAdapter } from '@meistrari/tela-local-config';
+export declare function createCliCredentialAdapter(env?: Record<string, string | undefined>): CredentialAdapter;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};