clawspec 1.0.0

package/src/utils/markdown.ts

@@ -0,0 +1,136 @@
+import type { ExecutionResult, OpenSpecCommandResult, TaskCountSummary } from "../types.ts";
+import { takeLineExcerpt } from "./fs.ts";
+
+export function fence(text: string, language = ""): string {
+  return `\`\`\`${language}\n${text}\n\`\`\``;
+}
+
+export function formatCommandOutputSection(results: OpenSpecCommandResult<unknown>[]): string {
+  if (results.length === 0) {
+    return "";
+  }
+
+  const lines = ["## OpenSpec Commands", ""];
+  for (const result of results) {
+    lines.push(`- \`${result.command}\``);
+    lines.push(`- cwd: \`${result.cwd}\``);
+    lines.push(`- duration: ${result.durationMs}ms`);
+    const parsedSummary = summarizeParsedCommand(result);
+    if (parsedSummary) {
+      lines.push(`- ${parsedSummary}`);
+    }
+    const stdoutExcerpt = shouldShowRawStdout(result)
+      ? takeMeaningfulExcerpt(result.stdout)
+      : "";
+    if (stdoutExcerpt.length > 0) {
+      lines.push(fence(stdoutExcerpt, "text"));
+    }
+    const stderrExcerpt = takeMeaningfulExcerpt(result.stderr);
+    if (stderrExcerpt.length > 0) {
+      lines.push(fence(stderrExcerpt, "text"));
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatExecutionSummary(result: ExecutionResult): string {
+  const lines = [
+    `Status: ${result.status}`,
+    `Summary: ${result.summary}`,
+  ];
+
+  if (result.completedTask) {
+    lines.push(`Completed Task: ${result.completedTask}`);
+  }
+  if (result.currentArtifact) {
+    lines.push(`Artifact: ${result.currentArtifact}`);
+  }
+  if (result.changedFiles.length > 0) {
+    lines.push("Files Changed:");
+    for (const changedFile of result.changedFiles) {
+      lines.push(`- ${changedFile}`);
+    }
+  }
+  if (result.notes.length > 0) {
+    lines.push("Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  if (typeof result.remainingTasks === "number") {
+    lines.push(`Remaining Tasks: ${result.remainingTasks}`);
+  }
+  if (result.blocker) {
+    lines.push(`Blocker: ${result.blocker}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatTaskCounts(counts: TaskCountSummary | undefined): string {
+  if (!counts) {
+    return "Task counts: unavailable";
+  }
+  return `Task counts: ${counts.complete}/${counts.total} complete, ${counts.remaining} remaining`;
+}
+
+export function heading(title: string): string {
+  return `## ${title}`;
+}
+
+function shouldShowRawStdout(result: OpenSpecCommandResult<unknown>): boolean {
+  return !(result.command.includes("--json") && result.parsed !== undefined);
+}
+
+function takeMeaningfulExcerpt(text: string): string {
+  const excerpt = takeLineExcerpt(text);
+  if (excerpt.length === 0) {
+    return "";
+  }
+
+  const lines = excerpt
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0 && !/^loading\b/i.test(line));
+
+  return lines.join("\n");
+}
+
+function summarizeParsedCommand(result: OpenSpecCommandResult<unknown>): string | undefined {
+  const parsed = result.parsed;
+  if (!parsed || typeof parsed !== "object") {
+    return undefined;
+  }
+
+  const value = parsed as Record<string, unknown>;
+  if (typeof value.schemaName === "string" && Array.isArray(value.artifacts)) {
+    const doneCount = value.artifacts.filter((artifact) =>
+      artifact && typeof artifact === "object" && (artifact as Record<string, unknown>).status === "done"
+    ).length;
+    return `status summary: schema \`${value.schemaName}\`, ${doneCount}/${value.artifacts.length} artifacts done`;
+  }
+
+  if (
+    typeof value.artifactId === "string" &&
+    typeof value.outputPath === "string" &&
+    typeof value.schemaName === "string"
+  ) {
+    return `artifact summary: \`${value.artifactId}\` -> \`${value.outputPath}\` (${value.schemaName})`;
+  }
+
+  if (
+    typeof value.state === "string" &&
+    value.progress &&
+    typeof value.progress === "object" &&
+    typeof (value.progress as Record<string, unknown>).complete === "number" &&
+    typeof (value.progress as Record<string, unknown>).total === "number"
+  ) {
+    const progress = value.progress as Record<string, unknown>;
+    return `apply summary: ${progress.complete}/${progress.total} tasks complete, state \`${value.state}\``;
+  }
+
+  if (typeof value.valid === "boolean") {
+    return `validation summary: ${value.valid ? "valid" : "invalid"}`;
+  }
+
+  return result.command.includes("--json") ? "JSON response parsed successfully" : undefined;
+}

package/src/utils/messages.ts

@@ -0,0 +1,5 @@
+export const BLOCKING_EXECUTION_MSG =
+  "Background execution is armed or running. Use `/clawspec pause` or `/clawspec cancel` first.";
+
+export const SELECT_PROJECT_FIRST_MSG =
+  "Select a project first with `/clawspec use <project-name>`.";

package/src/utils/paths.ts

@@ -0,0 +1,127 @@
+import os from "node:os";
+import path from "node:path";
+
+export type RepoStatePaths = {
+  root: string;
+  stateFile: string;
+  executionControlFile: string;
+  executionResultFile: string;
+  workerProgressFile: string;
+  progressFile: string;
+  changedFilesFile: string;
+  decisionLogFile: string;
+  latestSummaryFile: string;
+  planningJournalFile: string;
+  planningJournalSnapshotFile: string;
+  rollbackManifestFile: string;
+  snapshotsRoot: string;
+  archivesRoot: string;
+};
+
+export function getPluginStateRoot(stateDir: string): string {
+  return path.join(stateDir, "clawspec");
+}
+
+export function getDefaultWorkspacePath(): string {
+  return path.join(os.homedir(), "clawspec", "workspace");
+}
+
+export function expandHomeDir(input: string): string {
+  const trimmed = input.trim();
+  if (trimmed === "~") {
+    return os.homedir();
+  }
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  return trimmed;
+}
+
+export function resolveUserPath(input: string, baseDir = process.cwd()): string {
+  const expanded = expandHomeDir(input);
+  return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(baseDir, expanded);
+}
+
+export function getProjectMemoryFilePath(stateDir: string): string {
+  return path.join(getPluginStateRoot(stateDir), "project-memory.json");
+}
+
+export function getWorkspaceStateFilePath(stateDir: string): string {
+  return path.join(getPluginStateRoot(stateDir), "workspace-state.json");
+}
+
+export function getActiveProjectMapPath(stateDir: string): string {
+  return path.join(getPluginStateRoot(stateDir), "active-projects.json");
+}
+
+export function getGlobalProjectStatePath(stateDir: string, projectId: string): string {
+  return path.join(getPluginStateRoot(stateDir), "projects", `${projectId}.json`);
+}
+
+export function getRepoStatePaths(repoPath: string, archiveDirName: string): RepoStatePaths {
+  const root = path.join(repoPath, ".openclaw", "clawspec");
+  return {
+    root,
+    stateFile: path.join(root, "state.json"),
+    executionControlFile: path.join(root, "execution-control.json"),
+    executionResultFile: path.join(root, "execution-result.json"),
+    workerProgressFile: path.join(root, "worker-progress.jsonl"),
+    progressFile: path.join(root, "progress.md"),
+    changedFilesFile: path.join(root, "changed-files.md"),
+    decisionLogFile: path.join(root, "decision-log.md"),
+    latestSummaryFile: path.join(root, "latest-summary.md"),
+    planningJournalFile: path.join(root, "planning-journal.jsonl"),
+    planningJournalSnapshotFile: path.join(root, "planning-journal.snapshot.json"),
+    rollbackManifestFile: path.join(root, "rollback-manifest.json"),
+    snapshotsRoot: path.join(root, "snapshots"),
+    archivesRoot: path.join(root, archiveDirName),
+  };
+}
+
+export function getChangeDir(repoPath: string, changeName: string): string {
+  return path.join(repoPath, "openspec", "changes", changeName);
+}
+
+export function getTasksPath(repoPath: string, changeName: string): string {
+  return path.join(getChangeDir(repoPath, changeName), "tasks.md");
+}
+
+export function getChangeSnapshotRoot(repoPath: string, archiveDirName: string, changeName: string): string {
+  return path.join(getRepoStatePaths(repoPath, archiveDirName).snapshotsRoot, changeName);
+}
+
+export function getChangeBaselineRoot(repoPath: string, archiveDirName: string, changeName: string): string {
+  return path.join(getChangeSnapshotRoot(repoPath, archiveDirName, changeName), "baseline");
+}
+
+export function resolveProjectScopedPath(
+  project: { repoPath?: string; changeDir?: string },
+  targetPath: string,
+): string {
+  if (!targetPath || path.isAbsolute(targetPath)) {
+    return targetPath;
+  }
+
+  const normalized = targetPath.replace(/^[.][\\/]/, "");
+  if (/^(openspec|\.openclaw)([\\/]|$)/.test(normalized)) {
+    return project.repoPath ? path.join(project.repoPath, normalized) : normalized;
+  }
+
+  if (project.changeDir) {
+    return path.join(project.changeDir, normalized);
+  }
+
+  return project.repoPath ? path.join(project.repoPath, normalized) : normalized;
+}
+
+export function sameNormalizedPath(left: string | undefined, right: string | undefined): boolean {
+  if (!left || !right) {
+    return false;
+  }
+  const normalizedLeft = path.normalize(left);
+  const normalizedRight = path.normalize(right);
+  if (process.platform === "win32") {
+    return normalizedLeft.toLowerCase() === normalizedRight.toLowerCase();
+  }
+  return normalizedLeft === normalizedRight;
+}

package/src/utils/shell-command.ts

@@ -0,0 +1,227 @@
+import { spawn, type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
+import path from "node:path";
+
+export type ShellCommandResult = {
+  code?: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+};
+
+export function spawnShellCommand(params: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+}): ChildProcessWithoutNullStreams {
+  if (shouldUseShell(params.command)) {
+    const commandLabel = buildShellCommand(params.command, params.args);
+    return spawn(commandLabel, {
+      cwd: params.cwd,
+      env: params.env,
+      shell: true,
+      windowsHide: true,
+    });
+  }
+
+  return spawn(params.command, params.args, {
+    cwd: params.cwd,
+    env: params.env,
+    shell: false,
+    detached: true,
+  });
+}
+
+export async function runShellCommand(params: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  input?: string;
+  timeoutMs?: number;
+}): Promise<ShellCommandResult> {
+  return await new Promise((resolve) => {
+    const child = spawnShellCommand(params);
+    let timeoutError: Error | undefined;
+    const timeout = typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0
+      ? setTimeout(() => {
+        timeoutError = new Error(`${params.command} timed out after ${params.timeoutMs}ms`);
+        terminateChildProcess(child);
+      }, params.timeoutMs)
+      : undefined;
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+
+    if (typeof params.input === "string") {
+      child.stdin.end(params.input);
+    } else {
+      child.stdin.end();
+    }
+
+    child.on("error", (error) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      resolve({
+        code: undefined,
+        stdout,
+        stderr,
+        error,
+      });
+    });
+
+    child.on("close", (code, signal) => {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      resolve({
+        code,
+        stdout,
+        stderr,
+        signal,
+        killed: child.killed,
+        error: timeoutError,
+      });
+    });
+  });
+}
+
+export function terminateChildProcess(
+  child: Pick<ChildProcess, "pid" | "killed" | "kill">,
+  options?: { force?: boolean },
+): void {
+  if (child.killed) {
+    return;
+  }
+
+  const force = options?.force === true;
+  const pid = typeof child.pid === "number" && Number.isFinite(child.pid) ? child.pid : undefined;
+  if (process.platform === "win32") {
+    if (pid) {
+      try {
+        const killer = spawn("taskkill", [
+          "/PID",
+          String(pid),
+          "/T",
+          "/F",
+        ], {
+          stdio: "ignore",
+          windowsHide: true,
+          shell: false,
+        });
+        killer.unref();
+      } catch {
+        // Fall back to killing the direct child below.
+      }
+    }
+    try {
+      child.kill();
+    } catch {
+      return;
+    }
+    return;
+  }
+
+  const signal: NodeJS.Signals = force ? "SIGKILL" : "SIGTERM";
+  if (pid && pid > 0) {
+    try {
+      process.kill(-pid, signal);
+    } catch {
+      try {
+        child.kill(signal);
+      } catch {
+        return;
+      }
+    }
+  } else {
+    try {
+      child.kill(signal);
+    } catch {
+      return;
+    }
+  }
+
+  if (!force) {
+    const escalator = setTimeout(() => {
+      terminateChildProcess(child, { force: true });
+    }, 1_000);
+    escalator.unref?.();
+  }
+}
+
+export function isMissingCommandResult(result: ShellCommandResult, command: string): boolean {
+  const combined = `${result.stdout}\n${result.stderr}\n${result.error?.message ?? ""}`.toLowerCase();
+  const normalizedCommand = command.toLowerCase();
+  return combined.includes("not recognized")
+    || combined.includes("not found")
+    || combined.includes(`'${normalizedCommand}' is not recognized`)
+    || combined.includes(`"${normalizedCommand}" is not recognized`);
+}
+
+export function describeCommandFailure(result: ShellCommandResult, label: string): string {
+  if (result.error) {
+    return result.error.message;
+  }
+  const stderr = result.stderr.trim();
+  const stdout = result.stdout.trim();
+  return stderr || stdout || `${label} exited with code ${result.code ?? "unknown"}`;
+}
+
+export 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 shouldUseShell(command: string): boolean {
+  if (process.platform !== "win32") {
+    return false;
+  }
+
+  const extension = path.extname(command).toLowerCase();
+  if (extension === ".exe" || extension === ".com") {
+    return false;
+  }
+
+  return true;
+}
+
+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, `'\\''`)}'`;
+}

package/src/utils/slug.ts

@@ -0,0 +1,50 @@
+export function slugify(input: string): string {
+  const normalized = input
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+  return normalized.slice(0, 80) || `change-${Date.now()}`;
+}
+
+export function deriveProjectTitle(description: string): string {
+  const firstLine = description
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  if (firstLine && firstLine.length <= 80) {
+    return firstLine;
+  }
+  return slugToTitle(slugify(description));
+}
+
+export function deriveChangeName(description: string): string {
+  return slugify(description);
+}
+
+export function slugToTitle(slug: string): string {
+  return slug
+    .split("-")
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export function createProjectId(now = new Date()): string {
+  const stamp = [
+    now.getUTCFullYear(),
+    pad(now.getUTCMonth() + 1),
+    pad(now.getUTCDate()),
+    pad(now.getUTCHours()),
+    pad(now.getUTCMinutes()),
+    pad(now.getUTCSeconds()),
+  ].join("");
+  const random = Math.random().toString(36).slice(2, 8);
+  return `clawspec-${stamp}-${random}`;
+}
+
+function pad(value: number): string {
+  return value.toString().padStart(2, "0");
+}