kb/openspec/changes/archive/2026-03-29-independent-versioning/specs/go-client/spec.md at 0c124c4ab7630a727b7114dac61b6260d005ba0e

steve/kb

Files

T

steve 7f4decee26 Reindex command, implicit note shorthand, add→addfile rename

- Add `kb reindex` command with confirmation prompt and --yes flag
- Add implicit note shorthand: `kb "my note"` submits a note directly
- Rename `add` to `addfile`, remove --note/--title/--type flags
- Add client-side file extension validation before upload
- Add `kb examples` command for common usage patterns
- Update README, SKILL.md, and main specs
- Archive completed changes and sync delta specs

BREAKING: `kb add` renamed to `kb addfile`, `kb add --note` replaced by `kb "text"`

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-29 13:58:04 +01:00

2.7 KiB

Raw Blame History

ADDED Requirements

Requirement: Engine version compatibility check

The client SHALL verify that the connected engine meets a minimum version requirement before executing any API command. The minimum required engine version SHALL be embedded in the client binary at build time. If the engine version is below the minimum, the client SHALL print an error message and exit with a non-zero code. There SHALL be no flag to skip or suppress this check.

Scenario: Compatible engine version

WHEN the client connects to an engine reporting version 2.1.5 and MinEngineVersion is 2.1.0
THEN the client SHALL proceed with the command normally

Scenario: Incompatible engine version

WHEN the client connects to an engine reporting version 2.0.3 and MinEngineVersion is 2.1.0
THEN the client SHALL print to stderr: Error: kb client vX.Y.Z requires engine v2.1.0+ (connected engine is v2.0.3) followed by an upgrade hint, and exit with code 1

Scenario: Engine unreachable during version check

WHEN the client cannot reach the engine's /api/v1/status endpoint
THEN the client SHALL skip the version check and proceed with the original command (the actual API call will surface the connectivity error)

Scenario: Version check is cached per session

WHEN the client has already verified engine compatibility during the current invocation
THEN subsequent API calls within the same invocation SHALL NOT repeat the version check

Scenario: Client version command does not check engine

WHEN the user runs kb --version
THEN the client SHALL print the client version without contacting the engine

Scenario: MinEngineVersion not set

WHEN the client binary has MinEngineVersion set to empty string or dev
THEN the client SHALL skip the version check entirely (development builds)

MODIFIED Requirements

Requirement: Single static binary with zero runtime dependencies

The Go client SHALL compile to a single static binary with no runtime dependencies. It SHALL support cross-compilation for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64). The build SHALL inject both Version and MinEngineVersion via ldflags.

Scenario: Install on a clean machine

WHEN a user downloads the kb binary for their platform
THEN they SHALL be able to run it immediately with no additional installs (no Python, no Docker, no shared libraries)

Scenario: Version and compatibility info embedded at build time

WHEN the client is built with make all VERSION=2.1.0 MIN_ENGINE_VERSION=2.0.0
THEN kb --version SHALL report 2.1.0 and the compatibility check SHALL use 2.0.0 as the minimum engine version

2.7 KiB Raw Blame History