@clicksmith/daemon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClickSmith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @clicksmith/daemon
+
+The localhost brain of ClickSmith. A single Node process that owns sessions,
+runs, and **safety**. It exposes:
+
+- **HTTP** (Fastify) — capture, submit, apply, session reads.
+- **WebSocket** (Fastify) — live run events streamed to the extension.
+- **MCP** (stdio) — read-only tools for any MCP-capable coding agent.
+- **Git sandbox orchestration** — throwaway worktrees, dirty-tree refusal, apply.
+- **Config-driven agent launching** — spawns the selected agent via `execa`.
+
+Everything stays local. No cloud, no telemetry.
+
+## Run it
+
+```bash
+clicksmith daemon --port 8722        # HTTP + WS + state under .clicksmith/
+clicksmith mcp                       # read-only MCP stdio server
+clicksmith version
+```
+
+## HTTP surface
+
+| Method & path | Purpose |
+| --- | --- |
+| `GET /health` | Liveness + daemon metadata. |
+| `POST /capture` | Create/append the active session for an app/route. |
+| `POST /submit` | Finalize a bundle and start a run. `409` if the tree is dirty. |
+| `POST /apply/:runId` | Merge the sandbox back; reports conflicts. |
+| `GET /session/:id` | Read a session. |
+| `DELETE /element/:sessionId/:elementId` | Remove a captured mark. |
+
+WebSocket (`/ws`) streams: `capture-ack`, `element-removed`, `agent-started`,
+`agent-log`, `plan-ready`, `agent-done`, `agent-error`, `apply-started`,
+`apply-done`, `apply-error`. Send `{ "type": "subscribe" }` to replay buffered
+events on reconnect.
+
+## Safety model
+
+`POST /submit` with the default `plan + worktree` options:
+
+1. Detects the repo root and base commit.
+2. **Refuses** (`409`) if the working tree has uncommitted changes (ignoring
+   `.clicksmith/` itself) — unless you explicitly choose `inplace`.
+3. Creates a throwaway worktree at `.clicksmith/worktrees/<runId>` on branch
+   `clicksmith/<runId>`. Falls back to a dedicated branch if worktrees are
+   unavailable.
+4. Launches the agent **in the sandbox** — your main tree is never touched.
+5. Captures the agent's stdout as `plan.md` and a binary-safe `diff.patch`.
+6. `POST /apply/:runId` 3-way-applies the patch onto the main tree, commits,
+   records revert metadata, and cleans up the worktree. Conflicts are reported,
+   not forced.
+
+## Persistence layout
+
+```
+.clicksmith/                 (or OS cache dir when not in a repo)
+  sessions/<id>.json
+  runs/<runId>/
+    bundle.json  plan.md  diff.patch  agent.log  run.json
+  worktrees/<runId>/         (throwaway git worktree)
+  agents.config.json         (optional project agent overrides)
+```
+
+Unsubmitted sessions expire after a configurable default of 24 hours.
+
+## Programmatic use
+
+```ts
+import { DaemonService, buildServer, resolveDaemonConfig } from '@clicksmith/daemon';
+
+const config = await resolveDaemonConfig({ port: 8722 });
+const service = new DaemonService({ config });
+await service.init();
+const app = await buildServer(service);
+await app.listen({ host: config.host, port: config.port });
+```
+
+The `DaemonService` is framework-agnostic and fully unit-/integration-tested,
+including the end-to-end acceptance flow (capture → plan in worktree → prove the
+main tree is untouched → apply → cleanup).

package/dist/chunk-FY7JGOX6.js

