@gramatr/client 0.6.10 → 0.6.11

package/CLAUDE.md

@@ -10,6 +10,18 @@ ISC scaffold, capability audit, phase templates, and composed agents.
 **Memory:** Use gramatr MCP tools (`search_semantic`, `create_entity`, `add_observation`),
 not local markdown files.
 
+**Entity types (33-type taxonomy):** When calling `create_entity`, `entity_type` MUST be
+one of: user_profile, organization, team, project, decision, task, milestone, prd,
+steering_rule, skill, agent_definition, playbook, standard, reference, blog_idea,
+agent_diary, session, conversation, turn, classification_record, agent_execution,
+intelligence_packet, learning_signal, learning_reflection, learning_pattern,
+learning_correction, attachment, execution_record, model_evaluation, benchmark,
+external_connection, infrastructure, audit_log. Invalid types will be blocked by
+the PreToolUse hook. Call `gramatr_list_entity_types` for descriptions.
+
+**Required fields:** task/milestone status: open|in_progress|blocked|review|done.
+Decision requires status + project_id. Session requires status + project_id.
+
 **Identity:** Read from `~/.gramatr/settings.json` — `daidentity` for your name,
 `principal` for the user's name.
 

package/README.md

@@ -64,7 +64,7 @@ Every interaction trains the classifier. Memory powers routing, routing generate
 gramatr is a thin client + smart server:
 
 - **Client** (this package): 29 files, ~290KB. Hooks into your AI agent, forwards to server.
-- **Server**: Decision routing engine (BERT + Qwen), knowledge graph (PostgreSQL + pgvector), pattern learning.
+- **Server**: Decision routing engine (BERT + Llama 3.2 3B), knowledge graph (PostgreSQL + pgvector), pattern learning.
 - **Protocol**: MCP (Model Context Protocol) for Claude Code/Codex, REST API for web/mobile.
 
 The client never stores intelligence locally. The server delivers everything: behavioral rules, skill routing, agent composition, ISC scaffolds, capability audits.

package/core/install.ts

