SPB Git

spb/zyquo-cloud Public MIT

Native macOS AI chat client for 12 cloud providers — your keys, every cloud model, one beautiful chat.

macosswiftaichat
Swift 97.4% Shell 1.7% Makefile 1%
11.6 KB
View source Raw Blame History

# Zyquo Cloud — Build Plan

# Phase 0 — Provider Research ✅ (completed 2026-07-30)

  • Live-probe /models endpoints of all 12 providers with real keys (authoritative current model IDs)
  • Live SSE streaming smoke test on all 12 providers (all HTTP 200)
  • Web research: official docs for each provider (auth, endpoints, schema, streaming, special params, rate limits, pricing)
  • Write docs/PROVIDERS.md covering all 12 providers × 8 research points
  • Phase checkpoint: PROVIDERS.md complete + summary

Phase 0 checkpoint summary: All 12 providers documented in docs/PROVIDERS.md (assembled from per-provider files in docs/research/), each covering the 8 mandatory points, verified against live probes with real keys — every key authenticated, every provider streamed successfully. Major catalog churn found vs. training data: DeepSeek → v4-flash/v4-pro only; Mistral deprecates Magistral/Devstral/ Nemo 2026-07-31 (reasoning via reasoning_effort); xAI catalog now grok-4.5/4.3/4.20/build; Cerebras down to 3 models; Perplexity has no /models (built-in catalog: sonar, sonar-pro, sonar-reasoning-pro, sonar-deep-research). Items unverifiable from docs are flagged inline and queued for Phase 7.

# Phase 1 — Project Setup ✅ (completed 2026-07-30)

  • Package.swift — executable targets ZyquoCloud + zyquo-verify, test target, macOS 13+, swift-markdown dep
  • Minimal @main SwiftUI app that builds and launches (activation policy handled)
  • Makefile: make dev (release build + assemble Zyquo Cloud.app + ad-hoc sign), make release (universal + Developer ID + notarize skeleton, completed in Phase 8), scripts/write-info-plist.sh
  • Phase checkpoint: swift build clean (0 warnings), make dev assembles bundle, app launched via open, process verified, quit cleanly

Phase 1 checkpoint summary: SPM-only toolchain working on Swift 6.4. make dev produces an ad-hoc-signed dist/Zyquo Cloud.app with correct Info.plist (com.zyquo.cloud, macOS 13+, productivity category). Release/notarization targets stubbed to scripts/notarize.sh using the verified zyquo-term identity + MacLustr-Notarize profile (implemented fully in Phase 8).

# Phase 2 — Architecture ✅ (completed 2026-07-30)

  • Models: ProviderID, AIModel, ModelCapabilities, ModelPricing, ParameterSupport, Message, Conversation, Persona, PromptTemplate, ChatParameters, TokenUsage
  • Providers: ProviderProtocol (ChatRequest → AsyncThrowingStream<ChatEvent>), OpenAICompatibleClient (11 providers incl. Gemini-compat + custom), AnthropicClient (native Messages API), ProviderRegistry
  • Services: StreamingService (SSE parser + URLSession streaming), ModelCatalog (+ seed ModelCatalogData, full data generated next), PersistenceService (JSON in Application Support)
  • ViewModels/Views skeleton folders
  • Phase checkpoint: builds clean (0 warnings), 10/10 unit tests pass (SSE parser incl. Anthropic named events / keep-alive comments / multi-line data; model JSON round-trip; error mapping)

Phase 2 checkpoint summary: Full provider abstraction in place — all quirks (auth headers, stream_options, max_completion_tokens, enable_thinking, reasoning_content, citations, bare-array /models) isolated in the two clients. Toolchain note: no Xcode on this machine (CLT only), so tests use Swift Testing with scripts/test.sh wiring the CLT TestingMacros plugin + framework symlinks (make test).

