@gr8ful/spf 0.5.0 → 0.5.1

package/dist/cli/commands/watch.js

@@ -260,6 +260,17 @@ export async function watchCommand(argv) {
      */
     function linkDataDir(worktreePath) {
         const target = path.join(worktreePath, ".spf", "data");
+        // Hard guard, independent of however `worktreePath` got resolved: a real
+        // self-referential .spf/data symlink was observed live once already
+        // (points at itself — every later `mkdirSync` through it throws ELOOP;
+        // see `paths.healBrokenDataDir` for the recovery side of this same bug).
+        // The exact trigger was never pinned down, but `worktreePath` resolving
+        // to the main repo's own `data_dir` can never be correct regardless of
+        // how it got there, so refuse outright rather than create it again.
+        if (path.resolve(target) === path.resolve(dataPaths.data_dir)) {
+            console.error(`watch: refusing to link ${target} to itself — worktree path resolved to the main repo's own data_dir`);
+            return;
+        }
         if (existsSync(target))
             return;
         mkdirSync(path.dirname(target), { recursive: true });

package/dist/core/paths.d.ts

@@ -67,6 +67,9 @@ export interface DataPaths {
  * alwaysWritable()` matches `cfg.defaults.data_dir` against repo-relative git
  * output, so that field stays exactly as configured. This produces a
  * parallel, absolute set of paths for filesystem use instead of mutating it.
+ *
+ * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
+ * caller needs run before its own first `mkdirSync` against `data_dir`.
  */
 export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDbPath: string): DataPaths;
 /**

package/dist/core/paths.js

@@ -16,7 +16,7 @@
  * levels below the package root, so the same relative path resolves either
  * way), with `assets/` a direct child of it.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, lstatSync, realpathSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { findRepoRoot } from "./git_helper.js";
 export const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..", "..");
@@ -67,6 +67,49 @@ export function resolveConfigPaths(anchor, explicit) {
     }
     return { paths: [BUILTIN_CONFIG_PATH], source: "built-in-only" };
 }
+/**
+ * Self-heals one specific, previously-observed failure mode: `data_dir`
+ * existing as a broken symlink — self-referential (points at itself) or
+ * dangling (points at something that no longer exists) — instead of a real
+ * directory. `spf watch`'s `linkDataDir` guards against ever CREATING one of
+ * these now (see its comment in `cli/commands/watch.ts`), but a prior,
+ * unguarded build already left one behind on at least one real checkout, and
+ * that state persists across every later `spf` invocation until something
+ * removes it: `mkdirSync(data_dir, {recursive: true})` — the very first
+ * filesystem touch nearly every command makes, whether via `ensureDir`'s
+ * session dirs or `acquireLock`'s lockfile dir — throws `ELOOP` before
+ * anything else runs, with no recovery path of its own.
+ *
+ * This has to run HERE, in the one function every one of those call sites
+ * resolves `data_dir` through, rather than as a guard inside each of them
+ * individually — a fix duplicated at every call site is a fix that's one new
+ * call site away from being missed again.
+ *
+ * `lstatSync` (never follows the link itself) distinguishes "nothing here
+ * yet" (the ordinary first-run case — silently returns, nothing to heal)
+ * from "a symlink sits here." Only for the symlink case does `realpathSync`
+ * (which fully resolves it) get a chance to throw — `ELOOP` for a circular
+ * link, `ENOENT` for a dangling target — and only then is anything removed.
+ * A real directory never reaches the `realpathSync` call at all.
+ */
+function healBrokenDataDir(data_dir) {
+    let entry;
+    try {
+        entry = lstatSync(data_dir);
+    }
+    catch {
+        return; // nothing at this path at all — ordinary first run
+    }
+    if (!entry.isSymbolicLink())
+        return; // a real directory (or file) — not this bug
+    try {
+        realpathSync(data_dir);
+    }
+    catch {
+        rmSync(data_dir);
+        console.error(`spf: removed a broken data_dir symlink at ${data_dir} (self-referential or dangling) — a fresh directory will be created in its place`);
+    }
+}
 /**
  * Anchor a config's own `data_dir`/`observability.db` (as loaded — relative
  * or absolute, whichever the YAML says) to `repo_root`.
@@ -75,9 +118,13 @@ export function resolveConfigPaths(anchor, explicit) {
  * alwaysWritable()` matches `cfg.defaults.data_dir` against repo-relative git
  * output, so that field stays exactly as configured. This produces a
  * parallel, absolute set of paths for filesystem use instead of mutating it.
+ *
+ * Not otherwise side-effect-free: see `healBrokenDataDir` above, which every
+ * caller needs run before its own first `mkdirSync` against `data_dir`.
  */
 export function resolveDataPaths(anchor, rawDataDir, rawDbPath) {
     const data_dir = path.resolve(anchor.repo_root, rawDataDir);
+    healBrokenDataDir(data_dir);
     const data_dir_rel = path.relative(anchor.repo_root, data_dir).split(path.sep).join("/");
     const db_path = path.resolve(anchor.repo_root, rawDbPath);
     const sessions_dir = path.resolve(path.dirname(db_path), "sessions");

package/dist/test/paths.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/paths.test.js

@@ -0,0 +1,68 @@
+/**
+ * Regression guard for `resolveDataPaths`'s self-heal: a `data_dir` that
+ * exists as a broken symlink (self-referential or dangling) must be removed
+ * before anything tries to `mkdirSync` through it — see `paths.ts`'s
+ * `healBrokenDataDir` for why this lives here and not at each `mkdirSync`
+ * call site individually. This is a live bug that shipped once already: a
+ * self-referential `.spf/data -> .spf/data` symlink was observed on a real
+ * checkout, and every subsequent command failed with `ELOOP` at its very
+ * first filesystem touch.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveAnchor, resolveDataPaths } from "../core/paths.js";
+let dir;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "spf-paths-test-"));
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+test("resolveDataPaths: a self-referential data_dir symlink is removed, not left to ELOOP later", () => {
+    const dataDir = join(dir, ".spf", "data");
+    mkdirSync(join(dir, ".spf"), { recursive: true });
+    symlinkSync(dataDir, dataDir, "dir"); // exactly the observed bug: points at itself
+    const anchor = resolveAnchor(dir);
+    const paths = resolveDataPaths(anchor, ".spf/data", ".spf/data/spf.db");
+    assert.equal(paths.data_dir, dataDir);
+    assert.equal(existsSync(dataDir), false, "the broken symlink must be gone, not just tolerated");
+    // Confirms the actual failure mode is fixed: this would throw ELOOP before the fix.
+    mkdirSync(dataDir, { recursive: true });
+    assert.ok(existsSync(dataDir));
+});
+test("resolveDataPaths: a dangling data_dir symlink (target removed) is also cleaned up", () => {
+    const realTarget = join(dir, "somewhere-else");
+    const dataDir = join(dir, ".spf", "data");
+    mkdirSync(realTarget, { recursive: true });
+    mkdirSync(join(dir, ".spf"), { recursive: true });
+    symlinkSync(realTarget, dataDir, "dir");
+    rmSync(realTarget, { recursive: true, force: true }); // now dataDir points at nothing
+    const anchor = resolveAnchor(dir);
+    resolveDataPaths(anchor, ".spf/data", ".spf/data/spf.db");
+    assert.equal(existsSync(dataDir), false);
+});
+test("resolveDataPaths: an ordinary real directory is left completely alone", () => {
+    const dataDir = join(dir, ".spf", "data");
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(join(dataDir, "spf.db"), "not actually sqlite, just a marker");
+    const anchor = resolveAnchor(dir);
+    resolveDataPaths(anchor, ".spf/data", ".spf/data/spf.db");
+    assert.ok(existsSync(join(dataDir, "spf.db")), "a real, already-populated data_dir must never be touched");
+});
+test("resolveDataPaths: data_dir not existing yet (the ordinary first-run case) is a silent no-op", () => {
+    const anchor = resolveAnchor(dir);
+    assert.doesNotThrow(() => resolveDataPaths(anchor, ".spf/data", ".spf/data/spf.db"));
+    assert.equal(existsSync(join(dir, ".spf", "data")), false, "resolveDataPaths itself never creates the directory — only heals a broken one");
+});
+test("resolveDataPaths: a real FILE at data_dir's path (not a symlink) is left alone — not this bug", () => {
+    mkdirSync(join(dir, ".spf"), { recursive: true });
+    const dataDir = join(dir, ".spf", "data");
+    writeFileSync(dataDir, "oops, a file where a directory should be");
+    const anchor = resolveAnchor(dir);
+    resolveDataPaths(anchor, ".spf/data", ".spf/data/spf.db");
+    assert.ok(existsSync(dataDir), "only a broken SYMLINK is this function's concern, not any other kind of misconfiguration");
+    assert.equal(lstatSync(dataDir).isSymbolicLink(), false);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",