@@ -31,6 +31,7 @@ const CLAUDE_HOOKS: HookSpec[] = [
   { event: 'PreToolUse', matcher: 'Edit', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
   { event: 'PreToolUse', matcher: 'Write', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
   { event: 'PreToolUse', matcher: 'Read', relativeCommand: 'hooks/gramatr-security-validator.hook.ts' },
+  { event: 'PreToolUse', matcher: 'mcp__.*gramatr.*__', relativeCommand: 'hooks/gramatr-input-validator.hook.ts' },
   { event: 'PostToolUse', matcher: 'mcp__.*gramatr.*__', relativeCommand: 'hooks/gramatr-tool-tracker.hook.ts' },
   { event: 'UserPromptSubmit', relativeCommand: 'hooks/gramatr-rating-capture.hook.ts' },
   { event: 'UserPromptSubmit', relativeCommand: 'hooks/gramatr-prompt-enricher.hook.ts' },

package/hooks/generated/schema-constants.ts

@@ -0,0 +1,100 @@
+/**
+ * AUTO-GENERATED — do not edit manually.
+ * Source: @gramatr/core/contracts/mcp-schemas.ts
+ * Generator: scripts/generate-schema-constants.ts
+ * Generated: 2026-04-09T18:14:19.706Z
+ *
+ * These constants are extracted from canonical Zod schemas at build time
+ * so client hooks can validate MCP tool inputs without depending on
+ * @gramatr/core at runtime.
+ */
+
+// ── Classifier enums ──
+export const EFFORT_LEVELS = ["instant","fast","standard","extended","deep","advanced","comprehensive"] as const;
+export const INTENT_TYPES = ["search","retrieve","create","update","analyze","generate"] as const;
+export const MEMORY_TIERS = ["hot","warm","cold","none"] as const;
+
+// ── Entity type enum (33-type taxonomy) ──
+export const ENTITY_TYPES = ["user_profile","organization","team","project","decision","task","milestone","prd","steering_rule","skill","agent_definition","playbook","standard","reference","blog_idea","agent_diary","session","conversation","turn","classification_record","agent_execution","intelligence_packet","learning_signal","learning_reflection","learning_pattern","learning_correction","attachment","execution_record","model_evaluation","benchmark","external_connection","infrastructure","audit_log"] as const;
+
+// ── Lifecycle enums ──
+export const WORK_STATUSES = ["open","in_progress","blocked","review","done"] as const;
+export const PROJECT_STATUSES = ["active","archived","planning"] as const;
+export const SESSION_STATUSES = ["active","completed","abandoned"] as const;
+export const DECISION_STATUSES = ["proposed","accepted","superseded","deprecated"] as const;
+export const PRD_STATUSES = ["draft","criteria_defined","planned","in_progress","verifying","complete","failed","blocked"] as const;
+export const OUTCOMES = ["success","partial","failed","abandoned"] as const;
+export const EMBEDDING_STATUSES = ["pending","processing","complete","failed"] as const;
+
+// ── Domain & classification ──
+export const DOMAINS = ["data-engineering","platform-engineering","ai-infrastructure","product","operations","security","frontend","backend","devops","design"] as const;
+export const ALGORITHM_PHASES = ["observe","think","plan","build","execute","verify","learn"] as const;
+export const AGENT_TYPES = ["Architect","Engineer","Researcher","QATester","Designer","Intern","Pentester","Artist","custom"] as const;
+export const PATTERN_TYPES = ["sequential_actions","tool_preference","effort_pattern","time_pattern","domain_affinity","skill_chain"] as const;
+export const DIARY_SCOPES = ["project","user","team","org"] as const;
+
+// ── Infrastructure & connection ──
+export const INFRA_TYPES = ["compute","database","storage","network","workstation","cluster","service"] as const;
+export const EXTERNAL_SERVICES = ["superset","salesforce","github","jira","linear","slack","discord","notion","custom"] as const;
+export const AUTH_TYPES = ["oauth2","api_key","basic","token"] as const;
+export const CONNECTION_STATUSES = ["connected","expired","revoked","error"] as const;
+
+// ── Knowledge & content ──
+export const ENFORCEMENT_LEVELS = ["mandatory","recommended","informational"] as const;
+export const DECISION_TYPES = ["architecture","tooling","process","security","data","infrastructure","product","operational"] as const;
+export const REFERENCE_TYPES = ["documentation","api_spec","diagram","article","url"] as const;
+export const MODEL_PREFERENCES = ["opus","sonnet","haiku","gpt-4o","gpt-4o-mini","o3","llama-3.2","qwen-3","gemini-2.5"] as const;
+
+// ── Audit ──
+export const AUDIT_EVENT_TYPES = ["auth","entity_crud","search","admin","api_key","config","oauth","export"] as const;
+export const AUDIT_ACTIONS = ["create","read","update","delete","login","logout","grant","revoke","export","import"] as const;
+export const AUDIT_RESOURCE_TYPES = ["entity","observation","relation","api_key","session","oauth_client","user","embedding_model"] as const;
+
+// ── Lookup sets (for O(1) validation in hooks) ──
+export const ENTITY_TYPE_SET = new Set<string>(ENTITY_TYPES);
+export const EFFORT_LEVEL_SET = new Set<string>(EFFORT_LEVELS);
+export const INTENT_TYPE_SET = new Set<string>(INTENT_TYPES);
+export const MEMORY_TIER_SET = new Set<string>(MEMORY_TIERS);
+export const WORK_STATUS_SET = new Set<string>(WORK_STATUSES);
+
+/**
+ * Per-tool required field validation rules.
+ * Maps tool name -> array of { field, validValues? } checks.
+ * If validValues is provided, the field must be one of those values.
+ * If validValues is omitted, the field just needs to be present and non-empty.
+ */
+export const TOOL_INPUT_RULES: Record<string, Array<{ field: string; validValues?: readonly string[] }>> = {
+  create_entity: [
+    { field: 'name' },
+    { field: 'entity_type', validValues: ENTITY_TYPES },
+  ],
+  update_entity: [
+    { field: 'entity_id' },
+  ],
+  add_observation: [
+    { field: 'entity_id' },
+    { field: 'content' },
+  ],
+  search_semantic: [
+    { field: 'query' },
+  ],
+  search_entities: [],  // all fields optional
+  create_relation: [
+    { field: 'source_entity_id' },
+    { field: 'target_entity_id' },
+    { field: 'relation_type' },
+  ],
+  mark_entity_inactive: [
+    { field: 'entity_id' },
+  ],
+  mark_observation_inactive: [
+    { field: 'observation_id' },
+  ],
+  reactivate_entity: [
+    { field: 'entity_id' },
+  ],
+  get_entities: [
+    { field: 'entity_ids' },
+  ],
+  list_entities: [],  // all fields optional
+};

package/hooks/gramatr-input-validator.hook.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env npx tsx
+/**
+ * gramatr-input-validator.hook.ts — PreToolUse Schema Validation
+ *
+ * Validates MCP tool inputs BEFORE the call reaches the server.
+ * Blocks invalid inputs (wrong entity_type, missing required fields)
+ * to save a wasted round trip and tokens.
+ *
+ * TRIGGER: PreToolUse (matcher: mcp__.*gramatr.*__)
+ * PERFORMANCE: <2ms — Set lookups only, no network calls.
+ * SAFETY: On any error, allows the call through (fail-open).
+ *
+ * Issue #459 — Strong typed MCP tool I/O shapes
+ */
+
+import { TOOL_INPUT_RULES, ENTITY_TYPE_SET } from './generated/schema-constants.ts';
+
+// ── Types ──
+
+interface HookInput {
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  session_id?: string;
+  hook_event_name?: string;
+}
+
+interface HookOutput {
+  decision: 'allow' | 'block';
+  reason?: string;
+}
+
+// ── Stdin Reader ──
+
+function readStdin(timeoutMs: number): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk: string) => { data += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.resume();
+  });
+}
+
+// ── Validation ──
+
+function extractToolShortName(fullName: string): string {
+  // mcp__gramatr__create_entity -> create_entity
+  const parts = fullName.split('__');
+  return parts.length >= 3 ? parts.slice(2).join('__') : fullName;
+}
+
+function validate(toolName: string, input: Record<string, unknown>): HookOutput {
+  const shortName = extractToolShortName(toolName);
+  const rules = TOOL_INPUT_RULES[shortName];
+
+  // No rules for this tool — allow
+  if (!rules || rules.length === 0) {
+    return { decision: 'allow' };
+  }
+
+  for (const rule of rules) {
+    const value = input[rule.field];
+
+    // Check presence
+    if (value === undefined || value === null || value === '') {
+      return {
+        decision: 'block',
+        reason: `Missing required field "${rule.field}" for ${shortName}. Provide a non-empty value.`,
+      };
+    }
+
+    // Check enum values
+    if (rule.validValues && typeof value === 'string') {
+      const validSet = rule.field === 'entity_type' ? ENTITY_TYPE_SET : new Set(rule.validValues);
+      if (!validSet.has(value)) {
+        return {
+          decision: 'block',
+          reason: `Invalid ${rule.field}="${value}" for ${shortName}. Valid values: ${rule.validValues.join(', ')}`,
+        };
+      }
+    }
+  }
+
+  // Additional: if any tool passes entity_type, validate it even if not in rules
+  if ('entity_type' in input && typeof input.entity_type === 'string') {
+    if (!ENTITY_TYPE_SET.has(input.entity_type)) {
+      return {
+        decision: 'block',
+        reason: `Invalid entity_type="${input.entity_type}". Valid types: ${[...ENTITY_TYPE_SET].slice(0, 10).join(', ')}... (33 total). Call gramatr_list_entity_types for the full list.`,
+      };
+    }
+  }
+
+  return { decision: 'allow' };
+}
+
+// ── Main ──
+
+async function main() {
+  const raw = await readStdin(2000);
+
+  // Fail-open on any parse error
+  if (!raw.trim()) {
+    console.log(JSON.stringify({ decision: 'allow' }));
+    return;
+  }
+
+  let input: HookInput;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    console.log(JSON.stringify({ decision: 'allow' }));
+    return;
+  }
+
+  const { tool_name, tool_input } = input;
+  if (!tool_name || !tool_input) {
+    console.log(JSON.stringify({ decision: 'allow' }));
+    return;
+  }
+
+  try {
+    const result = validate(tool_name, tool_input);
+    console.log(JSON.stringify(result));
+  } catch {
+    // Fail-open on any validation error
+    console.log(JSON.stringify({ decision: 'allow' }));
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramatr/client",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "publishConfig": {
     "access": "public"
   },
