Metadata-Version: 2.4
Name: komainu-sync
Version: 0.1.0
Summary: Local CLI for syncing test files from disk to KomAInu backend.
Author: KomAInu
License-Expression: MIT
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0

# komainu-sync

`komainu-sync` is the local CLI that sends your local test files to KomAInu backend.

Think of it this way:
- your machine reads files from disk,
- KomAInu backend stores/snapshots them,
- MCP can trigger this CLI, but does not read file contents itself.

## User Story (first-time setup)

You are a user with local tests in a folder and want KomAInu to keep a synced server copy.

1. Install/prepare the CLI (`komainu-sync`).
2. Create a `.komainu.json` file in your repo (or a parent folder).
3. Push one or more files to initialize/verify mapping.
4. Continue syncing only changed files after edits.

## 1) Configure `.komainu.json`

`komainu-sync` searches for `.komainu.json` from your current directory upward.

Example:

```json
{
  "api_base_url": "https://your-komainu-api.example.com",
  "tests_root": "./tests"
}
```

Fields:
- `api_base_url`: URL of your KomAInu backend.
- `tests_root`: local root folder used to compute relative paths.

Token source (same as `komainu-mcp`):
- `KOMAINU_ACCESS_TOKEN` environment variable (**recommended**).
- Optional fallback: `access_token` in `.komainu.json`.

`komainu-sync` and `komainu-mcp` both use the same token variable:
- `KOMAINU_ACCESS_TOKEN`

How to obtain it:
- From KomAInu web app MCP page (`Add to Cursor` flow), or
- by creating an MCP token via backend (`/mcp/tokens/...`) and reusing it.

Important:
- You do **not** provide backend storage paths.
- Backend path is always derived from local path relative to `tests_root`.

Example mapping:
- local file: `./tests/smoke/login.xml`
- sent as backend `relative_path`: `smoke/login.xml`

## 2) Sync commands

- Push one file:
  - `komainu-sync push-file tests/smoke/login.xml`
- Push multiple files:
  - `komainu-sync push-files tests/smoke/login.xml tests/regression/order.xml`
- Delete one file remotely:
  - `komainu-sync delete-file tests/legacy/old_case.xml`

Each command calls backend endpoint:
- `POST /workspace/tests/sync`

## 3) Typical workflow after setup

- You edit local test files.
- You push only changed files (`push-file` / `push-files`).
- If a file is removed locally and should be removed server-side, run `delete-file`.

This keeps sync incremental and fast (no full re-upload each time).

## Troubleshooting

- `Missing .komainu.json`:
  - create it in your repo (or run command from a child directory).
- `Path is outside tests_root`:
  - file must be inside configured `tests_root`.
- `401/403` from backend:
  - `KOMAINU_ACCESS_TOKEN` is missing/expired/invalid.
- `404/5xx` from backend:
  - check `api_base_url` and backend availability.

## Notes for MCP users

When called through MCP tools, the same CLI is used under the hood.
MCP passes only file paths; file reading is still done locally by `komainu-sync`.