# Phase 3 — SecureKeyStore ✅ (completed 2026-07-30)

  • AES-256-GCM vault via CryptoKit at ~/Library/Application Support/ZyquoCloud/vault.zq
  • HKDF master key: random salt + IOPlatformUUID (IOKit) + home path + obfuscated compiled-in pepper (XOR-assembled at runtime)
  • Vault format [salt 32B][nonce+ciphertext+tag], plaintext JSON dict of provider→key, atomic writes, stable salt across saves
  • Round-trip encrypt/decrypt test (phase gate) + tamper test + machine-binding test + plaintext-leak test + no-Keychain sweep (clean)

Phase 3 checkpoint summary: Vault gate passed — 17/17 tests green including encrypt/decrypt round-trip, GCM tamper detection, cross-machine rejection (injected entropy), salt stability, and a scan proving no key material or field names appear in the vault file. Zero Keychain/SecItem usage in the codebase. Keys redact to •••• + last 4 via SecureKeyStore.redacted.

# Phase 4 — Design System & UI Spec ✅ (completed 2026-07-30)

  • ZyquoTheme tokens: full color spec (light flagship + night-sky dark derivation as dynamic NSColors), typography scale (title/body 13.5 lh 1.45/caption/code SF Mono), spacing 4–32, radii 6/10/14, soft shadow token, layout metrics (sidebar 260, header 52, column 760…), motion tokens
  • Reusable components: ZyquoHairline (0.5pt), ZyquoBadge, StatusDot, hover highlight (80ms), pressable style (0.97), provider glyphs
  • AppearanceStore: light/dark/system, 5 accent choices (sky-indigo default), chat font size 12–18 clamped, persisted
  • Phase checkpoint: builds clean; tokens are the only color/size source (raw-hex sweep of Views/ViewModels clean)

Phase 4 checkpoint summary: Design system complete per spec; the Phase 4.2 layout spec is the contract for all Phase 6 UI and the 4.4 quality gate is re-checked before "done". Toolchain: builds pinned to macOS 26 SDK (SDKROOT in Makefile/test.sh) because CLT lacks Xcode's SwiftUIMacros plugin required by SDK 27's macro-based @State.

# Phase 5 — App Icon ✅ (completed 2026-07-30)

  • assets/icon/zyquo-cloud.svg — white geometric cloud + luminous-beam Z on a true superellipse squircle (n=4.6, computed path), sky gradient #82B4FF→#4E6AF0→#3A3F9E, soft top light, two distant parallax cloud layers; no SVG filters (CoreSVG-safe)
  • Rendered 16→1024 and visually inspected; iterated (lightened sky; small sizes were muddy → dedicated zyquo-cloud-small.svg: bigger cloud, 86px Z stroke, flat fills — used for 16/32 slots)
  • scripts/generate-icon.sh → iconset (small variant for ≤64px slots) → Resources/AppIcon.icns, embedded in the bundle by make dev/release; rasterizer: scripts/rasterize-svg.swift (AppKit)
  • Menu bar template glyph zyquo-cloud-template.svg (cloud silhouette, Z knocked out via mask) → Resources/MenuBarIcon(@2x).png; in-app wordmark/empty-state glyph will draw the same geometry as a SwiftUI Shape in Phase 6

Phase 5 checkpoint summary: Icon is crisp and on-identity at every size (verified visually at 1024/512/256/128/64/32/16). SVG sources are the single source of truth in assets/icon/.

# Phase 6 — Features ✅ (completed 2026-07-30; design gate re-checked before Done)

  • Core chat: sidebar (search ⌘F, pin, rename, delete, tags), streaming with stop (⌘.), model picker per conversation + per message, message actions (copy/edit&resend/regenerate/delete/quote), reasoning display (collapsible), Perplexity citations chips, per-message + per-conversation tokens & est. cost, system prompt per conversation + global default, gated parameters editor
  • Vision & attachments: image + text-file drag/drop + picker, 56pt thumbnails, dashed drop highlight
  • Productivity: 56-template prompt library + user templates ({{input}}), 8 personas + user personas, Quick Chat (⌥Space floating panel + "Continue in app"), compare mode (2–4 columns), export Markdown/PDF, full-text search, auto-titles via cheapest same-provider model
  • macOS polish: ⌘N/⌘K palette/⌘F/⌘↩/⌘⇧E/⌥Space/⌘., menu bar extra (template icon, toggleable), empty state per spec
  • Model management: 195-model built-in catalog, dynamic /models refresh + catalog diff in Settings, custom OpenAI-compatible models (ID + base URL), favorites
  • Markdown: full rendering (tables, quotes, lists, links, headings) + code blocks with copy button, language label, 11-language syntax highlighter; streaming-safe, memoized
  • Checkpoint: builds clean 0 warnings, 26 tests green, app launched + UI visually verified (dark)

