clawspec 1.0.0

package/test/config.test.ts

@@ -0,0 +1,77 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parsePluginConfig } from "../src/config.ts";
+
+test("parsePluginConfig returns defaults for empty input", () => {
+  const config = parsePluginConfig(undefined);
+  assert.equal(config.enabled, true);
+  assert.equal(config.workerAgentId, "codex");
+  assert.equal(config.archiveDirName, "archives");
+  assert.equal(config.openSpecTimeoutMs, 120_000);
+  assert.equal(config.watcherPollIntervalMs, 4_000);
+  assert.equal(config.maxAutoContinueTurns, 3);
+  assert.equal(config.maxNoProgressTurns, 2);
+  assert.equal(config.workerBackendId, undefined);
+  assert.equal(config.subagentLane, undefined);
+  assert.equal(config.allowedChannels, undefined);
+});
+
+test("parsePluginConfig overrides specific fields", () => {
+  const config = parsePluginConfig({
+    enabled: false,
+    workerAgentId: "my-agent",
+    archiveDirName: "custom-archive",
+  });
+  assert.equal(config.enabled, false);
+  assert.equal(config.workerAgentId, "my-agent");
+  assert.equal(config.archiveDirName, "custom-archive");
+});
+
+test("parsePluginConfig clamps integer values to range", () => {
+  const config = parsePluginConfig({
+    maxAutoContinueTurns: 999,
+    maxNoProgressTurns: 0,
+    openSpecTimeoutMs: 1,
+    watcherPollIntervalMs: 100_000,
+  });
+  assert.equal(config.maxAutoContinueTurns, 50);
+  assert.equal(config.maxNoProgressTurns, 1);
+  assert.equal(config.openSpecTimeoutMs, 5_000);
+  assert.equal(config.watcherPollIntervalMs, 60_000);
+});
+
+test("parsePluginConfig ignores invalid types", () => {
+  const config = parsePluginConfig({
+    enabled: "yes" as any,
+    maxAutoContinueTurns: "five" as any,
+    workerAgentId: 123 as any,
+  });
+  assert.equal(config.enabled, true); // falls back to default
+  assert.equal(config.maxAutoContinueTurns, 3); // falls back to default
+  assert.equal(config.workerAgentId, "codex"); // falls back to default
+});
+
+test("parsePluginConfig filters allowedChannels", () => {
+  const config = parsePluginConfig({
+    allowedChannels: ["chan1", "", "  ", "chan2", 42 as any],
+  });
+  assert.deepEqual(config.allowedChannels, ["chan1", "chan2"]);
+});
+
+test("parsePluginConfig trims string values", () => {
+  const config = parsePluginConfig({
+    workerAgentId: "  my-agent  ",
+    workerBackendId: "  backend  ",
+  });
+  assert.equal(config.workerAgentId, "my-agent");
+  assert.equal(config.workerBackendId, "backend");
+});
+
+test("parsePluginConfig treats empty strings as undefined for optional strings", () => {
+  const config = parsePluginConfig({
+    workerBackendId: "",
+    subagentLane: "   ",
+  });
+  assert.equal(config.workerBackendId, undefined);
+  assert.equal(config.subagentLane, undefined);
+});

package/test/detach-attach.test.ts

