Go repo for the Workspaces CLI and automatic sync-folder client.

This repo starts from the proven sync prototype and ports only the useful core: SQLite local state, fake HTTP Workspaces API tests, sync runner skeleton, and conflict file behavior.

workspaces login --api https://staging.workspaces.plannotator.ai
workspaces list
workspaces connect ws_... /tmp/context-platform

workspaces connect is the product path: it validates credentials, checks the workspace, writes local sync state, pulls remote documents once, then starts a background sync process through the operating system for the current user. macOS uses a LaunchAgent, Linux uses systemd --user, and Windows uses Task Scheduler. Logs are written to .workspaces/logs/sync.log. If no CLI token is stored for the API origin, it opens the browser login flow first. workspaces login --api ... remembers that API origin as the local default, so later list, connect, and logout commands do not need --api again. WORKSPACES_API_ORIGIN and explicit --api still override the remembered default.

The lower-level runner is still available for already-connected folders:

workspaces sync start --run-for 2s /tmp/context-platform
workspaces sync install /tmp/context-platform
workspaces sync uninstall /tmp/context-platform
workspaces sync stop /tmp/context-platform
workspaces sync conflicts /tmp/context-platform
workspaces status --json /tmp/context-platform
workspaces doctor /tmp/context-platform

Tests and local proofs can use the fake in-process API explicitly:

workspaces connect --api fake://workspaces --foreground --run-for 2s ws_fake /tmp/context-platform

--foreground keeps sync attached to the current terminal. It is mainly for tests, support, and debugging. --no-service uses the older detached child-process fallback for environments where OS-managed sync is not available, but it will not restart after login. Normal connect installs and starts OS-managed sync.

A file containing WORKSPACES_CONFLICT triggers a fake version conflict and writes a conflict file plus .workspaces/conflicts.json.

The sync scanner trusts the folder you choose, but skips obvious accidents: .workspaces, .git, editor temp files, dependency/build folders, .env/private-key files, invalid UTF-8, NUL-containing files, and files larger than the current Workspaces document limit. It does not read .gitignore; context folders are often intentionally ignored by a surrounding code repo.

When conflicts exist, workspaces status points to workspaces sync conflicts <local_root>. The conflicts command prints a short human list or stable JSON with --json. workspaces doctor <local_root> reports connection state, keychain login presence, OS-managed sync service state, sync process state, lock status, pending rows, conflict counts, and recent pending outbox errors. Doctor reports state only; it does not repair or create .workspaces for an unconnected folder.

The executable contract proof lives in tests. internal/workspacesapi includes an httptest server shaped like the real Workspaces API:

• GET /v1/workspaces/{wsId}
• GET /v1/workspaces/{wsId}/documents/{docId}
• POST /v1/workspaces/{wsId}/documents
• PATCH /v1/workspaces/{wsId}/documents/{docId} with If-Match

The runner tests prove remote-to-local pull, local-to-remote create, update, and 412 version_conflict handling against that HTTP shape. Asset sync and production packaging are intentionally out of scope for this slice.

Local Phase 1 proof:

go test ./...
go build -o /tmp/workspaces ./cmd/workspaces
./scripts/verify-local.sh

Normal staging use should sign in with workspaces login. The non-interactive staging sync verifier still uses a temporary Workspaces API key so it can run in CI or scripted proof sessions. The token is read from the environment and is not stored in .workspaces/state.sqlite.

WORKSPACES_API_TOKEN=wsk_live_... \
WORKSPACES_WORKSPACE_ID=ws_... \
./scripts/verify-staging.sh

The staging verifier creates a timestamped markdown proof document, edits it, then forces a real stale-version conflict and verifies a local conflict copy is written.