clawspec 1.0.0

package/src/execution/state.ts

@@ -0,0 +1,125 @@
+import type {
+  ExecutionControlFile,
+  ExecutionResult,
+  ExecutionResultStatus,
+  ExecutionState,
+} from "../types.ts";
+import { pathExists, readJsonFile } from "../utils/fs.ts";
+
+export async function readExecutionControl(filePath: string): Promise<ExecutionControlFile | null> {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+  return normalizeExecutionControl(await readJsonFile<unknown>(filePath, null));
+}
+
+export async function readExecutionResult(filePath: string): Promise<ExecutionResult | null> {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+  return normalizeExecutionResult(await readJsonFile<unknown>(filePath, null));
+}
+
+export function isExecutionTriggerText(text: string): boolean {
+  return /^(continue|go|start|run|proceed|ok|okay)$/i.test(text.trim());
+}
+
+function normalizeExecutionControl(value: unknown): ExecutionControlFile | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const maybe = value as Record<string, unknown>;
+  if (
+    maybe.version !== 1 ||
+    typeof maybe.changeName !== "string" ||
+    !isExecutionState(maybe.state) ||
+    !isExecutionMode(maybe.mode) ||
+    typeof maybe.armedAt !== "string" ||
+    typeof maybe.pauseRequested !== "boolean" ||
+    typeof maybe.cancelRequested !== "boolean"
+  ) {
+    return null;
+  }
+
+  return {
+    version: 1,
+    changeName: maybe.changeName,
+    mode: maybe.mode,
+    state: maybe.state,
+    armedAt: maybe.armedAt,
+    startedAt: typeof maybe.startedAt === "string" ? maybe.startedAt : undefined,
+    sessionKey: typeof maybe.sessionKey === "string" ? maybe.sessionKey : undefined,
+    pauseRequested: maybe.pauseRequested,
+    cancelRequested: maybe.cancelRequested,
+  };
+}
+
+function normalizeExecutionResult(value: unknown): ExecutionResult | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const maybe = value as Record<string, unknown>;
+  if (
+    maybe.version !== 1 ||
+    typeof maybe.changeName !== "string" ||
+    !isExecutionMode(maybe.mode) ||
+    !isExecutionResultStatus(maybe.status) ||
+    typeof maybe.timestamp !== "string" ||
+    typeof maybe.summary !== "string" ||
+    typeof maybe.progressMade !== "boolean"
+  ) {
+    return null;
+  }
+
+  return {
+    version: 1,
+    changeName: maybe.changeName,
+    mode: maybe.mode,
+    status: maybe.status,
+    timestamp: maybe.timestamp,
+    summary: maybe.summary,
+    progressMade: maybe.progressMade,
+    completedTask: typeof maybe.completedTask === "string" ? maybe.completedTask : undefined,
+    currentArtifact: typeof maybe.currentArtifact === "string" ? maybe.currentArtifact : undefined,
+    changedFiles: Array.isArray(maybe.changedFiles)
+      ? maybe.changedFiles.filter((entry): entry is string => typeof entry === "string")
+      : [],
+    notes: Array.isArray(maybe.notes)
+      ? maybe.notes.filter((entry): entry is string => typeof entry === "string")
+      : [],
+    blocker: typeof maybe.blocker === "string" ? maybe.blocker : undefined,
+    taskCounts: normalizeTaskCounts(maybe.taskCounts),
+    remainingTasks: typeof maybe.remainingTasks === "number" ? Math.trunc(maybe.remainingTasks) : undefined,
+  };
+}
+
+function normalizeTaskCounts(value: unknown): ExecutionResult["taskCounts"] {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  const maybe = value as Record<string, unknown>;
+  if (
+    typeof maybe.total !== "number" ||
+    typeof maybe.complete !== "number" ||
+    typeof maybe.remaining !== "number"
+  ) {
+    return undefined;
+  }
+  return {
+    total: Math.trunc(maybe.total),
+    complete: Math.trunc(maybe.complete),
+    remaining: Math.trunc(maybe.remaining),
+  };
+}
+
+function isExecutionState(value: unknown): value is ExecutionState {
+  return value === "armed" || value === "running";
+}
+
+function isExecutionMode(value: unknown): value is ExecutionControlFile["mode"] {
+  return value === "apply" || value === "continue";
+}
+
+function isExecutionResultStatus(value: unknown): value is ExecutionResultStatus {
+  return value === "running" || value === "paused" || value === "blocked" || value === "done" || value === "cancelled";
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { clawspecPluginConfigSchema, parsePluginConfig } from "./config.ts";
+import { ProjectMemoryStore } from "./memory/store.ts";
+import { OpenSpecClient } from "./openspec/cli.ts";
+import { ClawSpecService } from "./orchestrator/service.ts";
+import { ProjectStateStore } from "./state/store.ts";
+import { ensureDir } from "./utils/fs.ts";
+import {
+  getPluginStateRoot,
+  getProjectMemoryFilePath,
+  getWorkspaceStateFilePath,
+} from "./utils/paths.ts";
+import { WorkspaceStore } from "./workspace/store.ts";
+import { AcpWorkerClient } from "./acp/client.ts";
+import { ClawSpecNotifier } from "./watchers/notifier.ts";
+import { WatcherManager } from "./watchers/manager.ts";
+import { ensureOpenSpecCli } from "./dependencies/openspec.ts";
+import { ensureAcpxCli } from "./dependencies/acpx.ts";
+
+const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const LOCAL_BIN_DIR = path.join(PLUGIN_ROOT, "node_modules", ".bin");
+
+const plugin = {
+  id: "clawspec",
+  name: "ClawSpec",
+  description: "OpenSpec-aware project orchestration for OpenClaw channels",
+  configSchema: clawspecPluginConfigSchema,
+
+  register(api: OpenClawPluginApi) {
+    const config = parsePluginConfig(api.pluginConfig);
+    if (!config.enabled) {
+      api.logger.info("[clawspec] Plugin disabled by configuration.");
+      return;
+    }
+
+    const stateDir = api.runtime.state.resolveStateDir();
+    const pluginStateRoot = getPluginStateRoot(stateDir);
+    const stateStore = new ProjectStateStore(stateDir, config.archiveDirName);
+    const memoryStore = new ProjectMemoryStore(getProjectMemoryFilePath(stateDir));
+    const workspaceStore = new WorkspaceStore(getWorkspaceStateFilePath(stateDir), config.defaultWorkspace);
+    const openSpec = new OpenSpecClient({
+      timeoutMs: config.openSpecTimeoutMs,
+      extraPathEntries: [LOCAL_BIN_DIR],
+    });
+    const notifier = new ClawSpecNotifier({
+      api,
+      logger: api.logger,
+    });
+    let watcherManager: WatcherManager | undefined;
+    let service: ClawSpecService | undefined;
+
+    const initStores = () => Promise.all([
+      stateStore.initialize(),
+      memoryStore.initialize(),
+      workspaceStore.initialize(),
+    ]);
+
+    api.registerService({
+      id: "clawspec.bootstrap",
+      async start() {
+        await ensureDir(pluginStateRoot);
+        await ensureDir(config.defaultWorkspace);
+        await initStores();
+        await ensureOpenSpecCli({
+          pluginRoot: PLUGIN_ROOT,
+          logger: api.logger,
+        });
+        const acpx = await ensureAcpxCli({
+          pluginRoot: PLUGIN_ROOT,
+          logger: api.logger,
+        });
+        const acpClient = new AcpWorkerClient({
+          agentId: config.workerAgentId,
+          logger: api.logger,
+          command: acpx.command,
+          env: acpx.env,
+        });
+        watcherManager = new WatcherManager({
+          stateStore,
+          openSpec,
+          archiveDirName: config.archiveDirName,
+          logger: api.logger,
+          notifier,
+          acpClient,
+          pollIntervalMs: config.watcherPollIntervalMs,
+        });
+        service = new ClawSpecService({
+          api,
+          config: api.config,
+          logger: api.logger,
+          stateStore,
+          memoryStore,
+          openSpec,
+          archiveDirName: config.archiveDirName,
+          allowedChannels: config.allowedChannels,
+          defaultWorkspace: config.defaultWorkspace,
+          defaultWorkerAgentId: config.workerAgentId,
+          workspaceStore,
+          watcherManager,
+        });
+        await watcherManager.start();
+      },
+      async stop() {
+        await watcherManager?.stop();
+      },
+    });
+
+    api.registerCli(
+      ({ program, logger }) => {
+        program
+          .command("clawspec-projects")
+          .description("List saved ClawSpec workspaces")
+          .action(async () => {
+            await initStores();
+            const entries = await workspaceStore.list();
+            if (entries.length === 0) {
+              logger.info("No remembered ClawSpec workspaces.");
+              return;
+            }
+            for (const entry of entries) {
+              logger.info(entry.path);
+            }
+          });
+      },
+      { commands: ["clawspec-projects"] },
+    );
+
+    api.registerCommand({
+      name: "clawspec",
+      description: "Manage a ClawSpec project workflow",
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: async (ctx) => {
+        await initStores();
+        if (!service) {
+          return {
+            ok: false,
+            text: "ClawSpec is still bootstrapping dependencies. Try again in a moment.",
+          };
+        }
+        return service.handleProjectCommand(ctx);
+      },
+    });
+
+    api.on("message_received", async (event, ctx) => {
+      await stateStore.initialize();
+      if (!service) {
+        return;
+      }
+      await service.recordPlanningMessageFromContext({
+        channel: ctx.channel ?? ctx.messageProvider ?? ctx.channelId,
+        channelId: ctx.channelId,
+        accountId: ctx.accountId,
+        conversationId: ctx.conversationId,
+        sessionKey: (ctx as { sessionKey?: string }).sessionKey,
+      }, event.content);
+    });
+
+    api.on("before_prompt_build", async (event, ctx) => {
+      await stateStore.initialize();
+      if (!service) {
+        return;
+      }
+      return service.handleBeforePromptBuild(event, ctx);
+    });
+
+    api.on("agent_end", async (event, ctx) => {
+      await stateStore.initialize();
+      if (!service) {
+        return;
+      }
+      await service.handleAgentEnd(event, ctx);
+    });
+  },
+};
+
+export default plugin;

package/src/memory/store.ts

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { ensureDir, pathExists, readJsonFile, writeJsonFile } from "../utils/fs.ts";
+import type { ProjectMemoryFile, RememberedProject } from "../types.ts";
+
+export class DuplicateRememberedProjectError extends Error {
+  readonly existing: RememberedProject;
+
+  constructor(existing: RememberedProject) {
+    super(`Remembered project "${existing.name}" already exists.`);
+    this.existing = existing;
+  }
+}
+
+export class RememberedProjectNotFoundError extends Error {
+  constructor(name: string) {
+    super(`Remembered project "${name}" was not found.`);
+  }
+}
+
+export class RememberedProjectPathInvalidError extends Error {
+  readonly entry: RememberedProject;
+
+  constructor(entry: RememberedProject) {
+    super(`Remembered project "${entry.name}" points to an invalid path: ${entry.repoPath}`);
+    this.entry = entry;
+  }
+}
+
+export class ProjectMemoryStore {
+  readonly filePath: string;
+  private initPromise: Promise<void> | undefined;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  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.writeRegistry({ version: 1, projects: [] });
+    }
+  }
+
+  async list(): Promise<RememberedProject[]> {
+    const registry = await this.readRegistry();
+    return [...registry.projects].sort((left, right) => left.name.localeCompare(right.name));
+  }
+
+  async get(name: string): Promise<RememberedProject | null> {
+    const normalizedName = normalizeName(name);
+    const registry = await this.readRegistry();
+    return registry.projects.find((entry) => entry.normalizedName === normalizedName) ?? null;
+  }
+
+  async remember(
+    name: string,
+    repoPath: string,
+    options?: { overwrite?: boolean },
+  ): Promise<{ entry: RememberedProject; created: boolean; overwritten: boolean }> {
+    const overwrite = options?.overwrite === true;
+    const normalizedName = normalizeName(name);
+    const registry = await this.readRegistry();
+    const now = new Date().toISOString();
+    const existing = registry.projects.find((entry) => entry.normalizedName === normalizedName);
+    if (existing && !overwrite) {
+      throw new DuplicateRememberedProjectError(existing);
+    }
+
+    const entry: RememberedProject = {
+      name: name.trim(),
+      normalizedName,
+      repoPath: path.resolve(repoPath),
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    };
+
+    registry.projects = registry.projects.filter((candidate) => candidate.normalizedName !== normalizedName);
+    registry.projects.push(entry);
+    await this.writeRegistry(registry);
+
+    return {
+      entry,
+      created: !existing,
+      overwritten: Boolean(existing),
+    };
+  }
+
+  async resolveForUse(name: string): Promise<RememberedProject> {
+    const entry = await this.get(name);
+    if (!entry) {
+      throw new RememberedProjectNotFoundError(name);
+    }
+    if (!(await pathExists(entry.repoPath))) {
+      throw new RememberedProjectPathInvalidError(entry);
+    }
+    return entry;
+  }
+
+  private async readRegistry(): Promise<ProjectMemoryFile> {
+    return readJsonFile<ProjectMemoryFile>(this.filePath, {
+      version: 1,
+      projects: [],
+    });
+  }
+
+  private async writeRegistry(value: ProjectMemoryFile): Promise<void> {
+    await writeJsonFile(this.filePath, value);
+  }
+}
+
+function normalizeName(name: string): string {
+  return name.trim().toLowerCase();
+}