@@ -0,0 +1,98 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readJsonFile, readUtf8 } from "../src/utils/fs.ts";
+import { getRepoStatePaths } from "../src/utils/paths.ts";
+import { createServiceHarness } from "./helpers/harness.ts";
+
+test("detach stops prompt injection but keeps controls", async () => {
+  const harness = await createServiceHarness("clawspec-detach-context-");
+  const { service, stateStore, repoPath } = harness;
+  const channelKey = "discord:detached-chat:default:main";
+  const promptContext = {
+    trigger: "user",
+    channel: "discord",
+    channelId: "detached-chat",
+    accountId: "default",
+    conversationId: "main",
+    sessionKey: "agent:main:discord:channel:detached-chat",
+  };
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+
+  const detached = await service.detachProject(channelKey);
+  assert.match(detached.text ?? "", /Context Detached/);
+
+  const detachedPrompt = await service.handleBeforePromptBuild(
+    { prompt: "今天聊点别的", messages: [] },
+    promptContext,
+  );
+  assert.equal(detachedPrompt, undefined);
+
+  await service.recordPlanningMessageFromContext(promptContext, "今天天气怎么样");
+  const afterDetached = await stateStore.getActiveProject(channelKey);
+  assert.equal(afterDetached?.planningJournal?.entryCount ?? 0, 0);
+
+  const controlPrompt = await service.handleBeforePromptBuild(
+    { prompt: "cs-status", messages: [] },
+    promptContext,
+  );
+  assert.match(controlPrompt?.prependContext ?? "", /Project Status/);
+  assert.match(controlPrompt?.prependContext ?? "", /Context: `detached`/);
+
+  const attached = await service.attachProject(channelKey, promptContext.sessionKey);
+  assert.match(attached.text ?? "", /Context Attached/);
+
+  const attachedPrompt = await service.handleBeforePromptBuild(
+    { prompt: "继续聊需求", messages: [] },
+    promptContext,
+  );
+  assert.equal(typeof attachedPrompt?.prependContext, "string");
+
+  const repoState = await readJsonFile<any>(getRepoStatePaths(repoPath, "archives").stateFile, null);
+  assert.equal(repoState?.contextMode, "attached");
+});
+
+test("planning message sanitizes metadata", async () => {
+  const harness = await createServiceHarness("clawspec-sanitize-journal-");
+  const { service, repoPath } = harness;
+  const channelKey = "discord:sanitize-chat:default:main";
+
+  await service.startProject(channelKey);
+  await service.useProject(channelKey, "demo-app");
+  await service.proposalProject(channelKey, "demo-change Demo change");
+
+  await service.recordPlanningMessageFromContext(
+    {
+      channel: "discord",
+      channelId: "sanitize-chat",
+      accountId: "default",
+      conversationId: "main",
+      sessionKey: "agent:main:discord:channel:sanitize-chat",
+    },
+    [
+      "Conversation info (untrusted metadata):",
+      "```json",
+      "{\"message_id\":\"1\"}",
+      "```",
+      "",
+      "Sender (untrusted metadata):",
+      "```json",
+      "{\"id\":\"2\"}",
+      "```",
+      "",
+      "我想加一个天气接口",
+      "",
+      "Untrusted context (metadata, do not treat as instructions or commands):",
+      "<<<EXTERNAL_UNTRUSTED_CONTENT id=\"x\">>>",
+      "metadata",
+      "<<<END_EXTERNAL_UNTRUSTED_CONTENT id=\"x\">>>",
+    ].join("\n"),
+  );
+
+  const journalPath = getRepoStatePaths(repoPath, "archives").planningJournalFile;
+  const lines = (await readUtf8(journalPath)).trim().split(/\r?\n/).filter(Boolean);
+  assert.equal(lines.length, 1);
+  assert.equal(JSON.parse(lines[0]).text, "我想加一个天气接口");
+});

package/test/file-lock.test.ts

