devflow-kit 1.8.2 → 2.0.0

package/src/assets/scripts/hooks/lib/project-paths.cjs

@@ -0,0 +1,230 @@
+// src/assets/scripts/hooks/lib/project-paths.cjs
+//
+// Centralized path construction for all project-relative directories and files.
+//
+// DESIGN: Every function takes `projectRoot` (absolute path) and returns an
+// absolute path string. All construction uses path.join() — no string concatenation.
+//
+// ARCHITECTURE: This module is the single source of truth for path layout in
+// the CJS hook layer. Must match src/core/project-paths.ts exactly.
+//
+// TS COUNTERPART: src/core/project-paths.ts must mirror this file exactly.
+// Keep them in sync when adding or changing functions.
+
+'use strict';
+
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Core directories
+// ---------------------------------------------------------------------------
+
+/** .devflow/memory/ — working memory root */
+function getMemoryDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'memory');
+}
+
+/** .devflow/learning/ — learning state root */
+function getLearningDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning');
+}
+
+/** .devflow/features/ — per-feature knowledge bases */
+function getFeaturesDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'features');
+}
+
+/** .devflow/docs/ — generated documentation artifacts */
+function getDocsDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'docs');
+}
+
+// ---------------------------------------------------------------------------
+// Feature config (neutral .devflow root — not inside learning/)
+// ---------------------------------------------------------------------------
+
+/** .devflow/config.json — feature toggles {memory, learning, knowledge} */
+function getFeatureConfigPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'config.json');
+}
+
+// ---------------------------------------------------------------------------
+// Learning queue files
+// ---------------------------------------------------------------------------
+
+/** .devflow/learning/.pending-turns.jsonl — decisions detection queue */
+function getLearningPendingTurnsPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.jsonl');
+}
+
+/** .devflow/learning/.pending-turns.processing — atomic claim held by the Learning agent while processing */
+function getLearningPendingTurnsProcessingPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.processing');
+}
+
+// ---------------------------------------------------------------------------
+// Learning content files
+// ---------------------------------------------------------------------------
+
+/** .devflow/learning/decisions.md */
+function getDecisionsFilePath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'decisions.md');
+}
+
+/** .devflow/learning/pitfalls.md */
+function getPitfallsFilePath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'pitfalls.md');
+}
+
+/** .devflow/learning/learning.json — project-level learning agent tuning config */
+function getLearningTuningConfigPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'learning.json');
+}
+
+/** .devflow/learning/decisions-ledger.jsonl — anchored ledger rows (single source of truth for rendering) */
+function getDecisionsLedgerPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'decisions-ledger.jsonl');
+}
+
+/** .devflow/learning/decisions-log.jsonl */
+function getDecisionsLogPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'decisions-log.jsonl');
+}
+
+/** .devflow/learning/decisions-log.archive.jsonl — rotated-out stale observing rows (gitignored) */
+function getDecisionsArchivePath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'decisions-log.archive.jsonl');
+}
+
+/** .devflow/learning/.decisions.lock — mkdir-based lock directory */
+function getDecisionsLockDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.decisions.lock');
+}
+
+/** .devflow/learning/.decisions-usage.json */
+function getDecisionsUsagePath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.decisions-usage.json');
+}
+
+/** .devflow/learning/.decisions-usage.lock/ — mkdir-based lock directory for usage file */
+function getDecisionsUsageLockDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.decisions-usage.lock');
+}
+
+/** .devflow/learning/index.md — pre-rendered compact index written by render-decisions.cjs */
+function getDecisionsIndexPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'index.md');
+}
+
+/** .devflow/learning/.observations.lock — mkdir-based lock directory for observation log writes */
+function getObservationsLockDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.observations.lock');
+}
+
+// ---------------------------------------------------------------------------
+// Memory / working-memory files
+// ---------------------------------------------------------------------------
+
+/** .devflow/memory/WORKING-MEMORY.md */
+function getWorkingMemoryPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'memory', 'WORKING-MEMORY.md');
+}
+
+/** .devflow/memory/backup.json — pre-compact git state snapshot */
+function getBackupPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'memory', 'backup.json');
+}
+
+/** .devflow/memory/.pending-turns.jsonl — queue of captured turns */
+function getPendingTurnsPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'memory', '.pending-turns.jsonl');
+}
+
+/** .devflow/memory/.pending-turns.processing — atomic handoff during processing */
+function getPendingTurnsProcessingPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'memory', '.pending-turns.processing');
+}
+
+/** .devflow/memory/.pending-turns.lock — mutex for queue operations */
+function getPendingTurnsLockDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'memory', '.pending-turns.lock');
+}
+
+// ---------------------------------------------------------------------------
+// Docs files
+// ---------------------------------------------------------------------------
+
+/** .devflow/docs/reviews/ */
+function getReviewsDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'docs', 'reviews');
+}
+
+/** .devflow/docs/design/ */
+function getDesignDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'docs', 'design');
+}
+
+/** .devflow/docs/research/ */
+function getResearchDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'docs', 'research');
+}
+
+/** .devflow/docs/handoff-{branchSlug}.md — Code agent phase handoff artifact */
+function getHandoffPath(projectRoot, branchSlug) {
+  return path.join(projectRoot, '.devflow', 'docs', `handoff-${branchSlug}.md`);
+}
+
+// ---------------------------------------------------------------------------
+// Gitignore entries
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical list of generic gitignore entries Devflow adds to a project's
+ * root .gitignore for LOCAL-scope installs. Currently just `.claude/`.
+ *
+ * `.devflow/` is intentionally NOT here: it is managed by ensureDevflowGitignore
+ * (TS) / ensure-root-gitignore (hook), which write the feature-knowledge carve-out
+ * for ALL scopes. Adding a bare `.devflow/` here would append a wholesale-ignore
+ * line after the carve-out and re-bury it (last match wins in .gitignore).
+ */
+function getGitignoreEntries() {
+  return ['.claude/'];
+}
+
+module.exports = {
+  // Core directories
+  getMemoryDir,
+  getLearningDir,
+  getFeaturesDir,
+  getDocsDir,
+  // Feature config
+  getFeatureConfigPath,
+  // Learning queue files
+  getLearningPendingTurnsPath,
+  getLearningPendingTurnsProcessingPath,
+  // Learning content files
+  getDecisionsFilePath,
+  getPitfallsFilePath,
+  getLearningTuningConfigPath,
+  getDecisionsLedgerPath,
+  getDecisionsLogPath,
+  getDecisionsArchivePath,
+  getDecisionsLockDir,
+  getObservationsLockDir,
+  getDecisionsUsagePath,
+  getDecisionsUsageLockDir,
+  getDecisionsIndexPath,
+  // Memory files
+  getWorkingMemoryPath,
+  getBackupPath,
+  getPendingTurnsPath,
+  getPendingTurnsProcessingPath,
+  getPendingTurnsLockDir,
+  // Docs files
+  getReviewsDir,
+  getDesignDir,
+  getResearchDir,
+  getHandoffPath,
+  // Gitignore entries
+  getGitignoreEntries,
+};