@@ -43,6 +43,7 @@
     "build-mcpb": "npx tsx desktop/build-mcpb.ts",
     "install-web": "echo 'No local install needed. See packages/client/web/README.md for setup instructions.'",
     "migrate-clean-install": "npx tsx bin/clean-legacy-install.ts --apply",
+    "generate-schemas": "npx tsx scripts/generate-schema-constants.ts",
     "gramatr": "npx tsx bin/gramatr.ts",
     "lint": "pnpm exec biome lint --files-ignore-unknown=true package.json bin chatgpt codex core desktop gemini hooks lib tools web vitest.config.ts",
     "test": "vitest run",

package/scripts/generate-schema-constants.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env npx tsx
+/**
+ * Build-time schema constant generator.
+ *
+ * Reads canonical Zod enums from @gramatr/core and writes plain TypeScript
+ * constants into hooks/generated/schema-constants.ts. This keeps the client
+ * hooks self-contained (no runtime dependency on @gramatr/core) while
+ * maintaining a single source of truth for enum values.
+ *
+ * Run: npx tsx scripts/generate-schema-constants.ts
+ * Or:  pnpm generate-schemas
+ *
+ * Issue #459 — Strong typed MCP tool I/O shapes
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// Import canonical schemas from @gramatr/core
+import {
+  EntityTypeEnum,
+  EffortLevelEnum,
+  IntentTypeEnum,
+  MemoryTierEnum,
+  WorkStatusEnum,
+  ProjectStatusEnum,
+  SessionStatusEnum,
+  DecisionStatusEnum,
+  PrdStatusEnum,
+  OutcomeEnum,
+  DomainEnum,
+  AlgorithmPhaseEnum,
+  AgentTypeEnum,
+  PatternTypeEnum,
+  DiaryScopeEnum,
+  InfraTypeEnum,
+  ExternalServiceEnum,
+  AuthTypeEnum,
+  ConnectionStatusEnum,
+  EnforcementEnum,
+  DecisionTypeEnum,
+  ReferenceTypeEnum,
+  AuditEventTypeEnum,
+  AuditActionEnum,
+  AuditResourceTypeEnum,
+  EmbeddingStatusEnum,
+  ModelPreferenceEnum,
+} from '@gramatr/core';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const outDir = join(__dirname, '..', 'hooks', 'generated');
+const outFile = join(outDir, 'schema-constants.ts');
+
+// Extract .options from each Zod enum
+function vals(zodEnum: { options: readonly string[] }): string {
+  return JSON.stringify([...zodEnum.options]);
+}
+
+const content = `/**
+ * AUTO-GENERATED — do not edit manually.
+ * Source: @gramatr/core/contracts/mcp-schemas.ts
+ * Generator: scripts/generate-schema-constants.ts
+ * Generated: ${new Date().toISOString()}
+ *
+ * These constants are extracted from canonical Zod schemas at build time
+ * so client hooks can validate MCP tool inputs without depending on
+ * @gramatr/core at runtime.
+ */
+
+// ── Classifier enums ──
+export const EFFORT_LEVELS = ${vals(EffortLevelEnum)} as const;
+export const INTENT_TYPES = ${vals(IntentTypeEnum)} as const;
+export const MEMORY_TIERS = ${vals(MemoryTierEnum)} as const;
+
+// ── Entity type enum (33-type taxonomy) ──
+export const ENTITY_TYPES = ${vals(EntityTypeEnum)} as const;
+
+// ── Lifecycle enums ──
+export const WORK_STATUSES = ${vals(WorkStatusEnum)} as const;
+export const PROJECT_STATUSES = ${vals(ProjectStatusEnum)} as const;
+export const SESSION_STATUSES = ${vals(SessionStatusEnum)} as const;
+export const DECISION_STATUSES = ${vals(DecisionStatusEnum)} as const;
+export const PRD_STATUSES = ${vals(PrdStatusEnum)} as const;
+export const OUTCOMES = ${vals(OutcomeEnum)} as const;
+export const EMBEDDING_STATUSES = ${vals(EmbeddingStatusEnum)} as const;
+
+// ── Domain & classification ──
+export const DOMAINS = ${vals(DomainEnum)} as const;
+export const ALGORITHM_PHASES = ${vals(AlgorithmPhaseEnum)} as const;
+export const AGENT_TYPES = ${vals(AgentTypeEnum)} as const;
+export const PATTERN_TYPES = ${vals(PatternTypeEnum)} as const;
+export const DIARY_SCOPES = ${vals(DiaryScopeEnum)} as const;
+
+// ── Infrastructure & connection ──
+export const INFRA_TYPES = ${vals(InfraTypeEnum)} as const;
+export const EXTERNAL_SERVICES = ${vals(ExternalServiceEnum)} as const;
+export const AUTH_TYPES = ${vals(AuthTypeEnum)} as const;
+export const CONNECTION_STATUSES = ${vals(ConnectionStatusEnum)} as const;
+
+// ── Knowledge & content ──
+export const ENFORCEMENT_LEVELS = ${vals(EnforcementEnum)} as const;
+export const DECISION_TYPES = ${vals(DecisionTypeEnum)} as const;
+export const REFERENCE_TYPES = ${vals(ReferenceTypeEnum)} as const;
+export const MODEL_PREFERENCES = ${vals(ModelPreferenceEnum)} as const;
+
+// ── Audit ──
+export const AUDIT_EVENT_TYPES = ${vals(AuditEventTypeEnum)} as const;
+export const AUDIT_ACTIONS = ${vals(AuditActionEnum)} as const;
+export const AUDIT_RESOURCE_TYPES = ${vals(AuditResourceTypeEnum)} as const;
+
+// ── Lookup sets (for O(1) validation in hooks) ──
+export const ENTITY_TYPE_SET = new Set<string>(ENTITY_TYPES);
+export const EFFORT_LEVEL_SET = new Set<string>(EFFORT_LEVELS);
+export const INTENT_TYPE_SET = new Set<string>(INTENT_TYPES);
+export const MEMORY_TIER_SET = new Set<string>(MEMORY_TIERS);
+export const WORK_STATUS_SET = new Set<string>(WORK_STATUSES);
+
+/**
+ * Per-tool required field validation rules.
+ * Maps tool name -> array of { field, validValues? } checks.
+ * If validValues is provided, the field must be one of those values.
+ * If validValues is omitted, the field just needs to be present and non-empty.
+ */
+export const TOOL_INPUT_RULES: Record<string, Array<{ field: string; validValues?: readonly string[] }>> = {
+  create_entity: [
+    { field: 'name' },
+    { field: 'entity_type', validValues: ENTITY_TYPES },
+  ],
+  update_entity: [
+    { field: 'entity_id' },
+  ],
+  add_observation: [
+    { field: 'entity_id' },
+    { field: 'content' },
+  ],
+  search_semantic: [
+    { field: 'query' },
+  ],
+  search_entities: [],  // all fields optional
+  create_relation: [
+    { field: 'source_entity_id' },
+    { field: 'target_entity_id' },
+    { field: 'relation_type' },
+  ],
+  mark_entity_inactive: [
+    { field: 'entity_id' },
+  ],
+  mark_observation_inactive: [
+    { field: 'observation_id' },
+  ],
+  reactivate_entity: [
+    { field: 'entity_id' },
+  ],
+  get_entities: [
+    { field: 'entity_ids' },
+  ],
+  list_entities: [],  // all fields optional
+};
+`;
+
+mkdirSync(outDir, { recursive: true });
+writeFileSync(outFile, content, 'utf-8');
+console.log(`Generated ${outFile} (${content.length} bytes)`);

package/test/install-matrix/Dockerfile.linux-fresh

@@ -0,0 +1,25 @@
+FROM ubuntu:24.04
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       curl ca-certificates git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20.x
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create unprivileged test user (mirrors fresh Linux install)
+RUN useradd -m -s /bin/bash testuser
+
+USER testuser
+WORKDIR /home/testuser
+
+# Pre-create .claude so the installer doesn't fail on prerequisite check
+RUN mkdir -p /home/testuser/.claude
+
+ENV HOME=/home/testuser
+ENV CI=1
+
+ENTRYPOINT ["/bin/bash"]

package/test/install-matrix/Dockerfile.linux-wsl

@@ -0,0 +1,32 @@
+FROM ubuntu:24.04
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       curl ca-certificates git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 20.x
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create unprivileged test user
+RUN useradd -m -s /bin/bash testuser
+
+USER testuser
+WORKDIR /home/testuser
+
+# Pre-create .claude so the installer doesn't fail on prerequisite check
+RUN mkdir -p /home/testuser/.claude
+
+ENV HOME=/home/testuser
+ENV CI=1
+
+# WSL simulation: these env vars trigger WSL-specific paths in installer
+ENV WSL_DISTRO_NAME=Ubuntu-24.04
+ENV WSLENV=1
+
+# Ensure no display (headless WSL scenario — no X11/Wayland)
+# DISPLAY and WAYLAND_DISPLAY are intentionally unset
+
+ENTRYPOINT ["/bin/bash"]

package/test/install-matrix/mock-auth-server.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Mock auth server for install-matrix CI tests.
+ *
+ * Simulates the gramatr API server endpoints used by the installer and
+ * gmtr-login device flow. Uses only Node built-ins (node:http) so it can
+ * run inside Docker containers without tsx or any npm dependencies.
+ *
+ * Binds to port 18930 (or MOCK_PORT env).
+ *
+ * Endpoints:
+ *   GET  /health         -> server health check
+ *   POST /device/start   -> device authorization initiation
+ *   POST /device/token   -> device token polling (pending -> success)
+ *   POST /mcp            -> minimal JSON-RPC success (validates token)
+ *   GET  /verify         -> mock verification page
+ */
+
+import { createServer } from 'node:http';
+
+const PORT = parseInt(process.env.MOCK_PORT || '18930', 10);
+
+// In-memory state for device flow polling.
+// First poll returns authorization_pending, second returns the token.
+let pollCount = 0;
+
+const MOCK_TOKEN = 'mock-access-token-for-ci';
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function html(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'text/html' });
+  res.end(body);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url || '/', `http://localhost:${PORT}`);
+  const method = req.method || 'GET';
+
+  // Log every request for CI debugging
+  process.stderr.write(`[mock-auth] ${method} ${url.pathname}\n`);
+
+  // ── GET /health ──
+  if (method === 'GET' && url.pathname === '/health') {
+    json(res, 200, { status: 'ok', version: '0.0.0-mock' });
+    return;
+  }
+
+  // ── POST /device/start ──
+  if (method === 'POST' && url.pathname === '/device/start') {
+    // Reset poll counter for each new device flow
+    pollCount = 0;
+    json(res, 200, {
+      device_code: 'mock-device-code-ci',
+      user_code: 'MOCK-1234',
+      verification_uri: `http://localhost:${PORT}/verify`,
+      verification_uri_complete: `http://localhost:${PORT}/verify?code=MOCK-1234`,
+      expires_in: 300,
+      interval: 1,
+    });
+    return;
+  }
+
+  // ── POST /device/token ──
+  if (method === 'POST' && url.pathname === '/device/token') {
+    pollCount++;
+    if (pollCount < 2) {
+      // First poll: still pending
+      json(res, 428, {
+        error: 'authorization_pending',
+        error_description: 'The user has not yet authorized the device.',
+        interval: 1,
+      });
+    } else {
+      // Second poll: success
+      json(res, 200, {
+        access_token: MOCK_TOKEN,
+        token_type: 'bearer',
+        expires_in: 31536000,
+      });
+    }
+    return;
+  }
+
+  // ── POST /mcp ──
+  // Minimal JSON-RPC response so testToken() in gmtr-login.ts considers the
+  // token valid. The client sends a tools/call request and parses SSE lines.
+  if (method === 'POST' && url.pathname === '/mcp') {
+    const body = await readBody(req);
+    let id = 1;
+    try {
+      const parsed = JSON.parse(body);
+      id = parsed.id || 1;
+    } catch { /* ignore */ }
+
+    // Check authorization header
+    const auth = req.headers.authorization || '';
+    if (!auth.includes(MOCK_TOKEN)) {
+      // Reject invalid tokens
+      const ssePayload = `data: ${JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32000, message: 'JWT token is required' },
+      })}\n\n`;
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+      });
+      res.end(ssePayload);
+      return;
+    }
+
+    // Valid token: return a successful aggregate_stats response
+    const ssePayload = `data: ${JSON.stringify({
+      jsonrpc: '2.0',
+      id,
+      result: {
+        content: [{ type: 'text', text: JSON.stringify({ entities: 0, observations: 0, relations: 0 }) }],
+      },
+    })}\n\n`;
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+    });
+    res.end(ssePayload);
+    return;
+  }
+
+  // ── GET /verify ──
+  if (method === 'GET' && url.pathname === '/verify') {
+    html(res, 200, `<!DOCTYPE html>
+<html><head><title>Mock Verification</title></head>
+<body><h1>Mock verification complete</h1>
+<p>This is the CI mock auth server. Device code approved automatically.</p>
+</body></html>`);
+    return;
+  }
+
+  // ── Catch-all ──
+  json(res, 404, { error: 'not_found', path: url.pathname });
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  process.stderr.write(`[mock-auth] Listening on http://127.0.0.1:${PORT}\n`);
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => { server.close(); process.exit(0); });
+process.on('SIGINT', () => { server.close(); process.exit(0); });

