clawspec 1.0.19 → 1.0.21

package/README.md

@@ -1,5 +1,11 @@
 # ClawSpec
 
+<p align="center">
+  <a href="https://linux.do" target="_blank">
+    <img src="https://img.shields.io/badge/LINUX-DO-FFB003?style=for-the-badge&logo=linux&logoColor=white" alt="LINUX DO" />
+  </a>
+</p>
+
 [Chinese (Simplified)](./README.zh-CN.md)
 
 ClawSpec is an OpenClaw plugin that embeds an OpenSpec workflow directly into chat. It splits project control and execution on purpose:

package/README.zh-CN.md

@@ -1,5 +1,11 @@
 # ClawSpec
 
+<p align="center">
+  <a href="https://linux.do" target="_blank">
+    <img src="https://img.shields.io/badge/LINUX-DO-FFB003?style=for-the-badge&logo=linux&logoColor=white" alt="LINUX DO" />
+  </a>
+</p>
+
 [English](./README.md)
 
 ClawSpec 是一个把 OpenSpec 工作流嵌入 OpenClaw 聊天窗口的插件。它有意把“项目控制”和“执行触发”分成两层：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -23,7 +23,6 @@
     "index.ts",
     "src",
     "skills",
-    "test",
     "README.md",
     "README.zh-CN.md",
     "openclaw.plugin.json",

package/src/bootstrap/state.ts

