@aprimediet/codewalker 1.0.0 → 1.2.0

package/src/libs/resolve.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Tests for libs/resolve.ts — library dependency discovery.
+ *
+ * Covers:
+ * - PURE parseDependencies (deps / deps+devDeps)
+ * - PURE resolveTypesEntry (types → typings → index.d.ts → main)
+ * - Integration locateLibrary over a fixture node_modules
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { parseDependencies, resolveTypesEntry, locateLibrary } from "./resolve.ts";
+
+// ── PURE: parseDependencies ────────────────────────────────────
+describe("parseDependencies", () => {
+  it("returns names from `dependencies`", () => {
+    const pkg = { dependencies: { express: "^4.0.0", lodash: "^4.17.0" } };
+    const result = parseDependencies(pkg);
+    expect(result).toEqual(["express", "lodash"]);
+  });
+
+  it("returns empty array when no dependencies", () => {
+    expect(parseDependencies({})).toEqual([]);
+  });
+
+  it("ignores devDependencies by default", () => {
+    const pkg = {
+      dependencies: { express: "^4.0.0" },
+      devDependencies: { vitest: "^1.0.0" },
+    };
+    expect(parseDependencies(pkg)).toEqual(["express"]);
+  });
+
+  it("includes devDependencies when includeDev=true", () => {
+    const pkg = {
+      dependencies: { express: "^4.0.0" },
+      devDependencies: { vitest: "^1.0.0", typescript: "^5.0.0" },
+    };
+    const result = parseDependencies(pkg, true);
+    expect(result).toContain("express");
+    expect(result).toContain("vitest");
+    expect(result).toContain("typescript");
+    expect(result).toHaveLength(3);
+  });
+
+  it("ignores peerDependencies and optionalDependencies", () => {
+    const pkg = {
+      dependencies: { express: "^4.0.0" },
+      peerDependencies: { react: "^18.0.0" },
+      optionalDependencies: { fsevents: "^2.0.0" },
+    };
+    expect(parseDependencies(pkg)).toEqual(["express"]);
+  });
+
+  it("returns empty array for null/undefined input", () => {
+    expect(parseDependencies(null as any)).toEqual([]);
+    expect(parseDependencies(undefined as any)).toEqual([]);
+  });
+});
+
+// ── PURE: resolveTypesEntry ────────────────────────────────────
+describe("resolveTypesEntry", () => {
+  it("prefers `types` field", () => {
+    const pkg = { types: "dist/index.d.ts", typings: "lib/index.d.ts" };
+    expect(resolveTypesEntry(pkg)).toBe("dist/index.d.ts");
+  });
+
+  it("falls back to `typings` field", () => {
+    const pkg = { typings: "lib/index.d.ts" };
+    expect(resolveTypesEntry(pkg)).toBe("lib/index.d.ts");
+  });
+
+  it("falls back to `index.d.ts`", () => {
+    const pkg = {};
+    expect(resolveTypesEntry(pkg)).toBe("index.d.ts");
+  });
+
+  it("derives from `main` by swapping .js for .d.ts", () => {
+    const pkg = { main: "dist/main.js" };
+    expect(resolveTypesEntry(pkg)).toBe("dist/main.d.ts");
+  });
+
+  it("handles main with no extension by appending .d.ts", () => {
+    const pkg = { main: "dist/main" };
+    expect(resolveTypesEntry(pkg)).toBe("dist/main.d.ts");
+  });
+
+  it("returns index.d.ts when main is not present", () => {
+    const pkg = {};
+    expect(resolveTypesEntry(pkg)).toBe("index.d.ts");
+  });
+});
+
+// ── Integration: locateLibrary ─────────────────────────────────
+describe("locateLibrary", () => {
+  let tmpDir: string;
+  let projectRoot: string;
+  let nodeModulesDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cw-resolve-"));
+    projectRoot = path.join(tmpDir, "my-project");
+    nodeModulesDir = path.join(projectRoot, "node_modules");
+    fs.mkdirSync(nodeModulesDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns version, dtsPath, and readmePath for a typed package", () => {
+    // Create a typed package
+    const pkgDir = path.join(nodeModulesDir, "typed-pkg");
+    fs.mkdirSync(path.join(pkgDir, "dist"), { recursive: true });
+
+    fs.writeFileSync(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({
+        name: "typed-pkg",
+        version: "2.1.0",
+        types: "dist/index.d.ts",
+        main: "dist/index.js",
+      }),
+    );
+
+    fs.writeFileSync(
+      path.join(pkgDir, "dist", "index.d.ts"),
+      "export declare function hello(): void;\n",
+    );
+
+    fs.writeFileSync(
+      path.join(pkgDir, "README.md"),
+      "# typed-pkg\nA typed package.\n",
+    );
+
+    const result = locateLibrary(projectRoot, "typed-pkg");
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe("2.1.0");
+    expect(result!.dtsPath).toBe(path.join(pkgDir, "dist", "index.d.ts"));
+    expect(result!.readmePath).toBe(path.join(pkgDir, "README.md"));
+  });
+
+  it("returns null for a non-existent package", () => {
+    const result = locateLibrary(projectRoot, "non-existent-pkg");
+    expect(result).toBeNull();
+  });
+
+  it("returns null when node_modules does not exist", () => {
+    const noNodeModules = path.join(tmpDir, "empty-project");
+    fs.mkdirSync(noNodeModules);
+    const result = locateLibrary(noNodeModules, "anything");
+    expect(result).toBeNull();
+  });
+
+  it("returns dtsPath=null for a package with no .d.ts file", () => {
+    // JS-only package, no types
+    const pkgDir = path.join(nodeModulesDir, "js-only");
+    fs.mkdirSync(pkgDir);
+
+    fs.writeFileSync(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({
+        name: "js-only",
+        version: "0.5.0",
+        main: "index.js",
+      }),
+    );
+
+    // Create the JS file but no .d.ts
+    fs.writeFileSync(path.join(pkgDir, "index.js"), "module.exports = {};\n");
+
+    // Also no README
+    const result = locateLibrary(projectRoot, "js-only");
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe("0.5.0");
+    expect(result!.dtsPath).toBeNull();
+    expect(result!.readmePath).toBeNull();
+  });
+
+  it("finds README.md case-insensitively (README.md or readme.md)", () => {
+    const pkgDir = path.join(nodeModulesDir, "readme-case");
+    fs.mkdirSync(path.join(pkgDir, "dist"), { recursive: true });
+
+    fs.writeFileSync(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({ name: "readme-case", version: "1.0.0" }),
+    );
+
+    // Only readme.md (lowercase)
+    fs.writeFileSync(path.join(pkgDir, "readme.md"), "# Lowercase readme\n");
+
+    // Need index.d.ts so it doesn't return null
+    fs.writeFileSync(path.join(pkgDir, "index.d.ts"), "export const foo: number;\n");
+
+    const result = locateLibrary(projectRoot, "readme-case");
+    expect(result).not.toBeNull();
+    expect(result!.readmePath).toBe(path.join(pkgDir, "readme.md"));
+  });
+
+  it("resolves package.json even without types field (uses index.d.ts fallback)", () => {
+    const pkgDir = path.join(nodeModulesDir, "no-types-field");
+    fs.mkdirSync(pkgDir);
+
+    fs.writeFileSync(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({ name: "no-types-field", version: "3.0.0" }),
+    );
+
+    fs.writeFileSync(path.join(pkgDir, "index.d.ts"), "export const bar: boolean;\n");
+
+    const result = locateLibrary(projectRoot, "no-types-field");
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe("3.0.0");
+    expect(result!.dtsPath).toBe(path.join(pkgDir, "index.d.ts"));
+  });
+});

