clawspec 1.0.0

package/src/types.ts

@@ -0,0 +1,301 @@
+export const PROJECT_STATUSES = [
+  "idle",
+  "collecting_path",
+  "collecting_description",
+  "bootstrapping",
+  "planning",
+  "ready",
+  "armed",
+  "running",
+  "paused",
+  "blocked",
+  "done",
+  "archived",
+  "cancelled",
+  "error",
+] as const;
+
+export const PROJECT_PHASES = [
+  "init",
+  "proposal",
+  "specs",
+  "design",
+  "tasks",
+  "planning_sync",
+  "implementing",
+  "validating",
+  "archiving",
+  "cancelling",
+] as const;
+
+export const EXECUTION_STATES = ["armed", "running"] as const;
+export const EXECUTION_RESULT_STATUSES = ["running", "paused", "blocked", "done", "cancelled"] as const;
+export const EXECUTION_MODES = ["apply", "continue"] as const;
+export const EXECUTION_ACTIONS = ["plan", "work"] as const;
+export const EXECUTION_STARTUP_PHASES = ["queued", "starting", "connected", "waiting_for_update", "active"] as const;
+
+export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
+export type ProjectPhase = (typeof PROJECT_PHASES)[number];
+export type ExecutionState = (typeof EXECUTION_STATES)[number];
+export type ExecutionResultStatus = (typeof EXECUTION_RESULT_STATUSES)[number];
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+export type ExecutionAction = (typeof EXECUTION_ACTIONS)[number];
+export type ExecutionStartupPhase = (typeof EXECUTION_STARTUP_PHASES)[number];
+
+export type TaskCountSummary = {
+  total: number;
+  complete: number;
+  remaining: number;
+};
+
+export type RememberedProject = {
+  name: string;
+  normalizedName: string;
+  repoPath: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type ProjectMemoryFile = {
+  version: 1;
+  projects: RememberedProject[];
+};
+
+export type WorkspaceRecord = {
+  path: string;
+  lastUsedAt: string;
+};
+
+export type WorkspaceStateFile = {
+  version: 1;
+  currentWorkspace: string;
+  currentWorkspaceByChannel?: Record<string, string>;
+  workspaces: WorkspaceRecord[];
+};
+
+export type ActiveProjectMap = {
+  version: 1;
+  channels: Record<
+    string,
+    {
+      projectId: string;
+      statePath: string;
+    }
+  >;
+};
+
+export type ProjectExecutionState = {
+  mode: ExecutionMode;
+  action: ExecutionAction;
+  state: ExecutionState;
+  startupPhase?: ExecutionStartupPhase;
+  workerAgentId?: string;
+  workerSlot?: string;
+  armedAt: string;
+  startedAt?: string;
+  connectedAt?: string;
+  firstProgressAt?: string;
+  lastStartupNoticeAt?: string;
+  sessionKey?: string;
+  backendId?: string;
+  triggerPrompt?: string;
+  lastTriggerAt?: string;
+  currentArtifact?: string;
+  currentTaskId?: string;
+  lastHeartbeatAt?: string;
+  progressOffset?: number;
+  restartCount?: number;
+  lastRestartAt?: string;
+  lastFailure?: string;
+};
+
+export type ExecutionControlFile = {
+  version: 1;
+  changeName: string;
+  mode: ExecutionMode;
+  state: ExecutionState;
+  armedAt: string;
+  startedAt?: string;
+  sessionKey?: string;
+  pauseRequested: boolean;
+  cancelRequested: boolean;
+};
+
+export type ExecutionResult = {
+  version: 1;
+  changeName: string;
+  mode: ExecutionMode;
+  status: ExecutionResultStatus;
+  timestamp: string;
+  summary: string;
+  progressMade: boolean;
+  completedTask?: string;
+  currentArtifact?: string;
+  changedFiles: string[];
+  notes: string[];
+  blocker?: string;
+  taskCounts?: TaskCountSummary;
+  remainingTasks?: number;
+};
+
+export type ProjectState = {
+  version: 1;
+  projectId: string;
+  channelKey: string;
+  storagePath: string;
+  status: ProjectStatus;
+  phase: ProjectPhase;
+  createdAt: string;
+  updatedAt: string;
+  workspacePath?: string;
+  repoPath?: string;
+  projectName?: string;
+  rememberedProjectName?: string;
+  projectTitle?: string;
+  workerAgentId?: string;
+  description?: string;
+  changeName?: string;
+  openspecRoot?: string;
+  changeDir?: string;
+  pauseRequested: boolean;
+  cancelRequested?: boolean;
+  blockedReason?: string;
+  currentTask?: string;
+  taskCounts?: TaskCountSummary;
+  latestSummary?: string;
+  lastNotificationKey?: string;
+  execution?: ProjectExecutionState;
+  lastExecutionAt?: string;
+  lastExecution?: ExecutionResult;
+  planningJournal?: PlanningJournalState;
+  rollback?: RollbackState;
+  archivePath?: string;
+  boundSessionKey?: string;
+  contextMode?: "attached" | "detached";
+};
+
+export type PlanningJournalEntry = {
+  timestamp: string;
+  changeName: string;
+  role: "user" | "assistant";
+  text: string;
+};
+
+export type PlanningJournalState = {
+  dirty: boolean;
+  entryCount: number;
+  lastEntryAt?: string;
+  lastSyncedAt?: string;
+};
+
+export type PlanningJournalSnapshot = {
+  version: 1;
+  changeName: string;
+  syncedAt: string;
+  entryCount: number;
+  lastEntryAt?: string;
+  contentHash: string;
+};
+
+export type RollbackTrackedFileKind = "modified" | "created" | "deleted";
+
+export type RollbackTrackedFile = {
+  path: string;
+  kind: RollbackTrackedFileKind;
+};
+
+export type RollbackManifest = {
+  version: 1;
+  changeName: string;
+  baselineRoot: string;
+  createdAt: string;
+  updatedAt: string;
+  files: RollbackTrackedFile[];
+  cancelledAt?: string;
+  archivedAt?: string;
+};
+
+export type RollbackState = {
+  baselineRoot?: string;
+  manifestPath?: string;
+  snapshotReady?: boolean;
+  touchedFileCount?: number;
+  lastUpdatedAt?: string;
+};
+
+export type ParsedTask = {
+  raw: string;
+  lineNumber: number;
+  checked: boolean;
+  taskId: string;
+  description: string;
+};
+
+export type ParsedTaskList = {
+  tasks: ParsedTask[];
+  counts: TaskCountSummary;
+};
+
+export type OpenSpecArtifactRecord = {
+  id: string;
+  outputPath: string;
+  status: string;
+};
+
+export type OpenSpecStatusResponse = {
+  changeName: string;
+  schemaName: string;
+  isComplete: boolean;
+  applyRequires: string[];
+  artifacts: OpenSpecArtifactRecord[];
+};
+
+export type OpenSpecArtifactDependency = {
+  id: string;
+  done: boolean;
+  path: string;
+  description: string;
+};
+
+export type OpenSpecInstructionsResponse = {
+  changeName: string;
+  artifactId: string;
+  schemaName: string;
+  changeDir: string;
+  outputPath: string;
+  description: string;
+  instruction: string;
+  template: string;
+  dependencies: OpenSpecArtifactDependency[];
+  unlocks: string[];
+};
+
+export type OpenSpecApplyInstructionsResponse = {
+  changeName: string;
+  changeDir: string;
+  schemaName: string;
+  contextFiles: Record<string, string>;
+  progress: TaskCountSummary;
+  tasks: Array<{
+    id: string;
+    description: string;
+    done: boolean;
+  }>;
+  state: "ready" | "blocked" | "all_done";
+  instruction: string;
+};
+
+export type OpenSpecValidationResponse = {
+  valid?: boolean;
+  errors?: unknown[];
+  warnings?: unknown[];
+};
+
+export type OpenSpecCommandResult<T = undefined> = {
+  command: string;
+  cwd: string;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  parsed?: T;
+};

package/src/utils/args.ts

@@ -0,0 +1,88 @@
+export function tokenizeArgs(input: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | null = null;
+  let escaping = false;
+
+  for (const char of input) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === "\"") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (quote) {
+    throw new Error("Unterminated quoted argument.");
+  }
+
+  if (escaping) {
+    current += "\\";
+  }
+
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+export function splitSubcommand(rawArgs: string | undefined): {
+  subcommand: string;
+  rest: string;
+} {
+  const trimmed = (rawArgs ?? "").trim();
+  if (trimmed.length === 0) {
+    return { subcommand: "", rest: "" };
+  }
+
+  const firstWhitespace = trimmed.search(/\s/);
+  if (firstWhitespace === -1) {
+    return { subcommand: trimmed.toLowerCase(), rest: "" };
+  }
+
+  return {
+    subcommand: trimmed.slice(0, firstWhitespace).toLowerCase(),
+    rest: trimmed.slice(firstWhitespace + 1).trim(),
+  };
+}
+
+export function removeFlag(tokens: string[], flag: string): {
+  tokens: string[];
+  present: boolean;
+} {
+  const filtered = tokens.filter((token) => token !== flag);
+  return {
+    tokens: filtered,
+    present: filtered.length !== tokens.length,
+  };
+}

package/src/utils/channel-key.ts

@@ -0,0 +1,66 @@
+import type { PluginCommandContext } from "openclaw/plugin-sdk";
+
+export type ParsedChannelKey = {
+  channel: string;
+  channelId: string;
+  accountId: string;
+  conversationId: string;
+};
+
+export function buildChannelKeyFromCommand(ctx: PluginCommandContext): string {
+  const conversationKey = ctx.messageThreadId?.toString() ?? "main";
+  return buildChannelKey({
+    channel: ctx.channel,
+    channelId: ctx.channelId ?? ctx.channel,
+    accountId: ctx.accountId ?? "default",
+    conversationId: conversationKey,
+  });
+}
+
+export function buildLegacyChannelKeyFromCommand(ctx: PluginCommandContext): string {
+  const conversationKey = ctx.messageThreadId?.toString() ?? ctx.to ?? ctx.from ?? "main";
+  return buildChannelKey({
+    channel: ctx.channel,
+    channelId: ctx.channelId ?? ctx.channel,
+    accountId: ctx.accountId ?? "default",
+    conversationId: conversationKey,
+  });
+}
+
+export function buildChannelKeyFromMessage(params: {
+  channel?: string;
+  channelId: string;
+  accountId?: string;
+  conversationId?: string;
+}): string {
+  return buildChannelKey({
+    channel: params.channel ?? params.channelId,
+    channelId: params.channelId,
+    accountId: params.accountId ?? "default",
+    conversationId: params.conversationId ?? "main",
+  });
+}
+
+export function parseChannelKey(channelKey: string): ParsedChannelKey {
+  const [channel = "", channelId = "", accountId = "", ...conversationParts] = channelKey.split(":");
+  return {
+    channel,
+    channelId,
+    accountId,
+    conversationId: conversationParts.join(":"),
+  };
+}
+
+function buildChannelKey(params: {
+  channel: string;
+  channelId: string;
+  accountId: string;
+  conversationId: string;
+}): string {
+  return [
+    params.channel,
+    params.channelId,
+    params.accountId,
+    params.conversationId,
+  ].join(":");
+}

package/src/utils/env-path.ts

@@ -0,0 +1,31 @@
+export function prependPathEntries(
+  env: NodeJS.ProcessEnv | undefined,
+  entries: string[],
+): NodeJS.ProcessEnv {
+  const nextEnv: NodeJS.ProcessEnv = { ...(env ?? process.env) };
+  const cleanEntries = entries
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  if (cleanEntries.length === 0) {
+    return nextEnv;
+  }
+
+  const pathKey = findPathKey(nextEnv);
+  const current = nextEnv[pathKey] ?? "";
+  const parts = current
+    .split(process.platform === "win32" ? ";" : ":")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+
+  const merged = [...cleanEntries, ...parts.filter((part) => !cleanEntries.includes(part))];
+  nextEnv[pathKey] = merged.join(process.platform === "win32" ? ";" : ":");
+  return nextEnv;
+}
+
+function findPathKey(env: NodeJS.ProcessEnv): string {
+  const existing = Object.keys(env).find((key) => key.toLowerCase() === "path");
+  if (existing) {
+    return existing;
+  }
+  return process.platform === "win32" ? "Path" : "PATH";
+}

package/src/utils/fs.ts

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { appendFile, copyFile, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const ATOMIC_WRITE_RETRYABLE_CODES = new Set(["EPERM", "EACCES", "EBUSY", "ENOENT"]);
+const ATOMIC_WRITE_RETRY_DELAYS_MS = [20, 60, 120, 250];
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function directoryExists(targetPath: string): Promise<boolean> {
+  try {
+    return (await stat(targetPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function readUtf8(filePath: string): Promise<string> {
+  return readFile(filePath, "utf8");
+}
+
+export async function tryReadUtf8(filePath: string): Promise<string | undefined> {
+  try {
+    return await readUtf8(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeUtf8(filePath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, content, "utf8");
+  try {
+    await renameWithRetry(tempPath, filePath);
+  } catch (error) {
+    const code = getErrorCode(error);
+    if (!code || !ATOMIC_WRITE_RETRYABLE_CODES.has(code)) {
+      await cleanupTempFile(tempPath);
+      throw error;
+    }
+
+    await ensureDir(path.dirname(filePath));
+    await writeFile(filePath, content, "utf8");
+    await cleanupTempFile(tempPath);
+  }
+}
+
+export async function appendUtf8(filePath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  await appendFile(filePath, content, "utf8");
+}
+
+export async function readJsonFile<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    const raw = await readUtf8(filePath);
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  await writeUtf8(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function removeIfExists(targetPath: string): Promise<void> {
+  try {
+    await rm(targetPath, { force: true, recursive: true });
+  } catch {
+    return;
+  }
+}
+
+export async function copyIfExists(sourcePath: string, destinationPath: string): Promise<void> {
+  if (!(await pathExists(sourcePath))) {
+    return;
+  }
+  await ensureDir(path.dirname(destinationPath));
+  await copyFile(sourcePath, destinationPath, constants.COPYFILE_FICLONE_FORCE).catch(async () => {
+    await copyFile(sourcePath, destinationPath);
+  });
+}
+
+export async function listFilesRecursive(rootDir: string): Promise<string[]> {
+  if (!(await pathExists(rootDir))) {
+    return [];
+  }
+  const results: string[] = [];
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await listFilesRecursive(fullPath)));
+    } else if (entry.isFile()) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+export async function listDirectoryFiles(dirPath: string): Promise<string[]> {
+  if (!(await pathExists(dirPath))) {
+    return [];
+  }
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => path.join(dirPath, entry.name));
+}
+
+async function renameWithRetry(sourcePath: string, destinationPath: string): Promise<void> {
+  let lastError: unknown;
+  for (const delayMs of [0, ...ATOMIC_WRITE_RETRY_DELAYS_MS]) {
+    if (delayMs > 0) {
+      await delay(delayMs);
+    }
+
+    try {
+      await rename(sourcePath, destinationPath);
+      return;
+    } catch (error) {
+      lastError = error;
+      const code = getErrorCode(error);
+      if (!code || !ATOMIC_WRITE_RETRYABLE_CODES.has(code)) {
+        throw error;
+      }
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "rename failed"));
+}
+
+async function cleanupTempFile(filePath: string): Promise<void> {
+  try {
+    await unlink(filePath);
+  } catch {
+    return;
+  }
+}
+
+function getErrorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== "object") {
+    return undefined;
+  }
+  return typeof (error as { code?: unknown }).code === "string"
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function listDirectories(rootDir: string): Promise<string[]> {
+  if (!(await directoryExists(rootDir))) {
+    return [];
+  }
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+export function stripAnsi(input: string): string {
+  return input.replace(
+    // eslint-disable-next-line no-control-regex
+    /\u001b\[[0-9;]*m/g,
+    "",
+  );
+}
+
+export function normalizeSlashes(input: string): string {
+  return input.replace(/\\/g, "/");
+}
+
+export function toPosixRelative(baseDir: string, targetPath: string): string {
+  const relativePath = path.relative(baseDir, targetPath);
+  return normalizeSlashes(relativePath || ".");
+}
+
+export async function resolveSimpleGlob(baseDir: string, pattern: string): Promise<string[]> {
+  if (!pattern.includes("*")) {
+    const exact = path.join(baseDir, pattern);
+    return (await pathExists(exact)) ? [exact] : [];
+  }
+
+  const normalized = normalizeSlashes(pattern);
+  if (normalized.endsWith("**/*.md")) {
+    const prefix = normalized.slice(0, normalized.indexOf("**/*.md"));
+    const root = path.join(baseDir, prefix);
+    const files = await listFilesRecursive(root);
+    return files.filter((filePath) => filePath.toLowerCase().endsWith(".md"));
+  }
+
+  const files = await listFilesRecursive(baseDir);
+  const needle = normalized.replace(/\*\*/g, "").replace(/\*/g, "");
+  return files.filter((filePath) => normalizeSlashes(path.relative(baseDir, filePath)).includes(needle));
+}
+
+export function takeLineExcerpt(text: string, maxLines = 12): string {
+  const lines = stripAnsi(text)
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+  return lines.slice(0, maxLines).join("\n");
+}