@jaimevalasek/aioson 1.6.0 → 1.7.2

package/src/commands/context-trim.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const CHARS_PER_TOKEN = 4;
+const LARGE_SECTION_BULLETS = 20; // warn if a section has more than this many bullet lines
+
+function estimateTokens(content) {
+  return Math.ceil(content.length / CHARS_PER_TOKEN);
+}
+
+function formatBytes(bytes) {
+  return `${(bytes / 1024).toFixed(1)}KB`;
+}
+
+async function loadFeatureStatuses(contextDir) {
+  const featuresPath = path.join(contextDir, 'features.md');
+  try {
+    const content = await fs.readFile(featuresPath, 'utf8');
+    const done = new Set();
+    for (const line of content.split(/\r?\n/)) {
+      const m = line.match(/[-|]\s*([a-z0-9_-]+)\s*[:|]\s*done/i);
+      if (m) done.add(m[1].toLowerCase());
+    }
+    return done;
+  } catch {
+    return new Set();
+  }
+}
+
+function findLargeSections(content, fileName) {
+  const sections = [];
+  const sectionRe = /^#{2,4}\s+(.+)/gm;
+  let match;
+  const sectionStarts = [];
+
+  while ((match = sectionRe.exec(content)) !== null) {
+    sectionStarts.push({ title: match[1].trim(), start: match.index });
+  }
+
+  for (let i = 0; i < sectionStarts.length; i++) {
+    const { title, start } = sectionStarts[i];
+    const end = i + 1 < sectionStarts.length ? sectionStarts[i + 1].start : content.length;
+    const body = content.slice(start, end);
+    const bulletCount = (body.match(/^[-*]\s/gm) || []).length;
+    if (bulletCount > LARGE_SECTION_BULLETS) {
+      sections.push({
+        file: fileName,
+        section: title,
+        bulletCount,
+        sizeBytes: body.length,
+        tokens: estimateTokens(body)
+      });
+    }
+  }
+  return sections;
+}
+
+async function runContextTrim({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+  const archiveDir = path.join(contextDir, 'archive');
+  const dryRun = options['dry-run'] || options.dryRun || false;
+  const force = options.force || false;
+
+  let entries;
+  try {
+    entries = await fs.readdir(contextDir);
+  } catch {
+    if (!options.json) logger.log('No .aioson/context/ directory found.');
+    return { ok: false, reason: 'no_context_dir' };
+  }
+
+  const mdFiles = entries.filter((f) => f.endsWith('.md') && f !== 'archive');
+  const doneFeatures = await loadFeatureStatuses(contextDir);
+
+  const staleSpecs = [];
+  const largeSections = [];
+
+  for (const file of mdFiles) {
+    // Identify stale specs
+    if (file.startsWith('spec-')) {
+      const slug = file.replace(/^spec-/, '').replace(/\.md$/, '');
+      if (doneFeatures.has(slug)) {
+        const stat = await fs.stat(path.join(contextDir, file)).catch(() => null);
+        staleSpecs.push({
+          file,
+          slug,
+          sizeBytes: stat ? stat.size : 0
+        });
+      }
+    }
+
+    // Find large sections in active specs
+    if (file.startsWith('spec-') || file === 'spec.md') {
+      const content = await fs.readFile(path.join(contextDir, file), 'utf8').catch(() => null);
+      if (content) {
+        const found = findLargeSections(content, file);
+        largeSections.push(...found);
+      }
+    }
+  }
+
+  const totalStaleSaved = staleSpecs.reduce((s, r) => s + r.sizeBytes, 0);
+
+  if (options.json) {
+    return {
+      ok: true,
+      staleSpecs,
+      largeSections,
+      totalStaleSavedBytes: totalStaleSaved,
+      dryRun
+    };
+  }
+
+  logger.log('Context Trim Analysis');
+  logger.log('─'.repeat(50));
+
+  if (staleSpecs.length === 0 && largeSections.length === 0) {
+    logger.log('✓ No stale specs or oversized sections found.');
+    logger.log('');
+    return { ok: true, staleSpecs: [], largeSections: [], totalStaleSavedBytes: 0, dryRun };
+  }
+
+  if (staleSpecs.length > 0) {
+    logger.log(`Stale specs (feature: done):`);
+    for (const s of staleSpecs) {
+      logger.log(`  ${s.file.padEnd(30)} — ${s.slug} is done  (${formatBytes(s.sizeBytes)})`);
+    }
+    if (totalStaleSaved > 0) {
+      logger.log(`  → Archiving saves ~${formatBytes(totalStaleSaved)} (~${estimateTokens(totalStaleSaved * CHARS_PER_TOKEN)} tokens) per session`);
+    }
+    logger.log('');
+  }
+
+  if (largeSections.length > 0) {
+    logger.log('Large sections in active specs:');
+    for (const s of largeSections) {
+      logger.log(`  ${s.file} § ${s.section} (${s.bulletCount} entries, ${formatBytes(s.sizeBytes)})`);
+      logger.log(`    → Consider trimming to last ${LARGE_SECTION_BULLETS} entries to save ~${formatBytes(s.sizeBytes - Math.floor(s.sizeBytes * LARGE_SECTION_BULLETS / s.bulletCount))}`);
+    }
+    logger.log('');
+  }
+
+  // Archive stale specs
+  if (staleSpecs.length > 0) {
+    if (force || dryRun) {
+      if (!dryRun) {
+        await fs.mkdir(archiveDir, { recursive: true });
+        for (const s of staleSpecs) {
+          const src = path.join(contextDir, s.file);
+          const dest = path.join(archiveDir, s.file);
+          await fs.rename(src, dest);
+          logger.log(`  Archived: ${s.file} → context/archive/${s.file}`);
+        }
+        logger.log('');
+        logger.log(`${staleSpecs.length} spec(s) archived to .aioson/context/archive/`);
+      } else {
+        logger.log(`[dry-run] Would archive ${staleSpecs.length} stale spec(s) to .aioson/context/archive/`);
+      }
+    } else {
+      logger.log(`Run with --force to archive stale specs, or --dry-run to preview.`);
+    }
+  }
+
+  return {
+    ok: true,
+    staleSpecs,
+    largeSections,
+    totalStaleSavedBytes: totalStaleSaved,
+    archived: force && !dryRun ? staleSpecs.length : 0,
+    dryRun
+  };
+}
+
+module.exports = { runContextTrim };

package/src/commands/detect-test-runner.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * aioson detect:test-runner — detect test runner from project files.
+ *
+ * Checks for phpunit.xml, jest.config.*, vitest.config.*, pytest.ini, .rspec,
+ * foundry.toml and package.json scripts. Returns runner name and run command.
+ *
+ * Usage:
+ *   aioson detect:test-runner .
+ *   aioson detect:test-runner . --json
+ */
+
+const path = require('node:path');
+const { detectTestRunner } = require('../preflight-engine');
+
+const BAR = '━'.repeat(25);
+
+async function runDetectTestRunner({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+
+  const runner = await detectTestRunner(targetDir);
+
+  if (!runner) {
+    const result = { ok: true, detected: false, runner: null, command: null };
+    if (options.json) return result;
+    logger.log('');
+    logger.log('Test Runner Detection');
+    logger.log(BAR);
+    logger.log('No test runner detected.');
+    logger.log('');
+    return result;
+  }
+
+  const result = {
+    ok: true,
+    detected: true,
+    runner: runner.name,
+    command: runner.command,
+    config_file: runner.configFile
+  };
+
+  if (options.json) return result;
+
+  logger.log('');
+  logger.log('Test Runner Detection');
+  logger.log(BAR);
+  logger.log(`Found: ${runner.configFile} → ${runner.name}`);
+  logger.log(`Command: ${runner.command}`);
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runDetectTestRunner };

package/src/commands/devlog-export-brains.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { runLearningExport } = require('./learning-export');
+
+/**
+ * aioson devlog:export-brains [targetDir] [--min-frequency=N] [--json]
+ *
+ * Exports high-frequency project_learnings to .aioson/brains/ as Zettelkasten nodes.
+ * This is a focused wrapper over learning:export, intended to be run after devlog:process.
+ */
+async function runDevlogExportBrains({ args, options = {}, logger }) {
+  // Default min-frequency to 2 for devlog pipeline (lower than the general export default of 1)
+  const minFrequency = options['min-frequency'] != null ? options['min-frequency'] : options.minFrequency ?? 2;
+  const result = await runLearningExport({
+    args,
+    options: { ...options, 'min-frequency': minFrequency },
+    logger
+  });
+
+  if (result.ok && !options.json && result.exported > 0) {
+    logger.log('Run: aioson learning:evolve to promote high-frequency nodes to genome.');
+  }
+
+  return result;
+}
+
+module.exports = { runDevlogExportBrains };

package/src/commands/devlog-process.js

@@ -0,0 +1,292 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb, startTask, startRun, updateRun, updateTask, appendRunEvent, attachArtifact } = require('../runtime-store');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function createLearningId() {
+  return `learning-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) result[key] = value === 'null' ? null : value;
+  }
+  return result;
+}
+
+function extractSection(content, sectionName) {
+  const re = new RegExp(`^#{1,4}\\s+${sectionName}[\\s\\S]*?(?=^#{1,4}\\s|\\Z)`, 'im');
+  const match = content.match(re);
+  if (!match) return '';
+  return match[0].replace(/^#{1,4}\s+\S[^\n]*\n/, '').trim();
+}
+
+function extractListItems(content, sectionName) {
+  const section = extractSection(content, sectionName);
+  const items = [];
+  for (const line of section.split(/\r?\n/)) {
+    const trimmed = line.replace(/^[-*]\s*/, '').trim();
+    if (trimmed && trimmed.length > 2) items.push(trimmed);
+  }
+  return items;
+}
+
+function extractTaggedLearnings(content) {
+  const section = extractSection(content, 'Learnings');
+  const learnings = [];
+  for (const line of section.split(/\r?\n/)) {
+    const trimmed = line.replace(/^[-*]\s*/, '').trim();
+    if (!trimmed) continue;
+    const typeMatch = trimmed.match(/^\[(process|domain|quality|preference)\]\s+(.+)/i);
+    if (typeMatch) {
+      learnings.push({ type: typeMatch[1].toLowerCase(), title: typeMatch[2].trim() });
+    } else if (trimmed.length > 5) {
+      learnings.push({ type: 'process', title: trimmed });
+    }
+  }
+  return learnings;
+}
+
+function extractSummary(content) {
+  const section = extractSection(content, 'Summary');
+  if (section) return section.split(/\r?\n/)[0].trim();
+  // Fallback: first non-empty line of body after frontmatter
+  const body = content.replace(/^---[\s\S]*?---\r?\n/, '');
+  const firstHeading = body.match(/^#\s+(.+)/m);
+  return firstHeading ? firstHeading[1].trim() : null;
+}
+
+function upsertProjectLearning(db, { title, type, featureSlug, evidence, sourceSession }) {
+  const existing = db.prepare(
+    'SELECT learning_id, frequency FROM project_learnings WHERE title = ? AND (feature_slug = ? OR (feature_slug IS NULL AND ? IS NULL))'
+  ).get(title, featureSlug || null, featureSlug || null);
+
+  if (existing) {
+    db.prepare(
+      'UPDATE project_learnings SET frequency = ?, last_reinforced = ?, updated_at = ? WHERE learning_id = ?'
+    ).run(existing.frequency + 1, nowIso(), nowIso(), existing.learning_id);
+    return { action: 'updated', learningId: existing.learning_id };
+  }
+
+  const learningId = createLearningId();
+  db.prepare(`
+    INSERT INTO project_learnings
+      (learning_id, feature_slug, type, title, confidence, frequency, last_reinforced,
+       applies_to, source_session, evidence, status, created_at, updated_at)
+    VALUES (?, ?, ?, ?, 'medium', 1, ?, 'project', ?, ?, 'active', ?, ?)
+  `).run(learningId, featureSlug || null, type, title, nowIso(), sourceSession || null, evidence || null, nowIso(), nowIso());
+  return { action: 'inserted', learningId };
+}
+
+async function markAsProcessed(filePath, processedAt) {
+  const content = await fs.readFile(filePath, 'utf8');
+  const ts = processedAt || nowIso();
+
+  // If file already has processed_at, skip
+  if (/^processed_at:/m.test(content)) return;
+
+  // Inject processed_at into frontmatter
+  const updated = content.replace(/^(---\r?\n[\s\S]*?)(---)/m, `$1processed_at: ${ts}\n$2`);
+  await fs.writeFile(filePath, updated, 'utf8');
+}
+
+async function processDevlogFile(db, filePath) {
+  const content = await fs.readFile(filePath, 'utf8');
+  const fm = parseFrontmatter(content);
+
+  if (!fm || !fm.agent) {
+    return { status: 'malformed', file: path.basename(filePath), reason: 'missing frontmatter or agent field' };
+  }
+
+  // Skip already-processed devlogs
+  if (fm.processed_at) {
+    return { status: 'skipped', file: path.basename(filePath), reason: 'already processed' };
+  }
+
+  const body = content.replace(/^---[\s\S]*?---\r?\n?/, '');
+  const summary = extractSummary(body) || `@${fm.agent} devlog`;
+  const featureSlug = fm.feature && fm.feature !== 'project' ? fm.feature : null;
+  const sessionKey = fm.session_key || null;
+  const startedAt = fm.started_at || fm.session_start || nowIso();
+  const finishedAt = fm.finished_at || fm.session_end || nowIso();
+  const status = fm.status === 'partial' ? 'running' : 'completed';
+  const verdict = fm.verdict ? String(fm.verdict).trim().toUpperCase() : null;
+  const planStepId = fm.plan_step || null;
+
+  // Create task + run
+  const taskKey = startTask(db, {
+    title: `devlog: ${summary}`,
+    squadSlug: null,
+    sessionKey: sessionKey || undefined,
+    status,
+    createdBy: fm.agent
+  });
+
+  const runKey = startRun(db, {
+    taskKey,
+    agentName: fm.agent,
+    agentKind: 'devlog',
+    squadSlug: null,
+    title: `@${fm.agent} devlog`,
+    message: summary
+  });
+
+  // Register artifacts
+  const artifactPaths = extractListItems(body, 'Artifacts');
+  for (const filePath_ of artifactPaths) {
+    // Only register file-like entries (containing a slash or dot)
+    if (/[/.]/.test(filePath_)) {
+      attachArtifact(db, { runKey, agentName: fm.agent, kind: 'output', filePath: filePath_ });
+    }
+  }
+
+  // Register decisions as execution events
+  const decisions = extractListItems(body, 'Decisions');
+  for (const decision of decisions) {
+    appendRunEvent(db, {
+      runKey,
+      eventType: 'decision',
+      phase: 'devlog',
+      status: 'completed',
+      message: decision,
+      createdAt: finishedAt
+    });
+  }
+
+  // Upsert learnings
+  const learnings = extractTaggedLearnings(body);
+  for (const { type, title } of learnings) {
+    upsertProjectLearning(db, { title, type, featureSlug, sourceSession: sessionKey || path.basename(filePath) });
+  }
+
+  // Log verdict if present
+  if (verdict && verdict !== 'NULL') {
+    appendRunEvent(db, {
+      runKey,
+      eventType: 'qa_verdict',
+      phase: 'devlog',
+      status: 'completed',
+      message: `QA VERDICT: ${verdict}`,
+      verdict,
+      planStepId,
+      createdAt: finishedAt
+    });
+  }
+
+  // Close run
+  updateRun(db, runKey, {
+    status,
+    summary,
+    finishedAt
+  });
+
+  if (status === 'completed') {
+    updateTask(db, taskKey, { status: 'completed', finishedAt });
+  }
+
+  // Mark devlog as processed
+  await markAsProcessed(filePath, nowIso());
+
+  return {
+    status: 'ok',
+    file: path.basename(filePath),
+    runKey,
+    taskKey,
+    featureSlug,
+    artifactsCount: artifactPaths.filter((p) => /[/.]/.test(p)).length,
+    decisionsCount: decisions.length,
+    learningsCount: learnings.length,
+    verdict: verdict && verdict !== 'NULL' ? verdict : null
+  };
+}
+
+async function runDevlogProcess({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const logsDir = path.join(targetDir, 'aioson-logs');
+
+  let entries;
+  try {
+    entries = await fs.readdir(logsDir);
+  } catch {
+    if (!options.json) logger.log('No aioson-logs/ directory found — nothing to process.');
+    return { ok: true, processed: 0, skipped: 0, malformed: 0 };
+  }
+
+  const devlogFiles = entries
+    .filter((f) => f.startsWith('devlog-') && f.endsWith('.md'))
+    .sort();
+
+  if (devlogFiles.length === 0) {
+    if (!options.json) logger.log('No devlog files found.');
+    return { ok: true, processed: 0, skipped: 0, malformed: 0 };
+  }
+
+  const { db, dbPath } = await openRuntimeDb(targetDir);
+  const results = [];
+
+  try {
+    for (const file of devlogFiles) {
+      const result = await processDevlogFile(db, path.join(logsDir, file));
+      results.push(result);
+    }
+  } finally {
+    db.close();
+  }
+
+  const processed = results.filter((r) => r.status === 'ok');
+  const skipped = results.filter((r) => r.status === 'skipped');
+  const malformed = results.filter((r) => r.status === 'malformed');
+
+  const totalArtifacts = processed.reduce((s, r) => s + (r.artifactsCount || 0), 0);
+  const totalLearnings = processed.reduce((s, r) => s + (r.learningsCount || 0), 0);
+
+  if (options.json) {
+    return { ok: true, results, processed: processed.length, skipped: skipped.length, malformed: malformed.length, totalArtifacts, totalLearnings, dbPath };
+  }
+
+  logger.log(`Devlog Processing — ${path.basename(targetDir)}`);
+  logger.log('─'.repeat(50));
+
+  if (results.length === 0) {
+    logger.log('No devlogs to process.');
+  } else {
+    logger.log(`Found ${devlogFiles.length} devlog(s):`);
+    logger.log('');
+    for (const r of results) {
+      if (r.status === 'ok') {
+        logger.log(`${r.file}`);
+        logger.log(`  Agent: @${r.featureSlug ? `${r.featureSlug}` : 'project'} | run: ${r.runKey}`);
+        if (r.artifactsCount > 0) logger.log(`  Artifacts: ${r.artifactsCount} registered ✓`);
+        if (r.decisionsCount > 0) logger.log(`  Decisions: ${r.decisionsCount} logged ✓`);
+        if (r.learningsCount > 0) logger.log(`  Learnings: ${r.learningsCount} upserted ✓`);
+        if (r.verdict) logger.log(`  Verdict: ${r.verdict} ✓`);
+      } else if (r.status === 'skipped') {
+        logger.log(`${r.file} — skipped (${r.reason})`);
+      } else {
+        logger.log(`${r.file} — ⚠ ${r.reason}. Fix frontmatter and re-run.`);
+      }
+    }
+  }
+
+  logger.log('─'.repeat(50));
+  logger.log(`Processed: ${processed.length}/${devlogFiles.length} devlogs`);
+  if (totalLearnings > 0) logger.log(`New learnings: ${totalLearnings} (queued for brains export)`);
+  if (totalArtifacts > 0) logger.log(`Artifacts registered: ${totalArtifacts}`);
+  if (malformed.length > 0) logger.log(`Malformed (skipped): ${malformed.length}`);
+
+  return { ok: true, results, processed: processed.length, skipped: skipped.length, malformed: malformed.length, totalArtifacts, totalLearnings, dbPath };
+}
+
+module.exports = { runDevlogProcess, processDevlogFile };

package/src/commands/devlog-watch.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const fsSync = require('node:fs');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+const { processDevlogFile } = require('./devlog-process');
+
+const POLL_INTERVAL_MS = 5000;
+const WSL_VERSION_PATH = '/proc/version';
+
+async function isWsl2() {
+  try {
+    const version = await fs.readFile(WSL_VERSION_PATH, 'utf8');
+    return version.toLowerCase().includes('microsoft');
+  } catch {
+    return false;
+  }
+}
+
+async function processNewDevlog(targetDir, filePath, logger) {
+  const { db, dbPath } = await openRuntimeDb(targetDir).catch(() => ({ db: null }));
+  if (!db) {
+    logger.log(`[DEVLOG WATCHER] No database available — skipping ${path.basename(filePath)}`);
+    return;
+  }
+  try {
+    const result = await processDevlogFile(db, filePath);
+    if (result.status === 'ok') {
+      const parts = [];
+      if (result.learningsCount > 0) parts.push(`${result.learningsCount} learnings`);
+      if (result.artifactsCount > 0) parts.push(`${result.artifactsCount} artifacts`);
+      if (result.verdict) parts.push(`VERDICT: ${result.verdict}`);
+      const detail = parts.length > 0 ? ` → ${parts.join(', ')} → SQLite ✓` : ' → SQLite ✓';
+      logger.log(`[${new Date().toISOString().slice(11, 19)}] Processed: ${result.file}${detail}`);
+    } else if (result.status === 'skipped') {
+      // silently skip already-processed files
+    } else {
+      logger.log(`[${new Date().toISOString().slice(11, 19)}] ⚠ ${result.file}: ${result.reason}`);
+    }
+  } finally {
+    db.close();
+  }
+}
+
+async function watchWithFsWatch(logsDir, targetDir, logger) {
+  logger.log(`[DEVLOG WATCHER] Using fs.watch on ${logsDir}`);
+
+  return new Promise((resolve) => {
+    const watcher = fsSync.watch(logsDir, { persistent: true }, async (eventType, filename) => {
+      if (!filename || !filename.startsWith('devlog-') || !filename.endsWith('.md')) return;
+      if (eventType !== 'rename' && eventType !== 'change') return;
+
+      const filePath = path.join(logsDir, filename);
+      // Small delay to ensure file is fully written
+      setTimeout(async () => {
+        try {
+          await fs.access(filePath);
+          logger.log(`[${new Date().toISOString().slice(11, 19)}] New: ${filename} → processing...`);
+          await processNewDevlog(targetDir, filePath, logger);
+        } catch { /* file may have been removed */ }
+      }, 200);
+    });
+
+    process.on('SIGINT', () => { watcher.close(); resolve(); });
+    process.on('SIGTERM', () => { watcher.close(); resolve(); });
+  });
+}
+
+async function watchWithPolling(logsDir, targetDir, logger) {
+  logger.log(`[DEVLOG WATCHER] WSL2 detected — using polling (${POLL_INTERVAL_MS / 1000}s interval)`);
+
+  const seen = new Set();
+
+  // Seed with already-existing files so we don't reprocess them
+  try {
+    const entries = await fs.readdir(logsDir);
+    for (const f of entries) {
+      if (f.startsWith('devlog-') && f.endsWith('.md')) seen.add(f);
+    }
+  } catch { /* logsDir not yet created */ }
+
+  return new Promise((resolve) => {
+    const timer = setInterval(async () => {
+      try {
+        const entries = await fs.readdir(logsDir);
+        const devlogs = entries.filter((f) => f.startsWith('devlog-') && f.endsWith('.md'));
+        for (const filename of devlogs) {
+          if (!seen.has(filename)) {
+            seen.add(filename);
+            const filePath = path.join(logsDir, filename);
+            logger.log(`[${new Date().toISOString().slice(11, 19)}] New: ${filename} → processing...`);
+            await processNewDevlog(targetDir, filePath, logger);
+          }
+        }
+      } catch { /* directory may not exist yet */ }
+    }, POLL_INTERVAL_MS);
+
+    process.on('SIGINT', () => { clearInterval(timer); resolve(); });
+    process.on('SIGTERM', () => { clearInterval(timer); resolve(); });
+  });
+}
+
+async function runDevlogWatch({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const logsDir = path.join(targetDir, 'aioson-logs');
+  const usePolling = options.poll || await isWsl2();
+
+  // Ensure the directory exists
+  await fs.mkdir(logsDir, { recursive: true });
+
+  logger.log(`[DEVLOG WATCHER] Watching ${logsDir} for new devlogs...`);
+  logger.log('[DEVLOG WATCHER] Press Ctrl+C to stop.');
+
+  if (usePolling) {
+    await watchWithPolling(logsDir, targetDir, logger);
+  } else {
+    try {
+      await watchWithFsWatch(logsDir, targetDir, logger);
+    } catch (err) {
+      // Fall back to polling if fs.watch fails (can happen in some environments)
+      logger.log(`[DEVLOG WATCHER] fs.watch failed (${err.message}) — falling back to polling`);
+      await watchWithPolling(logsDir, targetDir, logger);
+    }
+  }
+
+  logger.log('[DEVLOG WATCHER] Stopped.');
+  return { ok: true };
+}
+
+module.exports = { runDevlogWatch };