@eddacraft/anvil-kindling-integration 0.1.0

package/src/emitters/gate-emitter.ts

@@ -0,0 +1,87 @@
+/**
+ * Gate Emitter (KINDLING-004)
+ *
+ * Emits gate_evaluated observations when gates are checked.
+ * Gate evaluations form the governance record -- why things were
+ * allowed or blocked.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type { GateEvaluatedObservation } from '../observation-contract.js';
+import { createDebugger } from '../utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+/**
+ * Gate evaluation result to be recorded
+ */
+export interface GateResult {
+  session_id: string;
+  gate_id: string;
+  gate_version?: string;
+  inputs: {
+    file_count?: number;
+    changed_files?: string[];
+    baseline_hash?: string;
+  };
+  outcome: 'pass' | 'fail' | 'error' | 'skipped';
+  rules_evaluated: string[];
+  rules_violated?: string[];
+  enforcement: 'blocking' | 'warning' | 'informational';
+  duration_ms: number;
+  violation_count?: number;
+  warning_count?: number;
+}
+
+// =============================================================================
+// Emitter
+// =============================================================================
+
+/**
+ * Emit a gate_evaluated observation.
+ *
+ * @param service - KindlingService instance
+ * @param gateResult - Gate evaluation result
+ * @returns The generated gate_eval_id
+ */
+export function emitGateEvaluated(service: KindlingService, gateResult: GateResult): string {
+  const gateEvalId = randomUUID();
+  debug('emitting gate_evaluated', {
+    gateId: gateResult.gate_id,
+    outcome: gateResult.outcome,
+    gateEvalId,
+  });
+
+  const observation: GateEvaluatedObservation = {
+    kind: 'gate_evaluated',
+    session_id: gateResult.session_id,
+    timestamp: new Date().toISOString(),
+    gate_eval_id: gateEvalId,
+    gate_id: gateResult.gate_id,
+    gate_version: gateResult.gate_version,
+    inputs: {
+      file_count: gateResult.inputs.file_count,
+      changed_files: gateResult.inputs.changed_files,
+      baseline_hash: gateResult.inputs.baseline_hash,
+    },
+    outcome: gateResult.outcome,
+    rules_evaluated: gateResult.rules_evaluated,
+    rules_violated: gateResult.rules_violated,
+    enforcement: gateResult.enforcement,
+    duration_ms: gateResult.duration_ms,
+    violation_count: gateResult.violation_count,
+    warning_count: gateResult.warning_count,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return gateEvalId;
+}

package/src/emitters/human-input-emitter.ts

@@ -0,0 +1,71 @@
+/**
+ * Human Input Emitter (KINDLING-007a)
+ *
+ * Emits human_input observations when a user makes a decision
+ * (approval, override, rejection, manual edit, confirmation, cancellation).
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type { HumanInputObservation } from '../observation-contract.js';
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+/**
+ * Human input details to be recorded
+ */
+export interface HumanInputDetails {
+  session_id: string;
+  input_type:
+    | 'approval'
+    | 'override'
+    | 'rejection'
+    | 'manual_edit'
+    | 'confirmation'
+    | 'cancellation';
+  context: {
+    prompt?: string;
+    target?: string;
+  };
+  decision: string;
+  reason?: string;
+  user_identifier: string;
+}
+
+// =============================================================================
+// Emitter
+// =============================================================================
+
+/**
+ * Emit a human_input observation.
+ *
+ * @param service - KindlingService instance
+ * @param input - Human input details
+ * @returns A generated ID for linking purposes
+ */
+export function emitHumanInput(service: KindlingService, input: HumanInputDetails): string {
+  const inputId = randomUUID();
+
+  const observation: HumanInputObservation = {
+    kind: 'human_input',
+    session_id: input.session_id,
+    timestamp: new Date().toISOString(),
+    input_type: input.input_type,
+    context: {
+      prompt: input.context.prompt,
+      target: input.context.target,
+    },
+    decision: input.decision,
+    reason: input.reason,
+    user_identifier: input.user_identifier,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return inputId;
+}

package/src/emitters/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Emitters Barrel Export (KINDLING-003 through 008)
+ *
+ * All emitter functions and their input types, re-exported for convenience.
+ */
+
+// Session (KINDLING-003)
+export {
+  emitSessionStart,
+  emitSessionEnd,
+  type SessionStartContext,
+  type SessionEndOutcome,
+} from './session-emitter.js';
+
+// Gate (KINDLING-004)
+export { emitGateEvaluated, type GateResult } from './gate-emitter.js';
+
+// Action (KINDLING-005)
+export { emitActionExecuted, type ActionDetails } from './action-emitter.js';
+
+// Plan (KINDLING-006)
+export {
+  emitPlanCreated,
+  emitPlanEdited,
+  emitPlanApproved,
+  emitPlanRejected,
+  type PlanCreatedInput,
+  type PlanEditedInput,
+  type PlanApprovedInput,
+  type PlanRejectedInput,
+} from './plan-emitter.js';
+
+// Human Input (KINDLING-007a)
+export { emitHumanInput, type HumanInputDetails } from './human-input-emitter.js';
+
+// Constraint (KINDLING-007b)
+export { emitConstraintApplied, type ConstraintDetails } from './constraint-emitter.js';
+
+// Error (KINDLING-008)
+export { emitError, type ErrorDetails } from './error-emitter.js';

package/src/emitters/plan-emitter.ts

@@ -0,0 +1,183 @@
+/**
+ * Plan Emitter (KINDLING-006)
+ *
+ * Emits plan lifecycle observations: created, edited, approved, rejected.
+ * Plans are the governance artifacts that authorize actions.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type {
+  PlanCreatedObservation,
+  PlanEditedObservation,
+  PlanApprovedObservation,
+  PlanRejectedObservation,
+} from '../observation-contract.js';
+import { createDebugger } from '../utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+export interface PlanCreatedInput {
+  session_id: string;
+  plan_id?: string;
+  plan_version: string;
+  plan_path: string;
+  plan_hash: string;
+  created_by: 'human' | 'ai' | 'system';
+  source?: string;
+}
+
+export interface PlanEditedInput {
+  session_id: string;
+  plan_id: string;
+  previous_version: string;
+  new_version: string;
+  previous_hash: string;
+  new_hash: string;
+  edited_by: 'human' | 'ai' | 'system';
+  change_summary?: string;
+}
+
+export interface PlanApprovedInput {
+  session_id: string;
+  plan_id: string;
+  plan_version: string;
+  approved_by: string;
+  approval_method: 'cli_confirm' | 'explicit_flag' | 'ci_gate';
+}
+
+export interface PlanRejectedInput {
+  session_id: string;
+  plan_id: string;
+  plan_version: string;
+  rejected_by: string;
+  rejection_reason?: string;
+}
+
+// =============================================================================
+// Emitters
+// =============================================================================
+
+/**
+ * Emit a plan_created observation.
+ *
+ * If no plan_id is provided, one is generated.
+ *
+ * @param service - KindlingService instance
+ * @param plan - Plan creation details
+ * @returns The plan_id (generated or provided)
+ */
+export function emitPlanCreated(service: KindlingService, plan: PlanCreatedInput): string {
+  const planId = plan.plan_id ?? randomUUID();
+  debug('emitting plan_created', { planId, createdBy: plan.created_by });
+
+  const observation: PlanCreatedObservation = {
+    kind: 'plan_created',
+    session_id: plan.session_id,
+    timestamp: new Date().toISOString(),
+    plan_id: planId,
+    plan_version: plan.plan_version,
+    plan_path: plan.plan_path,
+    plan_hash: plan.plan_hash,
+    created_by: plan.created_by,
+    source: plan.source,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return planId;
+}
+
+/**
+ * Emit a plan_edited observation.
+ *
+ * @param service - KindlingService instance
+ * @param edit - Plan edit details
+ * @returns The plan_id
+ */
+export function emitPlanEdited(service: KindlingService, edit: PlanEditedInput): string {
+  debug('emitting plan_edited', { planId: edit.plan_id, editedBy: edit.edited_by });
+
+  const observation: PlanEditedObservation = {
+    kind: 'plan_edited',
+    session_id: edit.session_id,
+    timestamp: new Date().toISOString(),
+    plan_id: edit.plan_id,
+    previous_version: edit.previous_version,
+    new_version: edit.new_version,
+    previous_hash: edit.previous_hash,
+    new_hash: edit.new_hash,
+    edited_by: edit.edited_by,
+    change_summary: edit.change_summary,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return edit.plan_id;
+}
+
+/**
+ * Emit a plan_approved observation.
+ *
+ * @param service - KindlingService instance
+ * @param approval - Plan approval details
+ * @returns The plan_id
+ */
+export function emitPlanApproved(service: KindlingService, approval: PlanApprovedInput): string {
+  debug('emitting plan_approved', { planId: approval.plan_id, approvedBy: approval.approved_by });
+
+  const observation: PlanApprovedObservation = {
+    kind: 'plan_approved',
+    session_id: approval.session_id,
+    timestamp: new Date().toISOString(),
+    plan_id: approval.plan_id,
+    plan_version: approval.plan_version,
+    approved_by: approval.approved_by,
+    approval_method: approval.approval_method,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return approval.plan_id;
+}
+
+/**
+ * Emit a plan_rejected observation.
+ *
+ * @param service - KindlingService instance
+ * @param rejection - Plan rejection details
+ * @returns The plan_id
+ */
+export function emitPlanRejected(service: KindlingService, rejection: PlanRejectedInput): string {
+  debug('emitting plan_rejected', { planId: rejection.plan_id, rejectedBy: rejection.rejected_by });
+
+  const observation: PlanRejectedObservation = {
+    kind: 'plan_rejected',
+    session_id: rejection.session_id,
+    timestamp: new Date().toISOString(),
+    plan_id: rejection.plan_id,
+    plan_version: rejection.plan_version,
+    rejected_by: rejection.rejected_by,
+    rejection_reason: rejection.rejection_reason,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return rejection.plan_id;
+}

package/src/emitters/session-emitter.ts

@@ -0,0 +1,131 @@
+/**
+ * Session Emitter (KINDLING-003)
+ *
+ * Emits session_start and session_end observations.
+ * Sessions form the "spine" of Kindling -- every other observation
+ * is linked to a session via session_id.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type { SessionStartObservation, SessionEndObservation } from '../observation-contract.js';
+import { createDebugger } from '../utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+/**
+ * Context needed to start a session observation
+ */
+export interface SessionStartContext {
+  working_directory: string;
+  git_ref?: string;
+  git_dirty?: boolean;
+  anvil_version: string;
+  command: string;
+  args: string[];
+  environment: 'development' | 'ci' | 'production' | 'unknown';
+  plan_id?: string;
+}
+
+/**
+ * Outcome data for ending a session
+ */
+export interface SessionEndOutcome {
+  outcome: 'success' | 'failure' | 'partial' | 'cancelled';
+  exit_code: number;
+  duration_ms: number;
+  summary: {
+    gates_evaluated: number;
+    gates_passed: number;
+    gates_failed: number;
+    actions_executed: number;
+    errors_encountered: number;
+  };
+}
+
+// =============================================================================
+// Emitters
+// =============================================================================
+
+/**
+ * Emit a session_start observation.
+ *
+ * Generates a new session_id and emits fire-and-forget.
+ * Returns the generated session_id so callers can link subsequent observations.
+ *
+ * @param service - KindlingService instance
+ * @param context - Session start context
+ * @returns The generated session_id
+ */
+export function emitSessionStart(service: KindlingService, context: SessionStartContext): string {
+  const sessionId = randomUUID();
+  debug('emitting session_start', {
+    sessionId,
+    command: context.command,
+    environment: context.environment,
+  });
+
+  const observation: SessionStartObservation = {
+    kind: 'session_start',
+    session_id: sessionId,
+    timestamp: new Date().toISOString(),
+    context: {
+      working_directory: context.working_directory,
+      git_ref: context.git_ref,
+      git_dirty: context.git_dirty,
+      anvil_version: context.anvil_version,
+      command: context.command,
+      args: context.args,
+      environment: context.environment,
+    },
+    plan_id: context.plan_id,
+  };
+
+  // Fire-and-forget: catch errors silently to not affect main flow
+  service.emit(observation).catch(() => {
+    // Silently swallow -- Kindling must never break the host
+  });
+
+  return sessionId;
+}
+
+/**
+ * Emit a session_end observation.
+ *
+ * @param service - KindlingService instance
+ * @param sessionId - The session_id from the corresponding session_start
+ * @param outcome - Session outcome data
+ * @returns The session_id (same as input, for chaining)
+ */
+export function emitSessionEnd(
+  service: KindlingService,
+  sessionId: string,
+  outcome: SessionEndOutcome
+): string {
+  debug('emitting session_end', {
+    sessionId,
+    outcome: outcome.outcome,
+    duration_ms: outcome.duration_ms,
+  });
+
+  const observation: SessionEndObservation = {
+    kind: 'session_end',
+    session_id: sessionId,
+    timestamp: new Date().toISOString(),
+    outcome: outcome.outcome,
+    exit_code: outcome.exit_code,
+    duration_ms: outcome.duration_ms,
+    summary: outcome.summary,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return sessionId;
+}