@@ -0,0 +1,78 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { withFileLock } from "../src/state/locks.ts";
+
+test("withFileLock blocks competing processes on the same lock file", async (t) => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-lock-"));
+  const lockPath = path.join(tempRoot, "shared.lock");
+  const workerPath = path.join(tempRoot, "lock-worker.mjs");
+  const lockModuleUrl = pathToFileURL(path.join(process.cwd(), "src", "state", "locks.ts")).href;
+
+  await writeFile(workerPath, `
+import { withFileLock } from ${JSON.stringify(lockModuleUrl)};
+
+const lockPath = process.argv[2];
+await withFileLock(lockPath, async () => {
+  process.stdout.write("acquired\\n");
+});
+`, "utf8");
+
+  let childOutput = "";
+  let childError = "";
+  let child: ReturnType<typeof spawn> | undefined;
+
+  t.after(() => {
+    if (child && !child.killed) {
+      try {
+        child.kill();
+      } catch {
+        return;
+      }
+    }
+  });
+
+  await withFileLock(lockPath, async () => {
+    child = spawn(process.execPath, ["--experimental-strip-types", workerPath, lockPath], {
+      cwd: process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      childOutput += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      childError += chunk;
+    });
+
+    await delay(150);
+    assert.equal(childOutput.includes("acquired"), false);
+  });
+
+  await waitFor(() => childOutput.includes("acquired"));
+  const exitCode = await new Promise<number | null>((resolve) => {
+    child?.once("close", (code) => resolve(code));
+  });
+
+  assert.equal(exitCode, 0, childError || undefined);
+});
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitFor(check: () => boolean, timeoutMs = 2_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (check()) {
+      return;
+    }
+    await delay(25);
+  }
+  throw new Error("timed out waiting for lock handoff");
+}

package/test/fs-utils.test.ts

@@ -0,0 +1,22 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp } from "node:fs/promises";
+import { appendUtf8, readUtf8 } from "../src/utils/fs.ts";
+
+test("appendUtf8 preserves concurrent appends", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-fs-append-"));
+  const targetFile = path.join(tempRoot, "journal.log");
+  const writes = Array.from({ length: 64 }, (_, index) => appendUtf8(targetFile, `line-${index}\n`));
+
+  await Promise.all(writes);
+
+  const lines = (await readUtf8(targetFile))
+    .trim()
+    .split(/\r?\n/)
+    .filter(Boolean);
+
+  assert.equal(lines.length, 64);
+  assert.equal(new Set(lines).size, 64);
+});

package/test/helpers/harness.ts

