gramatr 0.3.0

package/hooks/lib/identity.ts

@@ -0,0 +1,227 @@
+/**
+ * Central Identity Loader
+ * Single source of truth for DA (Digital Assistant) and Principal identity
+ *
+ * Reads from settings.json - the programmatic way, not markdown parsing.
+ * All hooks and tools should import from here.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const HOME = process.env.HOME!;
+const GMTR_DIR = process.env.GMTR_DIR || join(HOME, 'gmtr-client');
+const GMTR_SETTINGS_PATH = join(GMTR_DIR, 'settings.json');        // gramatr-owned, vendor-agnostic
+const CLAUDE_SETTINGS_PATH = join(HOME, '.claude/settings.json');   // legacy fallback only
+
+// Default identity (fallback if settings.json doesn't have identity section)
+const DEFAULT_IDENTITY = {
+  name: 'gramatr',
+  fullName: 'gramatr — Personal AI',
+  displayName: 'gramatr',
+  mainDAVoiceID: '',
+  color: '#3B82F6',
+};
+
+const DEFAULT_PRINCIPAL = {
+  name: 'User',
+  pronunciation: '',
+  timezone: 'UTC',
+};
+
+export interface VoiceProsody {
+  stability: number;
+  similarity_boost: number;
+  style: number;
+  speed: number;
+  use_speaker_boost: boolean;
+}
+
+export interface VoicePersonality {
+  baseVoice: string;
+  enthusiasm: number;
+  energy: number;
+  expressiveness: number;
+  resilience: number;
+  composure: number;
+  optimism: number;
+  warmth: number;
+  formality: number;
+  directness: number;
+  precision: number;
+  curiosity: number;
+  playfulness: number;
+}
+
+export interface Identity {
+  name: string;
+  fullName: string;
+  displayName: string;
+  mainDAVoiceID: string;
+  color: string;
+  voice?: VoiceProsody;
+  personality?: VoicePersonality;
+}
+
+export interface Principal {
+  name: string;
+  pronunciation: string;
+  timezone: string;
+}
+
+export interface Settings {
+  daidentity?: Partial<Identity>;
+  principal?: Partial<Principal>;
+  env?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+let cachedSettings: Settings | null = null;
+
+/**
+ * Load settings — gramatr-owned config first, Claude vendor file as legacy fallback.
+ *
+ * Priority:
+ *   1. ~/gmtr-client/settings.json (gramatr-owned, vendor-agnostic)
+ *   2. ~/.claude/settings.json (Claude vendor file — legacy fallback only)
+ *
+ * Merges both: gramatr settings take precedence for identity fields,
+ * Claude settings provide hook/permission config that gramatr doesn't own.
+ */
+function loadSettings(): Settings {
+  if (cachedSettings) return cachedSettings;
+
+  let gmtrSettings: Settings = {};
+  let claudeSettings: Settings = {};
+
+  // Load gramatr-owned settings (primary source for identity)
+  try {
+    if (existsSync(GMTR_SETTINGS_PATH)) {
+      gmtrSettings = JSON.parse(readFileSync(GMTR_SETTINGS_PATH, 'utf-8'));
+    }
+  } catch { /* ignore parse errors */ }
+
+  // Load Claude vendor settings (fallback, also provides hooks/permissions)
+  try {
+    if (existsSync(CLAUDE_SETTINGS_PATH)) {
+      claudeSettings = JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8'));
+    }
+  } catch { /* ignore parse errors */ }
+
+  // Merge: gramatr settings override Claude settings for identity fields
+  cachedSettings = {
+    ...claudeSettings,
+    // gramatr-owned fields take precedence
+    ...(gmtrSettings.daidentity ? { daidentity: gmtrSettings.daidentity } : {}),
+    ...(gmtrSettings.principal ? { principal: gmtrSettings.principal } : {}),
+    ...(gmtrSettings.notifications ? { notifications: gmtrSettings.notifications } : {}),
+    ...(gmtrSettings.counts ? { counts: gmtrSettings.counts } : {}),
+  };
+
+  return cachedSettings!;
+}
+
+/**
+ * Get DA (Digital Assistant) identity from settings.json
+ */
+export function getIdentity(): Identity {
+  const settings = loadSettings();
+
+  // Prefer settings.daidentity, fall back to env.DA for backward compat
+  const daidentity = settings.daidentity || {};
+  const envDA = settings.env?.DA;
+
+  // Support both old (daidentity.voice) and new (daidentity.voices.main) structures
+  const voices = (daidentity as any).voices || {};
+  const voiceConfig = voices.main || (daidentity as any).voice;
+
+  return {
+    name: daidentity.name || envDA || DEFAULT_IDENTITY.name,
+    fullName: daidentity.fullName || daidentity.name || envDA || DEFAULT_IDENTITY.fullName,
+    displayName: daidentity.displayName || daidentity.name || envDA || DEFAULT_IDENTITY.displayName,
+    mainDAVoiceID: voiceConfig?.voiceId || (daidentity as any).voiceId || daidentity.mainDAVoiceID || DEFAULT_IDENTITY.mainDAVoiceID,
+    color: daidentity.color || DEFAULT_IDENTITY.color,
+    voice: voiceConfig as VoiceProsody | undefined,
+    personality: (daidentity as any).personality as VoicePersonality | undefined,
+  };
+}
+
+/**
+ * Get Principal (human owner) identity from settings.json
+ */
+export function getPrincipal(): Principal {
+  const settings = loadSettings();
+
+  // Prefer settings.principal, fall back to env.PRINCIPAL for backward compat
+  const principal = settings.principal || {};
+  const envPrincipal = settings.env?.PRINCIPAL;
+
+  return {
+    name: principal.name || envPrincipal || DEFAULT_PRINCIPAL.name,
+    pronunciation: principal.pronunciation || DEFAULT_PRINCIPAL.pronunciation,
+    timezone: principal.timezone || DEFAULT_PRINCIPAL.timezone,
+  };
+}
+
+/**
+ * Clear cache (useful for testing or when settings.json changes)
+ */
+export function clearCache(): void {
+  cachedSettings = null;
+}
+
+/**
+ * Get just the DA name (convenience function)
+ */
+export function getDAName(): string {
+  return getIdentity().name;
+}
+
+/**
+ * Get just the Principal name (convenience function)
+ */
+export function getPrincipalName(): string {
+  return getPrincipal().name;
+}
+
+/**
+ * Get just the voice ID (convenience function)
+ */
+export function getVoiceId(): string {
+  return getIdentity().mainDAVoiceID;
+}
+
+/**
+ * Get the full settings object (for advanced use)
+ */
+export function getSettings(): Settings {
+  return loadSettings();
+}
+
+/**
+ * Get the default identity (for documentation/testing)
+ */
+export function getDefaultIdentity(): Identity {
+  return { ...DEFAULT_IDENTITY };
+}
+
+/**
+ * Get the default principal (for documentation/testing)
+ */
+export function getDefaultPrincipal(): Principal {
+  return { ...DEFAULT_PRINCIPAL };
+}
+
+/**
+ * Get voice prosody settings (convenience function) - legacy ElevenLabs
+ */
+export function getVoiceProsody(): VoiceProsody | undefined {
+  return getIdentity().voice;
+}
+
+/**
+ * Get voice personality settings (convenience function)
+ */
+export function getVoicePersonality(): VoicePersonality | undefined {
+  return getIdentity().personality;
+}

