@sumicom/quicksave-shared 0.1.0

package/src/protocol.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateMessageId,
+  createMessage,
+  createRequest,
+  parseMessage,
+  serializeMessage,
+  isResponseMessage,
+  getRequestType,
+  REQUEST_RESPONSE_MAP,
+} from './protocol.js';
+
+describe('generateMessageId', () => {
+  it('should generate unique IDs', () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      ids.add(generateMessageId());
+    }
+    expect(ids.size).toBe(100);
+  });
+
+  it('should generate IDs with expected format', () => {
+    const id = generateMessageId();
+    // Format: timestamp-randomString
+    expect(id).toMatch(/^\d+-[a-z0-9]+$/);
+  });
+});
+
+describe('createMessage', () => {
+  it('should create a properly structured message', () => {
+    const payload = { test: 'data' };
+    const message = createMessage('ping', payload);
+
+    expect(message.id).toBeDefined();
+    expect(message.type).toBe('ping');
+    expect(message.payload).toEqual(payload);
+    expect(message.timestamp).toBeDefined();
+    expect(typeof message.timestamp).toBe('number');
+  });
+
+  it('should create unique IDs for each message', () => {
+    const msg1 = createMessage('ping', {});
+    const msg2 = createMessage('ping', {});
+
+    expect(msg1.id).not.toBe(msg2.id);
+  });
+
+  it('should set timestamp close to current time', () => {
+    const before = Date.now();
+    const message = createMessage('pong', { timestamp: 0 });
+    const after = Date.now();
+
+    expect(message.timestamp).toBeGreaterThanOrEqual(before);
+    expect(message.timestamp).toBeLessThanOrEqual(after);
+  });
+});
+
+describe('createRequest', () => {
+  it('should create request with correct response type', () => {
+    const { message, responseType } = createRequest('git:status', { path: '/' });
+
+    expect(message.type).toBe('git:status');
+    expect(message.payload).toEqual({ path: '/' });
+    expect(responseType).toBe('git:status:response');
+  });
+
+  it('should work with different request types', () => {
+    const types = ['git:diff', 'git:stage', 'git:commit', 'git:log'];
+
+    for (const type of types) {
+      const { responseType } = createRequest(type as any, {});
+      expect(responseType).toBe(`${type}:response`);
+    }
+  });
+});
+
+describe('parseMessage', () => {
+  it('should parse valid JSON message', () => {
+    const original = createMessage('ping', { data: 'test' });
+    const json = JSON.stringify(original);
+
+    const parsed = parseMessage(json);
+
+    expect(parsed.id).toBe(original.id);
+    expect(parsed.type).toBe(original.type);
+    expect(parsed.payload).toEqual(original.payload);
+    expect(parsed.timestamp).toBe(original.timestamp);
+  });
+
+  it('should throw on invalid JSON', () => {
+    expect(() => parseMessage('not valid json')).toThrow();
+  });
+
+  it('should throw on missing id', () => {
+    const invalid = JSON.stringify({ type: 'ping', payload: {}, timestamp: 123 });
+    expect(() => parseMessage(invalid)).toThrow('Invalid message format');
+  });
+
+  it('should throw on missing type', () => {
+    const invalid = JSON.stringify({ id: '123', payload: {}, timestamp: 123 });
+    expect(() => parseMessage(invalid)).toThrow('Invalid message format');
+  });
+
+  it('should throw on missing timestamp', () => {
+    const invalid = JSON.stringify({ id: '123', type: 'ping', payload: {} });
+    expect(() => parseMessage(invalid)).toThrow('Invalid message format');
+  });
+
+  it('should throw on null message', () => {
+    expect(() => parseMessage('null')).toThrow('Invalid message format');
+  });
+
+  it('should throw on array', () => {
+    expect(() => parseMessage('[]')).toThrow('Invalid message format');
+  });
+});
+
+describe('serializeMessage', () => {
+  it('should serialize message to JSON string', () => {
+    const message = createMessage('ping', { test: true });
+    const json = serializeMessage(message);
+
+    expect(typeof json).toBe('string');
+
+    const parsed = JSON.parse(json);
+    expect(parsed.id).toBe(message.id);
+    expect(parsed.type).toBe(message.type);
+    expect(parsed.payload).toEqual(message.payload);
+  });
+
+  it('should produce valid JSON that can be parsed back', () => {
+    const original = createMessage('git:status:response', {
+      branch: 'main',
+      staged: [],
+      unstaged: [],
+      untracked: [],
+      ahead: 0,
+      behind: 0,
+    });
+
+    const json = serializeMessage(original);
+    const parsed = parseMessage(json);
+
+    expect(parsed).toEqual(original);
+  });
+});
+
+describe('isResponseMessage', () => {
+  it('should identify response messages', () => {
+    expect(isResponseMessage({ id: '1', type: 'git:status:response', payload: {}, timestamp: 1 })).toBe(true);
+    expect(isResponseMessage({ id: '1', type: 'git:diff:response', payload: {}, timestamp: 1 })).toBe(true);
+    expect(isResponseMessage({ id: '1', type: 'handshake:ack', payload: {}, timestamp: 1 })).toBe(false);
+  });
+
+  it('should identify non-response messages', () => {
+    expect(isResponseMessage({ id: '1', type: 'ping', payload: {}, timestamp: 1 })).toBe(false);
+    expect(isResponseMessage({ id: '1', type: 'git:status', payload: {}, timestamp: 1 })).toBe(false);
+    expect(isResponseMessage({ id: '1', type: 'handshake', payload: {}, timestamp: 1 })).toBe(false);
+  });
+});
+
+describe('getRequestType', () => {
+  it('should extract request type from response type', () => {
+    expect(getRequestType('git:status:response' as any)).toBe('git:status');
+    expect(getRequestType('git:diff:response' as any)).toBe('git:diff');
+    expect(getRequestType('git:commit:response' as any)).toBe('git:commit');
+  });
+});
+
+describe('REQUEST_RESPONSE_MAP', () => {
+  it('should contain all git operations', () => {
+    const expectedOperations = [
+      'git:status',
+      'git:diff',
+      'git:stage',
+      'git:unstage',
+      'git:commit',
+      'git:log',
+      'git:branches',
+      'git:checkout',
+      'git:discard',
+    ];
+
+    for (const op of expectedOperations) {
+      expect(REQUEST_RESPONSE_MAP[op]).toBeDefined();
+      expect(REQUEST_RESPONSE_MAP[op]).toBe(`${op}:response`);
+    }
+  });
+
+  it('should contain handshake mapping', () => {
+    expect(REQUEST_RESPONSE_MAP['handshake']).toBe('handshake:ack');
+  });
+
+  it('should contain ping/pong mapping', () => {
+    expect(REQUEST_RESPONSE_MAP['ping']).toBe('pong');
+  });
+});

