@gramatr/client 0.5.1

package/core/session.ts

@@ -0,0 +1,202 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+import {
+  callMcpTool,
+  createDefaultConfig,
+  deriveProjectId,
+  type GitContext,
+  type GmtrConfig,
+  migrateConfig,
+  now,
+  readGmtrConfig,
+  writeGmtrConfig,
+} from '../hooks/lib/gmtr-hook-utils.ts';
+import type { HandoffResponse, SessionStartResponse } from './types.ts';
+
+export interface PreparedProjectSession {
+  projectId: string;
+  config: GmtrConfig;
+  projectEntityId: string | null;
+  restoreNeeded: boolean;
+  hasRestoreContext: boolean;
+  created: boolean;
+}
+
+export interface CurrentProjectContextPayload {
+  type: 'git_project' | 'non_git';
+  session_id: string;
+  project_name: string;
+  working_directory: string;
+  session_start: string;
+  gmtr_config_path: string;
+  project_entity_id: string | null;
+  action_required: string;
+  project_id?: string;
+  git_root?: string;
+  git_branch?: string;
+  git_commit?: string;
+  git_remote?: string;
+  restore_needed?: boolean;
+}
+
+export function normalizeSessionStartResponse(
+  response: SessionStartResponse | null | undefined,
+): {
+  interactionId: string | null;
+  entityId: string | null;
+  resumed: boolean;
+  handoffContext: string | null;
+} {
+  return {
+    interactionId: response?.interaction_id || response?.interactionId || null,
+    entityId: response?.entity_id || response?.entityId || null,
+    resumed: response?.interaction_resumed === true || response?.interactionResumed === true,
+    handoffContext: response?.handoff_context || response?.handoffContext || null,
+  };
+}
+
+export function prepareProjectSessionState(options: {
+  git: GitContext;
+  sessionId: string;
+  transcriptPath: string;
+}): PreparedProjectSession {
+  const { git, sessionId, transcriptPath } = options;
+  const projectId = deriveProjectId(git.remote, git.projectName);
+  const timestamp = now();
+
+  let config = readGmtrConfig(git.root);
+  let created = false;
+
+  if (config) {
+    config = migrateConfig(config, projectId);
+    config.last_session_id = sessionId;
+    config.project_id = projectId;
+    config.current_session = {
+      ...config.current_session,
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+      last_updated: timestamp,
+      token_limit: 200000,
+    };
+    config.continuity_stats = config.continuity_stats || {};
+    config.continuity_stats.total_sessions = (config.continuity_stats.total_sessions || 0) + 1;
+    config.metadata = config.metadata || {};
+    config.metadata.updated = timestamp;
+  } else {
+    config = createDefaultConfig({
+      projectId,
+      projectName: git.projectName,
+      gitRemote: git.remote,
+      sessionId,
+      transcriptPath,
+    });
+    created = true;
+  }
+
+  writeGmtrConfig(git.root, config);
+
+  return {
+    projectId,
+    config,
+    projectEntityId: config.project_entity_id || null,
+    restoreNeeded: config.last_compact?.timestamp != null,
+    hasRestoreContext: config.last_compact?.summary != null,
+    created,
+  };
+}
+
+export async function startRemoteSession(options: {
+  clientType: string;
+  sessionId?: string;
+  projectId: string;
+  projectName?: string;
+  gitRemote: string;
+  directory: string;
+}): Promise<SessionStartResponse | null> {
+  return (await callMcpTool(
+    'gmtr_session_start',
+    {
+      client_type: options.clientType,
+      project_id: options.projectId,
+      ...(options.projectName ? { project_name: options.projectName } : {}),
+      git_remote: options.gitRemote,
+      directory: options.directory,
+      ...(options.sessionId ? { session_id: options.sessionId } : {}),
+    },
+    15000,
+  )) as SessionStartResponse | null;
+}
+
+export async function loadProjectHandoff(projectId: string): Promise<HandoffResponse | null> {
+  return (await callMcpTool(
+    'gmtr_load_handoff',
+    { project_id: projectId },
+    15000,
+  )) as HandoffResponse | null;
+}
+
+export function persistSessionRegistration(rootDir: string, response: SessionStartResponse | null): GmtrConfig | null {
+  const normalized = normalizeSessionStartResponse(response);
+  if (!normalized.interactionId && !normalized.entityId) return readGmtrConfig(rootDir);
+
+  const config = readGmtrConfig(rootDir);
+  if (!config) return null;
+  config.current_session = config.current_session || {};
+  if (normalized.interactionId) config.current_session.interaction_id = normalized.interactionId;
+  if (normalized.entityId) config.current_session.gmtr_entity_id = normalized.entityId;
+  writeGmtrConfig(rootDir, config);
+  return config;
+}
+
+export function writeCurrentProjectContextFile(payload: CurrentProjectContextPayload): void {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const claudeDir = join(home, '.claude');
+  if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
+  const contextFile = join(claudeDir, 'current-project-context.json');
+  writeFileSync(contextFile, JSON.stringify(payload, null, 2) + '\n');
+}
+
+export function buildGitProjectContextPayload(options: {
+  git: GitContext;
+  sessionId: string;
+  workingDirectory: string;
+  sessionStart: string;
+  projectId: string;
+  projectEntityId: string | null;
+  restoreNeeded: boolean;
+}): CurrentProjectContextPayload {
+  return {
+    type: 'git_project',
+    session_id: options.sessionId,
+    project_name: options.git.projectName,
+    project_id: options.projectId,
+    git_root: options.git.root,
+    git_branch: options.git.branch,
+    git_commit: options.git.commit,
+    git_remote: options.git.remote,
+    working_directory: options.workingDirectory,
+    session_start: options.sessionStart,
+    gmtr_config_path: join(options.git.root, '.gmtr', 'settings.json'),
+    project_entity_id: options.projectEntityId,
+    restore_needed: options.restoreNeeded,
+    action_required: 'check_or_create_project_entity',
+  };
+}
+
+export function buildNonGitProjectContextPayload(options: {
+  cwd: string;
+  sessionId: string;
+  sessionStart: string;
+  projectEntityId: string | null;
+}): CurrentProjectContextPayload {
+  return {
+    type: 'non_git',
+    session_id: options.sessionId,
+    project_name: basename(options.cwd),
+    working_directory: options.cwd,
+    session_start: options.sessionStart,
+    gmtr_config_path: join(options.cwd, '.gmtr', 'settings.json'),
+    project_entity_id: options.projectEntityId,
+    action_required: 'gmtr_init_needed',
+  };
+}

