@wazir-dev/cli 1.0.0

package/tooling/src/index/summarizers.js

@@ -0,0 +1,261 @@
+/**
+ * Heuristic summarizers for L0/L1 file-level and symbol-level summaries.
+ * All functions are pure: input is indexed data, output is a string.
+ */
+
+const BOM_UTF16_LE = '\xFF\xFE';
+const BOM_UTF16_BE = '\xFE\xFF';
+const BOM_UTF32_LE = '\xFF\xFE\x00\x00';
+const BOM_UTF32_BE = '\x00\x00\xFE\xFF';
+
+const BINARY_CHECK_LIMIT = 8192;
+const L0_CAP = 400;
+const L1_CAP = 8000;
+const SYMBOL_L1_CODE_CAP = 2000;
+const SYMBOL_L1_DATA_CAP = 800;
+const KEY_VALUE_PREVIEW_CAP = 200;
+const MAX_IMPORTS = 10;
+
+const CODE_LANGUAGES = new Set([
+  'javascript', 'typescript', 'python', 'go', 'rust', 'java', 'sql',
+]);
+
+const STRUCTURED_DATA_LANGUAGES = new Set(['json', 'yaml']);
+
+/**
+ * Detect binary content with BOM guard.
+ * Checks for UTF-16/UTF-32 BOMs first (return false if found),
+ * then checks for null bytes in the first 8192 characters.
+ *
+ * @param {string} content - File content read as UTF-8 string.
+ * @returns {boolean} True if content appears to be binary.
+ */
+export function isBinaryContent(content) {
+  if (content.length === 0) return false;
+
+  // Check for UTF-32 BOMs first (4-byte, must check before 2-byte)
+  if (content.length >= 4) {
+    if (content.startsWith(BOM_UTF32_LE)) return false;
+    if (content.startsWith(BOM_UTF32_BE)) return false;
+  }
+
+  // Check for UTF-16 BOMs (2-byte)
+  if (content.length >= 2) {
+    if (content.startsWith(BOM_UTF16_LE)) return false;
+    if (content.startsWith(BOM_UTF16_BE)) return false;
+  }
+
+  // Check for null bytes in first BINARY_CHECK_LIMIT characters
+  const limit = Math.min(content.length, BINARY_CHECK_LIMIT);
+  return content.slice(0, limit).includes('\0');
+}
+
+/**
+ * Extract top-level keys from JSON content.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractJsonTopLevelKeys(content) {
+  const keys = [];
+  for (const line of content.split('\n')) {
+    const match = line.match(/^\s*"([^"]+)"\s*:/);
+    if (match) keys.push(match[1]);
+  }
+  return keys;
+}
+
+/**
+ * Extract top-level keys from YAML content.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractYamlTopLevelKeys(content) {
+  const keys = [];
+  for (const line of content.split('\n')) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*/);
+    if (match) keys.push(match[1]);
+  }
+  return keys;
+}
+
+/**
+ * Generate a file-level L0 summary (single-line abstract, capped at 400 chars).
+ *
+ * @param {string} language - Detected language (javascript, markdown, json, etc.)
+ * @param {number} lineCount - Number of lines in the file.
+ * @param {Array<{name: string, kind: string}>} symbols - Extracted symbols.
+ * @param {string} content - File content.
+ * @returns {string}
+ */
+export function generateFileL0(language, lineCount, symbols, content) {
+  if (lineCount === 0) return `${language} file (empty)`;
+  if (lineCount === 1) return `${language} file (1 line) -- ${content.trim().slice(0, 80)}`.slice(0, L0_CAP);
+
+  if (language === 'markdown') {
+    return generateMarkdownL0(content);
+  }
+
+  if (STRUCTURED_DATA_LANGUAGES.has(language)) {
+    return generateStructuredDataL0(language, lineCount, content);
+  }
+
+  return generateCodeL0(language, lineCount, symbols, content);
+}
+
+function generateMarkdownL0(content) {
+  const lines = content.split('\n');
+  const heading = lines.find((l) => /^#{1,6}\s+/.test(l));
+  const headingText = heading ? heading.replace(/^#{1,6}\s+/, '').trim() : '';
+  const firstParagraph = lines.find((l) => l.trim().length > 0 && !/^#/.test(l));
+  const parts = [headingText, firstParagraph?.trim()].filter(Boolean);
+  return parts.join(' -- ').slice(0, L0_CAP);
+}
+
+function generateStructuredDataL0(language, lineCount, content) {
+  const keys = language === 'json'
+    ? extractJsonTopLevelKeys(content)
+    : extractYamlTopLevelKeys(content);
+
+  if (keys.length === 0) {
+    const firstLine = content.split('\n').find((l) => l.trim().length > 0) || '';
+    return `${language} file (${lineCount} lines) -- ${firstLine.trim().slice(0, 80)}`.slice(0, L0_CAP);
+  }
+
+  return `${language} file (${lineCount} lines) -- keys: ${keys.join(', ')}`.slice(0, L0_CAP);
+}
+
+function generateCodeL0(language, lineCount, symbols, content) {
+  const topNames = symbols
+    .filter((s) => s.kind === 'function' || s.kind === 'class' || s.kind === 'type')
+    .slice(0, 5)
+    .map((s) => s.name);
+
+  if (topNames.length > 0) {
+    return `${language} file (${lineCount} lines) -- ${topNames.join(', ')}`.slice(0, L0_CAP);
+  }
+
+  const firstLine = content.split('\n').find((l) => l.trim().length > 0) || '';
+  return `${language} file (${lineCount} lines) -- ${firstLine.trim().slice(0, 80)}`.slice(0, L0_CAP);
+}
+
+/**
+ * Generate a file-level L1 summary (detailed overview, capped at 8000 chars).
+ *
+ * @param {string} language - Detected language.
+ * @param {Array<{name: string, kind: string, signature: string}>} symbols - Extracted symbols.
+ * @param {string} content - File content.
+ * @returns {string}
+ */
+export function generateFileL1(language, symbols, content) {
+  if (language === 'markdown') return generateMarkdownL1(content);
+  if (STRUCTURED_DATA_LANGUAGES.has(language)) return generateStructuredDataL1(language, content);
+  return generateCodeL1(symbols, content);
+}
+
+function generateCodeL1(symbols, content) {
+  const lines = content.split('\n');
+  const parts = [];
+
+  const imports = lines
+    .filter((l) => /^\s*(import\s|from\s|require\(|use\s)/.test(l))
+    .slice(0, MAX_IMPORTS);
+  if (imports.length > 0) parts.push('## Imports\n' + imports.join('\n'));
+
+  const sigs = symbols.map((s) => `${s.kind} ${s.name}: ${s.signature}`);
+  if (sigs.length > 0) parts.push('## Symbols\n' + sigs.join('\n'));
+
+  return parts.join('\n\n').slice(0, L1_CAP);
+}
+
+function generateMarkdownL1(content) {
+  const lines = content.split('\n');
+  const headings = lines.filter((l) => /^#{1,6}\s+/.test(l));
+  return headings.join('\n').slice(0, L1_CAP);
+}
+
+function generateStructuredDataL1(language, content) {
+  const lines = content.split('\n');
+  const parts = [];
+
+  for (const line of lines) {
+    const jsonMatch = line.match(/^\s*"([^"]+)"\s*:\s*(.*)/);
+    const yamlMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)/);
+    const match = jsonMatch || yamlMatch;
+
+    if (match) {
+      const key = match[1];
+      const valuePreview = match[2].trim().slice(0, 200);
+      parts.push(`${key}: ${valuePreview}`);
+    }
+  }
+
+  return parts.join('\n').slice(0, L1_CAP);
+}
+
+/**
+ * Generate a symbol-level L0 summary (single line, capped at 400 chars).
+ *
+ * @param {{name: string, kind: string, signature: string}} symbol
+ * @returns {string}
+ */
+export function generateSymbolL0(symbol) {
+  const prefix = symbol.kind === 'key' ? 'key' : symbol.kind;
+  const firstLine = symbol.signature.split('\n')[0];
+  return `${prefix} ${symbol.name} -- ${firstLine}`.slice(0, L0_CAP);
+}
+
+/**
+ * Generate a symbol-level L1 summary.
+ * Code symbols: full signature + first comment block, capped at 2000 chars.
+ * JSON/YAML key symbols: key name + value preview, capped at 800 chars.
+ *
+ * @param {{name: string, kind: string, signature: string, line_start: number, line_end: number}} symbol
+ * @param {string} fileContent - Full file content.
+ * @returns {string}
+ */
+export function generateSymbolL1(symbol, fileContent) {
+  if (symbol.kind === 'key') {
+    return generateKeySymbolL1(symbol);
+  }
+  return generateCodeSymbolL1(symbol, fileContent);
+}
+
+function generateCodeSymbolL1(symbol, fileContent) {
+  const lines = fileContent.split('\n');
+  const parts = [];
+
+  // Look backward from line_start for a comment block (/** ... */ or # ...)
+  const commentBlock = extractCommentBlock(lines, symbol.line_start - 1);
+  if (commentBlock) parts.push(commentBlock);
+
+  parts.push(symbol.signature);
+
+  return parts.join('\n').slice(0, SYMBOL_L1_CODE_CAP);
+}
+
+function extractCommentBlock(lines, symbolLineIndex) {
+  const commentLines = [];
+  // Walk backward from the line before the symbol definition
+  for (let i = symbolLineIndex - 1; i >= 0; i--) {
+    const trimmed = lines[i].trim();
+    // JSDoc/block comment lines
+    if (trimmed.startsWith('*') || trimmed.startsWith('/**') || trimmed.startsWith('*/') || trimmed.startsWith('*')) {
+      commentLines.unshift(lines[i]);
+      if (trimmed.startsWith('/**') || trimmed === '/*') break;
+    // Hash comment lines (Python, etc.)
+    } else if (trimmed.startsWith('#') && !trimmed.startsWith('#!')) {
+      commentLines.unshift(lines[i]);
+    // Empty line between comments and symbol is ok if we already have comments
+    } else if (trimmed === '' && commentLines.length === 0) {
+      continue;
+    } else {
+      break;
+    }
+  }
+  return commentLines.length > 0 ? commentLines.join('\n') : null;
+}
+
+function generateKeySymbolL1(symbol) {
+  const valuePreview = symbol.signature.slice(0, KEY_VALUE_PREVIEW_CAP);
+  return `key ${symbol.name}\n${valuePreview}`.slice(0, SYMBOL_L1_DATA_CAP);
+}

package/tooling/src/loaders.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+
+export function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function readYamlFile(filePath) {
+  return YAML.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function listYamlFiles(dirPath) {
+  return fs.readdirSync(dirPath)
+    .filter((entry) => entry.endsWith('.yaml') || entry.endsWith('.yml'))
+    .sort()
+    .map((entry) => path.join(dirPath, entry));
+}

package/tooling/src/project-root.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MANIFEST_FILE = 'wazir.manifest.yaml';
+
+export function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = path.resolve(startDir);
+
+  while (true) {
+    if (fs.existsSync(path.join(currentDir, MANIFEST_FILE))) {
+      return currentDir;
+    }
+
+    const parentDir = path.dirname(currentDir);
+
+    if (parentDir === currentDir) {
+      throw new Error(`Could not find ${MANIFEST_FILE} from ${startDir}`);
+    }
+
+    currentDir = parentDir;
+  }
+}

package/tooling/src/recall/command.js

@@ -0,0 +1,225 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseCommandOptions, parsePositiveInteger } from '../command-options.js';
+import { readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { resolveStateRoot } from '../state-root.js';
+import {
+  findSymbol,
+  hashContent,
+  logRetrieval,
+  readFileSummary,
+  readIndexedFile,
+  readSymbolSummary,
+} from '../index/storage.js';
+
+function success(payload, options = {}) {
+  if (options.json) {
+    return {
+      exitCode: 0,
+      stdout: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `${options.formatText ? options.formatText(payload) : String(payload)}\n`,
+  };
+}
+
+function failure(message, exitCode = 1) {
+  return {
+    exitCode,
+    stderr: `${message}\n`,
+  };
+}
+
+function loadProjectContext(context, stateRootOverride) {
+  const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+  const manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+  const stateRoot = resolveStateRoot(projectRoot, manifest, {
+    cwd: context.cwd ?? process.cwd(),
+    override: stateRootOverride,
+  });
+
+  return {
+    projectRoot,
+    stateRoot,
+  };
+}
+
+function readSlice(projectRoot, relativePath, lineStart, lineEnd, contextLines = 0) {
+  const absolutePath = path.join(projectRoot, relativePath);
+  const lines = fs.readFileSync(absolutePath, 'utf8').split('\n');
+  const boundedStart = Math.max(1, lineStart);
+  const boundedEnd = Math.min(lines.length, lineEnd);
+  const expandedStart = Math.max(1, boundedStart - contextLines);
+  const expandedEnd = Math.min(lines.length, boundedEnd + contextLines);
+
+  return {
+    relative_path: relativePath,
+    line_start: boundedStart,
+    line_end: boundedEnd,
+    slice: lines.slice(boundedStart - 1, boundedEnd).join('\n'),
+    context_before: lines.slice(expandedStart - 1, boundedStart - 1).join('\n'),
+    context_after: lines.slice(boundedEnd, expandedEnd).join('\n'),
+  };
+}
+
+export function runRecallCommand(parsed, context = {}) {
+  try {
+    const { positional, options } = parseCommandOptions(parsed.args, {
+      boolean: ['json'],
+      string: ['state-root', 'start-line', 'end-line', 'context', 'tier'],
+    });
+
+    if (options.tier && options.tier !== 'L0' && options.tier !== 'L1') {
+      return failure('--tier must be L0 or L1');
+    }
+
+    if (options.tier && (options.startLine || options.endLine || options.context)) {
+      return failure('--tier is mutually exclusive with --start-line, --end-line, and --context');
+    }
+
+    const { projectRoot, stateRoot } = loadProjectContext(context, options.stateRoot);
+    const contextLines = options.context ? parsePositiveInteger(options.context, '--context') : 0;
+
+    switch (parsed.subcommand) {
+      case 'file': {
+        const relativePath = positional[0];
+
+        if (!relativePath) {
+          return failure('Usage: wazir recall file <relative-path> --start-line <n> --end-line <n> [--context <n>] [--state-root <path>] [--json]');
+        }
+
+        const fileRecord = readIndexedFile(stateRoot, relativePath);
+
+        if (!fileRecord) {
+          return failure(`File is not indexed: ${relativePath}`);
+        }
+
+        if (options.tier) {
+          const summary = readFileSummary(stateRoot, fileRecord.file_id, options.tier);
+
+          if (!summary) {
+            return failure(`No ${options.tier} summary found for ${relativePath}. Run 'wazir index summarize' first.`);
+          }
+
+          let liveContent;
+          try {
+            liveContent = fs.readFileSync(path.join(projectRoot, relativePath), 'utf8');
+          } catch (err) {
+            if (err.code === 'ENOENT') {
+              return failure(`File not found on disk: ${relativePath}`);
+            }
+            return failure(`Cannot read file: ${relativePath}: ${err.message}`);
+          }
+
+          const liveHash = hashContent(liveContent);
+          const fresh = liveHash === summary.source_hash;
+
+          logRetrieval(stateRoot, 'recall-file', relativePath, 1);
+          return success({
+            relative_path: relativePath,
+            tier: options.tier,
+            slice: summary.content,
+            generator: summary.generator,
+            generated_at: summary.generated_at,
+            fresh,
+          }, {
+            json: options.json,
+            formatText: (value) => value.slice,
+          });
+        }
+
+        if (!options.startLine || !options.endLine) {
+          return failure('wazir recall file requires --start-line and --end-line');
+        }
+
+        const slice = readSlice(
+          projectRoot,
+          relativePath,
+          parsePositiveInteger(options.startLine, '--start-line'),
+          parsePositiveInteger(options.endLine, '--end-line'),
+          contextLines,
+        );
+        logRetrieval(stateRoot, 'recall-file', relativePath, 1);
+        return success(slice, {
+          json: options.json,
+          formatText: (value) => value.slice,
+        });
+      }
+      case 'symbol': {
+        const query = positional[0];
+
+        if (!query) {
+          return failure('Usage: wazir recall symbol <name-or-id> [--context <n>] [--state-root <path>] [--json]');
+        }
+
+        const symbol = findSymbol(stateRoot, query);
+
+        if (!symbol) {
+          return failure(`No indexed symbol found for "${query}"`);
+        }
+
+        if (options.tier) {
+          const summary = readSymbolSummary(stateRoot, symbol.symbol_id, options.tier);
+
+          if (!summary) {
+            return failure(`No ${options.tier} summary found for ${symbol.name}. Run 'wazir index summarize' first.`);
+          }
+
+          let liveContent;
+          try {
+            liveContent = fs.readFileSync(path.join(projectRoot, symbol.relative_path), 'utf8');
+          } catch (err) {
+            if (err.code === 'ENOENT') {
+              return failure(`File not found on disk: ${symbol.relative_path}`);
+            }
+            return failure(`Cannot read file: ${symbol.relative_path}: ${err.message}`);
+          }
+
+          const liveHash = hashContent(liveContent);
+          const fresh = liveHash === summary.source_hash;
+
+          logRetrieval(stateRoot, 'recall-symbol', query, 1);
+          return success({
+            relative_path: symbol.relative_path,
+            name: symbol.name,
+            kind: symbol.kind,
+            signature: symbol.signature,
+            tier: options.tier,
+            slice: summary.content,
+            generator: summary.generator,
+            generated_at: summary.generated_at,
+            fresh,
+          }, {
+            json: options.json,
+            formatText: (value) => value.slice,
+          });
+        }
+
+        const slice = readSlice(
+          projectRoot,
+          symbol.relative_path,
+          symbol.line_start,
+          symbol.line_end,
+          contextLines,
+        );
+        logRetrieval(stateRoot, 'recall-symbol', query, 1);
+        return success({
+          ...symbol,
+          ...slice,
+        }, {
+          json: options.json,
+          formatText: (value) => value.slice,
+        });
+      }
+      default:
+        return failure('Usage: wazir recall <file|symbol> [options]');
+    }
+  } catch (error) {
+    return failure(error.message);
+  }
+}

package/tooling/src/schema-validator.js

@@ -0,0 +1,30 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+
+const ajv = new Ajv2020({
+  allErrors: true,
+  strict: false,
+  validateFormats: false,
+});
+const validatorCache = new Map();
+
+function formatError(error) {
+  const pointer = error.instancePath || '/';
+  return `${pointer} ${error.message}`;
+}
+
+export function validateAgainstSchema(schema, data) {
+  const schemaKey = schema.$id ?? JSON.stringify(schema);
+  let validate = validatorCache.get(schemaKey);
+
+  if (!validate) {
+    validate = ajv.compile(schema);
+    validatorCache.set(schemaKey, validate);
+  }
+
+  const valid = validate(data);
+
+  return {
+    valid,
+    errors: valid ? [] : (validate.errors ?? []).map(formatError),
+  };
+}

package/tooling/src/state-root.js

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import path from 'node:path';
+
+function expandHomeDir(filePath) {
+  if (filePath === '~') {
+    return os.homedir();
+  }
+
+  if (filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+
+  return filePath;
+}
+
+function slugifyProjectName(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'wazir-project';
+}
+
+export function resolveStateRoot(projectRoot, manifest, context = {}) {
+  const cwd = context.cwd ?? process.cwd();
+  const override = context.override;
+
+  if (override) {
+    return path.resolve(cwd, override);
+  }
+
+  const template = manifest.paths.state_root_default;
+  const projectSlug = slugifyProjectName(manifest.project.name || path.basename(projectRoot));
+  const interpolated = template.replace('{project_slug}', projectSlug);
+
+  return path.resolve(expandHomeDir(interpolated));
+}
+
+export function getIndexDatabasePath(stateRoot) {
+  return path.join(stateRoot, 'index', 'index.sqlite');
+}

package/tooling/src/status/command.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseCommandOptions } from '../command-options.js';
+import { readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { resolveStateRoot } from '../state-root.js';
+
+function success(payload, options = {}) {
+  if (options.json) {
+    return {
+      exitCode: 0,
+      stdout: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `${payload.run_id} ${payload.phase} ${payload.status}\n`,
+  };
+}
+
+export function runStatusCommand(parsed, context = {}) {
+  try {
+    if (parsed.subcommand) {
+      return {
+        exitCode: 1,
+        stderr: 'Usage: wazir status --run <id> [--state-root <path>] [--json]\n',
+      };
+    }
+
+    const { options } = parseCommandOptions(parsed.args, {
+      boolean: ['json'],
+      string: ['run', 'state-root'],
+    });
+
+    if (!options.run) {
+      return {
+        exitCode: 1,
+        stderr: 'wazir status requires --run <id>\n',
+      };
+    }
+
+    const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+    const manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+    const stateRoot = resolveStateRoot(projectRoot, manifest, {
+      cwd: context.cwd ?? process.cwd(),
+      override: options.stateRoot,
+    });
+    const statusPath = path.join(stateRoot, 'runs', options.run, 'status.json');
+
+    if (!fs.existsSync(statusPath)) {
+      return {
+        exitCode: 1,
+        stderr: `Run status not found: ${statusPath}\n`,
+      };
+    }
+
+    const payload = {
+      ...JSON.parse(fs.readFileSync(statusPath, 'utf8')),
+      status_path: statusPath,
+    };
+
+    return success(payload, { json: options.json });
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stderr: `${error.message}\n`,
+    };
+  }
+}