@aprimediet/codewalker 1.0.0 → 1.1.0

package/src/indexer.ts

@@ -0,0 +1,352 @@
+/**
+ * Codebase indexer: full scan and git-anchored incremental sync.
+ *
+ * - `scan()`: full build — walks the project tree, extracts symbols, writes cards, populates DB.
+ * - `sync()`: git-anchored incremental — reindexes only changed files.
+ * - `rebuildDbFromCards()`: rebuilds the DB from markdown cards alone (disposable-index property).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { openDb, upsertSymbol, deleteFileSymbols, deleteFile, setMeta, getMeta } from "./db.ts";
+import { detectCtags, runCtags, runCtagsOnFile } from "./extract/ctags.ts";
+import { parseCtagsOutput } from "./extract/ctags-parse.ts";
+import { extractRegex } from "./extract/regex.ts";
+import { extractDocComment } from "./extract/docs.ts";
+import { renderCard, parseCard } from "./cards.ts";
+import { getHeadSha, changedFilesSince } from "./git.ts";
+import type { Symbol } from "./types.ts";
+
+export interface ScanOptions {
+  projectRoot: string;
+  globalCodewalkerDir: string;
+  dbPath: string;
+  entriesDir: string;
+  symbolsDir: string;
+  useCtags?: boolean;
+}
+
+// Supported file extensions for extraction
+const SUPPORTED_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go",
+]);
+
+/**
+ * Full scan: walk the project tree, extract symbols, write cards, populate DB.
+ * Idempotent: re-running rebuilds everything from scratch.
+ */
+export async function scan(options: ScanOptions): Promise<void> {
+  const { projectRoot, dbPath, entriesDir, symbolsDir, globalCodewalkerDir } = options;
+  const useCtags = options.useCtags ?? detectCtags();
+
+  // Ensure directories exist
+  fs.mkdirSync(symbolsDir, { recursive: true });
+
+  // Collect all source files
+  const files = collectSourceFiles(projectRoot);
+
+  // Extract symbols
+  const allSymbols: Symbol[] = [];
+
+  if (useCtags) {
+    const ctagsSymbols = runCtagsWrapper(projectRoot, files);
+    allSymbols.push(...ctagsSymbols);
+  }
+
+  // Regex fallback for files ctags might have missed or when ctags is absent
+  const regexFiles = useCtags
+    ? files.filter(f => !hasCtagsSupport(path.extname(f)))
+    : files;
+
+  for (const filePath of regexFiles) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
+
+    const source = fs.readFileSync(filePath, "utf-8");
+    const symbols = extractRegex(source, filePath);
+    allSymbols.push(...symbols);
+  }
+
+  // For all symbols, extract doc comments
+  for (const sym of allSymbols) {
+    try {
+      const source = fs.readFileSync(sym.file_path, "utf-8");
+      const doc = extractDocComment(source, sym.line_start);
+      sym.doc = doc;
+    } catch {
+      // File might have been deleted between scan and read
+    }
+  }
+
+  // Open DB
+  const db = openDb(dbPath);
+
+  try {
+    // Start transaction
+    db.exec("BEGIN TRANSACTION");
+
+    // Clear existing data for this project's files
+    // We track which files we're about to index
+    const indexedPaths = new Set(allSymbols.map(s => s.file_path));
+
+    // Remove existing entries for files that no longer exist
+    const existingFiles = db.prepare("SELECT path FROM files").all() as { path: string }[];
+    for (const f of existingFiles) {
+      if (!indexedPaths.has(f.path)) {
+        deleteFileSymbols(db, f.path);
+        deleteFile(db, f.path);
+      }
+    }
+
+    // For existing files, also clean and re-insert
+    for (const sym of allSymbols) {
+      deleteFileSymbols(db, sym.file_path);
+    }
+
+    // Write cards and insert symbols
+    for (const sym of allSymbols) {
+      // Generate card path
+      const fileSlug = slugFromPath(sym.file_path);
+      const cardFileName = `${sanitizeName(sym.name)}.md`;
+      const cardDir = path.join(symbolsDir, fileSlug);
+      fs.mkdirSync(cardDir, { recursive: true });
+      const cardPath = path.join(cardDir, cardFileName);
+
+      // Render and write card
+      const card = renderCard(sym);
+      const tmpPath = cardPath + ".tmp";
+      fs.writeFileSync(tmpPath, card, { encoding: "utf-8", mode: 0o600 });
+      fs.renameSync(tmpPath, cardPath);
+
+      // Update sym with card_path and insert into DB
+      sym.card_path = cardPath;
+      upsertSymbol(db, sym);
+    }
+
+    // Update meta
+    const headSha = getHeadSha(projectRoot) ?? "";
+    setMeta(db, "last_indexed_commit", headSha);
+    setMeta(db, "last_full_scan", new Date().toISOString());
+    setMeta(db, "schema_version", "1");
+
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Git-anchored incremental sync.
+ * Reindexes only changed files since last_indexed_commit.
+ */
+export async function sync(options: ScanOptions): Promise<void> {
+  const { projectRoot, dbPath, entriesDir, symbolsDir } = options;
+  const useCtags = options.useCtags ?? detectCtags();
+
+  const db = openDb(dbPath);
+
+  try {
+    const lastCommit = getMeta(db, "last_indexed_commit");
+    let changedFiles: string[] = [];
+
+    if (lastCommit) {
+      changedFiles = changedFilesSince(projectRoot, lastCommit);
+    }
+
+    // Convert git's relative paths to absolute
+    const changedAbs = changedFiles.map((f) => path.resolve(projectRoot, f));
+
+    // Also scan for new files (git might not track untracked files)
+    const allFiles = collectSourceFiles(projectRoot);
+    const indexedFiles = new Set(
+      (db.prepare("SELECT path FROM files").all() as { path: string[] }).map(r => r.path as string),
+    );
+
+    // Find new files not yet indexed
+    const newFiles = allFiles.filter(f => !indexedFiles.has(f));
+
+    // Combine changed + new (all absolute paths)
+    const filesToProcess = new Set([...changedAbs, ...newFiles]);
+
+    if (filesToProcess.size === 0) {
+      // Nothing to do, but still update commit pointer
+      const headSha = getHeadSha(projectRoot) ?? "";
+      setMeta(db, "last_indexed_commit", headSha);
+      db.close();
+      return;
+    }
+
+    // Process changed files
+    for (const fullPath of filesToProcess) {
+      const ext = path.extname(fullPath).toLowerCase();
+
+      if (!fs.existsSync(fullPath)) {
+        // File was deleted — use absolute path for DB operations
+        deleteFileSymbols(db, fullPath);
+        deleteFile(db, fullPath);
+
+        // Remove card directory
+        const fileSlug = slugFromPath(fullPath);
+        const cardDir = path.join(symbolsDir, fileSlug);
+        if (fs.existsSync(cardDir)) {
+          fs.rmSync(cardDir, { recursive: true, force: true });
+        }
+        continue;
+      }
+
+      if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
+
+      // Re-extract
+      const source = fs.readFileSync(fullPath, "utf-8");
+      let symbols: Symbol[] = [];
+
+      if (useCtags && hasCtagsSupport(ext)) {
+        const ctagsOutput = runCtagsOnFile(fullPath, projectRoot);
+        symbols = parseCtagsOutput(ctagsOutput, projectRoot);
+      } else if (SUPPORTED_EXTENSIONS.has(ext)) {
+        symbols = extractRegex(source, fullPath);
+      }
+
+      // Extract doc comments
+      for (const sym of symbols) {
+        sym.doc = extractDocComment(source, sym.line_start);
+      }
+
+      // Remove old entries — use the full absolute path
+      deleteFileSymbols(db, fullPath);
+
+      // Write cards and insert
+      for (const sym of symbols) {
+        const fileSlug = slugFromPath(sym.file_path);
+        const cardFileName = `${sanitizeName(sym.name)}.md`;
+        const cardDir = path.join(symbolsDir, fileSlug);
+        fs.mkdirSync(cardDir, { recursive: true });
+        const cardPath = path.join(cardDir, cardFileName);
+
+        const card = renderCard(sym);
+        const tmpPath = cardPath + ".tmp";
+        fs.writeFileSync(tmpPath, card, { encoding: "utf-8", mode: 0o600 });
+        fs.renameSync(tmpPath, cardPath);
+
+        sym.card_path = cardPath;
+        upsertSymbol(db, sym);
+      }
+    }
+
+    // Update commit pointer
+    const headSha = getHeadSha(projectRoot) ?? "";
+    setMeta(db, "last_indexed_commit", headSha);
+
+    db.close();
+  } catch (e) {
+    db.close();
+    throw e;
+  }
+}
+
+/**
+ * Rebuild the SQLite DB from markdown cards alone.
+ * This demonstrates the disposable-index property: cards are the source of truth.
+ */
+export function rebuildDbFromCards(
+  dbPath: string,
+  entriesDir: string,
+): void {
+  const symbolsDir = path.join(entriesDir, "symbols");
+  if (!fs.existsSync(symbolsDir)) return;
+
+  const db = openDb(dbPath);
+
+  try {
+    db.exec("BEGIN TRANSACTION");
+
+    // Walk card files
+    const walkDir = (dir: string): void => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walkDir(fullPath);
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          const card = fs.readFileSync(fullPath, "utf-8");
+          const parsed = parseCard(card);
+          if (!parsed) continue;
+
+          const { head } = parsed;
+          const locMatch = head.location.match(/^(.+):(\d+)-(\d+)$/);
+          if (!locMatch) continue;
+
+          upsertSymbol(db, {
+            name: head.name,
+            kind: head.kind,
+            file_path: locMatch[1] ?? head.location,
+            line_start: parseInt(locMatch[2] ?? "0", 10),
+            line_end: parseInt(locMatch[3] ?? "0", 10),
+            signature: head.signature,
+            doc: parsed.body,
+            summary: head.summary,
+            card_path: fullPath,
+          });
+        }
+      }
+    };
+
+    walkDir(symbolsDir);
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+// ---- Internal helpers ----
+
+function collectSourceFiles(rootDir: string): string[] {
+  const files: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".pi" || entry.name.startsWith(".")) continue;
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (SUPPORTED_EXTENSIONS.has(ext)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  };
+  walk(rootDir);
+  return files;
+}
+
+function hasCtagsSupport(ext: string): boolean {
+  return [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go"].includes(ext);
+}
+
+function runCtagsWrapper(projectRoot: string, files: string[]): Symbol[] {
+  try {
+    const output = runCtags(files, projectRoot);
+    return parseCtagsOutput(output, projectRoot);
+  } catch {
+    return [];
+  }
+}
+
+function slugFromPath(filePath: string): string {
+  return filePath
+    .replace(/^\/+/, "")
+    .replace(/[^a-zA-Z0-9_\-/]/g, "_")
+    .replace(/\//g, "-")
+    .toLowerCase();
+}
+
+function sanitizeName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_$]/g, "_");
+}

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,204 @@
+/**
+ * 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;
+}
+
+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"),
+  };
+}
+
+/** 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]) {
+    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;
+}