package/core/targets.ts

@@ -0,0 +1,292 @@
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export type IntegrationTargetId =
+  | 'claude-code'
+  | 'claude-desktop'
+  | 'chatgpt-desktop'
+  | 'codex'
+  | 'gemini-cli'
+  | 'remote-mcp'
+  | 'claude-web'
+  | 'chatgpt-web';
+
+export interface IntegrationTarget {
+  id: IntegrationTargetId;
+  label: string;
+  kind: 'local' | 'remote';
+  description: string;
+  detect: () => DetectionResult;
+}
+
+export interface DetectionResult {
+  detected: boolean;
+  location?: string;
+  details?: string;
+}
+
+export interface DetectionContext {
+  exists: (path: string) => boolean;
+  readText: (path: string) => string;
+  home: string;
+}
+
+function defaultContext(): DetectionContext {
+  return {
+    exists: (path) => existsSync(path),
+    readText: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : ''),
+    home: homedir(),
+  };
+}
+
+function homePath(ctx: DetectionContext, ...segments: string[]): string {
+  return join(ctx.home, ...segments);
+}
+
+function detectClaudeCode(ctx: DetectionContext): DetectionResult {
+  const claudeDir = homePath(ctx, '.claude');
+  if (!ctx.exists(claudeDir)) {
+    return { detected: false, details: '~/.claude not found' };
+  }
+
+  const settingsPath = join(claudeDir, 'settings.json');
+  return {
+    detected: true,
+    location: claudeDir,
+    details: ctx.exists(settingsPath) ? settingsPath : 'Claude directory exists',
+  };
+}
+
+function detectCodex(ctx: DetectionContext): DetectionResult {
+  const codexDir = homePath(ctx, '.codex');
+  if (!ctx.exists(codexDir)) {
+    return { detected: false, details: '~/.codex not found' };
+  }
+
+  const hooksPath = join(codexDir, 'hooks.json');
+  const configPath = join(codexDir, 'config.toml');
+  const details = [hooksPath, configPath].filter((path) => ctx.exists(path)).join(', ') || codexDir;
+
+  return {
+    detected: true,
+    location: codexDir,
+    details,
+  };
+}
+
+function detectGeminiCli(ctx: DetectionContext): DetectionResult {
+  const geminiDir = homePath(ctx, '.gemini');
+  if (!ctx.exists(geminiDir)) {
+    return { detected: false, details: '~/.gemini not found' };
+  }
+
+  const settingsPath = join(geminiDir, 'settings.json');
+  const extensionsDir = join(geminiDir, 'extensions');
+  const details = [settingsPath, extensionsDir].filter((path) => ctx.exists(path)).join(', ') || geminiDir;
+
+  return {
+    detected: true,
+    location: geminiDir,
+    details,
+  };
+}
+
+function detectClaudeDesktop(ctx: DetectionContext): DetectionResult {
+  // macOS path — Claude Desktop is only available on macOS and Windows
+  const macConfigPath = join(
+    ctx.home,
+    'Library',
+    'Application Support',
+    'Claude',
+    'claude_desktop_config.json',
+  );
+  // Windows path — APPDATA is typically <home>\AppData\Roaming
+  const winConfigPath = join(ctx.home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+
+  if (ctx.exists(macConfigPath)) {
+    return {
+      detected: true,
+      location: macConfigPath,
+      details: 'Claude Desktop config found (macOS)',
+    };
+  }
+
+  if (ctx.exists(winConfigPath)) {
+    return {
+      detected: true,
+      location: winConfigPath,
+      details: 'Claude Desktop config found (Windows)',
+    };
+  }
+
+  return {
+    detected: false,
+    details: 'Claude Desktop config not found',
+  };
+}
+
+function detectChatGPTDesktop(ctx: DetectionContext): DetectionResult {
+  // macOS path — ChatGPT Desktop uses ~/.chatgpt/mcp.json
+  const macConfigDir = join(ctx.home, '.chatgpt');
+  const macConfigPath = join(macConfigDir, 'mcp.json');
+
+  // Windows path — APPDATA is typically <home>\AppData\Roaming
+  const winConfigDir = join(ctx.home, 'AppData', 'Roaming', 'ChatGPT');
+  const winConfigPath = join(winConfigDir, 'mcp.json');
+
+  if (ctx.exists(macConfigPath)) {
+    return {
+      detected: true,
+      location: macConfigPath,
+      details: 'ChatGPT Desktop config found (macOS)',
+    };
+  }
+
+  if (ctx.exists(macConfigDir)) {
+    return {
+      detected: true,
+      location: macConfigDir,
+      details: 'ChatGPT Desktop directory found (macOS, no mcp.json yet)',
+    };
+  }
+
+  if (ctx.exists(winConfigPath)) {
+    return {
+      detected: true,
+      location: winConfigPath,
+      details: 'ChatGPT Desktop config found (Windows)',
+    };
+  }
+
+  if (ctx.exists(winConfigDir)) {
+    return {
+      detected: true,
+      location: winConfigDir,
+      details: 'ChatGPT Desktop directory found (Windows, no mcp.json yet)',
+    };
+  }
+
+  return {
+    detected: false,
+    details: 'ChatGPT Desktop config not found',
+  };
+}
+
+function detectRemoteTarget(
+  kind: 'claude-web' | 'chatgpt-web' | 'remote-mcp',
+  ctx: DetectionContext,
+): DetectionResult {
+  const claudeJson = ctx.readText(homePath(ctx, '.claude.json'));
+  if (claudeJson.includes('gramatr') || claudeJson.includes('mcpServers')) {
+    return {
+      detected: true,
+      location: homePath(ctx, '.claude.json'),
+      details: 'Remote MCP-capable configuration file found',
+    };
+  }
+
+  return {
+    detected: false,
+    details:
+      kind === 'remote-mcp'
+        ? 'Remote MCP setup is available but not configured locally'
+        : `${kind} is a hosted target and requires remote MCP setup`,
+  };
+}
+
+export const INTEGRATION_TARGETS: IntegrationTarget[] = [
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    kind: 'local',
+    description: 'Local Claude Code hook integration',
+    detect: () => detectClaudeCode(defaultContext()),
+  },
+  {
+    id: 'claude-desktop',
+    label: 'Claude Desktop',
+    kind: 'local',
+    description: 'Claude Desktop app with MCP server support (Tier 3 — MCP only, no hooks)',
+    detect: () => detectClaudeDesktop(defaultContext()),
+  },
+  {
+    id: 'chatgpt-desktop',
+    label: 'ChatGPT Desktop',
+    kind: 'local',
+    description: 'ChatGPT Desktop app with MCP server support (Tier 3 — MCP only, no hooks)',
+    detect: () => detectChatGPTDesktop(defaultContext()),
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    kind: 'local',
+    description: 'Local Codex hook integration',
+    detect: () => detectCodex(defaultContext()),
+  },
+  {
+    id: 'gemini-cli',
+    label: 'Gemini CLI',
+    kind: 'local',
+    description: 'Local Gemini CLI extension integration',
+    detect: () => detectGeminiCli(defaultContext()),
+  },
+  {
+    id: 'remote-mcp',
+    label: 'Remote MCP',
+    kind: 'remote',
+    description: 'Shared remote MCP setup for hosted integrations',
+    detect: () => detectRemoteTarget('remote-mcp', defaultContext()),
+  },
+  {
+    id: 'claude-web',
+    label: 'Claude Web',
+    kind: 'remote',
+    description: 'Claude.ai web connector via remote MCP (Settings > Connectors)',
+    detect: () => detectRemoteTarget('claude-web', defaultContext()),
+  },
+  {
+    id: 'chatgpt-web',
+    label: 'ChatGPT Web',
+    kind: 'remote',
+    description: 'Hosted ChatGPT target via remote MCP',
+    detect: () => detectRemoteTarget('chatgpt-web', defaultContext()),
+  },
+];
+
+export function listTargets(): IntegrationTarget[] {
+  return INTEGRATION_TARGETS;
+}
+
+export function findTarget(id: string): IntegrationTarget | undefined {
+  return INTEGRATION_TARGETS.find((target) => target.id === id);
+}
+
+export function detectTargets(): Array<IntegrationTarget & { detection: DetectionResult }> {
+  return detectTargetsWithContext(defaultContext());
+}
+
+export function detectTargetsWithContext(
+  ctx: DetectionContext,
+): Array<IntegrationTarget & { detection: DetectionResult }> {
+  const detectors: Record<string, (ctx: DetectionContext) => DetectionResult> = {
+    'claude-code': detectClaudeCode,
+    'claude-desktop': detectClaudeDesktop,
+    'chatgpt-desktop': detectChatGPTDesktop,
+    codex: detectCodex,
+    'gemini-cli': detectGeminiCli,
+  };
+
+  return INTEGRATION_TARGETS.map((target) => ({
+    ...target,
+    detection: detectors[target.id]
+      ? detectors[target.id](ctx)
+      : detectRemoteTarget(target.id, ctx),
+  }));
+}
+
+export function summarizeDetectedLocalTargets(): IntegrationTargetId[] {
+  return detectTargets()
+    .filter((target) => target.kind === 'local' && target.detection.detected)
+    .map((target) => target.id);
+}