package/hooks/lib/notify.ts

@@ -0,0 +1,46 @@
+/**
+ * gramatr Notification Utility
+ *
+ * Sends local push notifications on macOS via osascript.
+ * Fails silently on non-macOS or if osascript is unavailable.
+ *
+ * Usage:
+ *   import { notify } from './lib/notify';
+ *   notify('Task complete', 'Built 3 files');
+ */
+
+import { platform } from 'os';
+
+/**
+ * Send a local push notification.
+ * macOS: uses osascript display notification
+ * Other platforms: no-op (silent)
+ */
+export function notify(subtitle: string, message: string): void {
+  if (platform() !== 'darwin') return;
+
+  try {
+    // Escape double quotes in message and subtitle
+    const safeMsg = message.replace(/"/g, '\\"');
+    const safeSub = subtitle.replace(/"/g, '\\"');
+
+    const { spawn } = require('child_process');
+    spawn('osascript', ['-e',
+      `display notification "${safeMsg}" with title "gramatr" subtitle "${safeSub}"`,
+    ], { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    // Notification is best-effort — never block on failure
+  }
+}
+
+/**
+ * Send a notification for a security event.
+ */
+export function notifySecurity(event: 'block' | 'confirm' | 'alert', reason: string): void {
+  const labels = {
+    block: 'Security Block',
+    confirm: 'Security Confirm',
+    alert: 'Security Alert',
+  };
+  notify(labels[event], reason);
+}

package/hooks/lib/paths.ts

@@ -0,0 +1,104 @@
+/**
+ * Centralized Path Resolution
+ *
+ * Handles environment variable expansion for portable GMTR configuration.
+ * Claude Code doesn't expand $HOME in settings.json env values, so we do it here.
+ *
+ * Usage:
+ *   import { getGmtrDir, getSettingsPath } from './lib/paths';
+ *   const gmtrDir = getGmtrDir(); // Always returns expanded absolute path
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * Expand shell variables in a path string
+ * Supports: $HOME, ${HOME}, ~
+ */
+export function expandPath(path: string): string {
+  const home = homedir();
+
+  return path
+    .replace(/^\$HOME(?=\/|$)/, home)
+    .replace(/^\$\{HOME\}(?=\/|$)/, home)
+    .replace(/^~(?=\/|$)/, home);
+}
+
+/**
+ * Get the GMTR base directory (expanded)
+ * Priority: GMTR_DIR env var → PAI_DIR env var (migration) → ~/.claude
+ */
+export function getGmtrDir(): string {
+  const envGmtrDir = process.env.GMTR_DIR;
+  if (envGmtrDir) {
+    return expandPath(envGmtrDir);
+  }
+
+  // Migration fallback: honor PAI_DIR if GMTR_DIR not set yet
+  const envPaiDir = process.env.PAI_DIR;
+  if (envPaiDir) {
+    return expandPath(envPaiDir);
+  }
+
+  return join(homedir(), '.claude');
+}
+
+// getPaiDir removed — all callers migrated to getGmtrDir (#116)
+
+/**
+ * Get the settings.json path
+ * Always ~/.claude/settings.json — NOT relative to GMTR_DIR.
+ * GMTR_DIR is the client payload directory (~/gmtr-client), not ~/.claude.
+ */
+export function getSettingsPath(): string {
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+/**
+ * Get a path relative to GMTR_DIR
+ */
+export function gmtrPath(...segments: string[]): string {
+  return join(getGmtrDir(), ...segments);
+}
+
+// Migration alias
+export const paiPath = gmtrPath;
+
+/**
+ * Get the hooks directory
+ */
+export function getHooksDir(): string {
+  return gmtrPath('hooks');
+}
+
+/**
+ * Get the skills directory
+ */
+export function getSkillsDir(): string {
+  return gmtrPath('skills');
+}
+
+/**
+ * Get the MEMORY directory
+ */
+export function getMemoryDir(): string {
+  return gmtrPath('MEMORY');
+}
+
+/**
+ * Get the tools directory
+ * Contains deterministic tools for hook lifecycle, agent-callable, and skill-workflow use.
+ */
+export function getToolsDir(): string {
+  return gmtrPath('tools');
+}
+
+/**
+ * Get the system skill directory
+ * Post-restructure: files live directly in skills/ (no GMTR/ or PAI/ subdirectory)
+ */
+export function getSystemSkillDir(): string {
+  return getSkillsDir();
+}