package/src/libs/resolve.ts

@@ -0,0 +1,120 @@
+/**
+ * Library dependency discovery for codewalker v1.2.
+ *
+ * - `parseDependencies(pkgJson, includeDev?)`: PURE — extract dep names from package.json.
+ * - `resolveTypesEntry(pkgJson)`: PURE — find the .d.ts entry point.
+ * - `locateLibrary(projectRoot, name)`: integration — read the installed package info.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface LocateResult {
+  version: string;
+  dtsPath: string | null;
+  readmePath: string | null;
+}
+
+/**
+ * Extract dependency names from a package.json object.
+ * By default returns only `dependencies`; set `includeDev=true` to add `devDependencies`.
+ * Ignores peerDependencies and optionalDependencies.
+ * PURE — no I/O.
+ */
+export function parseDependencies(
+  pkgJson: Record<string, any> | null | undefined,
+  includeDev = false,
+): string[] {
+  if (!pkgJson) return [];
+
+  const deps: string[] = [];
+
+  if (pkgJson.dependencies) {
+    deps.push(...Object.keys(pkgJson.dependencies));
+  }
+
+  if (includeDev && pkgJson.devDependencies) {
+    deps.push(...Object.keys(pkgJson.devDependencies));
+  }
+
+  return deps;
+}
+
+/**
+ * Resolve the `.d.ts` entry point for a package.
+ * Priority: `types` → `typings` → `index.d.ts` → derive from `main` (swap .js for .d.ts).
+ * Returns a relative path string.
+ * PURE — no I/O.
+ */
+export function resolveTypesEntry(
+  pkgJson: Record<string, any> | null | undefined,
+): string {
+  if (!pkgJson) return "index.d.ts";
+
+  if (pkgJson.types) return pkgJson.types;
+  if (pkgJson.typings) return pkgJson.typings;
+
+  // Derive from `main` if present
+  if (pkgJson.main) {
+    const main = pkgJson.main as string;
+    // Swap .js|.mjs|.cjs endings for .d.ts; otherwise append .d.ts
+    if (/\.(js|mjs|cjs)$/.test(main)) {
+      return main.replace(/\.(js|mjs|cjs)$/, ".d.ts");
+    }
+    return main + ".d.ts";
+  }
+
+  return "index.d.ts";
+}
+
+/**
+ * Locate an installed library in `node_modules/<name>`.
+ * Returns null if the package or its directory does not exist.
+ * Integration — reads the filesystem.
+ */
+export function locateLibrary(
+  projectRoot: string,
+  name: string,
+): LocateResult | null {
+  const nmDir = path.join(projectRoot, "node_modules");
+  if (!fs.existsSync(nmDir)) return null;
+
+  const pkgDir = path.join(nmDir, name);
+  const pkgJsonPath = path.join(pkgDir, "package.json");
+
+  if (!fs.existsSync(pkgJsonPath)) return null;
+
+  let pkgJson: Record<string, any>;
+  try {
+    pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+  } catch {
+    return null;
+  }
+
+  const version = pkgJson.version ?? "unknown";
+
+  // Resolve .d.ts path
+  const typesRel = resolveTypesEntry(pkgJson);
+  let dtsPath: string | null = path.join(pkgDir, typesRel);
+  if (!fs.existsSync(dtsPath)) {
+    // Try common alternative locations
+    const altDts = path.join(pkgDir, "index.d.ts");
+    if (fs.existsSync(altDts)) {
+      dtsPath = altDts;
+    } else {
+      dtsPath = null;
+    }
+  }
+
+  // Find README (case-insensitive)
+  let readmePath: string | null = null;
+  for (const name of ["README.md", "readme.md", "Readme.md"]) {
+    const candidate = path.join(pkgDir, name);
+    if (fs.existsSync(candidate)) {
+      readmePath = candidate;
+      break;
+    }
+  }
+
+  return { version, dtsPath, readmePath };
+}

