clawspec 1.0.0

package/src/planning/journal.ts

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import {
+  appendUtf8,
+  pathExists,
+  readJsonFile,
+  readUtf8,
+  removeIfExists,
+  writeJsonFile,
+} from "../utils/fs.ts";
+import type {
+  PlanningJournalEntry,
+  PlanningJournalSnapshot,
+} from "../types.ts";
+
+type PlanningJournalDigest = {
+  changeName: string;
+  entryCount: number;
+  lastEntryAt?: string;
+  contentHash: string;
+};
+
+export class PlanningJournalStore {
+  readonly filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  async append(entry: PlanningJournalEntry): Promise<void> {
+    await appendUtf8(this.filePath, `${JSON.stringify(entry)}\n`);
+  }
+
+  async list(changeName?: string): Promise<PlanningJournalEntry[]> {
+    if (!(await pathExists(this.filePath))) {
+      return [];
+    }
+    const raw = await readUtf8(this.filePath);
+    const entries = raw
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line) as PlanningJournalEntry];
+        } catch {
+          return [];
+        }
+      });
+    return changeName ? entries.filter((entry) => entry.changeName === changeName) : entries;
+  }
+
+  async clear(): Promise<void> {
+    await removeIfExists(this.filePath);
+  }
+
+  async readSnapshot(snapshotPath: string): Promise<PlanningJournalSnapshot | null> {
+    return await readJsonFile<PlanningJournalSnapshot | null>(snapshotPath, null);
+  }
+
+  async writeSnapshot(snapshotPath: string, changeName: string, syncedAt = new Date().toISOString()): Promise<PlanningJournalSnapshot> {
+    const digest = await this.digest(changeName);
+    const snapshot: PlanningJournalSnapshot = {
+      version: 1,
+      changeName,
+      syncedAt,
+      entryCount: digest.entryCount,
+      lastEntryAt: digest.lastEntryAt,
+      contentHash: digest.contentHash,
+    };
+    await writeJsonFile(snapshotPath, snapshot);
+    return snapshot;
+  }
+
+  async clearSnapshot(snapshotPath: string): Promise<void> {
+    await removeIfExists(snapshotPath);
+  }
+
+  async hasUnsyncedChanges(
+    changeName: string,
+    snapshotPath: string,
+    fallbackLastSyncedAt?: string,
+  ): Promise<boolean> {
+    const digest = await this.digest(changeName);
+    const snapshot = await this.readSnapshot(snapshotPath);
+    if (!snapshot) {
+      if (
+        fallbackLastSyncedAt
+        && digest.lastEntryAt
+        && Date.parse(digest.lastEntryAt) <= Date.parse(fallbackLastSyncedAt)
+      ) {
+        return false;
+      }
+      return digest.entryCount > 0;
+    }
+    return snapshot.changeName !== changeName
+      || snapshot.entryCount !== digest.entryCount
+      || snapshot.lastEntryAt !== digest.lastEntryAt
+      || snapshot.contentHash !== digest.contentHash;
+  }
+
+  async digest(changeName: string): Promise<PlanningJournalDigest> {
+    const entries = await this.list(changeName);
+    const normalized = entries.map((entry) => ({
+      timestamp: entry.timestamp,
+      changeName: entry.changeName,
+      role: entry.role,
+      text: entry.text,
+    }));
+    const serialized = JSON.stringify(normalized);
+    const contentHash = createHash("sha256").update(serialized).digest("hex");
+    return {
+      changeName,
+      entryCount: normalized.length,
+      lastEntryAt: normalized[normalized.length - 1]?.timestamp,
+      contentHash,
+    };
+  }
+}

package/src/rollback/store.ts