package/src/openspec/cli.ts

@@ -0,0 +1,279 @@
+import { spawn } from "node:child_process";
+import { stripAnsi } from "../utils/fs.ts";
+import { prependPathEntries } from "../utils/env-path.ts";
+import type {
+  OpenSpecApplyInstructionsResponse,
+  OpenSpecCommandResult,
+  OpenSpecInstructionsResponse,
+  OpenSpecStatusResponse,
+  OpenSpecValidationResponse,
+} from "../types.ts";
+
+type OpenSpecClientOptions = {
+  timeoutMs: number;
+  command?: string;
+  extraPathEntries?: string[];
+};
+
+export class OpenSpecCommandError extends Error {
+  readonly result: OpenSpecCommandResult<unknown>;
+
+  constructor(message: string, result: OpenSpecCommandResult<unknown>) {
+    super(message);
+    this.result = result;
+  }
+}
+
+export class OpenSpecClient {
+  readonly timeoutMs: number;
+  readonly command: string;
+  readonly extraPathEntries: string[];
+
+  constructor(options: OpenSpecClientOptions) {
+    this.timeoutMs = options.timeoutMs;
+    this.command = options.command ?? "openspec";
+    this.extraPathEntries = options.extraPathEntries ?? [];
+  }
+
+  async init(repoPath: string): Promise<OpenSpecCommandResult> {
+    return this.runText(["init", "--tools", "none", "."], repoPath);
+  }
+
+  async newChange(
+    repoPath: string,
+    changeName: string,
+    description?: string,
+  ): Promise<OpenSpecCommandResult> {
+    const args = ["new", "change", changeName];
+    if (description && description.trim().length > 0) {
+      args.push("--description", description);
+    }
+    return this.runText(args, repoPath);
+  }
+
+  async status(repoPath: string, changeName: string): Promise<OpenSpecCommandResult<OpenSpecStatusResponse>> {
+    return this.runJson<OpenSpecStatusResponse>(
+      ["status", "--change", changeName, "--json"],
+      repoPath,
+    );
+  }
+
+  async instructionsArtifact(
+    repoPath: string,
+    artifactId: string,
+    changeName: string,
+  ): Promise<OpenSpecCommandResult<OpenSpecInstructionsResponse>> {
+    return this.runJson<OpenSpecInstructionsResponse>(
+      ["instructions", artifactId, "--change", changeName, "--json"],
+      repoPath,
+    );
+  }
+
+  async instructionsApply(
+    repoPath: string,
+    changeName: string,
+  ): Promise<OpenSpecCommandResult<OpenSpecApplyInstructionsResponse>> {
+    return this.runJson<OpenSpecApplyInstructionsResponse>(
+      ["instructions", "apply", "--change", changeName, "--json"],
+      repoPath,
+    );
+  }
+
+  async validate(repoPath: string, changeName: string): Promise<OpenSpecCommandResult<OpenSpecValidationResponse>> {
+    return this.runJson<OpenSpecValidationResponse>(
+      ["validate", changeName, "--type", "change", "--json", "--no-interactive"],
+      repoPath,
+    );
+  }
+
+  async archive(repoPath: string, changeName: string): Promise<OpenSpecCommandResult> {
+    return this.runText(["archive", changeName, "-y"], repoPath);
+  }
+
+  private async runText(args: string[], cwd: string): Promise<OpenSpecCommandResult> {
+    return this.execute(args, cwd);
+  }
+
+  private async runJson<T>(args: string[], cwd: string): Promise<OpenSpecCommandResult<T>> {
+    return this.execute<T>(args, cwd);
+  }
+
+  private execute<T>(args: string[], cwd: string): Promise<OpenSpecCommandResult<T>> {
+    const commandLabel = buildShellCommand(this.command, args);
+    const startedAt = Date.now();
+
+    return new Promise((resolve, reject) => {
+      const child = spawn(commandLabel, {
+        cwd,
+        shell: true,
+        windowsHide: true,
+        env: prependPathEntries({
+          ...process.env,
+          FORCE_COLOR: "0",
+          NO_COLOR: "1",
+          CI: "1",
+        }, this.extraPathEntries),
+      });
+
+      let stdout = "";
+      let stderr = "";
+      let completed = false;
+
+      const timer = setTimeout(() => {
+        child.kill();
+      }, this.timeoutMs);
+
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+      });
+
+      child.on("error", (error) => {
+        clearTimeout(timer);
+        completed = true;
+        reject(
+          new OpenSpecCommandError(error.message, {
+            command: commandLabel,
+            cwd,
+            stdout,
+            stderr,
+            durationMs: Date.now() - startedAt,
+          }),
+        );
+      });
+
+      child.on("close", (exitCode) => {
+        if (completed) {
+          return;
+        }
+        clearTimeout(timer);
+        const result: OpenSpecCommandResult<T> = {
+          command: commandLabel,
+          cwd,
+          stdout: stripAnsi(stdout),
+          stderr: stripAnsi(stderr),
+          durationMs: Date.now() - startedAt,
+        };
+
+        if (exitCode !== 0) {
+          reject(new OpenSpecCommandError(`OpenSpec command failed: ${commandLabel}`, result));
+          return;
+        }
+
+        if (args.includes("--json")) {
+          try {
+            result.parsed = extractJsonFromMixedOutput<T>(`${stdout}\n${stderr}`);
+          } catch (error) {
+            reject(
+              new OpenSpecCommandError(
+                error instanceof Error ? error.message : "Failed to parse OpenSpec JSON output.",
+                result,
+              ),
+            );
+            return;
+          }
+        }
+
+        resolve(result);
+      });
+    });
+  }
+}
+
+function buildShellCommand(command: string, args: string[]): string {
+  return [command, ...args].map((arg) => quoteShellArg(arg)).join(" ");
+}
+
+function quoteShellArg(arg: string): string {
+  if (process.platform === "win32") {
+    return quoteWindowsShellArg(arg);
+  }
+  return quotePosixShellArg(arg);
+}
+
+function quoteWindowsShellArg(arg: string): string {
+  if (arg.length === 0) {
+    return "\"\"";
+  }
+  const escaped = arg
+    .replace(/"/g, "\"\"")
+    .replace(/%/g, "%%");
+  if (!/[\s"&|<>^()!]/.test(arg)) {
+    return escaped;
+  }
+  return `"${escaped}"`;
+}
+
+function quotePosixShellArg(arg: string): string {
+  if (arg.length === 0) {
+    return "''";
+  }
+  if (/^[A-Za-z0-9_./:=+-]+$/.test(arg)) {
+    return arg;
+  }
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
+function extractJsonFromMixedOutput<T>(text: string): T {
+  const cleaned = stripAnsi(text);
+  const firstBraceIndex = cleaned.search(/[\[{]/);
+  if (firstBraceIndex === -1) {
+    throw new Error("No JSON object or array found in OpenSpec output.");
+  }
+
+  const jsonSlice = findBalancedJson(cleaned.slice(firstBraceIndex));
+  return JSON.parse(jsonSlice) as T;
+}
+
+function findBalancedJson(text: string): string {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let started = false;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+
+    if (!started) {
+      if (char === "{" || char === "[") {
+        started = true;
+        depth = 1;
+      }
+      continue;
+    }
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === "\"") {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === "\"") {
+      inString = true;
+      continue;
+    }
+
+    if (char === "{" || char === "[") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}" || char === "]") {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(0, index + 1);
+      }
+    }
+  }
+
+  throw new Error("OpenSpec output contained incomplete JSON.");
+}