package/src/project.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import crypto from 'node:crypto';
+
+// We'll test project.ts after writing the test
+
+describe('project.ts', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-project-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('slug + id algorithm', () => {
+    it('generates a deterministic id from project root: slug(basename)-sha1(absRoot)[:8]', async () => {
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(tmpDir);
+      // slug = basename lowercased, non-alphanumeric → '-'
+      const basename = path.basename(tmpDir).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'project';
+      const hash = crypto.createHash('sha1').update(tmpDir).digest('hex').slice(0, 8);
+      const expectedId = `${basename}-${hash}`;
+      expect(p.id).toBe(expectedId);
+    });
+
+    it('reuses an existing .pi/<id>.md marker id (marker-wins)', async () => {
+      const configDir = path.join(tmpDir, '.pi');
+      fs.mkdirSync(configDir, { recursive: true });
+      const markerId = 'my-project-a1b2c3d4';
+      const markerPath = path.join(configDir, `${markerId}.md`);
+      fs.writeFileSync(markerPath, `---\npi-project: true\nid: ${markerId}\n---\n# marker\n`, 'utf-8');
+
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(tmpDir);
+      expect(p.id).toBe(markerId);
+      expect(p.markerPath).toBe(markerPath);
+    });
+  });
+
+  describe('findProjectRoot', () => {
+    it('walks up from cwd to find .git', async () => {
+      const gitDir = path.join(tmpDir, 'sub', 'dir');
+      fs.mkdirSync(gitDir, { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, '.git'), '');
+      const mod = await import('./project.ts');
+      // We need to call resolveProject from within sub/dir
+      const p = mod.resolveProject(gitDir);
+      expect(p.root).toBe(tmpDir);
+    });
+
+    it('walks up from cwd to find .pi config dir', async () => {
+      const piDir = path.join(tmpDir, 'deep', 'nested');
+      fs.mkdirSync(piDir, { recursive: true });
+      fs.mkdirSync(path.join(tmpDir, '.pi'), { recursive: true });
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(piDir);
+      expect(p.root).toBe(tmpDir);
+    });
+
+    it('returns cwd when no marker or .git is found', async () => {
+      const isolated = path.join(tmpDir, 'isolated');
+      fs.mkdirSync(isolated, { recursive: true });
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(isolated);
+      expect(p.root).toBe(isolated);
+    });
+  });
+
+  describe('ProjectPaths', () => {
+    it('resolves codewalker paths under ~/.pi/projects/<id>/codewalker/', async () => {
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(tmpDir);
+      expect(p.codewalkerDir).toContain(path.join('projects', p.id, 'codewalker'));
+      expect(p.dbPath).toBe(path.join(p.codewalkerDir, 'index.db'));
+      expect(p.metaFile).toBe(path.join(p.codewalkerDir, 'meta.json'));
+      expect(p.entriesDir).toBe(path.join(p.codewalkerDir, 'entries'));
+      expect(p.symbolsDir).toBe(path.join(p.codewalkerDir, 'entries', 'symbols'));
+    });
+  });
+
+  describe('ensureProject', () => {
+    it('creates the codewalker directory structure and returns paths', async () => {
+      const mod = await import('./project.ts');
+      const p = await mod.ensureProject(tmpDir);
+      // marker file exists
+      expect(fs.existsSync(p.markerPath)).toBe(true);
+      // codewalker dir is created
+      expect(fs.existsSync(p.codewalkerDir)).toBe(true);
+      expect(fs.existsSync(p.entriesDir)).toBe(true);
+      expect(fs.existsSync(p.symbolsDir)).toBe(true);
+      // meta.json written
+      expect(fs.existsSync(p.metaFile)).toBe(true);
+      // meta.json has correct shape
+      const meta = JSON.parse(fs.readFileSync(p.metaFile, 'utf-8'));
+      expect(meta.id).toBe(p.id);
+      expect(meta.name).toBe(path.basename(tmpDir));
+      expect(Array.isArray(meta.paths)).toBe(true);
+      expect(meta.paths).toContain(tmpDir);
+    });
+
+    it('is idempotent — calling ensureProject twice does not error', async () => {
+      const mod = await import('./project.ts');
+      await mod.ensureProject(tmpDir);
+      await mod.ensureProject(tmpDir);
+      // No error means idempotent
+      const p = mod.resolveProject(tmpDir);
+      expect(fs.existsSync(p.codewalkerDir)).toBe(true);
+    });
+  });
+});