@@ -0,0 +1,173 @@
+import path from "node:path";
+import type { RollbackManifest, RollbackTrackedFile } from "../types.ts";
+import {
+  copyIfExists,
+  ensureDir,
+  listFilesRecursive,
+  normalizeSlashes,
+  pathExists,
+  readJsonFile,
+  removeIfExists,
+  toPosixRelative,
+  writeJsonFile,
+} from "../utils/fs.ts";
+import { getChangeBaselineRoot, getChangeSnapshotRoot, getRepoStatePaths } from "../utils/paths.ts";
+
+export class RollbackStore {
+  readonly repoPath: string;
+  readonly archiveDirName: string;
+  readonly changeName: string;
+  readonly manifestPath: string;
+  readonly snapshotRoot: string;
+  readonly baselineRoot: string;
+
+  constructor(repoPath: string, archiveDirName: string, changeName: string) {
+    this.repoPath = repoPath;
+    this.archiveDirName = archiveDirName;
+    this.changeName = changeName;
+    const repoStatePaths = getRepoStatePaths(repoPath, archiveDirName);
+    this.manifestPath = repoStatePaths.rollbackManifestFile;
+    this.snapshotRoot = getChangeSnapshotRoot(repoPath, archiveDirName, changeName);
+    this.baselineRoot = getChangeBaselineRoot(repoPath, archiveDirName, changeName);
+  }
+
+  async initializeBaseline(): Promise<RollbackManifest> {
+    const existing = await this.readManifest();
+    if (existing && existing.changeName === this.changeName && await pathExists(this.baselineRoot)) {
+      return existing;
+    }
+
+    await removeIfExists(this.snapshotRoot);
+    await ensureDir(this.baselineRoot);
+
+    const repoFiles = await listFilesRecursive(this.repoPath);
+    for (const filePath of repoFiles) {
+      const relativePath = toPosixRelative(this.repoPath, filePath);
+      if (!shouldSnapshotPath(relativePath)) {
+        continue;
+      }
+      await copyIfExists(filePath, this.resolveBaselinePath(relativePath));
+    }
+
+    const now = new Date().toISOString();
+    const manifest: RollbackManifest = {
+      version: 1,
+      changeName: this.changeName,
+      baselineRoot: this.baselineRoot,
+      createdAt: now,
+      updatedAt: now,
+      files: [],
+    };
+    await writeJsonFile(this.manifestPath, manifest);
+    return manifest;
+  }
+
+  async readManifest(): Promise<RollbackManifest | null> {
+    const manifest = await readJsonFile<RollbackManifest | null>(this.manifestPath, null);
+    if (!manifest || manifest.changeName !== this.changeName) {
+      return null;
+    }
+    return manifest;
+  }
+
+  async recordTouchedFiles(relativePaths: string[]): Promise<RollbackManifest> {
+    const manifest = await this.requireManifest();
+    const trackedByPath = new Map<string, RollbackTrackedFile>(
+      manifest.files.map((entry) => [entry.path, entry]),
+    );
+
+    for (const relativePath of relativePaths) {
+      const normalized = normalizeTrackedPath(relativePath);
+      if (!normalized || !shouldTrackPath(normalized)) {
+        continue;
+      }
+      trackedByPath.set(normalized, {
+        path: normalized,
+        kind: await this.detectKind(normalized),
+      });
+    }
+
+    const next: RollbackManifest = {
+      ...manifest,
+      updatedAt: new Date().toISOString(),
+      files: Array.from(trackedByPath.values()).sort((left, right) => left.path.localeCompare(right.path)),
+    };
+    await writeJsonFile(this.manifestPath, next);
+    return next;
+  }
+
+  async restoreTouchedFiles(): Promise<RollbackManifest> {
+    const manifest = await this.requireManifest();
+
+    for (const entry of manifest.files) {
+      const livePath = this.resolveRepoPath(entry.path);
+      const baselinePath = this.resolveBaselinePath(entry.path);
+
+      if (entry.kind === "created") {
+        await removeIfExists(livePath);
+        continue;
+      }
+
+      if (await pathExists(baselinePath)) {
+        await copyIfExists(baselinePath, livePath);
+        continue;
+      }
+
+      await removeIfExists(livePath);
+    }
+
+    const next: RollbackManifest = {
+      ...manifest,
+      cancelledAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    await writeJsonFile(this.manifestPath, next);
+    return next;
+  }
+
+  async clear(): Promise<void> {
+    await removeIfExists(this.snapshotRoot);
+    await removeIfExists(this.manifestPath);
+  }
+
+  private async requireManifest(): Promise<RollbackManifest> {
+    const manifest = await this.readManifest();
+    if (!manifest) {
+      throw new Error(`Rollback manifest is missing for change \`${this.changeName}\`.`);
+    }
+    return manifest;
+  }
+
+  private async detectKind(relativePath: string): Promise<RollbackTrackedFile["kind"]> {
+    const baselineExists = await pathExists(this.resolveBaselinePath(relativePath));
+    const liveExists = await pathExists(this.resolveRepoPath(relativePath));
+    if (!baselineExists) {
+      return "created";
+    }
+    if (!liveExists) {
+      return "deleted";
+    }
+    return "modified";
+  }
+
+  private resolveRepoPath(relativePath: string): string {
+    return path.join(this.repoPath, ...relativePath.split("/"));
+  }
+
+  private resolveBaselinePath(relativePath: string): string {
+    return path.join(this.baselineRoot, ...relativePath.split("/"));
+  }
+}
+
+function normalizeTrackedPath(relativePath: string): string | undefined {
+  const normalized = normalizeSlashes(relativePath).replace(/^\.\//, "");
+  return normalized.length === 0 ? undefined : normalized;
+}
+
+function shouldSnapshotPath(relativePath: string): boolean {
+  return !relativePath.startsWith(".openclaw/clawspec/");
+}
+
+function shouldTrackPath(relativePath: string): boolean {
+  return shouldSnapshotPath(relativePath);
+}

package/src/state/locks.ts

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { open, stat } from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, readUtf8, removeIfExists } from "../utils/fs.ts";
+
+type FileLockOptions = {
+  retries?: number;
+  delayMs?: number;
+  staleMs?: number;
+};
+
+const activeLocks = new Map<string, Promise<void>>();
+const DEFAULT_LOCK_RETRIES = 400;
+const DEFAULT_LOCK_DELAY_MS = 25;
+const DEFAULT_LOCK_STALE_MS = 60_000;
+
+export async function withFileLock<T>(
+  lockPath: string,
+  action: () => Promise<T>,
+  options?: FileLockOptions,
+): Promise<T> {
+  await ensureDir(path.dirname(lockPath));
+  const previous = activeLocks.get(lockPath) ?? Promise.resolve();
+  let releaseLock: (() => void) | undefined;
+  const current = new Promise<void>((resolve) => {
+    releaseLock = resolve;
+  });
+  activeLocks.set(lockPath, previous.then(() => current));
+
+  await previous;
+
+  const token = randomUUID();
+  let handle: Awaited<ReturnType<typeof acquireLockHandle>> | undefined;
+
+  try {
+    handle = await acquireLockHandle(lockPath, token, options);
+    return await action();
+  } finally {
+    await handle?.close().catch(() => undefined);
+    if (handle) {
+      await releaseLockFile(lockPath, token);
+    }
+    releaseLock?.();
+    if (activeLocks.get(lockPath) === current) {
+      activeLocks.delete(lockPath);
+    }
+  }
+}
+
+async function acquireLockHandle(
+  lockPath: string,
+  token: string,
+  options?: FileLockOptions,
+) {
+  const retries = options?.retries ?? DEFAULT_LOCK_RETRIES;
+  const delayMs = options?.delayMs ?? DEFAULT_LOCK_DELAY_MS;
+  const staleMs = options?.staleMs ?? DEFAULT_LOCK_STALE_MS;
+
+  let attempt = 0;
+  while (attempt <= retries) {
+    try {
+      const handle = await open(lockPath, "wx");
+      await handle.writeFile(JSON.stringify({
+        token,
+        pid: process.pid,
+        acquiredAt: Date.now(),
+      }), "utf8");
+      return handle;
+    } catch (error) {
+      const code = getErrorCode(error);
+      if (code !== "EEXIST") {
+        throw error;
+      }
+
+      if (await isLockStale(lockPath, staleMs)) {
+        await removeIfExists(lockPath);
+        continue;
+      }
+
+      if (attempt === retries) {
+        throw new Error(`timed out waiting for lock ${lockPath}`);
+      }
+
+      attempt += 1;
+      await delay(delayMs);
+    }
+  }
+
+  throw new Error(`timed out waiting for lock ${lockPath}`);
+}
+
+async function isLockStale(lockPath: string, staleMs: number): Promise<boolean> {
+  try {
+    const metadata = JSON.parse(await readUtf8(lockPath)) as { acquiredAt?: unknown };
+    if (typeof metadata.acquiredAt === "number" && Number.isFinite(metadata.acquiredAt)) {
+      return (Date.now() - metadata.acquiredAt) > staleMs;
+    }
+  } catch {
+    // Fall through to stat-based detection.
+  }
+
+  try {
+    const details = await stat(lockPath);
+    return (Date.now() - details.mtimeMs) > staleMs;
+  } catch {
+    return false;
+  }
+}
+
+async function releaseLockFile(lockPath: string, token: string): Promise<void> {
+  try {
+    const metadata = JSON.parse(await readUtf8(lockPath)) as { token?: unknown };
+    if (metadata.token !== token) {
+      return;
+    }
+  } catch {
+    return;
+  }
+  await removeIfExists(lockPath);
+}
+
+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));
+}