@@ -0,0 +1,241 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, mkdir } from "node:fs/promises";
+import { PlanningJournalStore } from "../../src/planning/journal.ts";
+import { parsePluginConfig } from "../../src/config.ts";
+import { ProjectMemoryStore } from "../../src/memory/store.ts";
+import { ClawSpecService } from "../../src/orchestrator/service.ts";
+import { ProjectStateStore } from "../../src/state/store.ts";
+import { writeUtf8 } from "../../src/utils/fs.ts";
+import { getRepoStatePaths } from "../../src/utils/paths.ts";
+import { WorkspaceStore } from "../../src/workspace/store.ts";
+
+export type FakeWatcherManager = {
+  wakeCalls: string[];
+  interruptCalls: Array<{ channelKey: string; reason: string }>;
+  runtimeStatusCalls: string[];
+  runtimeStatus?: unknown;
+  wake: (channelKey: string) => Promise<void>;
+  interrupt: (channelKey: string, reason: string) => Promise<void>;
+  getWorkerRuntimeStatus: (channelKeyOrProject: string | { channelKey: string }) => Promise<unknown>;
+};
+
+export function createFakeWatcherManager(): FakeWatcherManager {
+  const wakeCalls: string[] = [];
+  const interruptCalls: Array<{ channelKey: string; reason: string }> = [];
+  const runtimeStatusCalls: string[] = [];
+  const manager: FakeWatcherManager = {
+    wakeCalls,
+    interruptCalls,
+    runtimeStatusCalls,
+    runtimeStatus: undefined,
+    wake: async (channelKey: string) => {
+      wakeCalls.push(channelKey);
+    },
+    interrupt: async (channelKey: string, reason: string) => {
+      interruptCalls.push({ channelKey, reason });
+    },
+    getWorkerRuntimeStatus: async (channelKeyOrProject: string | { channelKey: string }) => {
+      const channelKey = typeof channelKeyOrProject === "string"
+        ? channelKeyOrProject
+        : channelKeyOrProject.channelKey;
+      runtimeStatusCalls.push(channelKey);
+      return manager.runtimeStatus;
+    },
+  };
+  return manager;
+}
+
+export function createLogger() {
+  return {
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+    debug: () => undefined,
+  };
+}
+
+export async function waitFor(check: () => Promise<boolean>, timeoutMs = 4_000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await check()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error("Timed out waiting for test condition.");
+}
+
+export async function createServiceHarness(prefix: string): Promise<{
+  service: ClawSpecService;
+  stateStore: ProjectStateStore;
+  memoryStore: ProjectMemoryStore;
+  workspaceStore: WorkspaceStore;
+  watcherManager: FakeWatcherManager;
+  workspacePath: string;
+  repoPath: string;
+  changeDir: string;
+  openSpec: Record<string, any>;
+}> {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), prefix));
+  const workspacePath = path.join(tempRoot, "workspace");
+  const repoPath = path.join(workspacePath, "demo-app");
+  const changeDir = path.join(repoPath, "openspec", "changes", "demo-change");
+  await mkdir(workspacePath, { recursive: true });
+
+  const stateStore = new ProjectStateStore(tempRoot, "archives");
+  const memoryStore = new ProjectMemoryStore(path.join(tempRoot, "memory.json"));
+  const workspaceStore = new WorkspaceStore(path.join(tempRoot, "workspace-state.json"), workspacePath);
+  await stateStore.initialize();
+  await memoryStore.initialize();
+  await workspaceStore.initialize();
+
+  const openSpec = {
+    init: async (cwd: string) => {
+      await writeUtf8(path.join(cwd, "openspec", "config.yaml"), "schema: spec-driven\n");
+      return {
+        command: "openspec init --tools none .",
+        cwd,
+        stdout: "initialized",
+        stderr: "",
+        durationMs: 1,
+      };
+    },
+    newChange: async (cwd: string, changeName: string, description?: string) => {
+      const nextChangeDir = path.join(cwd, "openspec", "changes", changeName);
+      await mkdir(nextChangeDir, { recursive: true });
+      await writeUtf8(path.join(nextChangeDir, ".openspec.yaml"), "schema: spec-driven\n");
+      await writeUtf8(path.join(nextChangeDir, "proposal.md"), `# ${changeName}\n${description ?? ""}\n`);
+      return {
+        command: description
+          ? `openspec new change ${changeName} --description "${description}"`
+          : `openspec new change ${changeName}`,
+        cwd,
+        stdout: "change created",
+        stderr: "",
+        durationMs: 1,
+      };
+    },
+    status: async (cwd: string, changeName: string) => ({
+      command: `openspec status --change ${changeName} --json`,
+      cwd,
+      stdout: "{}",
+      stderr: "",
+      durationMs: 1,
+      parsed: {
+        changeName,
+        schemaName: "spec-driven",
+        isComplete: false,
+        applyRequires: ["tasks"],
+        artifacts: [
+          { id: "proposal", outputPath: path.join(changeDir, "proposal.md"), status: "done" },
+          { id: "tasks", outputPath: path.join(changeDir, "tasks.md"), status: "ready" },
+        ],
+      },
+    }),
+    instructionsApply: async (cwd: string, changeName: string) => ({
+      command: `openspec instructions apply --change ${changeName} --json`,
+      cwd,
+      stdout: "{}",
+      stderr: "",
+      durationMs: 1,
+      parsed: {
+        changeName,
+        changeDir,
+        schemaName: "spec-driven",
+        contextFiles: {},
+        progress: { total: 0, complete: 0, remaining: 0 },
+        tasks: [],
+        state: "ready",
+        instruction: "Implement the remaining tasks.",
+      },
+    }),
+  } as Record<string, any>;
+
+  const watcherManager = createFakeWatcherManager();
+  const service = new ClawSpecService({
+    api: {
+      config: {},
+      logger: createLogger(),
+    } as any,
+    config: {} as any,
+    logger: createLogger(),
+    stateStore,
+    memoryStore,
+    openSpec: openSpec as any,
+    archiveDirName: "archives",
+    defaultWorkspace: workspacePath,
+    defaultWorkerAgentId: "codex",
+    workspaceStore,
+    watcherManager: watcherManager as any,
+  });
+
+  return {
+    service,
+    stateStore,
+    memoryStore,
+    workspaceStore,
+    watcherManager,
+    workspacePath,
+    repoPath,
+    changeDir,
+    openSpec,
+  };
+}
+
+export async function seedPlanningProject(
+  stateStore: ProjectStateStore,
+  channelKey: string,
+  params: {
+    workspacePath: string;
+    repoPath: string;
+    projectName: string;
+    changeName: string;
+    changeDir: string;
+    phase: "proposal" | "planning_sync" | "tasks" | "implementing";
+    status: "ready" | "paused" | "planning" | "running";
+    planningDirty: boolean;
+    execution?: {
+      action: "plan" | "work";
+      state: "armed" | "running";
+      mode: "apply" | "continue";
+    };
+  },
+): Promise<void> {
+  await mkdir(params.changeDir, { recursive: true });
+  const repoStatePaths = getRepoStatePaths(params.repoPath, "archives");
+  const journalStore = new PlanningJournalStore(repoStatePaths.planningJournalFile);
+  await stateStore.createProject(channelKey);
+  await stateStore.updateProject(channelKey, (current) => ({
+    ...current,
+    workspacePath: params.workspacePath,
+    repoPath: params.repoPath,
+    projectName: params.projectName,
+    projectTitle: params.projectName,
+    changeName: params.changeName,
+    changeDir: params.changeDir,
+    status: params.status,
+    phase: params.phase,
+    planningJournal: {
+      dirty: params.planningDirty,
+      entryCount: params.planningDirty ? 1 : 0,
+      lastEntryAt: params.planningDirty ? new Date(Date.now() - 60_000).toISOString() : undefined,
+    },
+    execution: params.execution
+      ? {
+          ...params.execution,
+          workerSlot: "primary",
+          armedAt: new Date().toISOString(),
+        }
+      : current.execution,
+  }));
+
+  if (params.planningDirty) {
+    await journalStore.append({
+      timestamp: new Date(Date.now() - 60_000).toISOString(),
+      changeName: params.changeName,
+      role: "user",
+      text: "refresh planning for the active change",
+    });
+  }
+}