package/src/assets/scripts/hooks/lib/render-decisions.cjs

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+// src/assets/scripts/hooks/lib/render-decisions.cjs
+//
+// Pure renderer for decisions.md and pitfalls.md from a decisions-ledger.jsonl.
+//
+// DESIGN: Idempotent, clock-free render from anchored ledger rows. No timestamps
+// in output — render is a pure function of the ledger rows. Two consumers:
+//   1. renderDecisionsFile(rows, kind) — exported pure function for testing
+//   2. CLI: `render <worktree>` and `--check <worktree>` subcommands
+//
+// Filtering rules (must match AC-F3):
+//   - anchor_id must be set (unanchored observing rows are excluded)
+//   - type must match kind: 'decision' rows → decisions.md; 'pitfall' rows → pitfalls.md
+//   - decisions_status: undefined|'Accepted'|'Active' → included
+//     'Deprecated'|'Superseded'|'Retired' → excluded
+//
+// Row shape: see LearningObservation in src/core/observations.ts.
+// Ledger file: .devflow/learning/decisions-ledger.jsonl (anchored rows only).
+// If absent, treat as empty corpus.
+//
+// Byte-compat: formatDecisionBody / formatPitfallBody / buildTldrLine /
+// initDecisionsContent — all from decisions-format.cjs (single source of truth).
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  initDecisionsContent,
+  formatDecisionBody,
+  formatPitfallBody,
+  buildTldrLine,
+  buildIndexContent,
+} = require('./decisions-format.cjs');
+
+const {
+  getDecisionsFilePath,
+  getPitfallsFilePath,
+  getDecisionsIndexPath,
+  getDecisionsLockDir,
+} = require('./project-paths.cjs');
+const { acquireMkdirLock, releaseLock } = require('./mkdir-lock.cjs');
+const { safePath } = require('./safe-path.cjs');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Statuses that indicate an anchored entry should be HIDDEN from the render. */
+const INACTIVE_STATUSES = new Set(['Deprecated', 'Superseded', 'Retired']);
+
+/** Ledger filename relative to .devflow/learning/ */
+const LEDGER_FILENAME = 'decisions-ledger.jsonl';
+
+// ---------------------------------------------------------------------------
+// Ledger parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a JSONL ledger file into an array of row objects.
+ * Skips empty or malformed lines. Returns [] if file is absent.
+ *
+ * @param {string} ledgerPath
+ * @returns {object[]}
+ */
+function parseLedger(ledgerPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const rows = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      rows.push(JSON.parse(trimmed));
+    } catch {
+      // Skip malformed lines
+    }
+  }
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// Core renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether a row is "active" for render purposes.
+ * Active = decisions_status is undefined OR is one of 'Accepted'/'Active'.
+ *
+ * @param {object} row
+ * @returns {boolean}
+ */
+function isActive(row) {
+  if (!row.decisions_status) return true;
+  return !INACTIVE_STATUSES.has(row.decisions_status);
+}
+
+/**
+ * Extract the numeric suffix from an anchor_id like "ADR-016" or "PF-007".
+ * Returns Infinity for unparseable values so they sort to the end.
+ *
+ * @param {string} anchorId
+ * @returns {number}
+ */
+function anchorNumeric(anchorId) {
+  if (!anchorId) return Infinity;
+  const m = anchorId.match(/\d+$/);
+  return m ? parseInt(m[0], 10) : Infinity;
+}
+
+/**
+ * Select active rows of a given kind from the ledger, sorted by numeric anchor.
+ * Exported so callers (renderAndWriteAll, migrations) can build the index without
+ * going through renderDecisionsFile.
+ *
+ * @param {object[]} rows - all rows from the ledger (unfiltered)
+ * @param {'decisions'|'pitfalls'} kind
+ * @returns {object[]} filtered + sorted active rows
+ */
+function selectActiveRows(rows, kind) {
+  const type = kind === 'decisions' ? 'decision' : 'pitfall';
+  return rows
+    .filter(r => r.type === type && r.anchor_id && isActive(r))
+    .sort((a, b) => anchorNumeric(a.anchor_id) - anchorNumeric(b.anchor_id));
+}
+
+/**
+ * Build the full file content from already-filtered + sorted active rows.
+ * Internal helper — callers that have already run selectActiveRows can pass
+ * the result here directly to avoid re-filtering the ledger.
+ *
+ * Per-row content:
+ *   - If row.raw_body is truthy → emit verbatim (migrated entries)
+ *   - Otherwise → formatDecisionBody / formatPitfallBody from details
+ *
+ * @param {object[]} activeRows - already-filtered + sorted active rows
+ * @param {'decisions'|'pitfalls'} kind
+ * @returns {string} complete file content
+ */
+function renderBodyFromActive(activeRows, kind) {
+  // Build per-row blocks
+  const blocks = activeRows.map(row => {
+    if (row.raw_body) {
+      // Migrated entry: emit verbatim. raw_body must start with \n## so
+      // it fits seamlessly after the header preamble.
+      return row.raw_body;
+    }
+    return kind === 'decisions'
+      ? formatDecisionBody(row)
+      : formatPitfallBody(row);
+  });
+
+  // Build TL;DR line (uses active + sorted rows so last-5 are stable)
+  const tldr = buildTldrLine(kind, activeRows);
+
+  // Build header: replace placeholder TL;DR in the init content with the real one.
+  // initDecisionsContent returns "<!-- TL;DR: 0 {kind}. Key: -->\n..." so we
+  // replace the TL;DR line at position 0.
+  const initKind = kind === 'decisions' ? 'decision' : 'pitfall';
+  const headerWithPlaceholder = initDecisionsContent(initKind);
+  // Replace only the first line (the TL;DR comment)
+  const header = headerWithPlaceholder.replace(/^<!-- TL;DR:[^\n]*-->/, tldr);
+
+  return header + blocks.join('');
+}
+
+/**
+ * Pure render function. Produces the full content of a decisions.md or
+ * pitfalls.md file from the given ledger rows.
+ *
+ * Filtering:
+ *   - row.type must match kind ('decision' → decisions.md, 'pitfall' → pitfalls.md)
+ *   - row.anchor_id must be set
+ *   - row must be active (decisions_status not in INACTIVE_STATUSES)
+ *
+ * Output structure:
+ *   TL;DR line (line 1)
+ *   File header body (title + preamble)
+ *   Per-row blocks (sorted by numeric anchor ASC)
+ *   (no trailing newline beyond what the blocks naturally include)
+ *
+ * Idempotent and clock-free: no timestamps in output.
+ *
+ * @param {object[]} rows - all rows from the ledger (unfiltered)
+ * @param {'decisions'|'pitfalls'} kind
+ * @returns {string} complete file content
+ */
+function renderDecisionsFile(rows, kind) {
+  return renderBodyFromActive(selectActiveRows(rows, kind), kind);
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Write content atomically via a .tmp sibling + rename.
+ * Uses O_EXCL to prevent TOCTOU symlink attacks, retries once on EEXIST.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ */
+function writeAtomic(filePath, content) {
+  const tmp = filePath + '.tmp';
+  try {
+    fs.writeFileSync(tmp, content, { flag: 'wx' });
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    try { fs.unlinkSync(tmp); } catch { /* race */ }
+    fs.writeFileSync(tmp, content, { flag: 'wx' });
+  }
+  fs.renameSync(tmp, filePath);
+}
+
+// ---------------------------------------------------------------------------
+// Lock-free render+write helper (for callers that already hold .decisions.lock)
+// ---------------------------------------------------------------------------
+
+/**
+ * Render both decisions.md and pitfalls.md from the given ledger rows and write
+ * them atomically. Does NOT acquire any lock — callers (assign-anchor, retire-anchor)
+ * must already hold .decisions.lock. The standalone `render` CLI takes the lock
+ * before calling this function.
+ *
+ * Creates the decisionsDir if it does not exist.
+ *
+ * @param {string} worktreePath - Absolute path to the worktree root.
+ * @param {object[]} rows - All rows from the ledger (unfiltered).
+ */
+function renderAndWriteAll(worktreePath, rows) {
+  const decisionsDir = path.join(worktreePath, '.devflow', 'learning');
+  fs.mkdirSync(decisionsDir, { recursive: true });
+
+  const decisionsFilePath = getDecisionsFilePath(worktreePath);
+  const pitfallsFilePath = getPitfallsFilePath(worktreePath);
+  const indexFilePath = getDecisionsIndexPath(worktreePath);
+
+  // Hoist active-row selection: computed once per kind, reused for both the
+  // body render and the index build — avoids two redundant selectActiveRows passes.
+  const activeDecisionRows = selectActiveRows(rows, 'decisions');
+  const activePitfallRows = selectActiveRows(rows, 'pitfalls');
+
+  const decisionsContent = renderBodyFromActive(activeDecisionRows, 'decisions');
+  const pitfallsContent = renderBodyFromActive(activePitfallRows, 'pitfalls');
+
+  // Write body files first; index last. On a crash between body writes and the
+  // index write: on the FIRST render the index is absent (reader falls back to
+  // (none)); on a RE-render the index is stale — one generation behind the new
+  // body files — never corrupt. Both cases are benign and self-heal on the next
+  // successful render.
+  writeAtomic(decisionsFilePath, decisionsContent);
+  writeAtomic(pitfallsFilePath, pitfallsContent);
+
+  // Build and write compact index (write-time artifact; consumed via plain Read)
+  // Reuses the pre-computed active rows — no additional selectActiveRows pass.
+  const indexContent = buildIndexContent(activeDecisionRows, activePitfallRows, {
+    decisionsFilePath,
+    pitfallsFilePath,
+  });
+  writeAtomic(indexFilePath, indexContent + '\n');
+
+  process.stderr.write(
+    `[render-decisions] wrote decisions.md (${decisionsContent.length}B) + pitfalls.md (${pitfallsContent.length}B) + index.md (${indexContent.length}B)\n`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0) {
+    process.stderr.write(
+      'Usage:\n' +
+      '  render-decisions.cjs render <worktree>          Write both .md files\n' +
+      '  render-decisions.cjs --check <worktree>         Diff without writing; exit 1 on drift\n'
+    );
+    process.exit(1);
+  }
+
+  // Parse: `render <worktree>` or `--check <worktree>`
+  let mode; // 'render' | 'check'
+  let worktreePath;
+
+  if (argv[0] === 'render' && argv[1]) {
+    mode = 'render';
+    worktreePath = path.resolve(argv[1]);
+  } else if (argv[0] === '--check' && argv[1]) {
+    mode = 'check';
+    worktreePath = path.resolve(argv[1]);
+  } else {
+    process.stderr.write(
+      'Usage:\n' +
+      '  render-decisions.cjs render <worktree>          Write both .md files\n' +
+      '  render-decisions.cjs --check <worktree>         Diff without writing; exit 1 on drift\n'
+    );
+    process.exit(1);
+  }
+
+  // Validate path at trust boundary before any file operations.
+  // safePath rejects null bytes, which path.resolve preserves silently.
+  try {
+    worktreePath = safePath(worktreePath);
+  } catch (err) {
+    process.stderr.write(`render-decisions: invalid worktree path: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const decisionsDir = path.join(worktreePath, '.devflow', 'learning');
+  const ledgerPath = path.join(decisionsDir, LEDGER_FILENAME);
+  const decisionsFilePath = getDecisionsFilePath(worktreePath);
+  const pitfallsFilePath = getPitfallsFilePath(worktreePath);
+  const indexFilePath = getDecisionsIndexPath(worktreePath);
+  const lockDir = getDecisionsLockDir(worktreePath);
+
+  // Ensure decisionsDir exists (needed before lock acquisition and file reads)
+  fs.mkdirSync(decisionsDir, { recursive: true });
+
+  // Read ledger (empty corpus if absent)
+  const rows = parseLedger(ledgerPath);
+
+  if (mode === 'check') {
+    // Render all three files in memory and compare against on-disk content.
+    // Exit non-zero on drift.
+    // Hoist active-row selection (mirrors renderAndWriteAll): computed once per kind,
+    // reused for both body render and index build.
+    const activeDecisionRows = selectActiveRows(rows, 'decisions');
+    const activePitfallRows = selectActiveRows(rows, 'pitfalls');
+    const decisionsContent = renderBodyFromActive(activeDecisionRows, 'decisions');
+    const pitfallsContent = renderBodyFromActive(activePitfallRows, 'pitfalls');
+    const indexContent = buildIndexContent(activeDecisionRows, activePitfallRows, {
+      decisionsFilePath,
+      pitfallsFilePath,
+    }) + '\n';
+
+    let drift = false;
+    let existingDecisions = '';
+    let existingPitfalls = '';
+    let existingIndex = '';
+    try { existingDecisions = fs.readFileSync(decisionsFilePath, 'utf8'); } catch { drift = true; }
+    try { existingPitfalls = fs.readFileSync(pitfallsFilePath, 'utf8'); } catch { drift = true; }
+    // index.md missing is a drift condition (it should always be present after a render)
+    try { existingIndex = fs.readFileSync(indexFilePath, 'utf8'); } catch { drift = true; }
+
+    if (!drift) {
+      if (existingDecisions !== decisionsContent) {
+        process.stderr.write(`[render-decisions] DRIFT: ${decisionsFilePath}\n`);
+        drift = true;
+      }
+      if (existingPitfalls !== pitfallsContent) {
+        process.stderr.write(`[render-decisions] DRIFT: ${pitfallsFilePath}\n`);
+        drift = true;
+      }
+      if (existingIndex !== indexContent) {
+        process.stderr.write(`[render-decisions] DRIFT: ${indexFilePath}\n`);
+        drift = true;
+      }
+    }
+
+    process.exit(drift ? 1 : 0);
+  }
+
+  // mode === 'render': write atomically under lock
+  if (!acquireMkdirLock(lockDir, 30000, 60000)) {
+    process.stderr.write(`render-decisions: timeout acquiring lock at ${lockDir}\n`);
+    process.exit(1);
+  }
+
+  try {
+    // Use the lock-free helper — we already hold the lock.
+    renderAndWriteAll(worktreePath, rows);
+  } finally {
+    releaseLock(lockDir);
+  }
+
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Module exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  renderDecisionsFile,
+  renderAndWriteAll,
+  selectActiveRows,
+  parseLedger,
+  isActive,
+  anchorNumeric,
+};

package/src/assets/scripts/hooks/lib/safe-path.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Resolve a file path to an absolute path, optionally validating it
+ * falls within an allowed root directory.
+ *
+ * @param {string} filePath
+ * @param {string} [allowedRoot] — when provided, throws if resolved path escapes this root
+ * @returns {string}
+ */
+function safePath(filePath, allowedRoot) {
+  // D-SEC-001: Validate at boundary — reject null bytes before path.resolve, which
+  // preserves them silently. A null byte in a path is always hostile input.
+  if (filePath.includes('\0')) {
+    throw new Error(`Invalid path: contains null byte`);
+  }
+  const resolved = path.resolve(filePath);
+  if (typeof allowedRoot === 'string') {
+    const root = path.resolve(allowedRoot);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+      throw new Error(`Refused path outside ${root}: ${filePath}`);
+    }
+  }
+  return resolved;
+}
+
+module.exports = { safePath };

package/src/assets/scripts/hooks/log-paths

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Shared log path computation for Devflow hooks.
+# Source this file to get devflow_log_dir function.
+
+# Cache the computed log dir path to avoid spawning 4 subprocesses (sed+tr+mkdir+chmod)
+# on every call within the same hook process.
+_LOG_DIR_CACHED=""
+_LOG_DIR_CACHED_CWD=""
+
+devflow_log_dir() {
+  local cwd="$1"
+  if [ "$cwd" = "$_LOG_DIR_CACHED_CWD" ] && [ -n "$_LOG_DIR_CACHED" ]; then
+    echo "$_LOG_DIR_CACHED"
+    return 0
+  fi
+  local slug
+  slug=$(echo "$cwd" | sed 's|^/||' | tr '/' '-')
+  local dir="$HOME/.devflow/logs/$slug"
+  mkdir -p "$dir"
+  chmod 700 "$dir"
+  _LOG_DIR_CACHED="$dir"
+  _LOG_DIR_CACHED_CWD="$cwd"
+  echo "$dir"
+}