Metadata-Version: 2.4
Name: tko
Version: 12.0.12
Summary: Add your description here
Author-email: David <sena.ufc@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: diff-match-patch>=20241021
Requires-Dist: filelock>=3.25.2
Requires-Dist: markdown>=3.7
Requires-Dist: platformdirs>=4.9.2
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pygments>=2.19.1
Requires-Dist: pymdown-extensions>=10.15
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.25.0
Requires-Dist: watchdog>=6.0.0
Requires-Dist: wcwidth>=0.2.13
Requires-Dist: icecream>=2.1.4
Requires-Dist: loguru>=0.7.3
Requires-Dist: textual<7,>=6.8
Requires-Dist: rich<15,>=14.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: types-chardet>=5.0.4.6; extra == "dev"
Requires-Dist: types-markdown>=3.7.0.20250322; extra == "dev"
Dynamic: license-file

<!-- markdownlint-configure-file {
  "MD033": false,
  "MD041": false
} -->

# TKO

Distribuição de tarefas de programação com Git, desenvolvimento na IDE do aluno e análise contínua do processo de aprendizagem.

[![Tests](https://github.com/senapk/tko/actions/workflows/tests.yml/badge.svg)](https://github.com/senapk/tko/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/tko)](https://pypi.org/project/tko/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/tko/)
[![Downloads](https://static.pepy.tech/badge/tko/month)](https://pepy.tech/project/tko)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Repo](https://img.shields.io/badge/GitHub-senapk%2Ftko-181717?logo=github)](https://github.com/senapk/tko)
[![Stars](https://img.shields.io/github/stars/senapk/tko?style=social)](https://github.com/senapk/tko/stargazers)

O TKO é um ecossistema de ensino de programação centrado em prática, versionamento e evidências de aprendizagem. Ele distribui atividades via Git, permite desenvolvimento na IDE local e acompanha progresso de turmas com dados reais de evolução.

## Visão Geral

O TKO resolve o problema de acoplar ensino de programação a ambientes artificiais de navegador. Em vez disso, o aluno trabalha no próprio fluxo profissional: editor, terminal, compilador e controle de versão.

Para o professor, o sistema viabiliza distribuição de tarefas personalizadas e acompanhamento de execução com sinais de desenvolvimento, como tempo de resolução, histórico de versões e progresso por atividade.

Fluxo rápido:

1. Professor cria ou publica repositórios de questões.
2. Aluno baixa a atividade e desenvolve na própria IDE.
3. Aluno executa os testes localmente e itera com feedback imediato.
4. Aluno envia para o professor via Git, normalmente por um repositório compartilhado no GitHub.
5. Professor acompanha evolução, métricas de aprendizado, tentativas e progresso da turma.

## Quick Start

### Ubuntu / WSL / Codespaces

```bash
curl -fsSL https://raw.githubusercontent.com/senapk/tko/main/install.sh | bash
tko --version
tko --help
```

Saída esperada:

- O comando `tko --version` deve mostrar a versão instalada.
- O comando `tko --help` deve listar os comandos principais (`task`, `index`, `collect`, `config`, ...).

Se `tko` não for encontrado, adicione `~/.local/bin` ao PATH e abra um novo terminal:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Instalações existentes via `pipx` continuam suportadas:

```bash
pipx install tko
```

### Windows

Use o guia recomendado para setup com VS Code, WSL e Ubuntu:

- [Windows com WSL e Ubuntu](wiki/Windows-WSL.md)

## Comandos principais

```text
tko
├── init, open, run
├── task     build, show, open, list, tests, download
├── index    build, download, update
├── config
│   ├── set, list, reset, self-update, uninstall, clear-cache
│   ├── profile  link, status, update, unlink
│   └── source   list, add, remove, set
├── collect  repo, tasks, skills
├── audit    on, off, start, preview, unpack
└── tool     mdpp, convert-tests, older, diff, rebase, filter, html, migrate, pull
```

```bash
# No repositório do aluno
tko task download course@labs/fila
tko task show course/labs/fila
tko task open course/labs/fila

# Dentro da pasta da atividade, o caminho é implícito
tko task tests
tko run --language py --diff-mode side --failures first

# Escolher outra atividade explicitamente
tko task open --fzf

# Diretório efetivo para qualquer comando
tko -C caminho/do/repositorio tool migrate --dry-run
tko -C caminho/do/repositorio tool migrate
```

`task show`, `task open` e `task tests` aceitam caminhos existentes. Sem caminho,
usam a atividade da pasta atual ou abrem um seletor quando não há atividade atual.
`task download` recebe uma chave, pois a atividade ainda não foi baixada.
`--fzf/-f` abre o seletor; `--filter/-F` filtra código antes da execução.
O idioma da interface usa `--ui-language pt|en` antes do comando; a linguagem de
programação usa `--language/-l` em `init`, `run` e `collect skills`.

Veja a [referência da CLI](docs/REFERENCE.md) para parâmetros e exemplos completos.

## Casos de Uso

- Distribuição de listas e atividades de programação via Git.
- Desenvolvimento local na IDE do aluno, sem dependência de browser.
- Correção automática com testes e iteração rápida.
- Acompanhamento docente com indicadores de progresso e histórico.


## Documentação por Perfil

- Conceitos e arquitetura:
  [TKO: conceitos e organização](wiki/Conceitos-e-Arquitetura.md)
- Professor da disciplina (distribui conteúdo e coleta repositórios dos alunos via Git/GitHub):
  [Uso pelos professores](#uso-pelos-professores),
  [Guia para criar repositórios de tarefas](wiki/Criando-Atividades.md)
- Aluno da disciplina:
  [Uso do TKO pelos alunos](#uso-do-tko-pelos-alunos),
  [Fazendo as atividades](wiki/Fazendo-Atividades.md)
- Aluno em estudo autônomo (fora de disciplina):
  [Testando sem estar em uma disciplina](wiki/Testando-Sem-Disciplina.md),
  [Repositórios de referência](#repositórios-de-referência)
- Instalação e ambiente: [Instalação](#instalação)
- Desenvolvedores: [Uso pelos desenvolvedores](#uso-pelos-desenvolvedores)
- Ferramentas auxiliares: [Ferramentas](#ferramentas)

Repositórios de referência:

- [FUP - Fundamentos de Programação](https://github.com/qxcodefup/arcade)
- [ED - Estrutura de Dados](https://github.com/qxcodeed/arcade)
- [POO - Programação Orientada a Objetos](https://github.com/qxcodepoo/arcade)

## Instalação

- [Guia recomendado: Windows com WSL e Ubuntu](wiki/Windows-WSL.md)
- [Ubuntu / WSL: Git, Python e TKO](wiki/ubuntu_git_python_tko.md)
- [GitHub Codespaces](wiki/Codespaces.md)
- [VS Code no Ubuntu / WSL](wiki/ubuntu_vscode.md)
- [Linguagens - Java, C, C++, Python, TypeScript, Go](wiki/Linguagens.md)
- [Outros sistemas operacionais](wiki/Outros-Sistemas-Operacionais.md)
- [Windows sem WSL - legado](wiki/Windows-Sem-WSL.md)

## Uso do TKO pelos alunos

- [Testando sem estar em uma disciplina](wiki/Testando-Sem-Disciplina.md)
- [Como organizar seus repositórios da disciplina](wiki/Organizando-Disciplinas.md)
- [Fazendo as atividades](wiki/Fazendo-Atividades.md)

## Uso pelos professores

- [Conceitos e organização do TKO](wiki/Conceitos-e-Arquitetura.md)
- [Gestão de repositórios de turma](wiki/Classroom.md)
- [Guia para criar repositórios de tarefas](wiki/Criando-Atividades.md)
- [Marcadores e tipos de atividades](wiki/game/tasks.md)
- [Criando testes e conversões](wiki/Criando-Tarefas-e-Testes.md)
- [Gamificação e progressão](wiki/Gamificacao-e-Progressao.md)
- [Relizando provas com modo auditoria](wiki/audit.md)
- [Analisando a timeline de execução de uma tarefa](wiki/audit-preview.md)

## Uso pelos desenvolvedores

- [Desenvolvimento de tarefas no TKO](wiki/Desenvolvimento-de-Tarefas.md)
- [Gamificação e progressão](wiki/Gamificacao-e-Progressao.md)

## Ferramentas

- [Filtragem e Rascunhos](wiki/tools/filter.md)
- [Markdown Preprocessor](wiki/tools/mdpp.md)
- [Rebase de links markdown](wiki/tools/rebase-links.md)
- [Build task: pipeline de mdpp, filter e drafts](wiki/tools/build-all.md)
- [Build index: manter e atualizar índices](wiki/tools/build-index.md)

## Referência e suporte

- [Índice da documentação](docs/README.md)
- [Guia de contribuição](CONTRIBUTING.md)
- [Arquitetura técnica](docs/ARCHITECTURE.md)
- [FAQ](docs/FAQ.md)
- [Referência rápida da CLI](docs/REFERENCE.md)
- [Especificação de formatos](docs/FORMATS.md)
- [Exemplos end-to-end](docs/EXAMPLES.md)
- [Ciclo de vida de tarefas](docs/TASK_LIFECYCLE.md)
- [Suporte a linguagens](docs/LANGUAGE_SUPPORT.md)
- [Guia de testes e QA](docs/TESTING.md)

## Atualizando o TKO

Para a instalação recomendada, use:

```bash
tko config self-update
```

Para instalações existentes via `pipx`, use:

```bash
pipx upgrade tko
```

## Contribuição

Contribuições são bem-vindas via pull request.

Fluxo mínimo para validar mudanças localmente:

```bash
uv run pytest -q
```

Se possível, mantenha mudanças pequenas, com descrição clara do problema e da solução no PR.

## Licença

Este projeto está sob a licença MIT. Veja [LICENSE](LICENSE).