package/test/helpers.test.ts

@@ -0,0 +1,108 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { ProjectState } from "../src/types.ts";
+import {
+  hasBlockingExecution,
+  isFinishedStatus,
+  isProjectContextAttached,
+  requiresPlanningSync,
+  sanitizePlanningMessageText,
+  shouldCapturePlanningMessage,
+  isMeaningfulExecutionSummary,
+  okReply,
+  errorReply,
+  samePath,
+} from "../src/orchestrator/helpers.ts";
+
+function makeProject(overrides: Partial<ProjectState> = {}): ProjectState {
+  return {
+    projectId: "test-id",
+    channelKey: "discord:test:default:main",
+    projectName: "test",
+    status: "ready",
+    phase: "tasks",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...overrides,
+  } as ProjectState;
+}
+
+test("hasBlockingExecution detects armed/running states", () => {
+  assert.equal(hasBlockingExecution(makeProject({ execution: { state: "armed" } as any })), true);
+  assert.equal(hasBlockingExecution(makeProject({ execution: { state: "running" } as any })), true);
+  assert.equal(hasBlockingExecution(makeProject({ status: "running" })), true);
+  assert.equal(hasBlockingExecution(makeProject({ status: "ready" })), false);
+  assert.equal(hasBlockingExecution(makeProject()), false);
+});
+
+test("isFinishedStatus identifies terminal statuses", () => {
+  assert.equal(isFinishedStatus("done"), true);
+  assert.equal(isFinishedStatus("archived"), true);
+  assert.equal(isFinishedStatus("cancelled"), true);
+  assert.equal(isFinishedStatus("ready"), false);
+  assert.equal(isFinishedStatus("running"), false);
+  assert.equal(isFinishedStatus("armed"), false);
+});
+
+test("isProjectContextAttached returns false when detached", () => {
+  assert.equal(isProjectContextAttached(makeProject({ contextMode: "detached" })), false);
+  assert.equal(isProjectContextAttached(makeProject({ contextMode: undefined })), true);
+  assert.equal(isProjectContextAttached(makeProject()), true);
+});
+
+test("requiresPlanningSync detects dirty journal", () => {
+  assert.equal(requiresPlanningSync(makeProject({ changeName: "x", planningJournal: { dirty: true, entryCount: 1 } })), true);
+  assert.equal(requiresPlanningSync(makeProject({ changeName: "x", phase: "proposal" })), true);
+  assert.equal(requiresPlanningSync(makeProject({ changeName: "x", planningJournal: { dirty: false, entryCount: 0 } })), false);
+  assert.equal(requiresPlanningSync(makeProject({ changeName: undefined as any })), false);
+  assert.equal(requiresPlanningSync(makeProject({ changeName: "x", status: "done" })), false);
+});
+
+test("shouldCapturePlanningMessage excludes running/archived/cancelled", () => {
+  assert.equal(shouldCapturePlanningMessage(makeProject({ changeName: "x", status: "ready" })), true);
+  assert.equal(shouldCapturePlanningMessage(makeProject({ changeName: "x", status: "running" })), false);
+  assert.equal(shouldCapturePlanningMessage(makeProject({ changeName: "x", status: "archived" })), false);
+  assert.equal(shouldCapturePlanningMessage(makeProject({ changeName: "x", status: "cancelled" })), false);
+  assert.equal(shouldCapturePlanningMessage(makeProject({ contextMode: "detached", changeName: "x" })), false);
+  assert.equal(shouldCapturePlanningMessage(makeProject({ changeName: undefined as any })), false);
+});
+
+test("sanitizePlanningMessageText strips metadata blocks", () => {
+  const input = `Hello\nConversation info (untrusted metadata):\n\`\`\`json\n{"key":"value"}\n\`\`\`\nWorld`;
+  const result = sanitizePlanningMessageText(input);
+  assert.equal(result, "Hello\nWorld");
+});
+
+test("sanitizePlanningMessageText preserves clean text", () => {
+  assert.equal(sanitizePlanningMessageText("  clean text  "), "clean text");
+});
+
+test("isMeaningfulExecutionSummary filters boilerplate", () => {
+  assert.equal(isMeaningfulExecutionSummary(undefined), false);
+  assert.equal(isMeaningfulExecutionSummary(""), false);
+  assert.equal(isMeaningfulExecutionSummary("No summary yet."), false);
+  assert.equal(isMeaningfulExecutionSummary("Visible execution ended without a structured result."), false);
+  assert.equal(isMeaningfulExecutionSummary("Visible execution started for something"), false);
+  assert.equal(isMeaningfulExecutionSummary("Completed task 1.1"), true);
+  assert.equal(isMeaningfulExecutionSummary("All tasks done."), true);
+});
+
+test("okReply and errorReply produce correct shapes", () => {
+  const ok = okReply("success");
+  assert.equal(ok.text, "success");
+  assert.equal(ok.isError, undefined);
+
+  const err = errorReply("failure");
+  assert.equal(err.text, "failure");
+  assert.equal(err.isError, true);
+});
+
+test("samePath respects platform case sensitivity rules", () => {
+  if (process.platform === "win32") {
+    assert.equal(samePath("C:\\Repo\\Demo", "c:\\repo\\demo"), true);
+    return;
+  }
+
+  assert.equal(samePath("/Repo/Demo", "/repo/demo"), false);
+  assert.equal(samePath("/repo/demo", "/repo/demo"), true);
+});