clawspec 1.0.0

package/src/workspace/store.ts

@@ -0,0 +1,140 @@
+import path from "node:path";
+import { ensureDir, pathExists, readJsonFile, writeJsonFile } from "../utils/fs.ts";
+import { sameNormalizedPath } from "../utils/paths.ts";
+import type { WorkspaceRecord, WorkspaceStateFile } from "../types.ts";
+
+export class WorkspaceStore {
+  readonly filePath: string;
+  readonly defaultWorkspace: string;
+  private initPromise: Promise<void> | undefined;
+
+  constructor(filePath: string, defaultWorkspace: string) {
+    this.filePath = filePath;
+    this.defaultWorkspace = path.normalize(defaultWorkspace);
+  }
+
+  async initialize(): Promise<void> {
+    this.initPromise ??= this.doInitialize();
+    return this.initPromise;
+  }
+
+  private async doInitialize(): Promise<void> {
+    await ensureDir(path.dirname(this.filePath));
+    if (!(await pathExists(this.filePath))) {
+      await this.writeState({
+        version: 1,
+        currentWorkspace: this.defaultWorkspace,
+        currentWorkspaceByChannel: {},
+        workspaces: [{
+          path: this.defaultWorkspace,
+          lastUsedAt: new Date().toISOString(),
+        }],
+      });
+    }
+
+    const currentWorkspace = await this.getCurrentWorkspace();
+    await ensureDir(currentWorkspace);
+  }
+
+  async getCurrentWorkspace(channelKey?: string): Promise<string> {
+    const state = await this.readState();
+    if (channelKey) {
+      const channelWorkspace = state.currentWorkspaceByChannel?.[channelKey];
+      if (channelWorkspace) {
+        return path.normalize(channelWorkspace);
+      }
+    }
+    return path.normalize(state.currentWorkspace || this.defaultWorkspace);
+  }
+
+  async list(): Promise<WorkspaceRecord[]> {
+    const state = await this.readState();
+    return [...state.workspaces].sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
+  }
+
+  async useWorkspace(workspacePath: string, channelKey?: string): Promise<WorkspaceStateFile> {
+    const normalized = path.normalize(workspacePath);
+    await ensureDir(normalized);
+    const state = await this.readState();
+    const now = new Date().toISOString();
+    const existing = state.workspaces.find((entry) => sameNormalizedPath(entry.path, normalized));
+    const nextByChannel = { ...(state.currentWorkspaceByChannel ?? {}) };
+    if (channelKey) {
+      nextByChannel[channelKey] = normalized;
+    }
+
+    const next: WorkspaceStateFile = {
+      version: 1,
+      currentWorkspace: normalized,
+      currentWorkspaceByChannel: nextByChannel,
+      workspaces: [
+        ...state.workspaces.filter((entry) => !sameNormalizedPath(entry.path, normalized)),
+        {
+          path: normalized,
+          lastUsedAt: now,
+        },
+      ],
+    };
+
+    if (!existing && next.workspaces.length === 0) {
+      next.workspaces.push({ path: normalized, lastUsedAt: now });
+    }
+
+    await this.writeState(next);
+    return next;
+  }
+
+  private async readState(): Promise<WorkspaceStateFile> {
+    const fallback: WorkspaceStateFile = {
+      version: 1,
+      currentWorkspace: this.defaultWorkspace,
+      currentWorkspaceByChannel: {},
+      workspaces: [{
+        path: this.defaultWorkspace,
+        lastUsedAt: new Date(0).toISOString(),
+      }],
+    };
+    const raw = await readJsonFile<WorkspaceStateFile | (WorkspaceStateFile & { workspace?: string })>(
+      this.filePath,
+      fallback,
+    );
+
+    const currentWorkspace = path.normalize(
+      (raw as WorkspaceStateFile).currentWorkspace ?? (raw as { workspace?: string }).workspace ?? this.defaultWorkspace,
+    );
+    const currentWorkspaceByChannel = typeof (raw as WorkspaceStateFile).currentWorkspaceByChannel === "object"
+      && (raw as WorkspaceStateFile).currentWorkspaceByChannel
+      ? Object.fromEntries(
+          Object.entries((raw as WorkspaceStateFile).currentWorkspaceByChannel ?? {})
+            .filter((entry): entry is [string, string] => typeof entry[0] === "string" && typeof entry[1] === "string")
+            .map(([channelKey, workspacePath]) => [channelKey, path.normalize(workspacePath)]),
+        )
+      : {};
+    const workspaces = Array.isArray((raw as WorkspaceStateFile).workspaces)
+      ? (raw as WorkspaceStateFile).workspaces
+          .filter((entry): entry is WorkspaceRecord => typeof entry?.path === "string" && entry.path.trim().length > 0)
+          .map((entry) => ({
+            path: path.normalize(entry.path),
+            lastUsedAt: entry.lastUsedAt || new Date(0).toISOString(),
+          }))
+      : [];
+
+    if (!workspaces.some((entry) => sameNormalizedPath(entry.path, currentWorkspace))) {
+      workspaces.push({
+        path: currentWorkspace,
+        lastUsedAt: new Date().toISOString(),
+      });
+    }
+
+    return {
+      version: 1,
+      currentWorkspace,
+      currentWorkspaceByChannel,
+      workspaces,
+    };
+  }
+
+  private async writeState(state: WorkspaceStateFile): Promise<void> {
+    await writeJsonFile(this.filePath, state);
+  }
+}

