@polymorphism-tech/morph-spec 7.8.1 → 7.9.0

package/framework/hooks/shared/activity-logger.js

@@ -1,160 +1,160 @@
-/**
- * Activity Logger — Session-scoped hook event log
- *
- * Writes hook activity to .morph/logs/activity.json for live consumption
- * by `morph-spec monitor`.
- *
- * Design constraints:
- * - Synchronous only (hooks run in process, no async overhead)
- * - Fail-silent (never throws — hooks must not be blocked by logger)
- * - ≤5ms per call (no retries, no network)
- * - Windows-safe paths via path.join
- */
-
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
-import { join } from 'path';
-
-const LOGS_DIR = '.morph/logs';
-const ACTIVITY_FILE = join(LOGS_DIR, 'activity.json');
-
-function getActivityPath(projectPath) {
-  return join(projectPath || process.cwd(), ACTIVITY_FILE);
-}
-
-function ensureLogsDir(projectPath) {
-  const dir = join(projectPath || process.cwd(), LOGS_DIR);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-}
-
-function readRaw(activityPath) {
-  try {
-    if (!existsSync(activityPath)) return null;
-    return JSON.parse(readFileSync(activityPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Log a hook firing event to the session activity log.
- *
- * @param {string} name   - Hook name (e.g. 'dispatch.js', 'enrich-prompt')
- * @param {string} event  - Claude Code event (e.g. 'PostToolUse', 'UserPromptSubmit')
- * @param {string} result - Outcome summary (e.g. 'ok', 'blocked', 'checkpoint_saved')
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
-export function logHookActivity(name, event, result, projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
-
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
-
-    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
-
-    data.hooks = data.hooks || [];
-    data.hooks.push({ name, event, result, ts });
-
-    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent — never block hooks
-  }
-}
-
-
-/**
- * Read the current activity log.
- *
- * @param {string} [projectPath]
- * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, skills: Array }|null}
- */
-export function readActivity(projectPath) {
-  try {
-    return readRaw(getActivityPath(projectPath));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Reset the activity log for a new session.
- * Called from SessionStart hook to clear stale data.
- *
- * @param {string} sessionId  - ISO timestamp of new session
- * @param {string} feature    - Active feature name (empty string if none)
- * @param {string} phase      - Current phase (empty string if none)
- * @param {string} [projectPath]
- */
-export function resetActivity(sessionId, feature, phase, projectPath) {
-  try {
-    ensureLogsDir(projectPath);
-    const data = {
-      sessionId: sessionId || new Date().toISOString(),
-      feature: feature || '',
-      phase: phase || '',
-      hooks: [],
-      skills: []
-    };
-    writeFileSync(getActivityPath(projectPath), JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent
-  }
-}
-
-/**
- * Log a structured event to the session activity log.
- *
- * @param {string} type   - Event type (e.g., 'task_start', 'loop_detected')
- * @param {Object} data   - Event data payload
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
-export function logEvent(type, data, projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
-
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
-
-    const activity = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], events: [] };
-    activity.events = activity.events || [];
-    activity.events.push({ type, data, ts });
-
-    writeFileSync(activityPath, JSON.stringify(activity, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent
-  }
-}
-
-/**
- * Archive current activity.json to sessions/ directory for historical logging.
- * Called at the start of a new session.
- *
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
-export function archiveSession(projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    if (!existsSync(activityPath)) return;
-
-    const data = readRaw(activityPath);
-    if (!data) return;
-
-    // Only archive if there are meaningful events
-    if ((!data.hooks || data.hooks.length === 0) && (!data.events || data.events.length === 0)) return;
-
-    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
-    mkdirSync(sessionsDir, { recursive: true });
-
-    const sessionId = (data.sessionId || new Date().toISOString()).replace(/[:.]/g, '-');
-    const archivePath = join(sessionsDir, `${sessionId}.json`);
-    writeFileSync(archivePath, JSON.stringify(data, null, 2), 'utf-8');
-
-    unlinkSync(activityPath);
-  } catch {
-    // Fail-silent
-  }
-}
+/**
+ * Activity Logger — Session-scoped hook event log
+ *
+ * Writes hook activity to .morph/logs/activity.json for live consumption
+ * by `morph-spec monitor`.
+ *
+ * Design constraints:
+ * - Synchronous only (hooks run in process, no async overhead)
+ * - Fail-silent (never throws — hooks must not be blocked by logger)
+ * - ≤5ms per call (no retries, no network)
+ * - Windows-safe paths via path.join
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
+import { join } from 'path';
+
+const LOGS_DIR = '.morph/logs';
+const ACTIVITY_FILE = join(LOGS_DIR, 'activity.json');
+
+function getActivityPath(projectPath) {
+  return join(projectPath || process.cwd(), ACTIVITY_FILE);
+}
+
+function ensureLogsDir(projectPath) {
+  const dir = join(projectPath || process.cwd(), LOGS_DIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readRaw(activityPath) {
+  try {
+    if (!existsSync(activityPath)) return null;
+    return JSON.parse(readFileSync(activityPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Log a hook firing event to the session activity log.
+ *
+ * @param {string} name   - Hook name (e.g. 'dispatch.js', 'enrich-prompt')
+ * @param {string} event  - Claude Code event (e.g. 'PostToolUse', 'UserPromptSubmit')
+ * @param {string} result - Outcome summary (e.g. 'ok', 'blocked', 'checkpoint_saved')
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function logHookActivity(name, event, result, projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    ensureLogsDir(projectPath);
+
+    const now = new Date();
+    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
+
+    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
+
+    data.hooks = data.hooks || [];
+    data.hooks.push({ name, event, result, ts });
+
+    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent — never block hooks
+  }
+}
+
+
+/**
+ * Read the current activity log.
+ *
+ * @param {string} [projectPath]
+ * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, skills: Array }|null}
+ */
+export function readActivity(projectPath) {
+  try {
+    return readRaw(getActivityPath(projectPath));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reset the activity log for a new session.
+ * Called from SessionStart hook to clear stale data.
+ *
+ * @param {string} sessionId  - ISO timestamp of new session
+ * @param {string} feature    - Active feature name (empty string if none)
+ * @param {string} phase      - Current phase (empty string if none)
+ * @param {string} [projectPath]
+ */
+export function resetActivity(sessionId, feature, phase, projectPath) {
+  try {
+    ensureLogsDir(projectPath);
+    const data = {
+      sessionId: sessionId || new Date().toISOString(),
+      feature: feature || '',
+      phase: phase || '',
+      hooks: [],
+      skills: []
+    };
+    writeFileSync(getActivityPath(projectPath), JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Log a structured event to the session activity log.
+ *
+ * @param {string} type   - Event type (e.g., 'task_start', 'loop_detected')
+ * @param {Object} data   - Event data payload
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function logEvent(type, data, projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    ensureLogsDir(projectPath);
+
+    const now = new Date();
+    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
+
+    const activity = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], events: [] };
+    activity.events = activity.events || [];
+    activity.events.push({ type, data, ts });
+
+    writeFileSync(activityPath, JSON.stringify(activity, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Archive current activity.json to sessions/ directory for historical logging.
+ * Called at the start of a new session.
+ *
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function archiveSession(projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    if (!existsSync(activityPath)) return;
+
+    const data = readRaw(activityPath);
+    if (!data) return;
+
+    // Only archive if there are meaningful events
+    if ((!data.hooks || data.hooks.length === 0) && (!data.events || data.events.length === 0)) return;
+
+    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
+    mkdirSync(sessionsDir, { recursive: true });
+
+    const sessionId = (data.sessionId || new Date().toISOString()).replace(/[:.]/g, '-');
+    const archivePath = join(sessionsDir, `${sessionId}.json`);
+    writeFileSync(archivePath, JSON.stringify(data, null, 2), 'utf-8');
+
+    unlinkSync(activityPath);
+  } catch {
+    // Fail-silent
+  }
+}

package/framework/hooks/shared/hook-response.js

@@ -1,45 +1,45 @@
-/**
- * Shared hook response builders for Claude Code hooks.
- *
- * Claude Code hooks communicate via JSON to stdout.
- * - PreToolUse: { "decision": "block"|"approve", "reason": "..." }
- * - SessionStart/Stop/etc: { "additionalContext": "..." }
- */
-
-/**
- * Block a tool use with a reason.
- * @param {string} reason - Human-readable reason for blocking
- */
-export function block(reason) {
-  console.log(JSON.stringify({ decision: 'block', reason }));
-  process.exit(0);
-}
-
-/**
- * Approve a tool use, optionally injecting context.
- * @param {string} [context] - Additional context to inject
- */
-export function approve(context) {
-  if (context) {
-    console.log(JSON.stringify({ decision: 'approve', additionalContext: context }));
-  }
-  // No output = implicit approve
-  process.exit(0);
-}
-
-/**
- * Inject additional context (for SessionStart, Stop, UserPromptSubmit, etc.).
- * @param {string} text - Context text to inject
- * @param {Object} [extra] - Additional fields to include in response
- */
-export function injectContext(text, extra = {}) {
-  console.log(JSON.stringify({ additionalContext: text, ...extra }));
-  process.exit(0);
-}
-
-/**
- * Silent exit — no output, no blocking.
- */
-export function pass() {
-  process.exit(0);
-}
+/**
+ * Shared hook response builders for Claude Code hooks.
+ *
+ * Claude Code hooks communicate via JSON to stdout.
+ * - PreToolUse: { "decision": "block"|"approve", "reason": "..." }
+ * - SessionStart/Stop/etc: { "additionalContext": "..." }
+ */
+
+/**
+ * Block a tool use with a reason.
+ * @param {string} reason - Human-readable reason for blocking
+ */
+export function block(reason) {
+  console.log(JSON.stringify({ decision: 'block', reason }));
+  process.exit(0);
+}
+
+/**
+ * Approve a tool use, optionally injecting context.
+ * @param {string} [context] - Additional context to inject
+ */
+export function approve(context) {
+  if (context) {
+    console.log(JSON.stringify({ decision: 'approve', additionalContext: context }));
+  }
+  // No output = implicit approve
+  process.exit(0);
+}
+
+/**
+ * Inject additional context (for SessionStart, Stop, UserPromptSubmit, etc.).
+ * @param {string} text - Context text to inject
+ * @param {Object} [extra] - Additional fields to include in response
+ */
+export function injectContext(text, extra = {}) {
+  console.log(JSON.stringify({ additionalContext: text, ...extra }));
+  process.exit(0);
+}
+
+/**
+ * Silent exit — no output, no blocking.
+ */
+export function pass() {
+  process.exit(0);
+}

package/framework/hooks/shared/payload-utils.js

@@ -1,78 +1,78 @@
-/**
- * Shared payload utilities for Claude Code Write/Edit hooks.
- *
- * Extracts file path and content from tool_input payloads,
- * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
- */
-
-/**
- * Get the file path from a hook payload, normalizing backslashes.
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Normalized file path or empty string
- */
-export function getFilePath(payload) {
-  const raw = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
-  return raw.replace(/\\/g, '/');
-}
-
-/**
- * Get the content being written or edited.
- * For Write: returns `content` (full file content).
- * For Edit: returns `new_string` (replacement text).
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Content string or empty string
- */
-export function getContentToValidate(payload) {
-  const input = payload?.tool_input;
-  if (!input) return '';
-  // Write tool uses 'content', Edit tool uses 'new_string'
-  return input.content || input.new_string || '';
-}
-
-/**
- * Check if this is a Write operation (full file content available).
- * @param {Object} payload - Hook payload from stdin
- * @returns {boolean} True if Write (content exists), false if Edit or unknown
- */
-export function isWriteOperation(payload) {
-  return typeof payload?.tool_input?.content === 'string';
-}
-
-/**
- * Get the tool name from a hook payload.
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Tool name or 'unknown'
- */
-export function getToolName(payload) {
-  return payload?.tool_name || 'unknown';
-}
-
-/**
- * Build a normalized signature for loop detection.
- * - Edit/Write: "Edit:normalized/file/path"
- * - Bash: "Bash:first two words" (e.g., "Bash:npm test")
- * - Other: just the tool name
- *
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Signature string
- */
-export function getCommandSignature(payload) {
-  const tool = getToolName(payload);
-  if (tool === 'unknown') return 'unknown';
-
-  const input = payload?.tool_input;
-  if (!input) return tool;
-
-  if (tool === 'Edit' || tool === 'Write') {
-    const path = (input.file_path || input.path || '').replace(/\\/g, '/');
-    return path ? `${tool}:${path}` : tool;
-  }
-
-  if (tool === 'Bash') {
-    const cmd = (input.command || '').trim();
-    const words = cmd.split(/\s+/).slice(0, 2).join(' ');
-    return words ? `Bash:${words}` : 'Bash';
-  }
-
-  return tool;
-}
+/**
+ * Shared payload utilities for Claude Code Write/Edit hooks.
+ *
+ * Extracts file path and content from tool_input payloads,
+ * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
+ */
+
+/**
+ * Get the file path from a hook payload, normalizing backslashes.
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Normalized file path or empty string
+ */
+export function getFilePath(payload) {
+  const raw = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  return raw.replace(/\\/g, '/');
+}
+
+/**
+ * Get the content being written or edited.
+ * For Write: returns `content` (full file content).
+ * For Edit: returns `new_string` (replacement text).
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Content string or empty string
+ */
+export function getContentToValidate(payload) {
+  const input = payload?.tool_input;
+  if (!input) return '';
+  // Write tool uses 'content', Edit tool uses 'new_string'
+  return input.content || input.new_string || '';
+}
+
+/**
+ * Check if this is a Write operation (full file content available).
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {boolean} True if Write (content exists), false if Edit or unknown
+ */
+export function isWriteOperation(payload) {
+  return typeof payload?.tool_input?.content === 'string';
+}
+
+/**
+ * Get the tool name from a hook payload.
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Tool name or 'unknown'
+ */
+export function getToolName(payload) {
+  return payload?.tool_name || 'unknown';
+}
+
+/**
+ * Build a normalized signature for loop detection.
+ * - Edit/Write: "Edit:normalized/file/path"
+ * - Bash: "Bash:first two words" (e.g., "Bash:npm test")
+ * - Other: just the tool name
+ *
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Signature string
+ */
+export function getCommandSignature(payload) {
+  const tool = getToolName(payload);
+  if (tool === 'unknown') return 'unknown';
+
+  const input = payload?.tool_input;
+  if (!input) return tool;
+
+  if (tool === 'Edit' || tool === 'Write') {
+    const path = (input.file_path || input.path || '').replace(/\\/g, '/');
+    return path ? `${tool}:${path}` : tool;
+  }
+
+  if (tool === 'Bash') {
+    const cmd = (input.command || '').trim();
+    const words = cmd.split(/\s+/).slice(0, 2).join(' ');
+    return words ? `Bash:${words}` : 'Bash';
+  }
+
+  return tool;
+}

package/framework/hooks/shared/stdin-reader.js

@@ -1,26 +1,26 @@
-/**
- * Shared stdin reader for Claude Code hooks.
- *
- * Reads JSON payload from stdin (provided by Claude Code to hooks).
- * Returns parsed object or null on failure.
- */
-
-/**
- * Read and parse JSON from stdin
- * @returns {Promise<Object|null>} Parsed JSON or null
- */
-export function readStdin() {
-  return new Promise((resolve) => {
-    let input = '';
-    process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (chunk) => { input += chunk; });
-    process.stdin.on('end', () => {
-      try {
-        resolve(JSON.parse(input || '{}'));
-      } catch {
-        resolve(null);
-      }
-    });
-    process.stdin.on('error', () => resolve(null));
-  });
-}
+/**
+ * Shared stdin reader for Claude Code hooks.
+ *
+ * Reads JSON payload from stdin (provided by Claude Code to hooks).
+ * Returns parsed object or null on failure.
+ */
+
+/**
+ * Read and parse JSON from stdin
+ * @returns {Promise<Object|null>} Parsed JSON or null
+ */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input || '{}'));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}