package/src/protocol.ts

@@ -0,0 +1,92 @@
+import type { Message, MessageType } from './types.js';
+
+/**
+ * Generate a unique message ID
+ */
+export function generateMessageId(): string {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Create a typed message
+ */
+export function createMessage<T>(type: MessageType, payload: T): Message<T> {
+  return {
+    id: generateMessageId(),
+    type,
+    payload,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Create a request message and return both the message and a response handler
+ */
+export function createRequest<TReq>(
+  type: MessageType,
+  payload: TReq
+): {
+  message: Message<TReq>;
+  responseType: MessageType;
+} {
+  const message = createMessage(type, payload);
+  const responseType = `${type}:response` as MessageType;
+  return { message, responseType };
+}
+
+/**
+ * Parse and validate a message
+ */
+export function parseMessage(data: string): Message {
+  const parsed = JSON.parse(data);
+
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    typeof parsed.id !== 'string' ||
+    typeof parsed.type !== 'string' ||
+    typeof parsed.timestamp !== 'number'
+  ) {
+    throw new Error('Invalid message format');
+  }
+
+  return parsed as Message;
+}
+
+/**
+ * Serialize a message to JSON
+ */
+export function serializeMessage(message: Message): string {
+  return JSON.stringify(message);
+}
+
+/**
+ * Type guard for response messages
+ */
+export function isResponseMessage(message: Message): boolean {
+  return message.type.endsWith(':response');
+}
+
+/**
+ * Get the request type from a response type
+ */
+export function getRequestType(responseType: MessageType): MessageType {
+  return responseType.replace(':response', '') as MessageType;
+}
+
+/**
+ * Request types and their expected response types
+ */
+export const REQUEST_RESPONSE_MAP: Record<string, string> = {
+  'git:status': 'git:status:response',
+  'git:diff': 'git:diff:response',
+  'git:stage': 'git:stage:response',
+  'git:unstage': 'git:unstage:response',
+  'git:commit': 'git:commit:response',
+  'git:log': 'git:log:response',
+  'git:branches': 'git:branches:response',
+  'git:checkout': 'git:checkout:response',
+  'git:discard': 'git:discard:response',
+  handshake: 'handshake:ack',
+  ping: 'pong',
+};

package/src/types.ts

@@ -0,0 +1,400 @@
+// ============================================================================
+// Message Types
+// ============================================================================
+
+export interface Message<T = unknown> {
+  id: string;
+  type: MessageType;
+  payload: T;
+  timestamp: number;
+}
+
+export type MessageType =
+  | 'ping'
+  | 'pong'
+  | 'handshake'
+  | 'handshake:ack'
+  | 'git:status'
+  | 'git:status:response'
+  | 'git:diff'
+  | 'git:diff:response'
+  | 'git:stage'
+  | 'git:stage:response'
+  | 'git:unstage'
+  | 'git:unstage:response'
+  | 'git:stage-patch'
+  | 'git:stage-patch:response'
+  | 'git:unstage-patch'
+  | 'git:unstage-patch:response'
+  | 'git:commit'
+  | 'git:commit:response'
+  | 'git:log'
+  | 'git:log:response'
+  | 'git:branches'
+  | 'git:branches:response'
+  | 'git:checkout'
+  | 'git:checkout:response'
+  | 'git:discard'
+  | 'git:discard:response'
+  | 'ai:generate-commit-summary'
+  | 'ai:generate-commit-summary:response'
+  | 'ai:set-api-key'
+  | 'ai:set-api-key:response'
+  | 'ai:get-api-key-status'
+  | 'ai:get-api-key-status:response'
+  | 'agent:list-repos'
+  | 'agent:list-repos:response'
+  | 'agent:switch-repo'
+  | 'agent:switch-repo:response'
+  | 'agent:browse-directory'
+  | 'agent:browse-directory:response'
+  | 'agent:add-repo'
+  | 'agent:add-repo:response'
+  | 'error';
+
+// ============================================================================
+// Git Types
+// ============================================================================
+
+export type FileStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied';
+
+export interface FileChange {
+  path: string;
+  status: FileStatus;
+  oldPath?: string; // For renamed/copied files
+}
+
+export interface GitStatus {
+  branch: string;
+  ahead: number;
+  behind: number;
+  staged: FileChange[];
+  unstaged: FileChange[];
+  untracked: string[];
+}
+
+export interface DiffHunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  content: string;
+}
+
+export interface FileDiff {
+  path: string;
+  oldPath?: string;
+  hunks: DiffHunk[];
+  isBinary: boolean;
+  truncated?: boolean;
+  truncatedReason?: string;
+}
+
+export interface Commit {
+  hash: string;
+  shortHash: string;
+  message: string;
+  author: string;
+  email: string;
+  date: string;
+}
+
+export interface Branch {
+  name: string;
+  current: boolean;
+  remote?: string;
+}
+
+export interface Repository {
+  path: string;
+  name: string;
+  currentBranch?: string;
+}
+
+// ============================================================================
+// Request/Response Payloads
+// ============================================================================
+
+// Handshake
+export interface HandshakePayload {
+  publicKey: string; // Base64 encoded
+  license?: License;
+}
+
+export interface HandshakeAckPayload {
+  success: boolean;
+  agentVersion: string;
+  repoPath: string;
+  availableRepos?: Repository[];
+}
+
+// Status
+export interface StatusRequestPayload {
+  path?: string;
+}
+
+export type StatusResponsePayload = GitStatus;
+
+// Diff
+export interface DiffRequestPayload {
+  path: string;
+  staged?: boolean;
+}
+
+export type DiffResponsePayload = FileDiff;
+
+// Stage/Unstage
+export interface StageRequestPayload {
+  paths: string[];
+}
+
+export interface StageResponsePayload {
+  success: boolean;
+  error?: string;
+}
+
+export type UnstageRequestPayload = StageRequestPayload;
+export type UnstageResponsePayload = StageResponsePayload;
+
+// Stage/Unstage Patch (for line-level staging)
+export interface StagePatchRequestPayload {
+  patch: string; // Unified diff format
+}
+
+export interface StagePatchResponsePayload {
+  success: boolean;
+  error?: string;
+}
+
+export type UnstagePatchRequestPayload = StagePatchRequestPayload;
+export type UnstagePatchResponsePayload = StagePatchResponsePayload;
+
+// Commit
+export interface CommitRequestPayload {
+  message: string;
+  description?: string;
+}
+
+export interface CommitResponsePayload {
+  success: boolean;
+  hash?: string;
+  error?: string;
+}
+
+// Log
+export interface LogRequestPayload {
+  limit?: number;
+}
+
+export interface LogResponsePayload {
+  commits: Commit[];
+}
+
+// Branches
+export type BranchesRequestPayload = Record<string, never>;
+
+export interface BranchesResponsePayload {
+  branches: Branch[];
+  current: string;
+}
+
+// Checkout
+export interface CheckoutRequestPayload {
+  branch: string;
+  create?: boolean;
+}
+
+export interface CheckoutResponsePayload {
+  success: boolean;
+  error?: string;
+}
+
+// Discard
+export interface DiscardRequestPayload {
+  paths: string[];
+}
+
+export interface DiscardResponsePayload {
+  success: boolean;
+  error?: string;
+}
+
+// Error
+export interface ErrorPayload {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+// List Repos
+export type ListReposRequestPayload = Record<string, never>;
+
+export interface ListReposResponsePayload {
+  repos: Repository[];
+  current: string;
+}
+
+// Switch Repo
+export interface SwitchRepoRequestPayload {
+  path: string;
+}
+
+export interface SwitchRepoResponsePayload {
+  success: boolean;
+  newPath: string;
+  error?: string;
+}
+
+// Browse Directory
+export interface BrowseDirectoryRequestPayload {
+  path: string;
+}
+
+export interface DirectoryEntry {
+  name: string;
+  path: string;
+  isDirectory: boolean;
+  isGitRepo: boolean;
+}
+
+export interface BrowseDirectoryResponsePayload {
+  path: string;
+  parentPath: string | null;
+  entries: DirectoryEntry[];
+  error?: string;
+}
+
+// Add Repo
+export interface AddRepoRequestPayload {
+  path: string;
+}
+
+export interface AddRepoResponsePayload {
+  success: boolean;
+  repo?: Repository;
+  error?: string;
+}
+
+// ============================================================================
+// License Types
+// ============================================================================
+
+export interface License {
+  version: 1;
+  publicKey: string;
+  issuedAt: number;
+  type: 'pro';
+  signature: string;
+}
+
+// ============================================================================
+// Signaling Types
+// ============================================================================
+
+export type SignalingMessageType =
+  | 'peer-connected'
+  | 'peer-offline'
+  | 'data'
+  | 'bye';
+
+export interface SignalingMessage {
+  type: SignalingMessageType;
+  payload?: unknown;
+}
+
+// ============================================================================
+// Key Exchange Types (V2 Protocol)
+// ============================================================================
+
+/**
+ * Key exchange message - PWA sends encrypted session DEK to Agent
+ * This provides forward secrecy: if Agent is compromised, only current session is exposed
+ */
+export interface KeyExchangeV2 {
+  type: 'key-exchange';
+  version: 2;
+  encryptedDEK: string; // Session DEK encrypted with Agent's public key (base64)
+  timestamp: number; // Unix timestamp for replay protection
+}
+
+/**
+ * V2 key exchange acknowledgment from Agent
+ */
+export interface KeyExchangeV2Ack {
+  type: 'key-exchange-ack';
+  version: 2;
+}
+
+/**
+ * Key exchange message type
+ */
+export type KeyExchangeMessage = KeyExchangeV2;
+
+// ============================================================================
+// Connection Types
+// ============================================================================
+
+export type ConnectionState =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'reconnecting'
+  | 'error';
+
+export interface ConnectionInfo {
+  state: ConnectionState;
+  agentId: string;
+  signalingServer: string;
+  connectedAt?: number;
+  error?: string;
+}
+
+// ============================================================================
+// AI Types
+// ============================================================================
+
+export type ClaudeModel =
+  | 'claude-haiku-4-5'
+  | 'claude-sonnet-4-5'
+  | 'claude-opus-4-5';
+
+export const CLAUDE_MODELS: { id: ClaudeModel; name: string; description: string }[] = [
+  { id: 'claude-haiku-4-5', name: 'Haiku', description: 'Fast & affordable' },
+  { id: 'claude-sonnet-4-5', name: 'Sonnet', description: 'Balanced speed & quality' },
+  { id: 'claude-opus-4-5', name: 'Opus', description: 'Highest quality' },
+];
+
+// Generate Commit Summary
+export interface GenerateCommitSummaryRequestPayload {
+  context?: string;
+  model?: ClaudeModel;
+}
+
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface GenerateCommitSummaryResponsePayload {
+  success: boolean;
+  summary?: string;
+  description?: string;
+  error?: string;
+  errorCode?: 'NO_API_KEY' | 'NO_STAGED_CHANGES' | 'API_ERROR' | 'RATE_LIMITED';
+  tokenUsage?: TokenUsage;
+  cached?: boolean;
+}
+
+// API Key Management
+export interface SetApiKeyRequestPayload {
+  apiKey: string;
+}
+
+export interface SetApiKeyResponsePayload {
+  success: boolean;
+  error?: string;
+}
+
+export interface GetApiKeyStatusResponsePayload {
+  configured: boolean;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ES2022"],
+    "composite": true
+  },
+  "include": ["src/**/*"]
+}