@@ -0,0 +1,128 @@
+export type BootstrapDependency = "openspec" | "acpx" | "service";
+export type BootstrapPhase = "initializing" | "checking" | "installing" | "starting" | "ready";
+export type BootstrapStatus = "idle" | "running" | "ready" | "failed";
+
+export type BootstrapSnapshot = {
+  status: BootstrapStatus;
+  attempt: number;
+  updatedAt: string;
+  dependency?: BootstrapDependency;
+  phase?: BootstrapPhase;
+  detail?: string;
+  error?: string;
+};
+
+export type BootstrapProgress = {
+  dependency?: BootstrapDependency;
+  phase: BootstrapPhase;
+  detail: string;
+};
+
+export class BootstrapCoordinator {
+  private readonly runner: (report: (progress: BootstrapProgress) => void | Promise<void>) => Promise<void>;
+  private readonly onFailure?: (error: unknown) => void;
+  private snapshot: BootstrapSnapshot = {
+    status: "idle",
+    attempt: 0,
+    updatedAt: new Date(0).toISOString(),
+  };
+
+  private inFlight?: Promise<void>;
+
+  constructor(
+    runner: (report: (progress: BootstrapProgress) => void | Promise<void>) => Promise<void>,
+    onFailure?: (error: unknown) => void,
+  ) {
+    this.runner = runner;
+    this.onFailure = onFailure;
+  }
+
+  getSnapshot(): BootstrapSnapshot {
+    return { ...this.snapshot };
+  }
+
+  async start(): Promise<void> {
+    if (this.snapshot.status === "ready") {
+      return;
+    }
+    if (this.inFlight) {
+      return await this.inFlight;
+    }
+
+    const attempt = this.snapshot.attempt + 1;
+    this.snapshot = {
+      status: "running",
+      attempt,
+      updatedAt: new Date().toISOString(),
+      phase: "initializing",
+      detail: "Initializing ClawSpec bootstrap.",
+    };
+
+    const report = async (progress: BootstrapProgress) => {
+      this.snapshot = {
+        status: "running",
+        attempt,
+        updatedAt: new Date().toISOString(),
+        dependency: progress.dependency,
+        phase: progress.phase,
+        detail: progress.detail,
+      };
+    };
+
+    this.inFlight = (async () => {
+      try {
+        await this.runner(report);
+        this.snapshot = {
+          status: "ready",
+          attempt,
+          updatedAt: new Date().toISOString(),
+          phase: "ready",
+          detail: "ClawSpec dependencies are ready.",
+        };
+      } catch (error) {
+        this.snapshot = {
+          status: "failed",
+          attempt,
+          updatedAt: new Date().toISOString(),
+          dependency: this.snapshot.dependency,
+          phase: this.snapshot.phase,
+          detail: this.snapshot.detail,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        this.onFailure?.(error);
+      } finally {
+        this.inFlight = undefined;
+      }
+    })();
+
+    return await this.inFlight;
+  }
+
+  startInBackground(): void {
+    void this.start();
+  }
+
+  reset(): void {
+    this.inFlight = undefined;
+    this.snapshot = {
+      status: "idle",
+      attempt: 0,
+      updatedAt: new Date().toISOString(),
+    };
+  }
+}
+
+export function buildBootstrapPendingMessage(snapshot: BootstrapSnapshot): string {
+  const detail = snapshot.detail?.trim() || "ClawSpec is preparing required dependencies.";
+  return `${detail} Try again in a moment.`;
+}
+
+export function buildBootstrapFailureMessage(snapshot: BootstrapSnapshot): string {
+  const detail = snapshot.detail?.trim() || "ClawSpec dependency bootstrap failed.";
+  const error = snapshot.error?.trim();
+  return [
+    `${detail} Bootstrap failed.`,
+    error ? `Reason: ${error}` : undefined,
+    "Retrying dependency bootstrap in the background now. Try again in a moment.",
+  ].filter(Boolean).join("\n");
+}

package/src/dependencies/acpx.ts

@@ -25,6 +25,7 @@ export type EnsureAcpxCliOptions = {
   runner?: CommandRunner;
   expectedVersion?: string;
   runtimeEntrypoint?: string;
+  onInstallStart?: (info: { packageName: string; reason: string; expectedVersion: string }) => void | Promise<void>;
 };
 
 export type EnsureAcpxCliResult = {
@@ -104,6 +105,11 @@ export async function ensureAcpxCli(
   options.logger?.warn?.(
     `[clawspec] acpx CLI not ready (${globalCheck.message}); installing plugin-local ${ACPX_PACKAGE_NAME}@${expectedVersion}`,
   );
+  await options.onInstallStart?.({
+    packageName: ACPX_PACKAGE_NAME,
+    reason: globalCheck.message,
+    expectedVersion,
+  });
 
   const install = await runner({
     command: "npm",

package/src/dependencies/openspec.ts

@@ -22,6 +22,7 @@ export type EnsureOpenSpecCliOptions = {
   logger?: PluginLogger;
   env?: NodeJS.ProcessEnv;
   runner?: CommandRunner;
+  onInstallStart?: (info: { packageName: string; reason: string }) => void | Promise<void>;
 };
 
 export type EnsureOpenSpecCliResult = {
@@ -72,6 +73,10 @@ export async function ensureOpenSpecCli(
   options.logger?.warn?.(
     `[clawspec] openspec CLI not ready (${globalCheck.message}); installing plugin-local ${OPENSPEC_PACKAGE_NAME}`,
   );
+  await options.onInstallStart?.({
+    packageName: OPENSPEC_PACKAGE_NAME,
+    reason: globalCheck.message,
+  });
 
   const install = await runner({
     command: "npm",

package/src/index.ts

@@ -19,6 +19,11 @@ import { WatcherManager } from "./watchers/manager.ts";
 import { ensureOpenSpecCli } from "./dependencies/openspec.ts";
 import { ensureAcpxCli } from "./dependencies/acpx.ts";
 import { getConfiguredDefaultWorkerAgent } from "./acp/openclaw-config.ts";
+import {
+  BootstrapCoordinator,
+  buildBootstrapFailureMessage,
+  buildBootstrapPendingMessage,
+} from "./bootstrap/state.ts";
 
 const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const LOCAL_BIN_DIR = path.join(PLUGIN_ROOT, "node_modules", ".bin");
@@ -51,6 +56,106 @@ const plugin = {
     });
     let watcherManager: WatcherManager | undefined;
     let service: ClawSpecService | undefined;
+    const bootstrap = new BootstrapCoordinator(
+      async (report) => {
+        let nextWatcherManager: WatcherManager | undefined;
+        try {
+          service = undefined;
+          watcherManager = undefined;
+
+          await report({
+            phase: "initializing",
+            detail: "ClawSpec is initializing local state.",
+          });
+          await ensureDir(pluginStateRoot);
+          await ensureDir(config.defaultWorkspace);
+          await initStores();
+
+          await report({
+            dependency: "openspec",
+            phase: "checking",
+            detail: "ClawSpec is checking the OpenSpec CLI.",
+          });
+          await ensureOpenSpecCli({
+            pluginRoot: PLUGIN_ROOT,
+            logger: api.logger,
+            onInstallStart: async ({ packageName, reason }) => {
+              await report({
+                dependency: "openspec",
+                phase: "installing",
+                detail: `ClawSpec is installing ${packageName} because OpenSpec is unavailable (${reason}).`,
+              });
+            },
+          });
+
+          await report({
+            dependency: "acpx",
+            phase: "checking",
+            detail: "ClawSpec is checking the ACPX CLI.",
+          });
+          const acpx = await ensureAcpxCli({
+            pluginRoot: PLUGIN_ROOT,
+            logger: api.logger,
+            onInstallStart: async ({ packageName, reason, expectedVersion }) => {
+              await report({
+                dependency: "acpx",
+                phase: "installing",
+                detail: `ClawSpec is installing ${packageName}@${expectedVersion} because no compatible ACPX CLI is available (${reason}).`,
+              });
+            },
+          });
+
+          await report({
+            dependency: "service",
+            phase: "starting",
+            detail: "ClawSpec dependencies are ready. Starting services.",
+          });
+          const configuredDefaultWorkerAgent = getConfiguredDefaultWorkerAgent(api.config) ?? "codex";
+          const acpClient = new AcpWorkerClient({
+            agentId: configuredDefaultWorkerAgent,
+            logger: api.logger,
+            command: acpx.command,
+            env: acpx.env,
+          });
+          nextWatcherManager = new WatcherManager({
+            stateStore,
+            openSpec,
+            archiveDirName: config.archiveDirName,
+            logger: api.logger,
+            notifier,
+            acpClient,
+            pollIntervalMs: config.watcherPollIntervalMs,
+          });
+          const nextService = new ClawSpecService({
+            api,
+            config: api.config,
+            logger: api.logger,
+            stateStore,
+            memoryStore,
+            openSpec,
+            archiveDirName: config.archiveDirName,
+            allowedChannels: config.allowedChannels,
+            defaultWorkspace: config.defaultWorkspace,
+            defaultWorkerAgentId: undefined,
+            workspaceStore,
+            watcherManager: nextWatcherManager,
+          });
+          await nextWatcherManager.start();
+          watcherManager = nextWatcherManager;
+          service = nextService;
+        } catch (error) {
+          service = undefined;
+          await nextWatcherManager?.stop();
+          watcherManager = undefined;
+          throw error;
+        }
+      },
+      (error) => {
+        api.logger.error?.(
+          `[clawspec] bootstrap failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      },
+    );
 
     const initStores = () => Promise.all([
       stateStore.initialize(),
@@ -61,51 +166,13 @@ const plugin = {
     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 configuredDefaultWorkerAgent = getConfiguredDefaultWorkerAgent(api.config) ?? "codex";
-        const acpClient = new AcpWorkerClient({
-          agentId: configuredDefaultWorkerAgent,
-          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: undefined,
-          workspaceStore,
-          watcherManager,
-        });
-        await watcherManager.start();
+        await bootstrap.start();
       },
       async stop() {
         await watcherManager?.stop();
+        watcherManager = undefined;
+        service = undefined;
+        bootstrap.reset();
       },
     });
 
@@ -137,9 +204,24 @@ const plugin = {
       handler: async (ctx) => {
         await initStores();
         if (!service) {
+          const snapshot = bootstrap.getSnapshot();
+          if (snapshot.status === "failed") {
+            bootstrap.startInBackground();
+            return {
+              ok: false,
+              text: buildBootstrapFailureMessage(snapshot),
+            };
+          }
+          if (snapshot.status === "idle") {
+            bootstrap.startInBackground();
+            return {
+              ok: false,
+              text: buildBootstrapPendingMessage(bootstrap.getSnapshot()),
+            };
+          }
           return {
             ok: false,
-            text: "ClawSpec is still bootstrapping dependencies. Try again in a moment.",
+            text: buildBootstrapPendingMessage(snapshot),
           };
         }
         const subcommand = parseSubcommand(ctx.args);

package/src/watchers/manager.ts

@@ -2795,7 +2795,7 @@ function parseWorkerProgressEvent(line: string): WorkerProgressEvent | undefined
 
 function formatWorkerProgressMessage(project: ProjectState, event: WorkerProgressEvent): string | undefined {
   const rawMessage = typeof event.message === "string" ? event.message : "";
-  const message = shortenActivityText(rawMessage, 120);
+  const message = shortenActivityText(compactWorkerProgressDisplayPaths(project, rawMessage), 120);
   if (!message) {
     return undefined;
   }
@@ -2916,6 +2916,74 @@ function compactProjectLabel(project: ProjectState): string {
   return `${projectName}-${changeName}`;
 }
 
+function compactWorkerProgressDisplayPaths(project: ProjectState, text: string): string {
+  try {
+    const compactRoot = compactWorkerProgressRoot(project);
+    if (!compactRoot) {
+      return text;
+    }
+
+    let compacted = text;
+    if (project.changeDir) {
+      compacted = replaceDisplayPathPrefix(compacted, project.changeDir, `${compactRoot}:`);
+    }
+    if (project.repoPath) {
+      compacted = replaceDisplayPathPrefix(compacted, project.repoPath, `${compactRoot}:`);
+    }
+    compacted = normalizeCompactedDisplayPaths(compacted, compactRoot);
+    return compacted.length < text.length ? compacted : text;
+  } catch {
+    return text;
+  }
+}
+
+function compactWorkerProgressRoot(project: ProjectState): string | undefined {
+  const changeName = project.changeName?.trim();
+  if (!changeName) {
+    return undefined;
+  }
+  const projectName = project.projectName?.trim()
+    || (project.repoPath ? path.basename(project.repoPath) : undefined)
+    || "project";
+  return `${projectName}@${changeName}`;
+}
+
+function replaceDisplayPathPrefix(text: string, targetPath: string, replacement: string): string {
+  const pattern = buildDisplayPathPrefixPattern(targetPath);
+  if (!pattern) {
+    return text;
+  }
+  return text.replace(pattern, replacement);
+}
+
+function normalizeCompactedDisplayPaths(text: string, compactRoot: string): string {
+  const prefix = escapeRegExp(`${compactRoot}:`);
+  const pattern = new RegExp("(" + prefix + ")([^\\s\"'`,)\\]}]+)", "g");
+  return text.replace(pattern, (_match, prefix: string, suffix: string) => `${prefix}${suffix.replace(/\\/g, "/")}`);
+}
+
+function buildDisplayPathPrefixPattern(targetPath: string): RegExp | undefined {
+  const normalized = normalizeSlashes(targetPath).replace(/\/+$/, "");
+  if (!normalized) {
+    return undefined;
+  }
+
+  const escaped = normalized
+    .split("/")
+    .map((segment) => escapeRegExp(segment))
+    .join("[/\\\\]+");
+  if (!escaped) {
+    return undefined;
+  }
+
+  const flags = /^[A-Za-z]:/.test(normalized) ? "gi" : "g";
+  return new RegExp(`${escaped}(?:[/\\\\]+)?`, flags);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function compactProgressMarker(current?: number, total?: number): string {
   if (!total || total <= 0 || !current || current <= 0) {
     return "";