smart-context-mcp 1.4.0 → 1.6.0

package/src/storage/sqlite.js

@@ -7,6 +7,7 @@ import { projectRoot } from '../utils/runtime-config.js';
 export const STATE_DB_FILENAME = 'state.sqlite';
 export const SQLITE_SCHEMA_VERSION = 5;
 export const ACTIVE_SESSION_SCOPE = 'project';
+export const STATE_DB_SOFT_MAX_BYTES = 32 * 1024 * 1024;
 export const EXPECTED_TABLES = [
   'active_session',
   'context_access',
@@ -191,6 +192,229 @@ const ensureStateDir = (filePath) => {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
 };
 
+const toRelativeStatePath = (filePath) =>
+  path.relative(projectRoot, filePath).replace(/\\/g, '/') || path.basename(filePath);
+
+const buildStorageDiagnostic = ({
+  filePath,
+  issue,
+  status,
+  exists,
+  sizeBytes,
+  walExists,
+  shmExists,
+  message,
+  recommendedActions,
+  integrity = null,
+  details = {},
+}) => ({
+  filePath,
+  relativePath: toRelativeStatePath(filePath),
+  issue,
+  status,
+  exists,
+  sizeBytes,
+  walExists,
+  shmExists,
+  softMaxBytes: STATE_DB_SOFT_MAX_BYTES,
+  message,
+  recommendedActions,
+  integrity,
+  ...details,
+});
+
+export const getStateStorageHealth = ({ filePath = getStateDbPath() } = {}) => {
+  const exists = fs.existsSync(filePath);
+  const sizeBytes = exists ? fs.statSync(filePath).size : 0;
+  const walExists = fs.existsSync(`${filePath}-wal`);
+  const shmExists = fs.existsSync(`${filePath}-shm`);
+
+  if (!exists) {
+    return buildStorageDiagnostic({
+      filePath,
+      issue: 'missing',
+      status: 'warning',
+      exists,
+      sizeBytes,
+      walExists,
+      shmExists,
+      message: 'Project-local SQLite state does not exist yet.',
+      recommendedActions: [
+        'Run a persisted devctx action such as smart_summary update or smart_turn end to initialize state.sqlite.',
+        'If you expected prior context, verify DEVCTX_STATE_DB_PATH / project root and that .devctx/ was not deleted.',
+      ],
+    });
+  }
+
+  if (sizeBytes > STATE_DB_SOFT_MAX_BYTES) {
+    return buildStorageDiagnostic({
+      filePath,
+      issue: 'oversized',
+      status: 'warning',
+      exists,
+      sizeBytes,
+      walExists,
+      shmExists,
+      message: 'Project-local SQLite state is larger than the recommended soft limit.',
+      recommendedActions: [
+        'Run smart_summary compact to prune retained events and metrics.',
+        'Archive or remove old local state after backing it up if the repository has become long-lived.',
+      ],
+    });
+  }
+
+  return buildStorageDiagnostic({
+    filePath,
+    issue: 'ok',
+    status: 'ok',
+    exists,
+    sizeBytes,
+    walExists,
+    shmExists,
+    message: 'Project-local SQLite state is present and within the recommended size range.',
+    recommendedActions: [],
+  });
+};
+
+export const classifyStateDbError = (error, { filePath = getStateDbPath(), readOnly = false } = {}) => {
+  const base = getStateStorageHealth({ filePath });
+  const message = String(error?.message ?? error ?? '');
+
+  if (/node:sqlite support|Node 22\+/i.test(message)) {
+    return buildStorageDiagnostic({
+      ...base,
+      filePath,
+      issue: 'unavailable',
+      status: 'error',
+      message: 'SQLite runtime support is unavailable in this Node.js process.',
+      recommendedActions: [
+        'Use Node 22+ for SQLite-backed state.',
+        'If you must stay on an older runtime, fall back to legacy JSON/JSONL storage paths only.',
+      ],
+      details: { errorMessage: message, readOnly },
+    });
+  }
+
+  if (/database is locked|database table is locked|SQLITE_BUSY|SQLITE_LOCKED/i.test(message)) {
+    return buildStorageDiagnostic({
+      ...base,
+      filePath,
+      issue: 'locked',
+      status: 'error',
+      message: 'Project-local SQLite state is locked by another process or unfinished transaction.',
+      recommendedActions: [
+        'Close other devctx processes or wait for the active write to finish, then retry.',
+        'Use snapshot-backed reads temporarily if you only need diagnostics while the lock clears.',
+      ],
+      details: { errorMessage: message, readOnly, retriable: true },
+    });
+  }
+
+  if (/file is not a database|database disk image is malformed|malformed/i.test(message)) {
+    return buildStorageDiagnostic({
+      ...base,
+      filePath,
+      issue: 'corrupted',
+      status: 'error',
+      message: 'Project-local SQLite state appears corrupted or unreadable as a database.',
+      recommendedActions: [
+        'Back up .devctx/state.sqlite before removing or replacing it.',
+        'Delete the corrupted state file and let devctx recreate it, then re-import any legacy state if available.',
+      ],
+      details: { errorMessage: message, readOnly, retriable: false },
+    });
+  }
+
+  if (!base.exists && (readOnly || /ENOENT|no such file|unable to open database file/i.test(message))) {
+    return buildStorageDiagnostic({
+      ...base,
+      filePath,
+      issue: 'missing',
+      status: 'warning',
+      message: 'Project-local SQLite state is missing for a read-only/open request.',
+      recommendedActions: [
+        'Run a persisted devctx action to initialize state.sqlite.',
+        'Verify the configured state path if the file should already exist.',
+      ],
+      details: { errorMessage: message, readOnly },
+    });
+  }
+
+  return buildStorageDiagnostic({
+    ...base,
+    filePath,
+    issue: 'unknown',
+    status: 'error',
+    message: 'Project-local SQLite state failed an unexpected storage operation.',
+    recommendedActions: [
+      'Retry once to rule out a transient failure.',
+      'If the problem persists, inspect or back up .devctx/state.sqlite before removing it.',
+    ],
+    details: { errorMessage: message, readOnly },
+  });
+};
+
+export const diagnoseStateStorage = async ({
+  filePath = getStateDbPath(),
+  verifyIntegrity = true,
+} = {}) => {
+  const base = getStateStorageHealth({ filePath });
+  if (!verifyIntegrity || !base.exists) {
+    return base;
+  }
+
+  try {
+    const { DatabaseSync } = await loadSqliteModule();
+    const db = new DatabaseSync(filePath, { readOnly: true });
+
+    try {
+      const quickCheckRows = db.prepare('PRAGMA quick_check(1)').all();
+      const integrity = quickCheckRows?.[0]?.quick_check ?? quickCheckRows?.[0]?.quickCheck ?? 'unknown';
+      const tables = listStateTables(db);
+      const missingTables = EXPECTED_TABLES.filter((table) => !tables.includes(table));
+
+      if (integrity !== 'ok' || missingTables.length > 0) {
+        return buildStorageDiagnostic({
+          ...base,
+          filePath,
+          issue: 'corrupted',
+          status: 'error',
+          message: integrity !== 'ok'
+            ? 'Project-local SQLite state failed integrity checks.'
+            : 'Project-local SQLite state is missing expected schema tables.',
+          recommendedActions: [
+            'Back up .devctx/state.sqlite before attempting recovery.',
+            'Delete and recreate the local state if integrity issues persist after retrying.',
+          ],
+          integrity,
+          details: { missingTables },
+        });
+      }
+
+      return {
+        ...base,
+        integrity: 'ok',
+        tableCount: tables.length,
+        missingTables: [],
+      };
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    return classifyStateDbError(error, { filePath, readOnly: true });
+  }
+};
+
+const enrichStateDbError = (error, { filePath = getStateDbPath(), readOnly = false } = {}) => {
+  const storageHealth = classifyStateDbError(error, { filePath, readOnly });
+  const enriched = new Error(`${storageHealth.message} Original error: ${String(error?.message ?? error ?? 'unknown')}`);
+  enriched.cause = error;
+  enriched.code = error?.code ?? null;
+  enriched.storageHealth = storageHealth;
+  enriched.stateDbIssue = storageHealth.issue;
+  return enriched;
+};
+
 const loadSqliteModule = async () => {
   if (!sqliteModulePromise) {
     sqliteModulePromise = import('node:sqlite')
@@ -280,17 +504,21 @@ export const listStateTables = (db) =>
   `).all().map((row) => row.name);
 
 export const openStateDb = async ({ filePath = getStateDbPath(), readOnly = false } = {}) => {
-  const { DatabaseSync } = await loadSqliteModule();
-  if (!readOnly) {
-    ensureStateDir(filePath);
-  }
+  try {
+    const { DatabaseSync } = await loadSqliteModule();
+    if (!readOnly) {
+      ensureStateDir(filePath);
+    }
 
-  const db = new DatabaseSync(filePath, readOnly ? { readOnly: true } : {});
-  if (!readOnly) {
-    applyPragmas(db);
-    runStateMigrations(db);
+    const db = new DatabaseSync(filePath, readOnly ? { readOnly: true } : {});
+    if (!readOnly) {
+      applyPragmas(db);
+      runStateMigrations(db);
+    }
+    return db;
+  } catch (error) {
+    throw enrichStateDbError(error, { filePath, readOnly });
   }
-  return db;
 };
 
 export const initializeStateDb = async ({ filePath = getStateDbPath() } = {}) => {
@@ -728,9 +956,10 @@ const upsertHookTurnRow = (db, record) => {
   );
 };
 
-export const getHookTurnState = async ({ filePath = getStateDbPath(), hookKey } = {}) => withStateDb((db) =>
-  normalizeHookTurnRow(readHookTurnRow(db, hookKey))
-, { filePath });
+export const getHookTurnState = async ({ filePath = getStateDbPath(), hookKey, readOnly = false } = {}) => {
+  const reader = readOnly ? withStateDbSnapshot : withStateDb;
+  return reader((db) => normalizeHookTurnRow(readHookTurnRow(db, hookKey)), { filePath });
+};
 
 export const setHookTurnState = async ({ filePath = getStateDbPath(), hookKey, state } = {}) => withStateDb((db) => {
   const record = buildHookTurnRecord(hookKey, state);

package/src/task-runner/policy.js

@@ -0,0 +1,354 @@
+const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+const truncate = (value, maxLength = 140) => {
+  const normalized = normalizeWhitespace(value);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  if (maxLength <= 3) {
+    return '';
+  }
+
+  return `${normalized.slice(0, maxLength - 3)}...`;
+};
+
+const buildContinuePrompt = (prompt) => {
+  const normalized = normalizeWhitespace(prompt);
+  if (!normalized) {
+    return 'Continue the active devctx task using the persisted context, follow the next recommended step, and checkpoint the next milestone.';
+  }
+  return [
+    'Continue the active devctx task using the persisted context and align with the next recommended step.',
+    '',
+    `User request: ${normalized}`,
+  ].join('\n');
+};
+
+export const RUNNER_COMMANDS = Object.freeze([
+  'task',
+  'implement',
+  'continue',
+  'resume',
+  'review',
+  'debug',
+  'refactor',
+  'test',
+  'doctor',
+  'status',
+  'checkpoint',
+  'cleanup',
+]);
+
+const DOCTOR_REQUIRED_STORAGE_ISSUES = new Set([
+  'locked',
+  'corrupted',
+  'unavailable',
+  'unknown',
+]);
+
+export const WORKFLOW_COMMANDS = new Set([
+  'task',
+  'implement',
+  'continue',
+  'resume',
+  'review',
+  'debug',
+  'refactor',
+  'test',
+]);
+
+export const SPECIALIZED_WORKFLOW_COMMANDS = new Set([
+  'implement',
+  'review',
+  'debug',
+  'refactor',
+  'test',
+]);
+
+export const WORKFLOW_DEFINITIONS = Object.freeze({
+  task: {
+    label: 'generic task',
+    defaultEvent: 'milestone',
+    requirePrompt: true,
+    workflowIntent: 'implementation',
+    policyMode: 'task_guided',
+    nextTools: ['smart_context', 'smart_read', 'smart_turn(end)'],
+    checkpointStrategy: 'Checkpoint the first meaningful milestone after you validate the working set.',
+    preflight: {
+      tool: 'smart_context',
+      detail: 'minimal',
+      include: ['hints', 'graph'],
+      maxTokens: 1200,
+    },
+    buildPrompt: (prompt) => normalizeWhitespace(prompt),
+  },
+  implement: {
+    label: 'implementation task',
+    defaultEvent: 'milestone',
+    requirePrompt: true,
+    workflowIntent: 'implementation',
+    policyMode: 'implement_guided',
+    nextTools: ['smart_context', 'smart_read(symbol)', 'smart_turn(end)'],
+    checkpointStrategy: 'Checkpoint after the first real implementation slice is integrated or behavior changes materially.',
+    preflight: {
+      tool: 'smart_context',
+      detail: 'minimal',
+      include: ['hints', 'graph', 'symbolDetail'],
+      maxTokens: 1400,
+    },
+    buildPrompt: (prompt) => {
+      const normalized = normalizeWhitespace(prompt);
+      return [
+        'Implement this change using devctx context first.',
+        'Prefer compact dependency-aware context and symbol reads before broad file edits.',
+        '',
+        `Implementation target: ${normalized}`,
+      ].join('\n');
+    },
+  },
+  continue: {
+    label: 'continue task',
+    defaultEvent: 'milestone',
+    requirePrompt: false,
+    workflowIntent: 'implementation',
+    policyMode: 'continue_guided',
+    nextTools: ['smart_turn(start)', 'smart_context', 'smart_turn(end)'],
+    checkpointStrategy: 'Continue until you reach the next concrete milestone, then checkpoint it.',
+    preflight: {
+      tool: 'smart_context',
+      detail: 'minimal',
+      include: ['hints', 'graph'],
+      maxTokens: 1200,
+    },
+    buildPrompt: buildContinuePrompt,
+  },
+  resume: {
+    label: 'resume task',
+    defaultEvent: 'milestone',
+    requirePrompt: false,
+    workflowIntent: 'implementation',
+    policyMode: 'resume_guided',
+    nextTools: ['smart_turn(start)', 'smart_context', 'smart_turn(end)'],
+    checkpointStrategy: 'Resume the active session and checkpoint the next meaningful slice rather than every minor step.',
+    preflight: {
+      tool: 'smart_context',
+      detail: 'minimal',
+      include: ['hints', 'graph'],
+      maxTokens: 1200,
+    },
+    buildPrompt: buildContinuePrompt,
+  },
+  review: {
+    label: 'code review',
+    defaultEvent: 'milestone',
+    requirePrompt: false,
+    workflowIntent: 'explore',
+    policyMode: 'review_guided',
+    nextTools: ['smart_context', 'smart_read', 'smart_turn(end)'],
+    checkpointStrategy: 'Checkpoint only after concrete findings, risk assessment, or a completed review slice.',
+    preflight: {
+      tool: 'smart_context',
+      detail: 'minimal',
+      include: ['hints', 'graph'],
+      maxTokens: 1200,
+    },
+    buildPrompt: (prompt) => {
+      const normalized = normalizeWhitespace(prompt) || 'Review the relevant diff or touched code path and surface concrete findings first.';
+      return [
+        'Perform a code review using devctx context first.',
+        'Prefer diff-aware context (`smart_context(diff=true)`) and compact reads before full-file reads.',
+        '',
+        `Review target: ${normalized}`,
+      ].join('\n');
+    },
+  },
+  debug: {
+    label: 'debugging task',
+    defaultEvent: 'milestone',
+    requirePrompt: false,
+    workflowIntent: 'debug',
+    policyMode: 'debug_guided',
+    nextTools: ['smart_search(intent=debug)', 'smart_read(symbol)', 'smart_turn(end)'],
+    checkpointStrategy: 'Checkpoint after the root cause is isolated or after the fix path is narrowed materially.',
+    preflight: {
+      tool: 'smart_search',
+      intent: 'debug',
+    },
+    buildPrompt: (prompt) => {
+      const normalized = normalizeWhitespace(prompt) || 'Investigate the failing path, identify the root cause, and propose or apply the smallest correct fix.';
+      return [
+        'Debug this issue using devctx search and compact reads first.',
+        'Prefer `smart_search(intent=debug)` and `smart_read(symbol)` before broad full-file reads.',
+        '',
+        `Debug target: ${normalized}`,
+      ].join('\n');
+    },
+  },
+  refactor: {
+    label: 'refactor task',
+    defaultEvent: 'milestone',
+    requirePrompt: false,
+    workflowIntent: 'implementation',
+    policyMode: 'refactor_guided',
+    nextTools: ['smart_context', 'smart_read(symbol)', 'smart_turn(end)'],
+    checkpointStrategy: 'Checkpoint each behavior-preserving slice once the dependency edges are revalidated.',
+    preflight: {
+      tool: 'smart_context',
+      detail: 'minimal',
+      include: ['hints', 'graph', 'symbolDetail'],
+      maxTokens: 1400,
+    },
+    buildPrompt: (prompt) => {
+      const normalized = normalizeWhitespace(prompt) || 'Refactor the target area while preserving behavior and validating the main dependency edges.';
+      return [
+        'Refactor this area using devctx dependency-aware context first.',
+        'Prefer compact context, symbol-level reads, and explicit checkpointing after each meaningful slice.',
+        '',
+        `Refactor target: ${normalized}`,
+      ].join('\n');
+    },
+  },
+  test: {
+    label: 'testing task',
+    defaultEvent: 'milestone',
+    requirePrompt: false,
+    workflowIntent: 'tests',
+    policyMode: 'test_guided',
+    nextTools: ['smart_search(intent=tests)', 'smart_read(symbol)', 'smart_turn(end)'],
+    checkpointStrategy: 'Checkpoint after the target tests are added, repaired, or conclusively validated.',
+    preflight: {
+      tool: 'smart_search',
+      intent: 'tests',
+    },
+    buildPrompt: (prompt) => {
+      const normalized = normalizeWhitespace(prompt) || 'Add or repair the relevant test coverage, then verify the main expected path.';
+      return [
+        'Work in testing mode using devctx context first.',
+        'Prefer `smart_search(intent=tests)` and targeted symbol reads before writing or updating tests.',
+        '',
+        `Testing target: ${normalized}`,
+      ].join('\n');
+    },
+  },
+});
+
+export const buildWorkflowPrompt = ({ commandName, prompt }) => {
+  const definition = WORKFLOW_DEFINITIONS[commandName];
+  if (!definition) {
+    throw new Error(`Unsupported workflow command: ${commandName}`);
+  }
+
+  const effectivePrompt = definition.buildPrompt(prompt ?? '');
+  if (definition.requirePrompt && !normalizeWhitespace(effectivePrompt)) {
+    throw new Error(`prompt is required for ${commandName}`);
+  }
+
+  return effectivePrompt;
+};
+
+export const buildWorkflowPolicyProfile = ({ commandName }) => {
+  const definition = WORKFLOW_DEFINITIONS[commandName];
+  if (!definition) {
+    throw new Error(`Unsupported workflow command: ${commandName}`);
+  }
+
+  return {
+    commandName,
+    label: definition.label,
+    workflowIntent: definition.workflowIntent ?? 'implementation',
+    policyMode: definition.policyMode ?? 'guided',
+    nextTools: [...(definition.nextTools ?? [])],
+    checkpointStrategy: definition.checkpointStrategy ?? null,
+    preflight: definition.preflight ? { ...definition.preflight } : null,
+    specialized: SPECIALIZED_WORKFLOW_COMMANDS.has(commandName),
+    defaultEvent: definition.defaultEvent ?? 'milestone',
+  };
+};
+
+export const evaluateRunnerGate = ({ startResult }) => {
+  const blocked = Boolean(startResult?.mutationSafety?.blocked);
+  const storageIssue = startResult?.storageHealth?.issue ?? 'ok';
+  const storageBlocked = DOCTOR_REQUIRED_STORAGE_ISSUES.has(storageIssue);
+  const pathBlocked = startResult?.recommendedPath?.mode === 'blocked_guided';
+
+  const reasons = [];
+  if (blocked) {
+    reasons.push('mutation_blocked');
+  }
+  if (storageBlocked) {
+    reasons.push(`storage_${storageIssue}`);
+  }
+  if (pathBlocked) {
+    reasons.push('recommended_path_blocked');
+  }
+
+  const requiresDoctor = blocked || storageBlocked || pathBlocked;
+
+  return {
+    blocked,
+    storageIssue,
+    pathBlocked,
+    requiresDoctor,
+    reasons,
+  };
+};
+
+export const buildBlockedRunnerMessage = ({ commandName, gate, doctorResult }) => {
+  const doctorMessage = normalizeWhitespace(doctorResult?.message ?? '');
+  if (doctorMessage) {
+    return doctorMessage;
+  }
+
+  if (gate.storageIssue !== 'ok') {
+    return `The ${commandName} workflow is paused until storageHealth.issue=${gate.storageIssue} is remediated.`;
+  }
+
+  if (gate.blocked) {
+    return `The ${commandName} workflow is paused until mutationSafety.blocked is remediated.`;
+  }
+
+  return `The ${commandName} workflow is paused until the operational state is remediated.`;
+};
+
+export const buildRunnerBlockedResult = ({
+  commandName,
+  client,
+  prompt,
+  startResult,
+  gate,
+  doctorResult,
+  allowDegraded,
+  workflowPolicy,
+}) => ({
+  success: false,
+  command: commandName,
+  client,
+  prompt: truncate(prompt, 240),
+  blocked: true,
+  usedWrapper: false,
+  allowDegraded,
+  message: buildBlockedRunnerMessage({ commandName, gate, doctorResult }),
+  gate,
+  start: startResult,
+  doctor: doctorResult,
+  sessionId: startResult?.sessionId ?? null,
+  recommendedActions: doctorResult?.recommendedActions ?? startResult?.mutationSafety?.recommendedActions ?? [],
+  workflowPolicy,
+});
+
+export const buildCleanupPlan = ({
+  mode = 'compact',
+  apply = false,
+  retentionDays = 30,
+  keepLatestEventsPerSession = 20,
+  keepLatestMetrics = 1000,
+  vacuum = false,
+}) => ({
+  mode,
+  apply,
+  retentionDays,
+  keepLatestEventsPerSession,
+  keepLatestMetrics,
+  vacuum,
+});