package/test/install-matrix/run-install-test.sh

@@ -0,0 +1,335 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────────
+# run-install-test.sh — Fresh-profile install harness for @gramatr/client
+#
+# Validates that `npx @gramatr/client install claude-code` works correctly
+# on a clean machine with no prior gramatr installation.
+#
+# Usage:
+#   ./run-install-test.sh                       # auto-find tarball
+#   ./run-install-test.sh /path/to/gramatr.tgz  # explicit tarball
+#
+# Exit codes:
+#   0 — all phases passed
+#   1 — one or more phases failed
+# ──────────────────────────────────────────────────────────────────────────────
+
+PASS_COUNT=0
+FAIL_COUNT=0
+MOCK_PID=""
+
+cleanup() {
+  if [ -n "$MOCK_PID" ] && kill -0 "$MOCK_PID" 2>/dev/null; then
+    kill "$MOCK_PID" 2>/dev/null || true
+    wait "$MOCK_PID" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+# ── Helpers ──
+
+pass() {
+  echo "  PASS: $1"
+  PASS_COUNT=$((PASS_COUNT + 1))
+}
+
+fail() {
+  echo "  FAIL: $1"
+  FAIL_COUNT=$((FAIL_COUNT + 1))
+}
+
+assert_file_exists() {
+  local path="$1"
+  local label="${2:-$1}"
+  if [ -f "$path" ]; then
+    pass "$label exists"
+  else
+    fail "$label missing ($path)"
+  fi
+}
+
+assert_json_field() {
+  local file="$1"
+  local query="$2"
+  local label="$3"
+  local val
+  val=$(node -e "
+    const fs = require('fs');
+    const data = JSON.parse(fs.readFileSync('$file', 'utf8'));
+    const val = $query;
+    if (val !== undefined && val !== null) {
+      if (typeof val === 'object') process.stdout.write(JSON.stringify(val));
+      else process.stdout.write(String(val));
+    }
+  " 2>/dev/null || true)
+  if [ -n "$val" ]; then
+    pass "$label (= $val)"
+  else
+    fail "$label — field missing or null in $file"
+  fi
+}
+
+assert_no_substring() {
+  local file="$1"
+  local needle="$2"
+  local label="$3"
+  if grep -q "$needle" "$file" 2>/dev/null; then
+    fail "$label — found '$needle' in $file"
+  else
+    pass "$label"
+  fi
+}
+
+# ── Locate tarball ──
+
+TARBALL="${1:-}"
+
+if [ -z "$TARBALL" ]; then
+  for candidate in /artifact/*.tgz ./artifact/*.tgz; do
+    if [ -f "$candidate" ]; then
+      TARBALL="$(cd "$(dirname "$candidate")" && pwd)/$(basename "$candidate")"
+      break
+    fi
+  done
+fi
+
+if [ -z "$TARBALL" ] || [ ! -f "$TARBALL" ]; then
+  echo "ERROR: No tarball found. Pass path as \$1 or place in /artifact/ or ./artifact/"
+  exit 1
+fi
+
+# ── Install tarball into temp dir to get the bin ──
+# npx cannot run a local tarball directly — it tries to execute the .tgz file.
+# Instead: npm install the tarball, then call the bin via node_modules/.bin/.
+
+INSTALL_DIR=$(mktemp -d)
+cd "$INSTALL_DIR"
+npm init -y > /dev/null 2>&1
+npm install "$TARBALL" --no-fund --no-audit > /dev/null 2>&1 || {
+  echo "ERROR: npm install of tarball failed"
+  exit 1
+}
+GRAMATR_BIN="$INSTALL_DIR/node_modules/.bin/gramatr"
+if [ ! -f "$GRAMATR_BIN" ]; then
+  echo "ERROR: gramatr bin not found after npm install"
+  exit 1
+fi
+
+echo "========================================"
+echo "  gramatr install-matrix test harness"
+echo "========================================"
+echo ""
+echo "  Tarball:  $TARBALL"
+echo "  Bin:      $GRAMATR_BIN"
+echo "  HOME:     $HOME"
+echo "  Node:     $(node --version)"
+echo "  Platform: $(uname -s) $(uname -m)"
+echo ""
+
+# ── Phase 0: Start mock auth server ──
+
+echo "--- Phase 0: Mock auth server ---"
+
+MOCK_SERVER_SCRIPT=""
+# Look for mock-auth-server.mjs in known locations
+for candidate in \
+  /test/mock-auth-server.mjs \
+  "$(dirname "$0")/mock-auth-server.mjs" \
+  ./packages/client/test/install-matrix/mock-auth-server.mjs; do
+  if [ -f "$candidate" ]; then
+    MOCK_SERVER_SCRIPT="$candidate"
+    break
+  fi
+done
+
+if [ -z "$MOCK_SERVER_SCRIPT" ]; then
+  echo "  WARNING: mock-auth-server.mjs not found — skipping auth phases"
+else
+  # Check if already running
+  if curl -sf http://127.0.0.1:18930/health >/dev/null 2>&1; then
+    pass "Mock auth server already running"
+  else
+    node "$MOCK_SERVER_SCRIPT" &
+    MOCK_PID=$!
+    # Wait for server to be ready (up to 5 seconds)
+    for i in $(seq 1 50); do
+      if curl -sf http://127.0.0.1:18930/health >/dev/null 2>&1; then
+        break
+      fi
+      sleep 0.1
+    done
+    if curl -sf http://127.0.0.1:18930/health >/dev/null 2>&1; then
+      pass "Mock auth server started (PID $MOCK_PID)"
+    else
+      fail "Mock auth server failed to start"
+      exit 1
+    fi
+  fi
+fi
+
+echo ""
+
+# ── Phase 1: Fresh install ──
+
+echo "--- Phase 1: Fresh install ---"
+
+# Set env so installer uses mock server and runs non-interactively
+export GRAMATR_URL="http://127.0.0.1:18930/mcp"
+export GRAMATR_API_KEY="mock-access-token-for-ci"
+export CI=1
+
+# Run the installer via the bin entry installed from the tarball
+"$GRAMATR_BIN" install claude-code --yes --name TestUser --timezone UTC 2>&1 || {
+  fail "Installer exited with non-zero status"
+  exit 1
+}
+pass "Installer completed successfully"
+
+GMTR_DIR="$HOME/.gramatr"
+
+# Verify critical files
+assert_file_exists "$GMTR_DIR/hooks/gramatr-prompt-enricher.hook.ts" "hooks/gramatr-prompt-enricher.hook.ts"
+assert_file_exists "$GMTR_DIR/hooks/gramatr-tool-tracker.hook.ts" "hooks/gramatr-tool-tracker.hook.ts"
+assert_file_exists "$GMTR_DIR/hooks/gramatr-security-validator.hook.ts" "hooks/gramatr-security-validator.hook.ts"
+assert_file_exists "$GMTR_DIR/hooks/gramatr-rating-capture.hook.ts" "hooks/gramatr-rating-capture.hook.ts"
+assert_file_exists "$GMTR_DIR/core/routing.ts" "core/routing.ts"
+assert_file_exists "$GMTR_DIR/core/types.ts" "core/types.ts"
+assert_file_exists "$GMTR_DIR/core/session.ts" "core/session.ts"
+assert_file_exists "$GMTR_DIR/core/version.ts" "core/version.ts"
+assert_file_exists "$GMTR_DIR/core/install.ts" "core/install.ts"
+assert_file_exists "$GMTR_DIR/bin/statusline.ts" "bin/statusline.ts"
+assert_file_exists "$GMTR_DIR/bin/gmtr-login.ts" "bin/gmtr-login.ts"
+assert_file_exists "$GMTR_DIR/CLAUDE.md" "CLAUDE.md"
+
+echo ""
+
+# ── Phase 2: Settings integrity ──
+
+echo "--- Phase 2: Settings integrity ---"
+
+SETTINGS="$HOME/.claude/settings.json"
+CLAUDE_JSON="$HOME/.claude.json"
+
+assert_file_exists "$SETTINGS" "settings.json"
+assert_file_exists "$CLAUDE_JSON" ".claude.json"
+
+# Hooks present
+assert_json_field "$SETTINGS" "data.hooks?.PreToolUse?.length" "PreToolUse hooks registered"
+assert_json_field "$SETTINGS" "data.hooks?.PostToolUse?.length" "PostToolUse hooks registered"
+assert_json_field "$SETTINGS" "data.hooks?.UserPromptSubmit?.length" "UserPromptSubmit hooks registered"
+assert_json_field "$SETTINGS" "data.hooks?.SessionStart?.length" "SessionStart hooks registered"
+assert_json_field "$SETTINGS" "data.hooks?.SessionEnd?.length" "SessionEnd hooks registered"
+assert_json_field "$SETTINGS" "data.hooks?.Stop?.length" "Stop hooks registered"
+
+# MCP server registered
+assert_json_field "$CLAUDE_JSON" "data.mcpServers?.gramatr?.url" "MCP server 'gramatr' in .claude.json"
+
+# GRAMATR_DIR env set
+assert_json_field "$SETTINGS" "data.env?.GRAMATR_DIR" "GRAMATR_DIR env in settings.json"
+
+# Status line configured
+assert_json_field "$SETTINGS" "data.statusLine?.command" "statusLine command in settings.json"
+
+# Identity config
+assert_file_exists "$GMTR_DIR/settings.json" "gramatr settings.json (identity)"
+assert_json_field "$GMTR_DIR/settings.json" "data.principal?.name" "principal.name set"
+
+echo ""
+
+# ── Phase 3: Headless login (mock device flow) ──
+
+echo "--- Phase 3: Headless login validation ---"
+
+# The installer used GRAMATR_API_KEY which resolveAuthToken picks up first.
+# Verify the token made it through to the config files.
+GMTR_JSON="$HOME/.gramatr.json"
+if [ -f "$GMTR_JSON" ]; then
+  pass ".gramatr.json created"
+  assert_json_field "$GMTR_JSON" "data.token" "Token stored in .gramatr.json"
+else
+  # Token may have been set only in settings.json env — that's also valid
+  pass ".gramatr.json not needed (token via env)"
+fi
+
+# Verify mock server accepted the token (smoke test the /mcp endpoint)
+if [ -n "$MOCK_SERVER_SCRIPT" ]; then
+  MCP_RESULT=$(curl -sf -X POST http://127.0.0.1:18930/mcp \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer mock-access-token-for-ci" \
+    -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"aggregate_stats","arguments":{}}}' \
+    2>/dev/null || true)
+  if echo "$MCP_RESULT" | grep -q '"result"'; then
+    pass "Mock MCP endpoint accepted token"
+  else
+    fail "Mock MCP endpoint rejected token"
+  fi
+fi
+
+echo ""
+
+# ── Phase 4: Idempotent reinstall ──
+
+echo "--- Phase 4: Idempotent reinstall ---"
+
+# Run install again — should not corrupt settings
+"$GRAMATR_BIN" install claude-code --yes --name TestUser --timezone UTC 2>&1 || {
+  fail "Reinstall exited with non-zero status"
+}
+
+# Re-verify critical invariants
+assert_file_exists "$GMTR_DIR/hooks/gramatr-prompt-enricher.hook.ts" "hooks/gramatr-prompt-enricher.hook.ts (after reinstall)"
+assert_json_field "$SETTINGS" "data.hooks?.PreToolUse?.length" "PreToolUse hooks still registered (after reinstall)"
+assert_json_field "$CLAUDE_JSON" "data.mcpServers?.gramatr?.url" "MCP server still registered (after reinstall)"
+
+# Verify settings.json is valid JSON
+if node -e "JSON.parse(require('fs').readFileSync('$SETTINGS', 'utf8'))" 2>/dev/null; then
+  pass "settings.json is valid JSON after reinstall"
+else
+  fail "settings.json is corrupt after reinstall"
+fi
+
+echo ""
+
+# ── Phase 5: No stale paths ──
+
+echo "--- Phase 5: No stale paths ---"
+
+assert_no_substring "$SETTINGS" "PAI_DIR" "No PAI_DIR in settings.json"
+assert_no_substring "$SETTINGS" "aios-v2-client" "No aios-v2-client in settings.json"
+
+if [ -f "$CLAUDE_JSON" ]; then
+  assert_no_substring "$CLAUDE_JSON" "PAI_DIR" "No PAI_DIR in .claude.json"
+  assert_no_substring "$CLAUDE_JSON" "aios-v2-client" "No aios-v2-client in .claude.json"
+fi
+
+# CLAUDE.md should contain GMTR section
+CLAUDE_MD="$HOME/.claude/CLAUDE.md"
+if [ -f "$CLAUDE_MD" ]; then
+  if grep -q "GMTR-START" "$CLAUDE_MD"; then
+    pass "CLAUDE.md contains GMTR-START marker"
+  else
+    fail "CLAUDE.md missing GMTR-START marker"
+  fi
+else
+  fail "CLAUDE.md not created"
+fi
+
+echo ""
+
+# ── Summary ──
+
+echo "========================================"
+echo "  Results: $PASS_COUNT passed, $FAIL_COUNT failed"
+echo "========================================"
+
+if [ "$FAIL_COUNT" -gt 0 ]; then
+  echo ""
+  echo "  SOME TESTS FAILED"
+  exit 1
+else
+  echo ""
+  echo "  ALL TESTS PASSED"
+  exit 0
+fi