gramatr 0.3.0

package/codex/lib/codex-install-utils.ts

@@ -0,0 +1,123 @@
+import { buildCodexHooksFile, type InstallHookMatcherEntry, type InstallHooksFile } from '../../core/install.ts';
+
+export interface HookCommand {
+  type: 'command';
+  command: string;
+  statusMessage?: string;
+  timeout?: number;
+}
+
+export interface HookMatcherEntry {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+
+export interface HooksFile {
+  hooks?: Record<string, HookMatcherEntry[]>;
+}
+
+export function upsertManagedBlock(
+  existing: string,
+  content: string,
+  startMarker: string,
+  endMarker: string,
+): string {
+  const block = `${startMarker}\n${content.trim()}\n${endMarker}`;
+  const pattern = new RegExp(
+    `${escapeRegExp(startMarker)}[\\s\\S]*?${escapeRegExp(endMarker)}`,
+    'm',
+  );
+
+  if (pattern.test(existing)) {
+    return existing.replace(pattern, block);
+  }
+
+  const trimmed = existing.trim();
+  return trimmed ? `${trimmed}\n\n${block}\n` : `${block}\n`;
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function sameHook(a: HookMatcherEntry, b: HookMatcherEntry): boolean {
+  if ((a.matcher || '') !== (b.matcher || '')) return false;
+  if (a.hooks.length !== b.hooks.length) return false;
+  return a.hooks.every((hook, index) => {
+    const other = b.hooks[index];
+    return (
+      hook.type === other.type &&
+      hook.command === other.command &&
+      hook.statusMessage === other.statusMessage &&
+      hook.timeout === other.timeout
+    );
+  });
+}
+
+function mergeHookEntries(
+  existing: HookMatcherEntry[] = [],
+  managed: HookMatcherEntry[],
+): HookMatcherEntry[] {
+  const managedSuffixes = managed.flatMap((entry) =>
+    entry.hooks.map((hook) => hook.command.replace(/^.*\/codex\/hooks\//, '/codex/hooks/')),
+  );
+
+  const filtered = existing.filter(
+    (entry) =>
+      !managed.some((managedEntry) =>
+        managedEntry.hooks.some(() =>
+          entry.hooks.some((hook) => {
+            const normalized = hook.command.replace(/^.*\/codex\/hooks\//, '/codex/hooks/');
+            return managedSuffixes.includes(normalized);
+          }),
+        ),
+      ),
+  );
+
+  return [...filtered, ...managed];
+}
+
+export function buildManagedHooks(clientDir: string): HooksFile {
+  const built = buildCodexHooksFile(clientDir) as InstallHooksFile;
+  return { hooks: built.hooks as Record<string, InstallHookMatcherEntry[]> };
+}
+
+export function mergeHooksFile(existing: HooksFile, managed: HooksFile): HooksFile {
+  const output: HooksFile = { hooks: { ...(existing.hooks || {}) } };
+  const managedHooks = managed.hooks || {};
+
+  for (const [eventName, managedEntries] of Object.entries(managedHooks)) {
+    const currentEntries = output.hooks?.[eventName] || [];
+    const merged = mergeHookEntries(currentEntries, managedEntries);
+
+    if (
+      currentEntries.length === merged.length &&
+      currentEntries.every((entry, index) => sameHook(entry, merged[index]!))
+    ) {
+      continue;
+    }
+
+    output.hooks![eventName] = merged;
+  }
+
+  return output;
+}
+
+export function ensureCodexHooksFeature(configToml: string): string {
+  const text = configToml.trimEnd();
+
+  if (/^\s*codex_hooks\s*=\s*true\s*$/m.test(text) && /^\s*\[features\]\s*$/m.test(text)) {
+    return `${text}\n`;
+  }
+
+  if (/^\s*\[features\]\s*$/m.test(text)) {
+    if (/^\s*codex_hooks\s*=.*$/m.test(text)) {
+      return `${text.replace(/^\s*codex_hooks\s*=.*$/m, 'codex_hooks = true')}\n`;
+    }
+
+    return `${text.replace(/^\s*\[features\]\s*$/m, '[features]\ncodex_hooks = true')}\n`;
+  }
+
+  const prefix = text ? `${text}\n\n` : '';
+  return `${prefix}[features]\ncodex_hooks = true\n`;
+}

package/core/feedback.ts

@@ -0,0 +1,55 @@
+import {
+  callMcpToolDetailed,
+  markClassificationFeedbackSubmitted,
+  readGmtrConfig,
+} from '../hooks/lib/gmtr-hook-utils.ts';
+
+export interface ClassificationFeedbackSubmitOptions {
+  rootDir: string;
+  sessionId: string;
+  originalPrompt?: string;
+  clientType: string;
+  agentName: string;
+  downstreamProvider?: string;
+}
+
+export async function submitPendingClassificationFeedback(
+  options: ClassificationFeedbackSubmitOptions,
+): Promise<{ submitted: boolean; reason: string }> {
+  const config = readGmtrConfig(options.rootDir);
+  const last = config?.current_session?.last_classification;
+
+  if (!last?.pending_feedback) {
+    return { submitted: false, reason: 'no_pending_feedback' };
+  }
+
+  const originalPrompt = (options.originalPrompt || last.original_prompt || '').trim();
+  if (!originalPrompt) {
+    return { submitted: false, reason: 'missing_original_prompt' };
+  }
+
+  if (config?.current_session?.session_id && config.current_session.session_id !== options.sessionId) {
+    return { submitted: false, reason: 'session_mismatch' };
+  }
+
+  const result = await callMcpToolDetailed(
+    'gmtr_classification_feedback',
+    {
+      timestamp: last.timestamp,
+      was_correct: true,
+      original_prompt: originalPrompt,
+      downstream_model: last.downstream_model || undefined,
+      downstream_provider: options.downstreamProvider,
+      client_type: options.clientType,
+      agent_name: options.agentName,
+    },
+    10000,
+  );
+
+  if (result.data) {
+    markClassificationFeedbackSubmitted(options.rootDir);
+    return { submitted: true, reason: 'submitted' };
+  }
+
+  return { submitted: false, reason: result.error?.reason || 'unknown_error' };
+}

package/core/formatting.ts

@@ -0,0 +1,167 @@
+import type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+} from './types.ts';
+
+function trimLine(line: string): string {
+  return line.replace(/\s+/g, ' ').trim();
+}
+
+function formatList(title: string, items: string[] | undefined, maxItems = 5): string[] {
+  if (!items || items.length === 0) return [];
+  const lines = [title];
+  for (const item of items.slice(0, maxItems)) {
+    const text = trimLine(item);
+    if (text) lines.push(`- ${text}`);
+  }
+  return lines.length > 1 ? lines : [];
+}
+
+function formatMemoryContext(route: RouteResponse): string[] {
+  const results = route.memory_context?.results ?? [];
+  if (results.length === 0) return [];
+
+  const lines = ['Memory context:'];
+  for (const result of results.slice(0, 3)) {
+    const labelParts = [result.entity_name, result.entity_type].filter(Boolean);
+    const label = labelParts.join(' / ');
+    const content = trimLine(result.content || '').slice(0, 220);
+    if (label && content) {
+      lines.push(`- ${label}: ${content}`);
+    } else if (label) {
+      lines.push(`- ${label}`);
+    } else if (content) {
+      lines.push(`- ${content}`);
+    }
+  }
+  return lines.length > 1 ? lines : [];
+}
+
+export function buildUserPromptAdditionalContext(route: RouteResponse): string {
+  const lines = ['[GMTR Intelligence]'];
+  const classification = route.classification;
+
+  if (classification) {
+    const parts = [
+      classification.effort_level ? `effort=${classification.effort_level}` : '',
+      classification.intent_type ? `intent=${classification.intent_type}` : '',
+      classification.memory_tier ? `memory=${classification.memory_tier}` : '',
+    ].filter(Boolean);
+    if (parts.length > 0) lines.push(parts.join(' | '));
+  }
+
+  if (route.project_state?.current_phase || route.project_state?.active_prd_title) {
+    const phase = route.project_state.current_phase || 'unknown';
+    const prd = route.project_state.active_prd_title;
+    lines.push(`Project state: phase=${phase}${prd ? ` | prd=${prd}` : ''}`);
+  }
+
+  if (route.capability_audit?.formatted_summary) {
+    lines.push(route.capability_audit.formatted_summary.trim());
+  }
+
+  if (route.context_pre_load_plan?.entity_types?.length) {
+    const tier = route.context_pre_load_plan.tier || 'none';
+    lines.push(`Preload plan: tier=${tier} | entities=${route.context_pre_load_plan.entity_types.join(', ')}`);
+  }
+
+  lines.push(...formatList('Explicit wants:', classification?.reverse_engineering?.explicit_wants));
+  lines.push(...formatList('Implicit wants:', classification?.reverse_engineering?.implicit_wants, 4));
+  lines.push(...formatList('Gotchas:', classification?.reverse_engineering?.gotchas, 4));
+  lines.push(...formatList('Constraints:', classification?.constraints_extracted, 4));
+  lines.push(...formatList('ISC scaffold:', classification?.isc_scaffold, 5));
+  lines.push(...formatList('Behavioral directives:', route.behavioral_directives, 6));
+  lines.push(...formatMemoryContext(route));
+
+  if (route.curated_context) {
+    lines.push('Curated context:');
+    lines.push(route.curated_context.trim());
+  }
+
+  if (route.project_state?.session_history_summary) {
+    lines.push('Session history:');
+    lines.push(route.project_state.session_history_summary.trim());
+  }
+
+  if (route.packet_diagnostics?.memory_context?.status === 'error') {
+    lines.push('Memory diagnostics:');
+    lines.push(`- ${trimLine(route.packet_diagnostics.memory_context.error || 'memory pre-load degraded')}`);
+  }
+
+  if (route.packet_diagnostics?.project_state?.status === 'error') {
+    lines.push('Project state diagnostics:');
+    lines.push(`- ${trimLine(route.packet_diagnostics.project_state.error || 'project state degraded')}`);
+  }
+
+  const degradedClassifierStages = route.execution_summary?.degraded_components?.filter((component) =>
+    component.startsWith('classification.'),
+  ) || [];
+  if (degradedClassifierStages.length > 0) {
+    lines.push('Classifier diagnostics:');
+    for (const component of degradedClassifierStages) {
+      lines.push(`- ${trimLine(component.replace('classification.', '').replace(/_/g, ' ') + ' degraded')}`);
+    }
+  }
+
+  return lines.join('\n').trim();
+}
+
+export function buildSessionStartAdditionalContext(
+  projectId: string,
+  sessionStart: SessionStartResponse | null,
+  handoff: HandoffResponse | null,
+): string {
+  const lines = ['[GMTR Session Context]'];
+  lines.push(`Project: ${projectId}`);
+
+  if (sessionStart?.interaction_id) {
+    lines.push(`Interaction: ${sessionStart.interaction_id}`);
+  }
+  if (handoff?.source || handoff?._meta?.platform || handoff?._meta?.branch) {
+    const metaParts = [
+      handoff.source ? `source=${handoff.source}` : '',
+      handoff._meta?.platform ? `platform=${handoff._meta.platform}` : '',
+      handoff._meta?.branch ? `branch=${handoff._meta.branch}` : '',
+    ].filter(Boolean);
+    if (metaParts.length > 0) lines.push(`Handoff meta: ${metaParts.join(' | ')}`);
+  }
+
+  if (handoff?.where_we_are) {
+    lines.push('Where we are:');
+    lines.push(handoff.where_we_are.trim());
+  }
+  if (handoff?.what_shipped) {
+    lines.push('What shipped:');
+    lines.push(handoff.what_shipped.trim());
+  }
+  if (handoff?.whats_next) {
+    lines.push('What is next:');
+    lines.push(handoff.whats_next.trim());
+  }
+  if (handoff?.key_context) {
+    lines.push('Key context:');
+    lines.push(handoff.key_context.trim());
+  }
+  if (handoff?.dont_forget) {
+    lines.push('Do not forget:');
+    lines.push(handoff.dont_forget.trim());
+  }
+
+  if (!handoff?.where_we_are && !handoff?.whats_next && !handoff?.key_context) {
+    lines.push('No saved handoff was found. Query gramatr memory before doing context recovery.');
+  }
+
+  return lines.join('\n').trim();
+}
+
+export function buildHookFailureAdditionalContext(failure: HookFailure): string {
+  const lines = ['[GMTR Intelligence Unavailable]'];
+  lines.push(failure.title);
+  lines.push(`Detail: ${trimLine(failure.detail)}`);
+  if (failure.action) {
+    lines.push(`Action: ${trimLine(failure.action)}`);
+  }
+  return lines.join('\n').trim();
+}

package/core/install.ts

@@ -0,0 +1,114 @@
+export interface InstallHookCommand {
+  type: 'command';
+  command: string;
+  statusMessage?: string;
+  timeout?: number;
+}
+
+export interface InstallHookMatcherEntry {
+  matcher?: string;
+  hooks: InstallHookCommand[];
+}
+
+export interface InstallHooksFile {
+  hooks: Record<string, InstallHookMatcherEntry[]>;
+}
+
+interface HookSpec {
+  event: string;
+  matcher?: string;
+  relativeCommand: string;
+  statusMessage?: string;
+  timeout?: number;
+}
+
+interface ClaudeHookOptions {
+  tsRunner?: string;
+}
+
+const CLAUDE_HOOKS: HookSpec[] = [
+  { event: 'PreToolUse', matcher: 'Bash', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Edit', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Write', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'Read', relativeCommand: 'hooks/GMTRSecurityValidator.hook.ts' },
+  { event: 'PostToolUse', matcher: 'mcp__.*gramatr.*__', relativeCommand: 'hooks/GMTRToolTracker.hook.ts' },
+  { event: 'UserPromptSubmit', relativeCommand: 'hooks/GMTRRatingCapture.hook.ts' },
+  { event: 'UserPromptSubmit', relativeCommand: 'hooks/GMTRPromptEnricher.hook.ts' },
+  { event: 'SessionStart', relativeCommand: 'hooks/session-start.hook.ts' },
+  { event: 'SessionEnd', relativeCommand: 'hooks/session-end.hook.ts' },
+  { event: 'Stop', relativeCommand: 'hooks/StopOrchestrator.hook.ts' },
+];
+
+const CODEX_HOOKS: HookSpec[] = [
+  {
+    event: 'SessionStart',
+    matcher: 'startup|resume',
+    relativeCommand: 'codex/hooks/session-start.ts',
+    statusMessage: 'Loading gramatr session context',
+    timeout: 15,
+  },
+  {
+    event: 'UserPromptSubmit',
+    relativeCommand: 'codex/hooks/user-prompt-submit.ts',
+    statusMessage: 'Routing request through gramatr',
+    timeout: 15,
+  },
+  {
+    event: 'Stop',
+    relativeCommand: 'codex/hooks/stop.ts',
+    statusMessage: 'Submitting gramatr classification feedback',
+    timeout: 10,
+  },
+];
+
+/**
+ * Detect the best available TypeScript runner.
+ * Priority: bun (fastest) > npx tsx (universal Node fallback)
+ */
+export function detectTsRunner(): string {
+  try {
+    const { execSync } = require('child_process');
+    execSync('bun --version', { stdio: 'ignore' });
+    return 'bun';
+  } catch {
+    return 'npx tsx';
+  }
+}
+
+function buildHooksFile(clientDir: string, specs: HookSpec[], tsRunner?: string): InstallHooksFile {
+  const runner = tsRunner || detectTsRunner();
+  const hooks: Record<string, InstallHookMatcherEntry[]> = {};
+
+  for (const spec of specs) {
+    const entry: InstallHookMatcherEntry = {
+      hooks: [
+        {
+          type: 'command',
+          command: `${runner} "${clientDir}/${spec.relativeCommand}"`,
+          statusMessage: spec.statusMessage,
+          timeout: spec.timeout,
+        },
+      ],
+    };
+
+    if (spec.matcher) {
+      entry.matcher = spec.matcher;
+    }
+
+    hooks[spec.event] ||= [];
+    hooks[spec.event].push(entry);
+  }
+
+  return { hooks };
+}
+
+export function buildClaudeHooksFile(
+  clientDir: string,
+  options: ClaudeHookOptions = {},
+): InstallHooksFile {
+  return buildHooksFile(clientDir, CLAUDE_HOOKS, options.tsRunner);
+}
+
+export function buildCodexHooksFile(clientDir: string, tsRunner?: string): InstallHooksFile {
+  return buildHooksFile(clientDir, CODEX_HOOKS, tsRunner);
+}

package/core/installer-cli.ts

@@ -0,0 +1,122 @@
+import type { StaleArtifact } from './migration.ts';
+import type { IntegrationTargetId } from './targets.ts';
+
+export interface DetectionDisplayTarget {
+  id: IntegrationTargetId;
+  label: string;
+  kind: 'local' | 'remote';
+  description: string;
+  detection: {
+    detected: boolean;
+    details?: string;
+  };
+}
+
+export function formatDetectionLines(detections: DetectionDisplayTarget[]): string[] {
+  const locals = detections.filter((target) => target.kind === 'local');
+  const remotes = detections.filter((target) => target.kind === 'remote');
+  const lines: string[] = [];
+
+  lines.push('Detected local integration targets:');
+  for (const target of locals) {
+    const status = target.detection.detected ? 'detected' : 'not found';
+    const suffix = target.detection.details ? ` (${target.detection.details})` : '';
+    lines.push(`- ${target.id}: ${status}${suffix}`);
+  }
+
+  lines.push('');
+  lines.push('Remote / hosted integration targets:');
+  for (const target of remotes) {
+    const suffix = target.detection.details ? ` (${target.detection.details})` : '';
+    lines.push(`- ${target.id}: ${target.description}${suffix}`);
+  }
+
+  return lines;
+}
+
+export function formatRemoteGuidanceLines(detections: DetectionDisplayTarget[]): string[] {
+  const remotes = detections.filter((target) => target.kind === 'remote');
+  const lines: string[] = [];
+  lines.push('');
+  lines.push('Hosted / remote targets are configured differently:');
+  for (const target of remotes) {
+    lines.push(`- ${target.id}: ${target.description}`);
+  }
+  lines.push("Use 'gramatr install remote-mcp' for remote setup guidance.");
+  return lines;
+}
+
+export function formatInstallMenuLines(
+  detections: DetectionDisplayTarget[],
+): { lines: string[]; targetIds: IntegrationTargetId[] } {
+  const targets = detections.filter((target) => target.kind === 'local');
+  const lines = ['Available local install targets:'];
+  for (const [index, target] of targets.entries()) {
+    const status = target.detection.detected ? 'detected' : 'not found';
+    lines.push(`${index + 1}. ${target.label} (${target.id}) - ${status}`);
+  }
+  lines.push(`${targets.length + 1}. all detected local targets`);
+  return { lines, targetIds: targets.map((target) => target.id) };
+}
+
+export function resolveInteractiveSelection(
+  answer: string,
+  targetIds: IntegrationTargetId[],
+  detectedLocalTargets: IntegrationTargetId[],
+  resolveTarget: (id: string) => { id: IntegrationTargetId; kind: 'local' | 'remote' } | undefined,
+): IntegrationTargetId[] {
+  if (!answer) return [];
+  if (answer === 'all') return detectedLocalTargets;
+
+  const parts = answer.split(',').map((part) => part.trim()).filter(Boolean);
+  const selected = new Set<IntegrationTargetId>();
+
+  for (const part of parts) {
+    const numeric = Number(part);
+    if (!Number.isNaN(numeric) && Number.isInteger(numeric)) {
+      if (numeric === targetIds.length + 1) {
+        for (const target of detectedLocalTargets) selected.add(target);
+        continue;
+      }
+      const indexed = targetIds[numeric - 1];
+      if (indexed) {
+        selected.add(indexed);
+        continue;
+      }
+    }
+
+    const target = resolveTarget(part);
+    if (target?.kind === 'local') {
+      selected.add(target.id);
+      continue;
+    }
+
+    throw new Error(`Unknown install target selection: ${part}`);
+  }
+
+  return Array.from(selected);
+}
+
+export function formatDoctorLines(
+  detections: DetectionDisplayTarget[],
+  payloadDir: string,
+  payloadPresent: boolean,
+  staleArtifacts: StaleArtifact[],
+): string[] {
+  const lines = formatDetectionLines(detections);
+  lines.push('');
+  lines.push(`Payload dir: ${payloadDir} ${payloadPresent ? '(present)' : '(missing)'}`);
+
+  if (staleArtifacts.length === 0) {
+    lines.push('Stale legacy artifacts: none detected');
+    return lines;
+  }
+
+  lines.push('Stale legacy artifacts:');
+  for (const artifact of staleArtifacts) {
+    lines.push(`- ${artifact.path} (${artifact.reason})`);
+  }
+  lines.push('Run `gramatr upgrade` after cleanup to re-sync installed targets.');
+  return lines;
+}
+