komainu-sync 0.1.0

Local CLI for syncing test files from disk to KomAInu backend.

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:

{
  "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.