@gramatr/client 0.5.1

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/auth.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared installer auth helper — OAuth-first credential resolution.
+ *
+ * Issue #484: Eliminates the paste-API-key prompt from installer flows.
+ * The only interactive auth path is OAuth via gmtr-login.ts. API key
+ * management is handled by the explicit `gramatr add-api-key` subcommand.
+ *
+ * Resolution chain (first non-empty wins):
+ *   1. GRAMATR_API_KEY env var
+ *   2. GMTR_TOKEN env var (legacy)
+ *   3. ~/.gmtr.json `token` field
+ *   4. ~/gmtr-client/settings.json `auth.api_key` (legacy, skips placeholder)
+ *   5. If interactive + TTY: spawn gmtr-login.ts (OAuth)
+ *   6. Otherwise: throw clean actionable error
+ *
+ * This helper NEVER prompts for paste. If you need to add an API key,
+ * use `gramatr add-api-key` (interactive / piped / --from-env).
+ */
+
+import { spawnSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+export interface ResolveAuthTokenOptions {
+  interactive: boolean;
+  installerLabel: string;
+}
+
+const PLACEHOLDER_KEY = "REPLACE_WITH_YOUR_API_KEY";
+
+function readJsonSafe(path: string): Record<string, any> | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function getHome(): string {
+  return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+
+function gmtrJsonPath(): string {
+  return join(getHome(), ".gmtr.json");
+}
+
+function legacySettingsPath(): string {
+  const gmtrDir = process.env.GMTR_DIR || join(getHome(), "gmtr-client");
+  return join(gmtrDir, "settings.json");
+}
+
+function tokenFromEnv(): string | null {
+  if (process.env.GRAMATR_API_KEY) return process.env.GRAMATR_API_KEY;
+  if (process.env.GMTR_TOKEN) return process.env.GMTR_TOKEN;
+  return null;
+}
+
+function tokenFromGmtrJson(): string | null {
+  const data = readJsonSafe(gmtrJsonPath());
+  if (data && typeof data.token === "string" && data.token.trim()) {
+    return data.token.trim();
+  }
+  return null;
+}
+
+function tokenFromLegacySettings(): string | null {
+  const data = readJsonSafe(legacySettingsPath());
+  if (!data) return null;
+  const key = data.auth?.api_key;
+  if (typeof key === "string" && key && key !== PLACEHOLDER_KEY) {
+    return key;
+  }
+  return null;
+}
+
+function findGmtrLoginScript(): string | null {
+  // Resolve gmtr-login.ts relative to this file. In source layout it's at
+  // ../bin/gmtr-login.ts; in installed layout the same relative path holds.
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidate = join(here, "..", "bin", "gmtr-login.ts");
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    // ignore
+  }
+  // Fallback to installed client dir
+  const installedCandidate = join(
+    process.env.GMTR_DIR || join(getHome(), "gmtr-client"),
+    "bin",
+    "gmtr-login.ts",
+  );
+  if (existsSync(installedCandidate)) return installedCandidate;
+  return null;
+}
+
+function spawnOAuthLogin(): { ok: boolean; reason?: string } {
+  const script = findGmtrLoginScript();
+  if (!script) {
+    return { ok: false, reason: "gmtr-login.ts not found on disk" };
+  }
+  // Match the existing handleAuth() pattern in bin/install.ts:383-401 —
+  // npx tsx with inherited stdio so the browser-open message reaches
+  // the user and stdin works correctly.
+  const npxBin = process.platform === "win32" ? "npx.cmd" : "npx";
+  const result = spawnSync(npxBin, ["tsx", script], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  if (result.error) {
+    return { ok: false, reason: result.error.message };
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    return { ok: false, reason: `gmtr-login exited with code ${result.status}` };
+  }
+  return { ok: true };
+}
+
+const HEADLESS_ERROR =
+  "No gramatr credentials found. Set one of:\n" +
+  "  - GRAMATR_API_KEY environment variable\n" +
+  "  - Run: npx @gramatr/client@latest login            (interactive, recommended)\n" +
+  "  - Run: npx @gramatr/client@latest add-api-key      (for headless / CI use)\n" +
+  "Then re-run the install.";
+
+const OAUTH_FAILED_ERROR =
+  'OAuth login failed. Run "npx @gramatr/client@latest login" to retry, ' +
+  'or "npx @gramatr/client@latest add-api-key" to use an API key instead.';
+
+/**
+ * Resolve a gramatr auth token, OAuth-first.
+ *
+ * Never prompts for an API key paste. If interactive and no token is
+ * stored, spawns gmtr-login.ts to run the OAuth flow. If headless or
+ * non-interactive, throws an actionable error pointing the user at the
+ * explicit `gramatr login` and `gramatr add-api-key` commands.
+ */
+export async function resolveAuthToken(opts: ResolveAuthTokenOptions): Promise<string> {
+  // 1 + 2: env vars
+  const envToken = tokenFromEnv();
+  if (envToken) return envToken;
+
+  // 3: ~/.gmtr.json
+  const stored = tokenFromGmtrJson();
+  if (stored) return stored;
+
+  // 4: legacy settings.json
+  const legacy = tokenFromLegacySettings();
+  if (legacy) return legacy;
+
+  // 5: spawn OAuth if interactive + TTY
+  const hasTty = Boolean(process.stdin.isTTY);
+  if (opts.interactive && hasTty) {
+    process.stdout.write(
+      `[${opts.installerLabel}] No gramatr credentials found. Starting OAuth login...\n`,
+    );
+    const result = spawnOAuthLogin();
+    if (!result.ok) {
+      throw new Error(OAUTH_FAILED_ERROR);
+    }
+    const after = tokenFromGmtrJson();
+    if (after) return after;
+    throw new Error("OAuth completed but no token was stored");
+  }
+
+  // 6: headless / non-interactive — clean actionable error
+  throw new Error(HEADLESS_ERROR);
+}

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,179 @@
+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: string[] = [];
+
+  // Cross-tool statusline injection (#496 Phase 3). When the server returns
+  // a composed markdown block, prepend it so Codex / Gemini surface gramatr
+  // status at the top of every turn. Claude Code's routing call leaves the
+  // include_statusline flag off (ISC-A1 of #496) because CC has a native
+  // terminal statusline and we must not double-inject.
+  if (typeof route.statusline_markdown === 'string' && route.statusline_markdown.trim()) {
+    lines.push(route.statusline_markdown.trim());
+    lines.push('');
+  }
+
+  lines.push('[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,107 @@
+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 {
+  includeOptionalUx?: boolean;
+}
+
+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,
+  },
+];
+
+/**
+ * All hook commands are invoked via `npx tsx`. This is the single, portable
+ * runner for every gramatr client install. See issue #468 for the architectural
+ * rationale: bun detection at install time silently produced broken configs on
+ * hosts where the runtime PATH did not match the installer's PATH.
+ */
+const TS_RUNNER = 'npx tsx';
+
+function buildHooksFile(clientDir: string, specs: HookSpec[]): InstallHooksFile {
+  const hooks: Record<string, InstallHookMatcherEntry[]> = {};
+
+  for (const spec of specs) {
+    const entry: InstallHookMatcherEntry = {
+      hooks: [
+        {
+          type: 'command',
+          command: `${TS_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);
+}
+
+export function buildCodexHooksFile(clientDir: string): InstallHooksFile {
+  return buildHooksFile(clientDir, CODEX_HOOKS);
+}