@almadar/workspace 0.1.0-alpha.0 → 0.1.1

package/dist/index.js

@@ -1,3 +1,1034 @@
+import path2 from 'path';
+import fs from 'fs';
+import { execFile } from 'child_process';
 
+// src/open-workspace.ts
+var LocalBackend = class {
+  async readFile(absPath) {
+    return fs.promises.readFile(absPath, "utf-8");
+  }
+  readFileSync(absPath) {
+    return fs.readFileSync(absPath, "utf-8");
+  }
+  async writeFile(absPath, content) {
+    await fs.promises.mkdir(path2.dirname(absPath), { recursive: true });
+    await fs.promises.writeFile(absPath, content, "utf-8");
+  }
+  writeFileSync(absPath, content) {
+    fs.mkdirSync(path2.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, content, "utf-8");
+  }
+  exists(absPath) {
+    return fs.existsSync(absPath);
+  }
+  async readdir(absPath) {
+    return fs.promises.readdir(absPath);
+  }
+  readdirSync(absPath) {
+    return fs.readdirSync(absPath);
+  }
+  async mkdir(absPath, opts) {
+    await fs.promises.mkdir(absPath, opts);
+  }
+  mkdirSync(absPath, opts) {
+    fs.mkdirSync(absPath, opts);
+  }
+  async unlink(absPath) {
+    await fs.promises.unlink(absPath);
+  }
+  async stat(absPath) {
+    const s = await fs.promises.stat(absPath);
+    return { size: s.size, mtimeMs: s.mtimeMs, isDirectory: s.isDirectory() };
+  }
+};
+
+// src/internal/backends/memory.ts
+var MemoryBackend = class {
+  constructor() {
+    this.files = /* @__PURE__ */ new Map();
+    this.dirs = /* @__PURE__ */ new Set();
+  }
+  async readFile(absPath) {
+    return this.readFileSync(absPath);
+  }
+  readFileSync(absPath) {
+    const content = this.files.get(absPath);
+    if (content === void 0) throw new Error(`ENOENT: ${absPath}`);
+    return content;
+  }
+  async writeFile(absPath, content) {
+    this.writeFileSync(absPath, content);
+  }
+  writeFileSync(absPath, content) {
+    this.files.set(absPath, content);
+  }
+  exists(absPath) {
+    if (this.files.has(absPath) || this.dirs.has(absPath)) return true;
+    const prefix = absPath.endsWith("/") ? absPath : absPath + "/";
+    for (const k of this.files.keys()) {
+      if (k.startsWith(prefix)) return true;
+    }
+    return false;
+  }
+  async readdir(absPath) {
+    return this.readdirSync(absPath);
+  }
+  readdirSync(absPath) {
+    const prefix = absPath.endsWith("/") ? absPath : absPath + "/";
+    const entries = /* @__PURE__ */ new Set();
+    for (const key of this.files.keys()) {
+      if (key.startsWith(prefix)) {
+        const rest = key.slice(prefix.length);
+        const firstSegment = rest.split("/")[0];
+        if (firstSegment) entries.add(firstSegment);
+      }
+    }
+    return Array.from(entries);
+  }
+  async mkdir(absPath) {
+    this.mkdirSync(absPath);
+  }
+  mkdirSync(absPath) {
+    this.dirs.add(absPath);
+  }
+  async unlink(absPath) {
+    this.files.delete(absPath);
+  }
+  async stat(absPath) {
+    const content = this.files.get(absPath);
+    if (content !== void 0) {
+      return { size: content.length, mtimeMs: Date.now(), isDirectory: false };
+    }
+    if (this.dirs.has(absPath)) return { size: 0, mtimeMs: Date.now(), isDirectory: true };
+    const prefix = absPath.endsWith("/") ? absPath : absPath + "/";
+    for (const k of this.files.keys()) {
+      if (k.startsWith(prefix)) return { size: 0, mtimeMs: Date.now(), isDirectory: true };
+    }
+    throw new Error(`ENOENT: ${absPath}`);
+  }
+  // Test helpers
+  getAll() {
+    return new Map(this.files);
+  }
+  clear() {
+    this.files.clear();
+    this.dirs.clear();
+  }
+};
+
+// src/internal/sink-manager.ts
+var SinkManager = class {
+  constructor() {
+    this.observers = [];
+  }
+  /** Register an observer; returns an unsubscribe function. */
+  subscribe(observer) {
+    this.observers.push(observer);
+    return () => {
+      const i = this.observers.indexOf(observer);
+      if (i >= 0) this.observers.splice(i, 1);
+    };
+  }
+  /** Snapshot of observer count — useful for diagnostics. */
+  get observerCount() {
+    return this.observers.length;
+  }
+  /**
+   * Notify all observers in parallel. Awaits all settlements. A rejected
+   * observer is captured in the result; subsequent writes still proceed.
+   */
+  async notifyAll(event) {
+    if (this.observers.length === 0) return;
+    const settled = await Promise.allSettled(
+      this.observers.map(async (o) => o.onWrite(event))
+    );
+    for (const r of settled) {
+      if (r.status === "rejected") {
+        const reason = r.reason instanceof Error ? r.reason.message : String(r.reason);
+        console.error(`[workspace] observer error on ${event.kind}: ${reason}`);
+      }
+    }
+  }
+};
+var WORKSPACE_LAYOUT = {
+  ALMADAR_DIR: ".almadar",
+  ORBITALS_DIR: "orbitals",
+  SESSIONS_DIR: ".almadar/sessions",
+  COORDINATOR_DIR: ".almadar/sessions/Coordinator",
+  TRACE_FILE: ".almadar/trace.jsonl",
+  SCHEMA_FILE: "schema.orb",
+  COMPILED_DIR: "apps",
+  APP_MARKER: ".almadar/app-marker.json",
+  USER_MEMORY: ".almadar/user.orb",
+  PROJECT_MEMORY: ".almadar/project.orb"
+};
+function orbitalFile(workDir, name) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.ORBITALS_DIR, `${name}.orb`);
+}
+function archivedOrbitalFile(workDir, name) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.ORBITALS_DIR, ".archived", `${name}.orb`);
+}
+function schemaFile(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.SCHEMA_FILE);
+}
+function coordinatorDir(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.COORDINATOR_DIR);
+}
+function coordinatorFile(workDir, basename) {
+  return path2.join(coordinatorDir(workDir), basename);
+}
+function orbitalSessionDir(workDir, orbital) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.SESSIONS_DIR, orbital);
+}
+function orbitalSessionFile(workDir, orbital, basename) {
+  return path2.join(orbitalSessionDir(workDir, orbital), basename);
+}
+function traceFile(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.TRACE_FILE);
+}
+function compiledDir(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.COMPILED_DIR);
+}
+function compiledFile(workDir, relPath) {
+  return path2.join(compiledDir(workDir), relPath);
+}
+function appMarkerFile(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.APP_MARKER);
+}
+function sandboxedPath(workDir, relPath) {
+  if (typeof relPath !== "string" || relPath.length === 0) {
+    throw new Error("sandbox: empty relative path");
+  }
+  if (path2.isAbsolute(relPath)) {
+    throw new Error(`sandbox: absolute paths are not allowed (${relPath})`);
+  }
+  if (/^[a-zA-Z]:[\\/]/.test(relPath)) {
+    throw new Error(`sandbox: drive-letter paths are not allowed (${relPath})`);
+  }
+  const rootAbs = path2.resolve(workDir);
+  const target = path2.resolve(rootAbs, relPath);
+  if (target !== rootAbs && !target.startsWith(rootAbs + path2.sep)) {
+    throw new Error(`sandbox: path escapes workspace (${relPath})`);
+  }
+  return target;
+}
+function assertOrbitalName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("orbital name: empty");
+  }
+  if (name.includes("/") || name.includes("\\") || name === "." || name === "..") {
+    throw new Error(`orbital name: invalid (${name})`);
+  }
+}
+
+// src/internal/templates.ts
+function createSchemaOrbTemplate(name) {
+  return {
+    name,
+    version: "1.0.0",
+    description: "",
+    orbitals: []
+  };
+}
+function createUserOrbTemplate(userId) {
+  return {
+    name: "UserMemory",
+    version: "1.0.0",
+    description: "User preferences and learned patterns",
+    orbitals: [
+      {
+        name: "PreferenceTracking",
+        entity: {
+          name: "UserPreference",
+          fields: [],
+          instances: [
+            {
+              id: `pref-${userId}`,
+              userId
+            }
+          ]
+        },
+        traits: [],
+        pages: []
+      }
+    ]
+  };
+}
+function createProjectOrbTemplate(projectName, appId) {
+  return {
+    name: "ProjectMemory",
+    version: "1.0.0",
+    description: `Domain knowledge for ${projectName}`,
+    orbitals: [
+      {
+        name: "DomainKnowledge",
+        entity: {
+          name: "ProjectContext",
+          fields: [],
+          instances: [
+            {
+              id: appId ?? `project-${projectName}`,
+              appId: appId ?? "",
+              projectName,
+              lastUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+            }
+          ]
+        },
+        traits: [],
+        pages: []
+      }
+    ]
+  };
+}
+function serializeJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+var GitClient = class {
+  constructor(cwd, backend) {
+    this.cwd = cwd;
+    this.backend = backend;
+  }
+  /** Is the working dir already a git repo? */
+  async isRepo() {
+    return this.backend.exists(path2.join(this.cwd, ".git"));
+  }
+  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"]);
+  }
+  async addAll() {
+    await this.exec(["add", "-A"]);
+  }
+  async commit(message) {
+    try {
+      const out = await this.exec(["commit", "-m", message, "--allow-empty-message"]);
+      const match = out.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;
+    }
+  }
+  async tag(name, message) {
+    const args = ["tag"];
+    if (message) {
+      args.push("-a", name, "-m", message);
+    } else {
+      args.push(name);
+    }
+    await this.exec(args);
+  }
+  async push(remote = "origin", branch) {
+    const args = ["push", remote];
+    if (branch) args.push(branch);
+    await this.exec(args);
+  }
+  async pull(remote = "origin", branch) {
+    const args = ["pull", remote];
+    if (branch) args.push(branch);
+    await this.exec(args);
+  }
+  async hasRemote(remote = "origin") {
+    try {
+      const out = await this.exec(["remote"]);
+      return out.split("\n").map((s) => s.trim()).includes(remote);
+    } catch {
+      return false;
+    }
+  }
+  async addRemote(remote, url) {
+    await this.exec(["remote", "add", remote, url]);
+  }
+  async status() {
+    const out = await this.exec(["status", "--porcelain"]);
+    const lines = out.split("\n").filter(Boolean);
+    const staged = [];
+    const modified = [];
+    const untracked = [];
+    for (const line of lines) {
+      const index = line[0];
+      const work = line[1];
+      const file = line.slice(3);
+      if (index === "?" && work === "?") untracked.push(file);
+      else if (index !== " " && index !== "?") staged.push(file);
+      else if (work !== " ") modified.push(file);
+    }
+    return { clean: lines.length === 0, staged, modified, untracked };
+  }
+  async headSha() {
+    try {
+      const out = await this.exec(["rev-parse", "HEAD"]);
+      return out.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  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);
+    });
+  });
+}
+
+// src/internal/workspace-manager.ts
+async function ensureSkeleton(backend, workDir) {
+  await backend.mkdir(workDir, { recursive: true });
+  await backend.mkdir(path2.join(workDir, WORKSPACE_LAYOUT.ALMADAR_DIR), { recursive: true });
+  await backend.mkdir(path2.join(workDir, WORKSPACE_LAYOUT.ORBITALS_DIR), { recursive: true });
+  await backend.mkdir(path2.join(workDir, WORKSPACE_LAYOUT.SESSIONS_DIR), { recursive: true });
+  await backend.mkdir(coordinatorDir(workDir), { recursive: true });
+}
+async function ensureOrbitalSessionDir(backend, workDir, orbital) {
+  await backend.mkdir(orbitalSessionDir(workDir, orbital), { recursive: true });
+}
+async function writeMintTemplatesIfMissing(backend, workDir, userId, projectName, appId) {
+  const schemaPath = schemaFile(workDir);
+  if (!backend.exists(schemaPath)) {
+    await backend.writeFile(schemaPath, serializeJson(createSchemaOrbTemplate(projectName)));
+  }
+  const userPath = path2.join(workDir, WORKSPACE_LAYOUT.USER_MEMORY);
+  if (!backend.exists(userPath)) {
+    await backend.writeFile(userPath, serializeJson(createUserOrbTemplate(userId)));
+  }
+  const projectPath = path2.join(workDir, WORKSPACE_LAYOUT.PROJECT_MEMORY);
+  if (!backend.exists(projectPath)) {
+    await backend.writeFile(
+      projectPath,
+      serializeJson(createProjectOrbTemplate(projectName, appId))
+    );
+  }
+}
+async function ensureGitInit(backend, workDir) {
+  const git = new GitClient(workDir, backend);
+  await git.init();
+  return git;
+}
+function readAppMarker(backend, workDir) {
+  const markerPath = appMarkerFile(workDir);
+  if (!backend.exists(markerPath)) return null;
+  try {
+    const raw = backend.readFileSync(markerPath);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.appId !== "string" || typeof parsed.userId !== "string" || typeof parsed.createdAt !== "number") {
+      return null;
+    }
+    const marker = {
+      appId: parsed.appId,
+      userId: parsed.userId,
+      createdAt: parsed.createdAt
+    };
+    if (typeof parsed.repoUrl === "string") marker.repoUrl = parsed.repoUrl;
+    return marker;
+  } catch {
+    return null;
+  }
+}
+async function writeAppMarker(backend, workDir, marker) {
+  const markerPath = appMarkerFile(workDir);
+  await backend.mkdir(path2.dirname(markerPath), { recursive: true });
+  await backend.writeFile(markerPath, JSON.stringify(marker, null, 2));
+}
+async function findLocalWorkspaceDir(backend, workspacesRoot, userId, appId) {
+  const userDir = path2.join(workspacesRoot, userId);
+  if (!backend.exists(userDir)) return null;
+  let entries;
+  try {
+    entries = await backend.readdir(userDir);
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    const sessionDir = path2.join(userDir, entry);
+    let isDir = false;
+    try {
+      const s = await backend.stat(sessionDir);
+      isDir = s.isDirectory;
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    const marker = readAppMarker(backend, sessionDir);
+    if (marker && marker.appId === appId) return sessionDir;
+  }
+  return null;
+}
+function mintSessionDir(workspacesRoot, userId) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const suffix = Date.now().toString(36);
+  return path2.join(workspacesRoot, userId, `${ts}_${suffix}`);
+}
+async function restoreWorkspace(backend, rootDir, restore) {
+  const rootAbs = path2.resolve(rootDir);
+  await backend.mkdir(rootAbs, { recursive: true });
+  const paths = await restore.listFiles();
+  let filesRestored = 0;
+  let bytesWritten = 0;
+  for (const relativePath of paths) {
+    const normalised = relativePath.replace(/\\/g, "/");
+    const target = path2.resolve(rootAbs, normalised);
+    if (target !== rootAbs && !target.startsWith(rootAbs + path2.sep)) {
+      continue;
+    }
+    const content = await restore.readFile(normalised);
+    if (content === null) continue;
+    await backend.mkdir(path2.dirname(target), { recursive: true });
+    await backend.writeFile(target, content);
+    filesRestored++;
+    bytesWritten += Buffer.byteLength(content, "utf-8");
+  }
+  return { filesRestored, bytesWritten };
+}
+
+// src/internal/memory-files.ts
+async function writeJsonFile(backend, absPath, value) {
+  await backend.writeFile(absPath, JSON.stringify(value, null, 2));
+}
+async function appendJsonLine(backend, absPath, value) {
+  const existing = backend.exists(absPath) ? await backend.readFile(absPath) : "";
+  const ending = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  await backend.writeFile(absPath, existing + ending + JSON.stringify(value) + "\n");
+}
+
+// src/service.ts
+var COORD_FILES = {
+  analysis: "analysis.json",
+  plan: "plan.json",
+  clarifications: "clarifications.json",
+  messages: "messages.json"
+};
+var ORBITAL_FILES = {
+  spec: "spec.json",
+  memory: "memory.json",
+  history: "history.jsonl",
+  paramsHistory: "params-history.jsonl",
+  errors: "errors.json",
+  messages: "messages.json"
+};
+var WorkspaceServiceImpl = class {
+  constructor(args) {
+    /** Per-absolute-path serial queue. */
+    this.writeQueue = /* @__PURE__ */ new Map();
+    this.workDir = args.workDir;
+    this.backend = args.backend;
+    this.sinks = args.sinks;
+    this._appId = args.appId;
+    this.git = args.git;
+    this.github = args.github;
+  }
+  // === Identity ===
+  get appId() {
+    return this._appId;
+  }
+  setAppId(id) {
+    this._appId = id;
+  }
+  // === Helpers ===
+  /** Run `op` under a per-path serial lock. */
+  withLock(absPath, op) {
+    const prev = this.writeQueue.get(absPath) ?? Promise.resolve();
+    let resolved;
+    const next = prev.then(async () => {
+      resolved = await op();
+    });
+    const swallowed = next.catch(() => void 0);
+    this.writeQueue.set(absPath, swallowed);
+    return next.then(() => resolved);
+  }
+  /** Make sure the parent directory of `absPath` exists. */
+  async ensureParent(absPath) {
+    await this.backend.mkdir(path2.dirname(absPath), { recursive: true });
+  }
+  async emit(event) {
+    await this.sinks.notifyAll(event);
+  }
+  // === Orbital artifacts ===
+  readOrbital(name) {
+    assertOrbitalName(name);
+    const p = orbitalFile(this.workDir, name);
+    if (!this.backend.exists(p)) return null;
+    try {
+      return this.backend.readFileSync(p);
+    } catch {
+      return null;
+    }
+  }
+  async writeOrbital(name, content) {
+    assertOrbitalName(name);
+    const p = orbitalFile(this.workDir, name);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await this.backend.writeFile(p, content);
+    });
+    await this.emit({ kind: "orbital", name, content });
+  }
+  listOrbitals() {
+    const dir = path2.join(this.workDir, WORKSPACE_LAYOUT.ORBITALS_DIR);
+    if (!this.backend.exists(dir)) return [];
+    try {
+      return this.backend.readdirSync(dir).filter((f) => f.endsWith(".orb")).map((f) => f.replace(/\.orb$/, "")).sort();
+    } catch {
+      return [];
+    }
+  }
+  async archiveOrbital(name) {
+    assertOrbitalName(name);
+    const src = orbitalFile(this.workDir, name);
+    if (!this.backend.exists(src)) return;
+    const content = await this.backend.readFile(src);
+    const dst = archivedOrbitalFile(this.workDir, name);
+    await this.withLock(src, async () => {
+      await this.ensureParent(dst);
+      await this.backend.writeFile(dst, content);
+      await this.backend.unlink(src);
+    });
+    await this.emit({ kind: "orbital-archived", name });
+  }
+  async renameOrbital(from, to) {
+    assertOrbitalName(from);
+    assertOrbitalName(to);
+    const src = orbitalFile(this.workDir, from);
+    const dst = orbitalFile(this.workDir, to);
+    if (!this.backend.exists(src)) return;
+    const content = await this.backend.readFile(src);
+    await this.withLock(src, async () => {
+      await this.ensureParent(dst);
+      await this.backend.writeFile(dst, content);
+      await this.backend.unlink(src);
+    });
+    await this.emit({ kind: "orbital-renamed", from, to });
+  }
+  // === Schema artifact ===
+  readSchema() {
+    const p = schemaFile(this.workDir);
+    if (!this.backend.exists(p)) return null;
+    try {
+      return this.backend.readFileSync(p);
+    } catch {
+      return null;
+    }
+  }
+  async writeSchema(content) {
+    const p = schemaFile(this.workDir);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await this.backend.writeFile(p, content);
+    });
+    await this.emit({ kind: "schema", content });
+  }
+  // === Coordinator session ===
+  readAnalysis() {
+    return readJsonFileSync(this.backend, coordinatorFile(this.workDir, COORD_FILES.analysis));
+  }
+  async writeAnalysis(analysis) {
+    const p = coordinatorFile(this.workDir, COORD_FILES.analysis);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await writeJsonFile(this.backend, p, analysis);
+    });
+    await this.emit({ kind: "analysis", content: analysis });
+  }
+  readPlan() {
+    return readJsonFileSync(this.backend, coordinatorFile(this.workDir, COORD_FILES.plan));
+  }
+  async writePlan(plan) {
+    const p = coordinatorFile(this.workDir, COORD_FILES.plan);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await writeJsonFile(this.backend, p, plan);
+    });
+    await this.emit({ kind: "plan", content: plan });
+  }
+  readClarificationAnswers() {
+    const p = coordinatorFile(this.workDir, COORD_FILES.clarifications);
+    if (!this.backend.exists(p)) return {};
+    try {
+      const parsed = JSON.parse(this.backend.readFileSync(p));
+      const out = {};
+      for (const k of Object.keys(parsed)) {
+        const v = parsed[k];
+        if (typeof v === "string") out[k] = v;
+      }
+      return out;
+    } catch {
+      return {};
+    }
+  }
+  async writeClarificationAnswers(answers) {
+    const p = coordinatorFile(this.workDir, COORD_FILES.clarifications);
+    const asJson = { ...answers };
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await writeJsonFile(this.backend, p, asJson);
+    });
+    await this.emit({ kind: "clarifications", content: answers });
+  }
+  readCoordinatorMessages() {
+    const p = coordinatorFile(this.workDir, COORD_FILES.messages);
+    if (!this.backend.exists(p)) return null;
+    try {
+      const parsed = JSON.parse(this.backend.readFileSync(p));
+      if (!Array.isArray(parsed)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  async writeCoordinatorMessages(messages) {
+    const p = coordinatorFile(this.workDir, COORD_FILES.messages);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await this.backend.writeFile(p, JSON.stringify(messages, null, 2));
+    });
+    await this.emit({ kind: "coordinator-messages", content: messages });
+  }
+  // === Per-orbital session ===
+  orbitalFile(orbital, basename) {
+    assertOrbitalName(orbital);
+    return orbitalSessionFile(this.workDir, orbital, basename);
+  }
+  readSpec(orbital) {
+    return readJsonFileSync(this.backend, this.orbitalFile(orbital, ORBITAL_FILES.spec));
+  }
+  async writeSpec(orbital, spec) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.spec);
+    await this.withLock(p, async () => {
+      await ensureOrbitalSessionDir(this.backend, this.workDir, orbital);
+      await writeJsonFile(this.backend, p, spec);
+    });
+    await this.emit({ kind: "spec", orbital, content: spec });
+  }
+  readMemory(orbital) {
+    return readJsonFileSync(this.backend, this.orbitalFile(orbital, ORBITAL_FILES.memory));
+  }
+  async writeMemory(orbital, memory) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.memory);
+    await this.withLock(p, async () => {
+      await ensureOrbitalSessionDir(this.backend, this.workDir, orbital);
+      await writeJsonFile(this.backend, p, memory);
+    });
+    await this.emit({ kind: "memory", orbital, content: memory });
+  }
+  async appendHistory(orbital, entry) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.history);
+    await this.withLock(p, async () => {
+      await ensureOrbitalSessionDir(this.backend, this.workDir, orbital);
+      await appendJsonLine(this.backend, p, entry);
+    });
+    await this.emit({ kind: "history", orbital, entry });
+  }
+  readHistory(orbital) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.history);
+    return readJsonLinesSync(this.backend, p);
+  }
+  async appendParamsHistory(orbital, row) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.paramsHistory);
+    await this.withLock(p, async () => {
+      await ensureOrbitalSessionDir(this.backend, this.workDir, orbital);
+      await appendJsonLine(this.backend, p, row);
+    });
+    await this.emit({ kind: "params-history", orbital, row });
+  }
+  readErrors(orbital) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.errors);
+    if (!this.backend.exists(p)) return [];
+    try {
+      const parsed = JSON.parse(this.backend.readFileSync(p));
+      if (!Array.isArray(parsed)) return [];
+      return parsed;
+    } catch {
+      return [];
+    }
+  }
+  async writeErrors(orbital, errors) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.errors);
+    await this.withLock(p, async () => {
+      await ensureOrbitalSessionDir(this.backend, this.workDir, orbital);
+      await this.backend.writeFile(p, JSON.stringify(errors, null, 2));
+    });
+    await this.emit({ kind: "errors", orbital, content: errors });
+  }
+  readSubagentMessages(orbital) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.messages);
+    if (!this.backend.exists(p)) return null;
+    try {
+      const parsed = JSON.parse(this.backend.readFileSync(p));
+      if (!Array.isArray(parsed)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  async writeSubagentMessages(orbital, messages) {
+    const p = this.orbitalFile(orbital, ORBITAL_FILES.messages);
+    await this.withLock(p, async () => {
+      await ensureOrbitalSessionDir(this.backend, this.workDir, orbital);
+      await this.backend.writeFile(p, JSON.stringify(messages, null, 2));
+    });
+    await this.emit({ kind: "subagent-messages", orbital, content: messages });
+  }
+  // === Trace ===
+  async emitTrace(event) {
+    const p = traceFile(this.workDir);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await appendJsonLine(this.backend, p, event);
+    });
+    await this.emit({ kind: "trace", event });
+  }
+  readTrace() {
+    const p = traceFile(this.workDir);
+    return readJsonLinesSync(this.backend, p);
+  }
+  // === Compiled output ===
+  async writeCompiled(relPath, content) {
+    if (relPath.includes("..") || path2.isAbsolute(relPath)) {
+      throw new Error(`compiled: invalid relPath (${relPath})`);
+    }
+    const p = compiledFile(this.workDir, relPath);
+    await this.withLock(p, async () => {
+      await this.ensureParent(p);
+      await this.backend.writeFile(p, content);
+    });
+    await this.emit({ kind: "compiled", relPath, content });
+  }
+  readCompiled(relPath) {
+    if (relPath.includes("..") || path2.isAbsolute(relPath)) return null;
+    const p = compiledFile(this.workDir, relPath);
+    if (!this.backend.exists(p)) return null;
+    try {
+      return this.backend.readFileSync(p);
+    } catch {
+      return null;
+    }
+  }
+  async clearCompiled() {
+    const dir = compiledDir(this.workDir);
+    if (!this.backend.exists(dir)) return;
+    await removeTree(this.backend, dir);
+  }
+  // === Sandboxed generic file I/O ===
+  async readFile(relPath) {
+    const abs = sandboxedPath(this.workDir, relPath);
+    if (!this.backend.exists(abs)) return null;
+    try {
+      return await this.backend.readFile(abs);
+    } catch {
+      return null;
+    }
+  }
+  async writeFile(relPath, content) {
+    const abs = sandboxedPath(this.workDir, relPath);
+    await this.withLock(abs, async () => {
+      await this.ensureParent(abs);
+      await this.backend.writeFile(abs, content);
+    });
+    await this.emit({ kind: "file", relPath, content });
+  }
+  async listTree(relPath) {
+    const base = relPath === void 0 ? this.workDir : sandboxedPath(this.workDir, relPath);
+    if (!this.backend.exists(base)) return [];
+    const out = [];
+    await walk(this.backend, base, this.workDir, out);
+    return out;
+  }
+  async exists(relPath) {
+    let abs;
+    try {
+      abs = sandboxedPath(this.workDir, relPath);
+    } catch {
+      return false;
+    }
+    return this.backend.exists(abs);
+  }
+  // === Git ===
+  async commitAndPush(opts) {
+    if (!this.git) return null;
+    await this.git.addAll();
+    const sha = await this.git.commit(opts.message);
+    if (sha === null) return null;
+    if (opts.tags) {
+      for (const t of opts.tags) await this.git.tag(t);
+    }
+    if (this.github && this.github.repoUrl) {
+      if (!await this.git.hasRemote("origin")) {
+        await this.git.addRemote("origin", this.github.repoUrl);
+      }
+      await this.git.push("origin", this.github.branch ?? "main");
+    }
+    return { sha };
+  }
+  async pullIfLinked() {
+    if (!this.git || !this.github) return false;
+    if (!await this.git.hasRemote("origin")) return false;
+    await this.git.pull("origin", this.github.branch ?? "main");
+    return true;
+  }
+  async gitStatus() {
+    if (!this.git) {
+      return { clean: true, staged: [], modified: [], untracked: [], linked: false };
+    }
+    const s = await this.git.status();
+    const linked = await this.git.hasRemote("origin");
+    return { ...s, linked };
+  }
+  // === Observation ===
+  subscribe(observer) {
+    return this.sinks.subscribe(observer);
+  }
+  // === Disposal ===
+  async dispose() {
+    const pending = Array.from(this.writeQueue.values());
+    await Promise.allSettled(pending);
+    if (this.git && this.github) {
+      try {
+        await this.commitAndPush({ message: "workspace: dispose" });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[workspace] dispose: commitAndPush failed: ${msg}`);
+      }
+    }
+  }
+};
+function readJsonFileSync(backend, absPath) {
+  if (!backend.exists(absPath)) return null;
+  try {
+    return JSON.parse(backend.readFileSync(absPath));
+  } catch {
+    return null;
+  }
+}
+function readJsonLinesSync(backend, absPath) {
+  if (!backend.exists(absPath)) return [];
+  try {
+    const raw = backend.readFileSync(absPath);
+    const out = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+async function walk(backend, dir, root, out) {
+  const entries = await backend.readdir(dir);
+  for (const name of entries) {
+    const full = path2.join(dir, name);
+    const s = await backend.stat(full);
+    const rel = path2.relative(root, full).split(path2.sep).join("/");
+    if (s.isDirectory) {
+      out.push({ path: rel, type: "directory", size: 0 });
+      await walk(backend, full, root, out);
+    } else {
+      out.push({ path: rel, type: "file", size: s.size });
+    }
+  }
+}
+async function removeTree(backend, dir) {
+  const entries = await backend.readdir(dir);
+  for (const name of entries) {
+    const full = path2.join(dir, name);
+    let isDir = false;
+    try {
+      isDir = (await backend.stat(full)).isDirectory;
+    } catch {
+      continue;
+    }
+    if (isDir) {
+      await removeTree(backend, full);
+    } else {
+      try {
+        await backend.unlink(full);
+      } catch {
+      }
+    }
+  }
+}
+
+// src/open-workspace.ts
+async function openWorkspace(opts) {
+  const backend = opts.backend === "memory" ? new MemoryBackend() : new LocalBackend();
+  const sinks = new SinkManager();
+  const resolved = await resolveLifecycle(backend, opts);
+  await ensureSkeleton(backend, resolved.workDir);
+  await writeMintTemplatesIfMissing(
+    backend,
+    resolved.workDir,
+    opts.userId,
+    opts.projectName ?? "Untitled",
+    resolved.appId
+  );
+  if (resolved.appId !== void 0) {
+    const existing = readAppMarker(backend, resolved.workDir);
+    if (!existing || existing.appId !== resolved.appId) {
+      const marker = {
+        appId: resolved.appId,
+        userId: opts.userId,
+        createdAt: existing?.createdAt ?? Date.now()
+      };
+      if (opts.github?.repoUrl) marker.repoUrl = opts.github.repoUrl;
+      await writeAppMarker(backend, resolved.workDir, marker);
+    }
+  }
+  let git;
+  if (opts.github && opts.backend !== "memory") {
+    git = await ensureGitInit(backend, resolved.workDir);
+  }
+  return new WorkspaceServiceImpl({
+    workDir: resolved.workDir,
+    backend,
+    sinks,
+    appId: resolved.appId,
+    git,
+    github: opts.github
+  });
+}
+async function resolveLifecycle(backend, opts) {
+  if (opts.adopt) {
+    const workDir2 = path2.resolve(opts.adopt);
+    const marker = readAppMarker(backend, workDir2);
+    return { workDir: workDir2, appId: marker?.appId ?? opts.appId };
+  }
+  if (opts.appId) {
+    const local = await findLocalWorkspaceDir(
+      backend,
+      opts.root,
+      opts.userId,
+      opts.appId
+    );
+    if (local) return { workDir: local, appId: opts.appId };
+  }
+  if (opts.appId && opts.restore) {
+    const workDir2 = mintSessionDir(opts.root, opts.userId);
+    await backend.mkdir(workDir2, { recursive: true });
+    await restoreWorkspace(backend, workDir2, opts.restore);
+    return { workDir: workDir2, appId: opts.appId };
+  }
+  if (opts.appId && opts.github && opts.github.repoUrl) {
+    const workDir2 = mintSessionDir(opts.root, opts.userId);
+    await backend.mkdir(workDir2, { recursive: true });
+    return { workDir: workDir2, appId: opts.appId };
+  }
+  const workDir = mintSessionDir(opts.root, opts.userId);
+  return { workDir, appId: opts.appId };
+}
+
+export { openWorkspace };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map