package/core/types.ts

@@ -0,0 +1,179 @@
+export interface RouteClassification {
+  effort_level?: string;
+  intent_type?: string;
+  confidence?: number;
+  memory_tier?: string;
+  matched_skills?: string[];
+  constraints_extracted?: string[];
+  reverse_engineering?: {
+    explicit_wants?: string[];
+    implicit_wants?: string[];
+    explicit_dont_wants?: string[];
+    implicit_dont_wants?: string[];
+    gotchas?: string[];
+  };
+  suggested_capabilities?: string[];
+  isc_scaffold?: string[];
+  is_fallback?: boolean;
+}
+
+export interface CapabilityAuditEntry {
+  id?: number;
+  name?: string;
+  section?: string;
+  disposition?: string;
+  reason?: string;
+  phase?: string;
+}
+
+export interface CapabilityAuditResult {
+  entries?: CapabilityAuditEntry[];
+  use_count?: number;
+  decline_count?: number;
+  na_count?: number;
+  formatted_summary?: string;
+}
+
+export interface PhaseTemplate {
+  header?: string;
+  time_check?: string;
+  voice_message?: string;
+  phase_description?: string;
+}
+
+export interface QualityGateRule {
+  id?: string;
+  name?: string;
+  description?: string;
+  min_effort?: string | null;
+  automated?: boolean;
+}
+
+export interface QualityGateConfig {
+  rules?: QualityGateRule[];
+  min_criteria?: number;
+  anti_required?: boolean;
+  word_range?: { min?: number; max?: number };
+}
+
+export interface ContextPreLoadPlan {
+  entity_types?: string[];
+  fetch_limits?: Record<string, number>;
+  tier?: string;
+}
+
+export interface RouteResponse {
+  classification?: RouteClassification;
+  statusline_markdown?: string;
+  capability_audit?: CapabilityAuditResult;
+  phase_template?: PhaseTemplate;
+  quality_gate_config?: QualityGateConfig;
+  context_pre_load_plan?: ContextPreLoadPlan;
+  project_state?: {
+    project_id?: string;
+    active_prd_id?: string | null;
+    active_prd_title?: string | null;
+    isc_summary?: { total?: number; passing?: number; failing?: number; pending?: number };
+    current_phase?: string | null;
+    active_client?: { client_id?: string; client_type?: string } | null;
+    last_updated?: string;
+    session_history_summary?: string;
+  } | null;
+  packet_diagnostics?: {
+    memory_context?: {
+      status?: string;
+      requested_types?: string[];
+      delivered_count?: number;
+      error?: string;
+    };
+    project_state?: {
+      status?: string;
+      project_id?: string;
+      error?: string;
+    };
+  };
+  curated_context?: string;
+  context_references?: Array<{
+    id?: string;
+    type?: string;
+    name?: string;
+  }> | string[];
+  behavioral_directives?: string[];
+  suggested_agents?: Array<{
+    display_name?: string;
+    model?: string;
+    reason?: string;
+  }>;
+  composed_agents?: Array<{
+    name?: string;
+    display_name?: string;
+    system_prompt?: string;
+    expertise_areas?: string[];
+    task_domain?: string;
+    model_preference?: string;
+    context_summary?: string;
+  }>;
+  memory_context?: {
+    total_count?: number;
+    results?: Array<{
+      entity_name?: string;
+      entity_type?: string;
+      content?: string;
+      similarity?: number;
+    }>;
+  };
+  token_savings?: {
+    claude_md_reduction?: number;
+    observe_work_offloaded?: number;
+    reasoning_tokens_used?: number;
+    total_saved?: number;
+    tokens_saved?: number;
+    savings_ratio?: number;
+  };
+  execution_summary?: {
+    classifier_model?: string;  // previously: qwen_model
+    classifier_time_ms?: number;  // previously: qwen_time_ms
+    execution_time_ms?: number;
+    server_version?: string;
+    stage_timing?: Record<string, number>;
+    degraded_components?: string[];
+  };
+}
+
+export interface SessionStartResponse {
+  project_id?: string;
+  interaction_id?: string;
+  entity_id?: string;
+}
+
+export interface HandoffMeta {
+  saved_at?: string;
+  branch?: string;
+  session_id?: string;
+  conversation_id?: string;
+  platform?: string;
+  legacy_missing_platform?: boolean;
+}
+
+export interface HandoffResponse {
+  status?: string;
+  source?: string;
+  project_id?: string;
+  session_id?: string;
+  branch?: string;
+  platform?: string;
+  created_at?: string;
+  section_count?: number;
+  _meta?: HandoffMeta;
+  where_we_are?: string;
+  what_shipped?: string;
+  whats_next?: string;
+  key_context?: string;
+  dont_forget?: string;
+}
+
+export interface HookFailure {
+  title: string;
+  detail: string;
+  action?: string;
+}