package/test/acp-client.test.ts

@@ -0,0 +1,234 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { chmod, mkdtemp, writeFile } from "node:fs/promises";
+import { AcpWorkerClient } from "../src/acp/client.ts";
+
+test("AcpWorkerClient tracks active worker lifecycle through acpx CLI", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-acpx-client-"));
+  const fake = await createFakeAcpx(tempRoot);
+  const client = new AcpWorkerClient({
+    agentId: "codex",
+    logger: createLogger(),
+    command: fake.command,
+    env: fake.env,
+  });
+
+  const events: Array<{ type: string; text?: string }> = [];
+  const runPromise = client.runTurn({
+    sessionKey: "session-1",
+    cwd: tempRoot,
+    text: "fix tests",
+    onEvent: async (event) => {
+      events.push(event);
+    },
+  });
+
+  await waitFor(async () => {
+    const status = await client.getSessionStatus({
+      sessionKey: "session-1",
+      cwd: tempRoot,
+      agentId: "codex",
+    });
+    return status?.details?.status === "alive";
+  });
+
+  await runPromise;
+
+  const finalStatus = await client.getSessionStatus({
+    sessionKey: "session-1",
+    cwd: tempRoot,
+    agentId: "codex",
+  });
+
+  assert.equal(events.some((event) => event.type === "text_delta" && event.text?.includes("Working on fix tests")), true);
+  assert.match(finalStatus?.summary ?? "", /status=dead/);
+});
+
+async function createFakeAcpx(tempRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
+  const scriptPath = path.join(tempRoot, "fake-acpx.js");
+  const wrapperPath = path.join(tempRoot, process.platform === "win32" ? "fake-acpx.cmd" : "fake-acpx");
+
+  await writeFile(scriptPath, `
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const args = process.argv.slice(2);
+const stateDir = process.env.FAKE_ACPX_STATE;
+
+function consumeGlobals(argv) {
+  const out = [...argv];
+  const result = [];
+  while (out.length > 0) {
+    const head = out[0];
+    if (head === "--format" || head === "--cwd" || head === "--ttl") {
+      out.shift();
+      out.shift();
+      continue;
+    }
+    if (head === "--json-strict" || head === "--approve-all" || head === "--approve-reads" || head === "--deny-all") {
+      out.shift();
+      continue;
+    }
+    result.push(...out);
+    break;
+  }
+  return result;
+}
+
+function flagValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0 && index + 1 < argv.length) {
+    return argv[index + 1];
+  }
+  return undefined;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function writeJsonLine(value) {
+  process.stdout.write(JSON.stringify(value) + "\\n");
+}
+
+async function main() {
+  if (args.includes("--version")) {
+    process.stdout.write("0.3.1\\n");
+    return;
+  }
+
+  const rest = consumeGlobals(args);
+  const agent = rest[0];
+  const verb = rest[1];
+  const tail = rest.slice(2);
+  const sessionName = flagValue(tail, "--session") || flagValue(tail, "--name") || tail[1];
+  const sessionFile = sessionName ? path.join(stateDir, sessionName + ".json") : "";
+  const runningFile = sessionName ? path.join(stateDir, sessionName + ".running") : "";
+
+  async function sessionExists() {
+    try {
+      await fs.access(sessionFile);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function runningExists() {
+    try {
+      await fs.access(runningFile);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  if (verb === "sessions" && tail[0] === "ensure") {
+    if (await sessionExists()) {
+      await writeJsonLine({ acpxRecordId: "record-" + sessionName, acpxSessionId: "backend-" + sessionName, agentSessionId: "agent-" + sessionName, agent });
+      return;
+    }
+    await writeJsonLine({ type: "error", code: "NO_SESSION", message: "missing session" });
+    return;
+  }
+
+  if (verb === "sessions" && tail[0] === "new") {
+    await fs.writeFile(sessionFile, JSON.stringify({ sessionName, agent }), "utf8");
+    await writeJsonLine({ acpxRecordId: "record-" + sessionName, acpxSessionId: "backend-" + sessionName, agentSessionId: "agent-" + sessionName, agent });
+    return;
+  }
+
+  if (verb === "status") {
+    if (!(await sessionExists())) {
+      await writeJsonLine({ type: "error", code: "NO_SESSION", message: "missing session" });
+      return;
+    }
+    await writeJsonLine({
+      status: await runningExists() ? "alive" : "dead",
+      acpxRecordId: "record-" + sessionName,
+      acpxSessionId: "backend-" + sessionName,
+      agentSessionId: "agent-" + sessionName,
+      pid: 1234,
+    });
+    return;
+  }
+
+  if (verb === "cancel") {
+    await fs.rm(runningFile, { force: true });
+    await writeJsonLine({ ok: true });
+    return;
+  }
+
+  if (verb === "prompt") {
+    const text = (await readStdin()).trim();
+    await fs.writeFile(runningFile, "running", "utf8");
+    process.on("SIGTERM", async () => {
+      await fs.rm(runningFile, { force: true });
+      process.exit(143);
+    });
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    await writeJsonLine({ text: "Working on " + text });
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    await fs.rm(runningFile, { force: true });
+    await writeJsonLine({ type: "done" });
+    return;
+  }
+
+  if (verb === "sessions" && tail[0] === "close") {
+    await fs.rm(sessionFile, { force: true });
+    await fs.rm(runningFile, { force: true });
+    await writeJsonLine({ ok: true });
+    return;
+  }
+
+  process.stderr.write("unexpected args: " + JSON.stringify(args));
+  process.exit(1);
+}
+
+main().catch((error) => {
+  process.stderr.write(String(error && error.stack ? error.stack : error));
+  process.exit(1);
+});
+`, "utf8");
+
+  if (process.platform === "win32") {
+    await writeFile(wrapperPath, `@echo off\r\nnode "${scriptPath}" %*\r\n`, "utf8");
+  } else {
+    await writeFile(wrapperPath, `#!/usr/bin/env bash\nnode "${scriptPath}" "$@"\n`, "utf8");
+    await chmod(wrapperPath, 0o755);
+  }
+
+  return {
+    command: wrapperPath,
+    env: {
+      ...process.env,
+      FAKE_ACPX_STATE: tempRoot,
+    },
+  };
+}
+
+function createLogger() {
+  return {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {},
+  };
+}
+
+async function waitFor(predicate: () => Promise<boolean>, timeoutMs = 2_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await predicate()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error("timed out waiting for condition");
+}

