agent-enderun 1.1.10 → 1.10.0

package/src/shared/errors.ts

@@ -1,17 +1,19 @@
 /**
- * Enterprise Base Error class for the Enderun Core Framework.
+ * Enterprise Base Error class for the Agent Enderun Framework.
  */
 export class EnderunBaseError extends Error {
     public readonly code: string;
     public readonly timestamp: Date;
     public readonly details?: unknown;
+    public readonly solution?: string;
 
-    constructor(message: string, code = "ENDERUN_INTERNAL_ERROR", details?: unknown) {
+    constructor(message: string, code = "ENDERUN_INTERNAL_ERROR", details?: unknown, solution?: string) {
         super(message);
         this.name = this.constructor.name;
         this.code = code;
         this.timestamp = new Date();
         this.details = details;
+        this.solution = solution;
         
         // Ensure proper prototype chain and capture stack trace
         Object.setPrototypeOf(this, new.target.prototype);
@@ -30,6 +32,7 @@ export class EnderunBaseError extends Error {
             code: this.code,
             timestamp: this.timestamp.toISOString(),
             details: this.details,
+            solution: this.solution,
             stack: this.stack,
         };
     }
@@ -39,8 +42,8 @@ export class EnderunBaseError extends Error {
  * Thrown when configuration loading or validation fails.
  */
 export class ConfigurationError extends EnderunBaseError {
-    constructor(message: string, details?: unknown) {
-        super(message, "CONFIGURATION_ERROR", details);
+    constructor(message: string, details?: unknown, solution?: string) {
+        super(message, "CONFIGURATION_ERROR", details, solution);
     }
 }
 
@@ -48,8 +51,8 @@ export class ConfigurationError extends EnderunBaseError {
  * Thrown when data schema or payload validation fails.
  */
 export class ValidationError extends EnderunBaseError {
-    constructor(message: string, details?: unknown) {
-        super(message, "VALIDATION_ERROR", details);
+    constructor(message: string, details?: unknown, solution?: string) {
+        super(message, "VALIDATION_ERROR", details, solution);
     }
 }
 
@@ -57,8 +60,8 @@ export class ValidationError extends EnderunBaseError {
  * Thrown when adapter initialization or execution fails.
  */
 export class AdapterError extends EnderunBaseError {
-    constructor(message: string, adapterId: string, details?: unknown) {
-        super(`Adapter '${adapterId}' failure: ${message}`, "ADAPTER_ERROR", details);
+    constructor(message: string, adapterId: string, details?: unknown, solution?: string) {
+        super(`Adapter '${adapterId}' failure: ${message}`, "ADAPTER_ERROR", details, solution);
     }
 }
 
@@ -66,7 +69,7 @@ export class AdapterError extends EnderunBaseError {
  * Thrown when orchestration or agent communication fails.
  */
 export class OrchestrationError extends EnderunBaseError {
-    constructor(message: string, details?: unknown) {
-        super(message, "ORCHESTRATION_ERROR", details);
+    constructor(message: string, details?: unknown, solution?: string) {
+        super(message, "ORCHESTRATION_ERROR", details, solution);
     }
 }

package/src/shared/fs.ts

@@ -11,13 +11,28 @@ export function ensureDir(dirPath: string, dryRun = false): void {
     }
 }
 
+/**
+ * Writes content to a file atomically by using a temporary file.
+ * This prevents data corruption during unexpected system failures.
+ */
 export function writeTextFile(filePath: string, content: string, dryRun = false): void {
     if (dryRun) {
         console.warn(`[DRY RUN] Would write file: ${filePath}`);
         return;
     }
-    ensureDir(path.dirname(filePath));
-    fs.writeFileSync(filePath, content.endsWith("\n") ? content : `${content}\n`);
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+
+    const tempPath = `${filePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    const finalContent = content.endsWith("\n") ? content : `${content}\n`;
+
+    try {
+        fs.writeFileSync(tempPath, finalContent, "utf8");
+        fs.renameSync(tempPath, filePath);
+    } catch (err) {
+        if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+        throw err;
+    }
 }
 
 export function appendFile(filePath: string, content: string, dryRun = false): void {

package/src/shared/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent Enderun Framework — Internal Branded Types
+ * Used to enforce absolute type safety within the core orchestration logic.
+ */
+
+export type Brand<K, T> = K & { __brand: T };
+
+export type TraceID = Brand<string, "TraceID">;
+export type AgentID = Brand<string, "AgentID">;
+export type PhaseID = Brand<string, "PhaseID">;
+export type ProjectPath = Brand<string, "ProjectPath">;
+
+/**
+ * Casts a raw string to a Branded Type.
+ * Use this only at the boundaries of the system.
+ */
+export function asTraceID(val: string): TraceID { return val as TraceID; }
+export function asAgentID(val: string): AgentID { return val as AgentID; }
+export function asPhaseID(val: string): PhaseID { return val as PhaseID; }
+export function asProjectPath(val: string): ProjectPath { return val as ProjectPath; }

package/bin/utils/docgen.ts

@@ -1,24 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { ALL_AGENTS, toClaudeCodeMd } from "../../src/modules/agents/definitions.js";
-
-const DOCS_DIR = path.join(process.cwd(), "docs/agents");
-const TEMPLATES_DIR = path.join(process.cwd(), "templates/standards");
-
-function generateAgentDocs() {
-    if (!fs.existsSync(DOCS_DIR)) {
-        fs.mkdirSync(DOCS_DIR, { recursive: true });
-    }
-
-    ALL_AGENTS.forEach(agent => {
-        // We use toClaudeCodeMd as a base for human-readable markdown documentation
-        // It injects the standards automatically.
-        const content = toClaudeCodeMd(agent, TEMPLATES_DIR);
-        
-        fs.writeFileSync(path.join(DOCS_DIR, `${agent.name}.md`), content);
-    });
-
-    console.warn(`✅ Generated documentation for ${ALL_AGENTS.length} agents in ${DOCS_DIR}`);
-}
-
-generateAgentDocs();