Phase 6 checkpoint summary: All Phase 6 features implemented and wired. UI verified running; light/dark render from the same tokens. End-to-end chat with live keys is exercised in Phase 7.

# Phase 7 — API Verification ✅ (completed 2026-07-30 — table fully green)

  • Verify harness: app binary gains --verify mode reusing the exact production provider clients; zyquo-verify target execs it (keys via env from .env.keys, never committed); --load-vault seeds the GUI vault
  • /models diff vs catalog per provider; "OK" completion on every catalog chat model; streaming test per provider; vision test per vision-capable provider
  • Final result: 202/202 tests passed (12 providers, 170 catalog models) — docs/VERIFICATION.md
  • Every failure across 3 sweeps fixed, PROVIDERS.md + catalog updated together

Phase 7 checkpoint summary: Live verification caught and fixed real bugs: SSE event separators dropped by AsyncBytes.lines (all streams hung); async @main breaking GUI task scheduling; a --verify MainActor deadlock; Together's completions-style choices[].text deltas; Mistral's high/none-only reasoning_effort + ThinkChunk content arrays; Gemini's models/ ID prefixes; deprecated models (OpenAI chat-latest generations, Gemini 2.0/3-pro-preview, 18 Together dedicated-only, broken DeepInfra gemma-4-31B) removed; streaming-only models flagged (requiresStreaming); 429/5xx backoff added. End-to-end GUI chat verified live; auto-title now uses cheapest non-reasoning model.

# Phase 8 — Signing & Notarization ✅ (completed 2026-07-30)

  • make release: universal binary (arm64 + x86_64 via lipo; x86_64 needs -U for CLT's arm64-only swiftCompatibility56), Developer ID sign (hardened runtime, minimal entitlements), notarize app zip + DMG (MacLustr-Notarize, both Accepted), staple both
  • spctl -a -vv → accepted, source=Notarized Developer ID · stapler validate OK · lipo -archs → x86_64 arm64 · notarized app launches and quits cleanly
  • Gotcha fixed: AMFI rejects XML comments inside the entitlements dict — plist is now comment-free

Phase 8 checkpoint summary: dist/Zyquo Cloud.app (signed, notarized, stapled, universal) and dist/ZyquoCloud.dmg (notarized, stapled) ship-ready. Identity "Developer ID Application: Simon-Pierre Boucher (3YM54G49SN)", profile MacLustr-Notarize.

# Definition of Done — final sweep (2026-07-30)

  • make release → Developer ID-signed, notarized, stapled Zyquo Cloud.app (spctl-verified), zero Xcode
  • Cloud SVG icon (+ small-size & template variants) striking at all sizes, embedded icns + menu bar template + in-app glyph/wordmark
  • Light theme per Phase 4 spec (visually verified), dark derived (visually verified)
  • Naming coherent: "Zyquo Cloud" UI, com.zyquo.cloud, ZyquoCloud target/data folder (sweeps clean)
  • 12 providers configured; custom AES-GCM vault, zero Keychain usage (sweep clean)
  • Verification harness: 202/202 green across all providers/models with real keys (docs/VERIFICATION.md)
  • All Phase 6 features implemented and functional
  • Header audit: every code file carries the Author/Mail header (scripts/audit-headers.sh)
  • PROVIDERS.md ↔ ModelCatalog in sync (Phase 7 amendments recorded); 27/27 unit tests; zero compiler warnings

# Phase 2 — Architecture (pending)

# Phase 3 — SecureKeyStore (pending)

# Phase 4 — Design System (pending)

# Phase 5 — App Icon (pending)

# Phase 6 — Features (pending)

# Phase 7 — API Verification (pending)

# Phase 8 — Signing & Notarization (pending)