package/test/acpx-dependency.test.ts

@@ -0,0 +1,112 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import {
+  ACPX_EXPECTED_VERSION,
+  ACPX_PACKAGE_NAME,
+  ensureAcpxCli,
+} from "../src/dependencies/acpx.ts";
+
+const ROOT_PREFIX = process.platform === "win32" ? "C:\\clawspec-test" : "/tmp/clawspec-test";
+const OPENCLAW_PREFIX = process.platform === "win32" ? "C:\\openclaw-test" : "/opt/openclaw";
+
+const LOCAL_COMMAND = path.join(
+  ROOT_PREFIX,
+  "node_modules",
+  ".bin",
+  process.platform === "win32" ? "acpx.cmd" : "acpx",
+);
+const BUILTIN_COMMAND = path.join(
+  OPENCLAW_PREFIX,
+  "dist",
+  "extensions",
+  "acpx",
+  "node_modules",
+  ".bin",
+  process.platform === "win32" ? "acpx.cmd" : "acpx",
+);
+const OPENCLAW_RUNTIME_ENTRYPOINT = path.join(
+  OPENCLAW_PREFIX,
+  "dist",
+  "index.js",
+);
+
+test("ensureAcpxCli uses the global acpx command when available", async () => {
+  const calls: Array<{ command: string; args: string[] }> = [];
+  const result = await ensureAcpxCli({
+    pluginRoot: ROOT_PREFIX,
+    runner: async ({ command, args }) => {
+      calls.push({ command, args });
+      if (command === LOCAL_COMMAND) {
+        return { code: 1, stdout: "", stderr: "not found" };
+      }
+      if (command === "acpx") {
+        return { code: 0, stdout: `${ACPX_EXPECTED_VERSION}\n`, stderr: "" };
+      }
+      return { code: 1, stdout: "", stderr: "unexpected command" };
+    },
+  });
+
+  assert.equal(result.source, "global");
+  assert.equal(result.version, ACPX_EXPECTED_VERSION);
+  assert.equal(calls.some((call) => call.command === "npm"), false);
+});
+
+test("ensureAcpxCli prefers the OpenClaw builtin acpx over an incompatible PATH acpx", async () => {
+  const calls: Array<{ command: string; args: string[] }> = [];
+  const result = await ensureAcpxCli({
+    pluginRoot: ROOT_PREFIX,
+    runtimeEntrypoint: OPENCLAW_RUNTIME_ENTRYPOINT,
+    runner: async ({ command, args }) => {
+      calls.push({ command, args });
+      if (command === LOCAL_COMMAND) {
+        return { code: 1, stdout: "", stderr: "not found" };
+      }
+      if (command === BUILTIN_COMMAND) {
+        return { code: 0, stdout: `${ACPX_EXPECTED_VERSION}\n`, stderr: "" };
+      }
+      if (command === "acpx") {
+        return { code: 0, stdout: "0.1.15\n", stderr: "" };
+      }
+      return { code: 1, stdout: "", stderr: "unexpected command" };
+    },
+  });
+
+  assert.equal(result.source, "builtin");
+  assert.equal(result.version, ACPX_EXPECTED_VERSION);
+  assert.equal(result.command, BUILTIN_COMMAND);
+  assert.equal(calls.some((call) => call.command === "npm"), false);
+});
+
+test("ensureAcpxCli installs a plugin-local acpx when none is available", async () => {
+  const calls: Array<{ command: string; args: string[] }> = [];
+  let localCheckCount = 0;
+
+  const result = await ensureAcpxCli({
+    pluginRoot: ROOT_PREFIX,
+    runner: async ({ command, args }) => {
+      calls.push({ command, args });
+      if (command === LOCAL_COMMAND) {
+        localCheckCount += 1;
+        if (localCheckCount === 1) {
+          return { code: 1, stdout: "", stderr: "not found" };
+        }
+        return { code: 0, stdout: `${ACPX_EXPECTED_VERSION}\n`, stderr: "" };
+      }
+      if (command === "acpx") {
+        return { code: 1, stdout: "", stderr: "not found" };
+      }
+      if (command === "npm") {
+        return { code: 0, stdout: "installed\n", stderr: "" };
+      }
+      return { code: 1, stdout: "", stderr: "unexpected command" };
+    },
+  });
+
+  assert.equal(result.source, "local");
+  assert.equal(result.version, ACPX_EXPECTED_VERSION);
+  assert.equal(
+    calls.some((call) => call.command === "npm" && call.args.includes(`${ACPX_PACKAGE_NAME}@${ACPX_EXPECTED_VERSION}`)),
+    true,
+  );
+});

