@almadar/agent 1.6.1 → 1.6.2

package/dist/workspace/index.js

@@ -0,0 +1,675 @@
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { basename, join } from 'path';
+import { execFile } from 'child_process';
+
+// src/workspace/types.ts
+var WORKSPACE_LAYOUT = {
+  /** Root directory for Almadar workspace state. */
+  ALMADAR_DIR: ".almadar",
+  /** User preferences and learned patterns. */
+  USER_MEMORY: ".almadar/user.orb",
+  /** Project-level domain knowledge. */
+  PROJECT_MEMORY: ".almadar/project.orb",
+  /** The generation artifact (shared memory for all agents). */
+  SCHEMA: ".almadar/schema.orb",
+  /** Individual orbital files (one per subagent). */
+  ORBITALS_DIR: ".almadar/orbitals"
+};
+
+// src/workspace/sink-manager.ts
+var SinkManager = class {
+  constructor() {
+    this.sinks = [];
+  }
+  /** Register a sink to receive file write notifications. */
+  register(sink) {
+    this.sinks.push(sink);
+  }
+  /** Get registered sink names (for diagnostics). */
+  get registeredSinks() {
+    return this.sinks.map((s) => s.name);
+  }
+  /**
+   * Notify all sinks that a file was written.
+   * Returns results from each sink — failures in one don't affect others.
+   */
+  async notifyFileWritten(path, content, meta) {
+    if (this.sinks.length === 0) return [];
+    const results = await Promise.allSettled(
+      this.sinks.map((sink) => sink.onFileWritten(path, content, meta))
+    );
+    return results.map((result, i) => ({
+      sinkName: this.sinks[i].name,
+      success: result.status === "fulfilled",
+      error: result.status === "rejected" ? toError(result.reason) : void 0
+    }));
+  }
+  /**
+   * Notify all sinks that the session has ended.
+   * Returns results from each sink — failures in one don't affect others.
+   */
+  async notifySessionEnd(sessionId) {
+    if (this.sinks.length === 0) return [];
+    const results = await Promise.allSettled(
+      this.sinks.map((sink) => sink.onSessionEnd(sessionId))
+    );
+    return results.map((result, i) => ({
+      sinkName: this.sinks[i].name,
+      success: result.status === "fulfilled",
+      error: result.status === "rejected" ? toError(result.reason) : void 0
+    }));
+  }
+};
+function toError(reason) {
+  if (reason instanceof Error) return reason;
+  return new Error(String(reason));
+}
+var GitClient = class {
+  constructor(cwd) {
+    this.cwd = cwd;
+  }
+  /** Check if git is available on the system. */
+  static async isAvailable() {
+    try {
+      await execGit(["--version"], "/tmp");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Check if the workspace is already a git repository. */
+  async isRepo() {
+    try {
+      await this.exec(["rev-parse", "--is-inside-work-tree"]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /** Initialize a new git repository. No-op if already initialized. */
+  async init() {
+    if (await this.isRepo()) return;
+    await this.exec(["init"]);
+    await this.exec(["config", "user.email", "agent@almadar.io"]);
+    await this.exec(["config", "user.name", "Almadar Agent"]);
+  }
+  /** Stage files for commit. */
+  async add(paths) {
+    if (paths.length === 0) return;
+    await this.exec(["add", ...paths]);
+  }
+  /** Stage all changes (equivalent to git add -A). */
+  async addAll() {
+    await this.exec(["add", "-A"]);
+  }
+  /**
+   * Create a commit with the given message.
+   * Returns the commit hash, or null if there was nothing to commit.
+   */
+  async commit(message) {
+    try {
+      const output = await this.exec(["commit", "-m", message, "--allow-empty-message"]);
+      const match = output.match(/\[[\w/.-]+ ([a-f0-9]+)\]/);
+      return match ? match[1] : null;
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("nothing to commit")) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  /** Create an annotated tag. */
+  async tag(name, message) {
+    const args = ["tag"];
+    if (message) {
+      args.push("-a", name, "-m", message);
+    } else {
+      args.push(name);
+    }
+    await this.exec(args);
+  }
+  /** Get recent commits. */
+  async log(limit = 10) {
+    try {
+      const output = await this.exec([
+        "log",
+        `--max-count=${limit}`,
+        "--format=%H|%s|%aI|%an"
+      ]);
+      return output.trim().split("\n").filter(Boolean).map((line) => {
+        const [hash, message, date, author] = line.split("|");
+        return { hash, message, date, author };
+      });
+    } catch {
+      return [];
+    }
+  }
+  /** Get workspace status. */
+  async status() {
+    const output = await this.exec(["status", "--porcelain"]);
+    const lines = output.trim().split("\n").filter(Boolean);
+    const staged = [];
+    const modified = [];
+    const untracked = [];
+    for (const line of lines) {
+      const indexStatus = line[0];
+      const workTreeStatus = line[1];
+      const file = line.slice(3);
+      if (indexStatus === "?" && workTreeStatus === "?") {
+        untracked.push(file);
+      } else if (indexStatus !== " " && indexStatus !== "?") {
+        staged.push(file);
+      } else if (workTreeStatus !== " ") {
+        modified.push(file);
+      }
+    }
+    return {
+      clean: lines.length === 0,
+      staged,
+      modified,
+      untracked
+    };
+  }
+  /** Get diff output between two references. */
+  async diff(from, to) {
+    const args = ["diff"];
+    if (from) args.push(from);
+    if (to) args.push(to);
+    return this.exec(args);
+  }
+  exec(args) {
+    return execGit(args, this.cwd);
+  }
+};
+function execGit(args, cwd) {
+  return new Promise((resolve, reject) => {
+    execFile("git", args, { cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) {
+        const message = stderr?.trim() || stdout?.trim() || err.message;
+        reject(new Error(`git ${args[0]}: ${message}`));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+var GitSink = class {
+  constructor(workspaceRoot) {
+    this.name = "git";
+    this.commitQueue = Promise.resolve();
+    this.available = null;
+    this.client = new GitClient(workspaceRoot);
+  }
+  /** Initialize the git repo. Must be called before onFileWritten. */
+  async initialize() {
+    this.available = await GitClient.isAvailable();
+    if (!this.available) {
+      console.warn("[GitSink] git not available \u2014 commits will be skipped");
+      return;
+    }
+    await this.client.init();
+  }
+  async onFileWritten(path, _content, meta) {
+    if (!this.available) return;
+    this.commitQueue = this.commitQueue.then(async () => {
+      const message = formatCommitMessage(path, meta);
+      await this.client.add([path]);
+      await this.client.commit(message);
+    });
+    await this.commitQueue;
+  }
+  async onSessionEnd(sessionId) {
+    if (!this.available) return;
+    await this.commitQueue;
+    const status = await this.client.status();
+    if (!status.clean) {
+      await this.client.addAll();
+      await this.client.commit(`session-end: ${sessionId}`);
+    }
+    await this.client.tag(
+      `session/${sessionId}`,
+      `Session ${sessionId} complete`
+    );
+  }
+};
+function formatCommitMessage(path, meta) {
+  const filename = basename(path);
+  switch (meta.fileType) {
+    case "orbital":
+      return `add(${meta.orbitalName ?? filename}): orbital generated`;
+    case "schema":
+      return `update(schema): ${filename}`;
+    case "memory":
+      return `update(memory): ${filename}`;
+    case "domain":
+      return `add(domain): ${filename}`;
+    default:
+      return `update: ${filename}`;
+  }
+}
+
+// src/memory/memory-orbital.ts
+var UserPreferenceEntity = {
+  name: "UserPreference",
+  persistence: "persistent",
+  fields: [
+    { name: "id", type: "string", required: true },
+    { name: "userId", type: "string", required: true },
+    { name: "namingConvention", type: "enum", values: ["PascalCase", "camelCase", "snake_case"], default: "PascalCase" },
+    { name: "validationStyle", type: "enum", values: ["strict", "minimal", "none"], default: "strict" },
+    { name: "preferredPatterns", type: "array", items: { name: "pattern", type: "string" }, default: [] },
+    { name: "commonEntities", type: "array", items: { name: "entity", type: "string" }, default: [] },
+    { name: "commonTraits", type: "array", items: { name: "trait", type: "string" }, default: [] },
+    { name: "learnedAt", type: "timestamp" },
+    { name: "confidence", type: "number", default: 0.5 }
+  ]
+};
+var ProjectContextEntity = {
+  name: "ProjectContext",
+  persistence: "persistent",
+  fields: [
+    { name: "id", type: "string", required: true },
+    { name: "appId", type: "string", required: true },
+    { name: "userId", type: "string", required: true },
+    { name: "projectName", type: "string" },
+    { name: "description", type: "string" },
+    { name: "existingEntities", type: "array", items: { name: "entity", type: "string" }, default: [] },
+    { name: "conventions", type: "array", items: { name: "convention", type: "string" }, default: [] },
+    { name: "domain", type: "enum", values: ["business", "ecommerce", "cms", "dashboard", "workflow"], default: "business" },
+    { name: "lastUpdatedAt", type: "timestamp", required: true }
+  ]
+};
+
+// src/workspace/templates.ts
+function createUserOrbTemplate(userId) {
+  const entity = {
+    ...UserPreferenceEntity,
+    instances: [{
+      id: `pref-${userId}`,
+      userId,
+      namingConvention: "PascalCase",
+      validationStyle: "strict",
+      preferredPatterns: [],
+      commonEntities: [],
+      commonTraits: [],
+      confidence: 0
+    }]
+  };
+  return {
+    name: "UserMemory",
+    version: "1.0.0",
+    description: "User preferences and learned patterns",
+    orbitals: [{
+      name: "PreferenceTracking",
+      entity,
+      traits: [{
+        name: "Learning",
+        category: "interaction",
+        linkedEntity: "UserPreference",
+        stateMachine: {
+          states: [
+            { name: "Cold", isInitial: true },
+            { name: "Warming" },
+            { name: "Confident" }
+          ],
+          events: [
+            { key: "SESSION_COMPLETE", name: "Session Complete" },
+            { key: "RESET", name: "Reset" }
+          ],
+          transitions: [
+            {
+              from: "Cold",
+              to: "Warming",
+              event: "SESSION_COMPLETE",
+              effects: [["set", "@entity.confidence", ["min", 1, ["add", "@entity.confidence", 0.1]]]]
+            },
+            {
+              from: "Warming",
+              to: "Warming",
+              event: "SESSION_COMPLETE",
+              guard: ["<", "@entity.confidence", 0.8],
+              effects: [["set", "@entity.confidence", ["min", 1, ["add", "@entity.confidence", 0.1]]]]
+            },
+            {
+              from: "Warming",
+              to: "Confident",
+              event: "SESSION_COMPLETE",
+              guard: [">=", "@entity.confidence", 0.8]
+            },
+            {
+              from: "Confident",
+              to: "Cold",
+              event: "RESET",
+              effects: [["set", "@entity.confidence", 0]]
+            }
+          ]
+        }
+      }],
+      pages: []
+    }]
+  };
+}
+function createProjectOrbTemplate(projectName, appId) {
+  const entity = {
+    ...ProjectContextEntity,
+    instances: [{
+      id: appId ?? `project-${projectName}`,
+      appId: appId ?? "",
+      userId: "",
+      projectName,
+      description: "",
+      existingEntities: [],
+      conventions: [],
+      domain: "business",
+      lastUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }]
+  };
+  return {
+    name: "ProjectMemory",
+    version: "1.0.0",
+    description: `Domain knowledge for ${projectName}`,
+    orbitals: [{
+      name: "DomainKnowledge",
+      entity,
+      traits: [{
+        name: "Accumulating",
+        category: "interaction",
+        linkedEntity: "ProjectContext",
+        stateMachine: {
+          states: [
+            { name: "Empty", isInitial: true },
+            { name: "Growing" },
+            { name: "Mature" }
+          ],
+          events: [
+            { key: "ENTITY_DISCOVERED", name: "Entity Discovered" },
+            { key: "SESSION_COMPLETE", name: "Session Complete" }
+          ],
+          transitions: [
+            { from: "Empty", to: "Growing", event: "ENTITY_DISCOVERED" },
+            { from: "Growing", to: "Growing", event: "ENTITY_DISCOVERED" },
+            {
+              from: "Growing",
+              to: "Mature",
+              event: "SESSION_COMPLETE",
+              guard: [">=", "@entity.sessionCount", 5]
+            }
+          ]
+        }
+      }],
+      pages: []
+    }]
+  };
+}
+function createSchemaOrbTemplate(name) {
+  return {
+    name,
+    version: "1.0.0",
+    description: "",
+    orbitals: []
+  };
+}
+function serializeOrb(schema) {
+  return JSON.stringify(schema, null, 2);
+}
+function parseOrb(content) {
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function readOrbInstances(filePath) {
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const schema = JSON.parse(content);
+    const entity = schema.orbitals?.[0]?.entity;
+    if (!entity || typeof entity === "string") return [];
+    return entity.instances ?? [];
+  } catch {
+    return [];
+  }
+}
+async function readOrb(filePath) {
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function writeOrbInstances(filePath, instances) {
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const schema = JSON.parse(content);
+    const entity = schema.orbitals?.[0]?.entity;
+    if (!entity || typeof entity === "string") return false;
+    entity.instances = instances;
+    await writeFile(filePath, JSON.stringify(schema, null, 2), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeOrb(filePath, schema) {
+  await writeFile(filePath, JSON.stringify(schema, null, 2), "utf-8");
+}
+
+// src/workspace/workspace-manager.ts
+var WorkspaceManager = class {
+  constructor(config) {
+    this.gitSink = null;
+    this.initialized = false;
+    this.config = config;
+    this.sinkManager = new SinkManager();
+    if (config.sinks) {
+      for (const sink of config.sinks) {
+        this.sinkManager.register(sink);
+      }
+    }
+  }
+  /** Get the absolute path to a workspace-relative path. */
+  resolve(relativePath) {
+    return join(this.config.rootDir, relativePath);
+  }
+  /** Get the SinkManager for direct registration of additional sinks. */
+  get sinks() {
+    return this.sinkManager;
+  }
+  // ==========================================================================
+  // Initialization
+  // ==========================================================================
+  /**
+   * Initialize the workspace: create directories, write .orb templates,
+   * optionally initialize git.
+   *
+   * Safe to call multiple times — skips if already initialized.
+   */
+  async initialize() {
+    if (this.initialized) return;
+    const almadarDir = this.resolve(WORKSPACE_LAYOUT.ALMADAR_DIR);
+    const orbitalsDir = this.resolve(WORKSPACE_LAYOUT.ORBITALS_DIR);
+    await mkdir(almadarDir, { recursive: true });
+    await mkdir(orbitalsDir, { recursive: true });
+    await this.writeTemplateIfMissing(
+      WORKSPACE_LAYOUT.USER_MEMORY,
+      serializeOrb(createUserOrbTemplate(this.config.userId))
+    );
+    await this.writeTemplateIfMissing(
+      WORKSPACE_LAYOUT.PROJECT_MEMORY,
+      serializeOrb(createProjectOrbTemplate(
+        this.config.projectName ?? "Untitled",
+        this.config.appId
+      ))
+    );
+    await this.writeTemplateIfMissing(
+      WORKSPACE_LAYOUT.SCHEMA,
+      serializeOrb(createSchemaOrbTemplate(
+        this.config.projectName ?? "Untitled"
+      ))
+    );
+    if (this.config.gitEnabled !== false) {
+      this.gitSink = new GitSink(this.config.rootDir);
+      await this.gitSink.initialize();
+      this.sinkManager.register(this.gitSink);
+      const git = new GitClient(this.config.rootDir);
+      if (await git.isRepo()) {
+        await git.addAll();
+        await git.commit("init: workspace initialized");
+      }
+    }
+    this.initialized = true;
+  }
+  // ==========================================================================
+  // File Write Notifications
+  // ==========================================================================
+  /**
+   * Notify sinks that a file was written.
+   * Call this from the server when the agent writes a file.
+   *
+   * @param relativePath - Path relative to workspace root
+   * @param content - File content as string
+   * @param meta - Optional metadata override (auto-inferred if not provided)
+   */
+  async onFileWritten(relativePath, content, meta) {
+    const fullMeta = inferFileMeta(relativePath, meta);
+    return this.sinkManager.notifyFileWritten(relativePath, content, fullMeta);
+  }
+  // ==========================================================================
+  // Memory Operations
+  // ==========================================================================
+  /**
+   * Load memory from .orb files. Call at session start to provide
+   * the agent with user preferences and project context.
+   */
+  async loadMemory() {
+    const [user, project] = await Promise.all([
+      readOrbInstances(this.resolve(WORKSPACE_LAYOUT.USER_MEMORY)),
+      readOrbInstances(this.resolve(WORKSPACE_LAYOUT.PROJECT_MEMORY))
+    ]);
+    return { user, project };
+  }
+  /**
+   * Update memory .orb file instances. Call at session end to
+   * persist learned preferences and discovered domain knowledge.
+   */
+  async saveMemory(updates) {
+    const writes = [];
+    if (updates.user) {
+      writes.push(
+        writeOrbInstances(this.resolve(WORKSPACE_LAYOUT.USER_MEMORY), updates.user)
+      );
+    }
+    if (updates.project) {
+      writes.push(
+        writeOrbInstances(this.resolve(WORKSPACE_LAYOUT.PROJECT_MEMORY), updates.project)
+      );
+    }
+    await Promise.all(writes);
+    if (updates.user) {
+      const content = JSON.stringify(updates.user, null, 2);
+      await this.sinkManager.notifyFileWritten(
+        WORKSPACE_LAYOUT.USER_MEMORY,
+        content,
+        { fileType: "memory", sessionId: this.config.sessionId }
+      );
+    }
+    if (updates.project) {
+      const content = JSON.stringify(updates.project, null, 2);
+      await this.sinkManager.notifyFileWritten(
+        WORKSPACE_LAYOUT.PROJECT_MEMORY,
+        content,
+        { fileType: "memory", sessionId: this.config.sessionId }
+      );
+    }
+  }
+  // ==========================================================================
+  // Session End
+  // ==========================================================================
+  /**
+   * End the session: notify all sinks, create git tag.
+   * Call from the server when the agent session completes.
+   */
+  async endSession() {
+    return this.sinkManager.notifySessionEnd(this.config.sessionId);
+  }
+  // ==========================================================================
+  // Helpers
+  // ==========================================================================
+  async writeTemplateIfMissing(relativePath, content) {
+    const fullPath = this.resolve(relativePath);
+    try {
+      await access(fullPath);
+    } catch {
+      await writeOrb(fullPath, JSON.parse(content));
+    }
+  }
+};
+function inferFileMeta(relativePath, partial) {
+  if (partial?.fileType) {
+    return {
+      fileType: partial.fileType,
+      orbitalName: partial.orbitalName,
+      sessionId: partial.sessionId
+    };
+  }
+  if (relativePath.includes("/orbitals/") || relativePath.match(/\.orbitals\//)) {
+    const name = relativePath.split("/").pop()?.replace(/\.(orb|json)$/, "") ?? void 0;
+    return { fileType: "orbital", orbitalName: name, sessionId: partial?.sessionId };
+  }
+  if (relativePath.endsWith("schema.orb") || relativePath.endsWith("schema.json")) {
+    return { fileType: "schema", sessionId: partial?.sessionId };
+  }
+  if (relativePath.endsWith("user.orb") || relativePath.endsWith("project.orb")) {
+    return { fileType: "memory", sessionId: partial?.sessionId };
+  }
+  if (relativePath.endsWith("domain.txt")) {
+    return { fileType: "domain", sessionId: partial?.sessionId };
+  }
+  return { fileType: "other", sessionId: partial?.sessionId };
+}
+
+// src/workspace/sinks/firestore-sink.ts
+var FirestoreSink = class {
+  constructor(config) {
+    this.name = "firestore";
+    this.config = config;
+  }
+  /** Update the appId after it's been assigned (e.g., on first schema write). */
+  setAppId(appId) {
+    this.config.appId = appId;
+  }
+  async onFileWritten(_path, content, meta) {
+    switch (meta.fileType) {
+      case "orbital": {
+        if (!meta.orbitalName) return;
+        const orbital = JSON.parse(content);
+        await this.config.saveOrbital(meta.orbitalName, orbital);
+        break;
+      }
+      case "schema": {
+        if (!this.config.saveSchema) return;
+        const schema = JSON.parse(content);
+        const result = await this.config.saveSchema(schema);
+        if (result.appId && !this.config.appId) {
+          this.config.appId = result.appId;
+          this.config.onAppCreated?.(result.appId);
+        }
+        break;
+      }
+      case "memory": {
+        if (!this.config.saveMemory) return;
+        const data = JSON.parse(content);
+        const memoryType = data?.name?.toLowerCase()?.replace("memory", "") || "unknown";
+        await this.config.saveMemory(memoryType, data);
+        break;
+      }
+    }
+  }
+  async onSessionEnd(_sessionId) {
+  }
+};
+
+export { FirestoreSink, GitClient, GitSink, SinkManager, WORKSPACE_LAYOUT, WorkspaceManager, createProjectOrbTemplate, createSchemaOrbTemplate, createUserOrbTemplate, parseOrb, readOrb, readOrbInstances, serializeOrb, writeOrb, writeOrbInstances };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map