@@ -0,0 +1,540 @@
+import {
+  FileStore,
+  Git,
+  describeSandbox,
+  version
+} from "./chunk-UVRW6O46.js";
+
+// src/events.ts
+var EventBus = class {
+  listeners = /* @__PURE__ */ new Set();
+  history = [];
+  maxHistory;
+  constructor(maxHistory = 500) {
+    this.maxHistory = maxHistory;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit(event) {
+    this.history.push(event);
+    if (this.history.length > this.maxHistory) this.history.shift();
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  /** Replay buffered events, optionally filtered to a run id. */
+  replay(runId) {
+    if (!runId) return [...this.history];
+    return this.history.filter((e) => "runId" in e && e.runId === runId);
+  }
+};
+
+// src/launcher.ts
+import { execa } from "execa";
+async function launchAgent(spec, handlers) {
+  const subprocess = execa(spec.command, spec.args, {
+    cwd: spec.cwd,
+    env: { ...process.env, ...spec.env },
+    reject: false,
+    all: false,
+    cancelSignal: handlers.signal
+  });
+  let stdout = "";
+  subprocess.stdout?.on("data", (data) => {
+    const chunk = data.toString();
+    stdout += chunk;
+    handlers.onLog("stdout", chunk);
+  });
+  subprocess.stderr?.on("data", (data) => {
+    handlers.onLog("stderr", data.toString());
+  });
+  const result = await subprocess;
+  return {
+    exitCode: result.exitCode ?? (result.isCanceled ? 130 : 0),
+    stdout,
+    canceled: Boolean(result.isCanceled)
+  };
+}
+
+// src/enrichment.ts
+async function enrichBundle(bundle, provider) {
+  if (!provider) return bundle;
+  try {
+    const enrichment = await provider.enrich(bundle);
+    if (!enrichment) return bundle;
+    return { ...bundle, enrichment };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ...bundle,
+      enrichment: {
+        source: "code-review-graph",
+        perElement: bundle.enrichment?.perElement ?? [],
+        warnings: [...bundle.enrichment?.warnings ?? [], `enrichment failed: ${message}`]
+      }
+    };
+  }
+}
+
+// src/run-manager.ts
+import { mkdir } from "fs/promises";
+import { join } from "path";
+import {
+  configToAdapter,
+  defaultBinExists,
+  renderInstructionBody,
+  resolveAgent
+} from "@clicksmith/agent-config";
+import {
+  newRunId
+} from "@clicksmith/core";
+var RefusalError = class extends Error {
+  code = "DIRTY_TREE";
+};
+var COMMIT_PREFIX = "ClickSmith";
+var RunManager = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  /**
+   * Prepare a sandbox and start an agent run. The sandbox is prepared
+   * synchronously so a dirty-tree refusal surfaces as an error to the caller;
+   * the agent itself runs in the background, emitting WebSocket events.
+   */
+  async createRun(input) {
+    const { store, config, bus, logger } = this.deps;
+    const agentConfig = resolveAgent(config.agents, input.execution.agentId);
+    if (!agentConfig) {
+      throw new RefusalError(`No agent configured (requested: ${input.execution.agentId ?? "default"}).`);
+    }
+    const runId = newRunId();
+    const now = /* @__PURE__ */ new Date();
+    const repoRoot = config.repoRoot;
+    const isolation = repoRoot ? input.execution.isolation : "inplace";
+    let sandbox = null;
+    let baseCommit = null;
+    let baseBranch = null;
+    if (repoRoot) {
+      const git = new Git(repoRoot);
+      baseCommit = await git.headCommit();
+      baseBranch = await safe(() => git.currentBranch());
+      const baseRef = input.execution.baseRef ?? baseCommit;
+      if (isolation !== "inplace" && await git.isDirty({ exclude: [".clicksmith/", ".clicksmith"] })) {
+        throw new RefusalError(
+          `Refusing to run in ${isolation} isolation: the working tree has uncommitted changes. Commit or stash them, or use inplace isolation explicitly.`
+        );
+      }
+      sandbox = await this.prepareSandbox(git, runId, isolation, baseRef, repoRoot, baseCommit, logger);
+    }
+    const enriched = await enrichBundle(input, this.deps.enrichment);
+    await store.saveBundle(runId, enriched);
+    const run = {
+      runId,
+      sessionId: enriched.sessionId,
+      agentId: agentConfig.id,
+      status: "running",
+      createdAt: now.toISOString(),
+      updatedAt: now.toISOString(),
+      mode: enriched.execution.mode,
+      isolation,
+      prompt: enriched.prompt,
+      repoRoot,
+      baseCommit,
+      baseBranch,
+      sandbox,
+      revert: null
+    };
+    await store.saveRun(run);
+    bus.emit({ type: "agent-started", runId, sessionId: run.sessionId, agentId: run.agentId, sandbox });
+    void this.execute(run, enriched, agentConfig).catch((err) => {
+      logger.error(`run ${runId} crashed`, err);
+    });
+    return { run };
+  }
+  async prepareSandbox(git, runId, isolation, baseRef, repoRoot, baseCommit, logger) {
+    const branch = `clicksmith/${runId}`;
+    if (isolation === "inplace") {
+      return describeSandbox("inplace", repoRoot, null, baseCommit);
+    }
+    if (isolation === "worktree") {
+      if (await git.supportsWorktree()) {
+        const path = this.deps.store.paths.sandboxDir(runId);
+        await mkdir(join(path, ".."), { recursive: true });
+        await git.createWorktree(path, branch, baseRef);
+        return describeSandbox("worktree", path, branch, baseCommit);
+      }
+      logger.warn("git worktrees unavailable; falling back to a dedicated branch");
+    }
+    await git.createBranch(branch, baseRef);
+    return describeSandbox("branch", repoRoot, branch, baseCommit);
+  }
+  async execute(run, bundle, agentConfig) {
+    const { store, config, bus, logger } = this.deps;
+    const sandboxPath = run.sandbox?.path ?? config.cwd;
+    const instructionFile = await this.resolveInstructionFile(run, agentConfig);
+    const ctx = {
+      bundlePath: store.bundlePath(run.runId),
+      prompt: bundle.prompt,
+      instructionFile,
+      mode: bundle.execution.mode,
+      mcpServer: "clicksmith",
+      cwd: sandboxPath,
+      isolation: run.isolation,
+      agentId: agentConfig.id,
+      binExists: this.deps.binExists ?? defaultBinExists
+    };
+    const adapter = configToAdapter(agentConfig);
+    if (!await adapter.isAvailable(ctx)) {
+      await this.fail(run, `Agent "${agentConfig.id}" is not available on PATH.`);
+      return;
+    }
+    const spec = adapter.buildCommand(ctx);
+    logger.info(`run ${run.runId}: ${spec.command} ${spec.args.join(" ")}`);
+    let result;
+    try {
+      result = await launchAgent(spec, {
+        onLog: (stream, chunk) => {
+          void store.appendLog(run.runId, chunk);
+          bus.emit({ type: "agent-log", runId: run.runId, stream, chunk });
+        }
+      });
+    } catch (err) {
+      await this.fail(run, err instanceof Error ? err.message : String(err));
+      return;
+    }
+    const plan = result.stdout.trim();
+    let diff = "";
+    if (run.sandbox && run.repoRoot) {
+      diff = await Git.captureDiff(run.sandbox.path);
+    }
+    if (plan) await store.writeArtifact(run.runId, "plan.md", plan);
+    if (diff) await store.writeArtifact(run.runId, "diff.patch", diff);
+    run.exitCode = result.exitCode;
+    run.hasPlan = plan.length > 0;
+    run.hasDiff = diff.length > 0;
+    if (result.exitCode !== 0) {
+      await this.fail(run, `Agent exited with code ${result.exitCode}.`);
+      return;
+    }
+    run.status = "plan-ready";
+    run.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await store.saveRun(run);
+    bus.emit({
+      type: "plan-ready",
+      runId: run.runId,
+      ...plan ? { plan } : {},
+      ...diff ? { diff } : {}
+    });
+    bus.emit({ type: "agent-done", runId: run.runId, exitCode: result.exitCode });
+    if (bundle.execution.autoApply) {
+      logger.info(`run ${run.runId}: autoApply enabled, applying`);
+      await this.apply(run.runId);
+    }
+  }
+  async fail(run, message) {
+    run.status = "error";
+    run.error = message;
+    run.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.deps.store.saveRun(run);
+    this.deps.bus.emit({ type: "agent-error", runId: run.runId, message });
+  }
+  /**
+   * Merge a finished run's sandbox changes back into the working tree. Reports
+   * conflicts, commits on success, records revert metadata, and cleans up the
+   * sandbox.
+   */
+  async apply(runId) {
+    const { store, bus, logger } = this.deps;
+    const run = await store.getRun(runId);
+    if (!run) throw new Error(`Unknown run: ${runId}`);
+    if (!run.repoRoot || !run.sandbox) {
+      throw new Error(`Run ${runId} has no git sandbox to apply.`);
+    }
+    bus.emit({ type: "apply-started", runId });
+    const git = new Git(run.repoRoot);
+    const previousHead = await git.headCommit();
+    const message = `${COMMIT_PREFIX} run ${runId}: ${truncate(run.prompt, 72)}`;
+    try {
+      let commit;
+      if (run.sandbox.isolation === "worktree") {
+        const diff = await store.readArtifact(runId, "diff.patch") ?? "";
+        const applied = await git.applyPatch(diff);
+        if (!applied.ok) return await this.applyConflict(run, applied.conflicts);
+        commit = diff.trim() ? await git.commit(message) : previousHead;
+        await this.cleanupSandbox(run);
+      } else if (run.sandbox.isolation === "branch") {
+        if (await git.hasChanges()) await git.commit(message);
+        if (run.baseBranch) await git.switchTo(run.baseBranch);
+        const merged = await git.merge(run.sandbox.branch, message);
+        if (!merged.ok) return await this.applyConflict(run, merged.conflicts);
+        commit = await git.headCommit();
+        await git.deleteBranch(run.sandbox.branch);
+      } else {
+        commit = await git.hasChanges() ? await git.commit(message) : previousHead;
+      }
+      run.status = "applied";
+      run.applied = { ...commit ? { commit } : {}, at: (/* @__PURE__ */ new Date()).toISOString() };
+      run.revert = {
+        previousHead,
+        ...commit && commit !== previousHead ? { appliedCommit: commit } : {},
+        instructions: commit && commit !== previousHead ? `git revert ${commit}  # or: git reset --hard ${previousHead}` : "No commit was created; nothing to revert."
+      };
+      run.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await store.saveRun(run);
+      bus.emit({ type: "apply-done", runId, ...commit ? { commit } : {} });
+      return { applied: true, ...commit ? { commit } : {} };
+    } catch (err) {
+      const messageText = err instanceof Error ? err.message : String(err);
+      logger.error(`apply ${runId} failed`, messageText);
+      run.status = "apply-error";
+      run.error = messageText;
+      await store.saveRun(run);
+      bus.emit({ type: "apply-error", runId, message: messageText });
+      return { applied: false };
+    }
+  }
+  async applyConflict(run, conflicts) {
+    run.status = "apply-error";
+    run.error = `Apply conflicts in: ${conflicts.join(", ") || "unknown files"}`;
+    run.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await this.deps.store.saveRun(run);
+    this.deps.bus.emit({
+      type: "apply-error",
+      runId: run.runId,
+      message: run.error,
+      conflicts
+    });
+    return { applied: false, conflicts };
+  }
+  async cleanupSandbox(run) {
+    if (!run.repoRoot || !run.sandbox) return;
+    if (run.sandbox.isolation === "worktree") {
+      const git = new Git(run.repoRoot);
+      await git.removeWorktree(run.sandbox.path, run.sandbox.branch ?? void 0);
+    }
+  }
+  /**
+   * Resolve the instruction file passed to the agent. Prefer the project's
+   * rendered file if it exists; otherwise write a run-local one from the shared
+   * template so every agent always has instructions.
+   */
+  async resolveInstructionFile(run, agentConfig) {
+    const { config, store } = this.deps;
+    if (config.repoRoot && agentConfig.instructions) {
+      const projectFile = join(config.repoRoot, agentConfig.instructions.file);
+      if (await fileExists(projectFile)) return projectFile;
+    }
+    const body = renderInstructionBody({ daemonPort: config.port });
+    return store.writeArtifact(run.runId, "AGENT_INSTRUCTIONS.md", body);
+  }
+};
+async function fileExists(path) {
+  const { access } = await import("fs/promises");
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function safe(fn) {
+  try {
+    return await fn();
+  } catch {
+    return null;
+  }
+}
+function truncate(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
+}
+
+// src/daemon-service.ts
+import {
+  appendElement,
+  createSession,
+  ExecutionOptionsSchema,
+  finalizeSession,
+  removeElement,
+  touchSession
+} from "@clicksmith/core";
+var DaemonService = class {
+  config;
+  store;
+  bus;
+  runs;
+  constructor(opts) {
+    this.config = opts.config;
+    this.store = new FileStore(opts.config.storageRoot);
+    this.bus = new EventBus();
+    this.runs = new RunManager({
+      store: this.store,
+      config: opts.config,
+      bus: this.bus,
+      logger: opts.config.logger,
+      ...opts.enrichment ? { enrichment: opts.enrichment } : {},
+      ...opts.binExists ? { binExists: opts.binExists } : {}
+    });
+  }
+  async init() {
+    await this.store.init();
+    await this.store.cleanupExpired();
+  }
+  /* ------------------------------- capture ------------------------------ */
+  /** Create or append to the active session for an app/route. */
+  async capture(req) {
+    const now = /* @__PURE__ */ new Date();
+    let session = req.sessionId ? await this.store.getSession(req.sessionId) : void 0;
+    if (!session) {
+      session = createSession({ app: req.app, now, ttlMs: this.config.ttlMs });
+    } else {
+      session = touchSession(session, now, this.config.ttlMs);
+    }
+    const { session: next, element } = appendElement(session, req.element, now);
+    await this.store.saveSession(next);
+    this.bus.emit({ type: "capture-ack", sessionId: next.id, element });
+    return { sessionId: next.id, element };
+  }
+  async removeElement(sessionId, elementId) {
+    const session = await this.store.getSession(sessionId);
+    if (!session) return { removed: false };
+    const { session: next, removed } = removeElement(session, elementId);
+    if (removed) {
+      await this.store.saveSession(next);
+      this.bus.emit({ type: "element-removed", sessionId, elementId });
+    }
+    return { removed };
+  }
+  async getSession(id) {
+    return this.store.getSession(id);
+  }
+  /* ------------------------------- submit ------------------------------- */
+  /** Finalize a session into a bundle and start a run. */
+  async submit(req) {
+    const session = await this.store.getSession(req.sessionId);
+    if (!session) throw new NotFoundError(`Unknown session: ${req.sessionId}`);
+    const execution = ExecutionOptionsSchema.parse(req.execution ?? {});
+    const bundle = finalizeSession(session, {
+      prompt: req.prompt,
+      execution,
+      ...req.enrichment ? { enrichment: req.enrichment } : {}
+    });
+    const submitted = { ...session, status: "submitted", prompt: req.prompt };
+    await this.store.saveSession(submitted);
+    const { run } = await this.runs.createRun(bundle);
+    return { runId: run.runId, bundle };
+  }
+  async apply(runId) {
+    return this.runs.apply(runId);
+  }
+  /* ------------------------------- health ------------------------------- */
+  async health() {
+    const sessions = await this.store.listSessions();
+    return {
+      ok: true,
+      name: "clicksmith-daemon",
+      version,
+      host: this.config.host,
+      port: this.config.port,
+      repoRoot: this.config.repoRoot,
+      activeSessions: sessions.filter((s) => s.status === "active").length
+    };
+  }
+};
+var NotFoundError = class extends Error {
+  code = "NOT_FOUND";
+};
+
+// src/server.ts
+import Fastify from "fastify";
+import websocket from "@fastify/websocket";
+import {
+  CaptureRequestSchema,
+  SubmitRequestSchema
+} from "@clicksmith/core";
+async function buildServer(service) {
+  const app = Fastify({ logger: false });
+  app.addHook("onRequest", async (req, reply) => {
+    reply.header("Access-Control-Allow-Origin", "*");
+    reply.header("Access-Control-Allow-Methods", "GET,POST,DELETE,OPTIONS");
+    reply.header("Access-Control-Allow-Headers", "content-type");
+    if (req.method === "OPTIONS") {
+      reply.code(204).send();
+    }
+  });
+  await app.register(websocket);
+  app.get("/health", async () => service.health());
+  app.post("/capture", async (req, reply) => {
+    const parsed = CaptureRequestSchema.safeParse(req.body);
+    if (!parsed.success) return reply.code(400).send({ error: parsed.error.message });
+    return service.capture(parsed.data);
+  });
+  app.post("/submit", async (req, reply) => {
+    const parsed = SubmitRequestSchema.safeParse(req.body);
+    if (!parsed.success) return reply.code(400).send({ error: parsed.error.message });
+    try {
+      return await service.submit(parsed.data);
+    } catch (err) {
+      if (err instanceof NotFoundError) return reply.code(404).send({ error: err.message });
+      if (err instanceof RefusalError) return reply.code(409).send({ error: err.message, code: err.code });
+      throw err;
+    }
+  });
+  app.post("/apply/:runId", async (req, reply) => {
+    try {
+      return await service.apply(req.params.runId);
+    } catch (err) {
+      return reply.code(404).send({ error: err instanceof Error ? err.message : String(err) });
+    }
+  });
+  app.get("/session/:id", async (req, reply) => {
+    const session = await service.getSession(req.params.id);
+    if (!session) return reply.code(404).send({ error: `Unknown session: ${req.params.id}` });
+    return session;
+  });
+  app.delete(
+    "/element/:sessionId/:elementId",
+    async (req) => {
+      const elementId = Number.parseInt(req.params.elementId, 10);
+      return service.removeElement(req.params.sessionId, elementId);
+    }
+  );
+  app.get("/ws", { websocket: true }, (socket) => {
+    const send = (event) => {
+      if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(event));
+    };
+    const unsubscribe = service.bus.subscribe(send);
+    socket.on("message", (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (msg.type === "ping") socket.send(JSON.stringify({ type: "pong" }));
+      else if (msg.type === "subscribe") {
+        for (const event of service.bus.replay(msg.sessionId)) send(event);
+      }
+    });
+    socket.on("close", unsubscribe);
+    socket.on("error", unsubscribe);
+  });
+  return app;
+}
+
+export {
+  EventBus,
+  launchAgent,
+  enrichBundle,
+  RefusalError,
+  RunManager,
+  DaemonService,
+  NotFoundError,
+  buildServer
+};
+//# sourceMappingURL=chunk-FY7JGOX6.js.map