package/test/assistant-journal.test.ts

@@ -0,0 +1,136 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { PlanningJournalStore } from "../src/planning/journal.ts";
+import { getRepoStatePaths } from "../src/utils/paths.ts";
+import { createServiceHarness } from "./helpers/harness.ts";
+
+function createPromptContext(channelId: string) {
+  return {
+    trigger: "user",
+    channel: "discord",
+    channelId,
+    accountId: "default",
+    conversationId: "main",
+    sessionKey: `agent:main:discord:channel:${channelId}`,
+  };
+}
+
+test("assistant planning suggestions are appended to the journal for attached discussion turns", async () => {
+  const harness = await createServiceHarness("clawspec-assistant-journal-");
+  const { service, stateStore, repoPath } = harness;
+  const channelKey = "discord:assistant-journal:default:main";
+  const promptContext = createPromptContext("assistant-journal");
+  const userPrompt = "Add JWT auth, refresh tokens, and forgot-password support.";
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.recordPlanningMessageFromContext(promptContext, userPrompt);
+  await service.handleBeforePromptBuild(
+    { prompt: userPrompt, messages: [] },
+    promptContext,
+  );
+
+  await service.handleAgentEnd(
+    {
+      success: true,
+      messages: [
+        { role: "user", content: userPrompt },
+        {
+          role: "assistant",
+          content: [
+            {
+              type: "text",
+              text: "We should keep short-lived access tokens, add a refresh endpoint, and split forgot-password into request and confirm steps.",
+            },
+          ],
+        },
+      ],
+    },
+    promptContext,
+  );
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  const entries = await journalStore.list("demo-change");
+  const project = await stateStore.getActiveProject(channelKey);
+
+  assert.equal(entries.length, 2);
+  assert.equal(entries[0]?.role, "user");
+  assert.equal(entries[1]?.role, "assistant");
+  assert.match(entries[1]?.text ?? "", /refresh endpoint/i);
+  assert.equal(project?.planningJournal?.dirty, true);
+  assert.equal(project?.planningJournal?.entryCount, 2);
+});
+
+test("passive assistant control replies are not appended to the planning journal", async () => {
+  const harness = await createServiceHarness("clawspec-passive-assistant-journal-");
+  const { service, repoPath } = harness;
+  const channelKey = "discord:passive-assistant-journal:default:main";
+  const promptContext = createPromptContext("passive-assistant-journal");
+  const userPrompt = "Add a help endpoint for the API catalog.";
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.recordPlanningMessageFromContext(promptContext, userPrompt);
+  await service.handleBeforePromptBuild(
+    { prompt: userPrompt, messages: [] },
+    promptContext,
+  );
+
+  await service.handleAgentEnd(
+    {
+      success: true,
+      messages: [
+        { role: "user", content: userPrompt },
+        {
+          role: "assistant",
+          content: "Continue describing requirements if needed.\nNext step: run `cs-plan`.",
+        },
+      ],
+    },
+    promptContext,
+  );
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  const entries = await journalStore.list("demo-change");
+
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0]?.role, "user");
+});
+
+test("assistant discussion replies are not journaled after the chat is detached", async () => {
+  const harness = await createServiceHarness("clawspec-detached-assistant-journal-");
+  const { service, repoPath } = harness;
+  const channelKey = "discord:detached-assistant-journal:default:main";
+  const promptContext = createPromptContext("detached-assistant-journal");
+  const userPrompt = "Add a city weather endpoint.";
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+  await service.handleBeforePromptBuild(
+    { prompt: userPrompt, messages: [] },
+    promptContext,
+  );
+  await service.detachProject(channelKey);
+
+  await service.handleAgentEnd(
+    {
+      success: true,
+      messages: [
+        { role: "user", content: userPrompt },
+        { role: "assistant", content: "We can resolve the city name first, then fetch weather details." },
+      ],
+    },
+    promptContext,
+  );
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  const entries = await journalStore.list("demo-change");
+
+  assert.equal(entries.length, 0);
+});

package/test/command-surface.test.ts

@@ -0,0 +1,23 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildHelpText } from "../src/orchestrator/helpers.ts";
+
+test("help text only advertises the clawspec command surface", () => {
+  const help = buildHelpText();
+
+  assert.match(help, /\/clawspec workspace/);
+  assert.match(help, /\/clawspec proposal <change-name> \[description\]/);
+  assert.match(help, /\/clawspec continue/);
+  assert.match(help, /\/clawspec detach/);
+  assert.match(help, /cs-detach/);
+  assert.match(help, /legacy aliases/);
+  assert.match(help, /cs-plan/);
+  assert.match(help, /cs-work/);
+
+  assert.doesNotMatch(help, /`\/project\b/);
+  assert.doesNotMatch(help, /\/clawspec apply\b/);
+  assert.doesNotMatch(help, /cs-proposal\b/);
+  assert.doesNotMatch(help, /cs-propose\b/);
+  assert.doesNotMatch(help, /cs-pop\b/);
+  assert.doesNotMatch(help, /cs-push\b/);
+});