package/src/project.ts

@@ -0,0 +1,206 @@
+/**
+ * Project identity + path layout for codewalker.
+ *
+ * The working tree stays clean: the only artifact written into <cwd>/.pi is a single identifier
+ * file `<project-id>.md`. Everything else (codewalker index, cards, meta) lives globally
+ * under ~/.pi/projects/<project-id>/codewalker/.
+ *
+ * The project id is deterministic from the project root path (`<slug>-<hash>`) so it is stable
+ * across runs; if the marker already records an id (e.g. the directory was moved), that id wins,
+ * so codewalker follows the project rather than the path.
+ *
+ * This module is adapted from @aprimediet/memory's project.ts — same id algorithm, same marker,
+ * different per-extension subdirectory.
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const CONFIG_DIR_NAME = ".pi";
+
+export interface ProjectPaths {
+  id: string;
+  root: string;
+  configDir: string;
+  markerPath: string;
+  globalDir: string;
+  codewalkerDir: string;
+  dbPath: string;
+  metaFile: string;
+  entriesDir: string;
+  symbolsDir: string;
+  libsDir: string;
+}
+
+function piHome(): string {
+  // Try common pi home locations; fallback to ~/.pi
+  const homePi = path.join(osHomedir(), ".pi");
+  const projects = path.join(homePi, "projects");
+  // If ~/.pi exists and has a projects/ dir, use it
+  if (fs.existsSync(projects)) return homePi;
+  // Otherwise create it
+  fs.mkdirSync(projects, { recursive: true });
+  return homePi;
+}
+
+function osHomedir(): string {
+  return process.env.HOME || process.env.USERPROFILE || "/root";
+}
+
+export function projectsRoot(): string {
+  return path.join(piHome(), "projects");
+}
+
+function slug(name: string): string {
+  const s = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return s || "project";
+}
+
+function pathHash(abs: string): string {
+  return crypto.createHash("sha1").update(abs).digest("hex").slice(0, 8);
+}
+
+function findProjectRoot(cwd: string): string {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, CONFIG_DIR_NAME)) || fs.existsSync(path.join(dir, ".git"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return cwd;
+    dir = parent;
+  }
+}
+
+/** Read an existing marker (a .pi/*.md file with `pi-project: true`); return its id + file. */
+function readMarker(configDir: string): { id: string; file: string } | null {
+  if (!fs.existsSync(configDir)) return null;
+  let names: string[];
+  try {
+    names = fs.readdirSync(configDir).filter((n) => n.endsWith(".md"));
+  } catch {
+    return null;
+  }
+  for (const name of names) {
+    const file = path.join(configDir, name);
+    try {
+      const content = fs.readFileSync(file, "utf-8");
+      const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+      if (!match) continue;
+      const fm = match[1] as string;
+      const lines = fm.split("\n");
+      const fmObj: Record<string, string> = {};
+      for (const line of lines) {
+        const sep = line.indexOf(":");
+        if (sep > 0) {
+          const key = line.slice(0, sep).trim();
+          const val = line.slice(sep + 1).trim();
+          fmObj[key] = val;
+        }
+      }
+      if (fmObj["pi-project"] === "true" && fmObj["id"]) {
+        return { id: fmObj["id"], file };
+      }
+    } catch {
+      /* not a marker */
+    }
+  }
+  return null;
+}
+
+function pathsForId(id: string, root: string, configDir: string, markerPath: string): ProjectPaths {
+  const globalDir = path.join(projectsRoot(), id);
+  return {
+    id,
+    root,
+    configDir,
+    markerPath,
+    globalDir,
+    codewalkerDir: path.join(globalDir, "codewalker"),
+    dbPath: path.join(globalDir, "codewalker", "index.db"),
+    metaFile: path.join(globalDir, "codewalker", "meta.json"),
+    entriesDir: path.join(globalDir, "codewalker", "entries"),
+    symbolsDir: path.join(globalDir, "codewalker", "entries", "symbols"),
+    libsDir: path.join(globalDir, "codewalker", "entries", "libs"),
+  };
+}
+
+/** Resolve project identity for a cwd (read-only — does not create anything). */
+export function resolveProject(cwd: string): ProjectPaths {
+  const root = findProjectRoot(cwd);
+  const configDir = path.join(root, CONFIG_DIR_NAME);
+  const existing = readMarker(configDir);
+  const id = existing?.id ?? `${slug(path.basename(root))}-${pathHash(root)}`;
+  const markerPath = existing?.file ?? path.join(configDir, `${id}.md`);
+  return pathsForId(id, root, configDir, markerPath);
+}
+
+function markerBody(id: string, createdISO: string): string {
+  return [
+    "---",
+    "pi-project: true",
+    `id: ${id}`,
+    `created: ${createdISO}`,
+    "---",
+    "# pi codewalker project",
+    "",
+    "This file marks this directory as a pi codewalker project. To keep your working tree clean,",
+    "all codewalker artifacts are stored globally — NOT here — under:",
+    "",
+    `    ~/.pi/projects/${id}/codewalker/`,
+    "",
+    "- `index.db`       disposable SQLite+FTS5 index",
+    "- `meta.json`      last-indexed commit and schema version",
+    "- `entries/`       markdown cards (source of truth)",
+    "",
+    "Managed by @aprimediet/codewalker. Safe to commit (stable id) and safe to delete (recreated).",
+    "",
+  ].join("\n");
+}
+
+/** Create the global directory structure + the cwd marker (idempotent). Returns the paths. */
+export async function ensureProject(cwd: string): Promise<ProjectPaths> {
+  const p = resolveProject(cwd);
+  const nowISO = new Date().toISOString();
+
+  for (const dir of [p.codewalkerDir, p.entriesDir, p.symbolsDir, p.libsDir]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // marker in cwd (the only thing we write into the working tree)
+  if (!fs.existsSync(p.markerPath)) {
+    fs.mkdirSync(p.configDir, { recursive: true });
+    const tmp = `${p.markerPath}.tmp`;
+    fs.writeFileSync(tmp, markerBody(p.id, nowISO), { encoding: "utf-8", mode: 0o644 });
+    fs.renameSync(tmp, p.markerPath);
+  }
+
+  // meta.json — track every path this project has been seen at
+  interface ProjectMeta {
+    id: string;
+    name: string;
+    paths: string[];
+    created: string;
+    lastSeen: string;
+  }
+  let meta: ProjectMeta = { id: p.id, name: path.basename(p.root), paths: [], created: nowISO, lastSeen: nowISO };
+  try {
+    meta = { ...meta, ...(JSON.parse(fs.readFileSync(p.metaFile, "utf-8")) as ProjectMeta) };
+  } catch {
+    /* first run */
+  }
+  if (!meta.paths.includes(p.root)) meta.paths.push(p.root);
+  meta.lastSeen = nowISO;
+  try {
+    const tmp = `${p.metaFile}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(meta, null, 2), { encoding: "utf-8", mode: 0o600 });
+    fs.renameSync(tmp, p.metaFile);
+  } catch {
+    /* non-fatal */
+  }
+
+  return p;
+}