@wazir-dev/cli 1.0.0

package/tooling/src/checks/commits.js

@@ -0,0 +1,102 @@
+import { execFileSync } from 'node:child_process';
+
+const CONVENTIONAL_PATTERN = /^(feat|fix|docs|chore|refactor|test|ci|perf|build)(\(.+\))?!?:\s.+/;
+const MERGE_PATTERN = /^Merge\s/;
+
+function getCommitsSinceBase(base, head, cwd) {
+  const range = head ? `${base}..${head}` : `${base}..HEAD`;
+  try {
+    const output = execFileSync('git', ['log', range, '--format=%s'], {
+      encoding: 'utf8',
+      cwd: cwd || process.cwd(),
+    });
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+function getCurrentBranch(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf8',
+      cwd: cwd || process.cwd(),
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function refExists(ref, cwd) {
+  try {
+    execFileSync('git', ['rev-parse', '--verify', ref], {
+      encoding: 'utf8',
+      cwd: cwd || process.cwd(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectBase(cwd) {
+  const branch = getCurrentBranch(cwd);
+
+  // Hotfix branches diff against main per git-flow
+  if (branch && branch.startsWith('hotfix/')) {
+    for (const ref of ['main', 'origin/main']) {
+      if (refExists(ref, cwd)) return ref;
+    }
+  }
+
+  // Everything else diffs against develop, falling back to main
+  for (const ref of ['develop', 'origin/develop', 'main', 'origin/main']) {
+    if (refExists(ref, cwd)) return ref;
+  }
+
+  return null;
+}
+
+export function validateCommits(options = {}) {
+  const base = options.base || detectBase(options.cwd);
+
+  if (!base) {
+    return {
+      exitCode: 1,
+      stderr: 'Commit validation failed:\n- Could not determine base branch (tried develop, main)\n',
+    };
+  }
+
+  const commits = getCommitsSinceBase(base, options.head, options.cwd);
+
+  if (commits === null) {
+    return {
+      exitCode: 1,
+      stderr: `Commit validation failed:\n- Could not read git log for range "${base}..${options.head || 'HEAD'}"\n`,
+    };
+  }
+
+  if (commits.length === 0) {
+    return {
+      exitCode: 0,
+      stdout: `Commit validation passed: no commits to check since "${base}"\n`,
+    };
+  }
+
+  const failures = commits.filter(
+    (msg) => !CONVENTIONAL_PATTERN.test(msg) && !MERGE_PATTERN.test(msg),
+  );
+
+  if (failures.length > 0) {
+    return {
+      exitCode: 1,
+      stderr: `Commit validation failed:\n- ${failures.map((msg) => `Non-conventional: "${msg}"`).join('\n- ')}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `Commit validation passed: ${commits.length} commit(s) checked against "${base}"\n`,
+  };
+}

package/tooling/src/checks/docs-drift.js

@@ -0,0 +1,103 @@
+import { execFileSync } from 'node:child_process';
+
+/**
+ * File-pair mapping: source directory prefixes to their documentation files.
+ * When a file under a source prefix changes, the corresponding doc file
+ * should also change to stay current.
+ */
+export const DOC_PAIRS = [
+  { source: 'roles/', doc: 'docs/reference/roles-reference.md' },
+  { source: 'workflows/', doc: 'docs/concepts/roles-and-workflows.md' },
+  { source: 'skills/', doc: 'docs/reference/skills.md' },
+  { source: 'hooks/definitions/', doc: 'docs/reference/hooks.md' },
+  { source: 'tooling/src/capture/', doc: 'docs/reference/tooling-cli.md' },
+  { source: 'tooling/src/checks/', doc: 'docs/reference/tooling-cli.md' },
+  { source: 'tooling/src/index/', doc: 'docs/concepts/indexing-and-recall.md' },
+  { source: 'tooling/src/recall/', doc: 'docs/concepts/indexing-and-recall.md' },
+];
+
+/**
+ * Pure logic: given a list of changed file paths, determine which doc files
+ * are potentially stale (source changed but doc did not).
+ *
+ * @param {string[]} changedFiles - List of changed file paths (repo-relative)
+ * @returns {{ drifted: Array<{ source: string, doc: string }> }}
+ */
+export function checkDocsDrift(changedFiles) {
+  const changedSet = new Set(changedFiles);
+
+  // Collect unique doc targets that have at least one source change
+  // but where the doc itself did not change.
+  const driftedDocs = new Map(); // doc -> [source prefixes that triggered]
+
+  for (const file of changedFiles) {
+    for (const pair of DOC_PAIRS) {
+      if (file.startsWith(pair.source)) {
+        if (!changedSet.has(pair.doc)) {
+          if (!driftedDocs.has(pair.doc)) {
+            driftedDocs.set(pair.doc, new Set());
+          }
+          driftedDocs.get(pair.doc).add(pair.source);
+        }
+      }
+    }
+  }
+
+  const drifted = [];
+  for (const [doc, sources] of driftedDocs) {
+    for (const source of sources) {
+      drifted.push({ source, doc });
+    }
+  }
+
+  return { drifted };
+}
+
+/**
+ * Run docs-drift detection using git diff.
+ *
+ * @param {object} options
+ * @param {string} [options.base='main'] - Base ref for git diff
+ * @param {string} [options.head='HEAD'] - Head ref for git diff
+ * @param {boolean} [options.strict=false] - Exit 1 on drift instead of 0
+ * @param {string} [options.cwd] - Working directory
+ * @returns {{ exitCode: number, stdout?: string, stderr?: string }}
+ */
+export function runDocsDriftCheck({ base = 'main', head = 'HEAD', strict = false, cwd } = {}) {
+  let changedFiles;
+  try {
+    const output = execFileSync(
+      'git',
+      ['diff', '--name-only', `${base}..${head}`],
+      { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+    changedFiles = output.trim().split('\n').filter(Boolean);
+  } catch (error) {
+    // If the git range is empty or invalid, treat as no changes
+    if (error.stderr && error.stderr.includes('unknown revision')) {
+      return { exitCode: 0, stdout: 'No git range found; skipping docs-drift check.\n' };
+    }
+    return { exitCode: 1, stderr: `Failed to run git diff: ${error.message}\n` };
+  }
+
+  if (changedFiles.length === 0) {
+    return { exitCode: 0, stdout: 'No files changed in range; no drift detected.\n' };
+  }
+
+  const { drifted } = checkDocsDrift(changedFiles);
+
+  if (drifted.length === 0) {
+    return { exitCode: 0, stdout: 'No documentation drift detected.\n' };
+  }
+
+  const warnings = drifted.map(
+    ({ source, doc }) => `  - ${source}* changed but ${doc} did not`,
+  );
+  const message = `Documentation drift detected:\n${warnings.join('\n')}\n`;
+
+  if (strict) {
+    return { exitCode: 1, stderr: message };
+  }
+
+  return { exitCode: 0, stdout: `[advisory] ${message}` };
+}

package/tooling/src/checks/docs-truth.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readJsonFile, readYamlFile } from '../loaders.js';
+import { validateAgainstSchema } from '../schema-validator.js';
+import { SUPPORTED_COMMAND_SUBJECTS } from './command-registry.js';
+
+const EXCLUDED_DOC_DIRS = new Set(['daemon', 'plans', 'research', 'audit']);
+
+function walkMarkdownFiles(dirPath, files = []) {
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_DOC_DIRS.has(entry.name)) {
+        walkMarkdownFiles(path.join(dirPath, entry.name), files);
+      }
+      continue;
+    }
+
+    if (entry.name.endsWith('.md')) {
+      files.push(path.join(dirPath, entry.name));
+    }
+  }
+
+  return files;
+}
+
+function listActiveDocFiles(projectRoot) {
+  return [
+    path.join(projectRoot, 'README.md'),
+    ...walkMarkdownFiles(path.join(projectRoot, 'docs')),
+  ].filter((filePath) => fs.existsSync(filePath));
+}
+
+function normalizeCommandSubject(commandText) {
+  const tokens = commandText.trim().split(/\s+/).filter(Boolean);
+
+  if (tokens[0] !== 'wazir' || tokens.length < 2) {
+    return null;
+  }
+
+  const family = tokens[1];
+  const thirdToken = tokens[2];
+
+  if (!thirdToken || thirdToken === '...' || thirdToken === '*') {
+    return `wazir ${family}`;
+  }
+
+  if (thirdToken === '--check' && family === 'export') {
+    return 'wazir export --check';
+  }
+
+  if (thirdToken.startsWith('--') || thirdToken.startsWith('<')) {
+    return `wazir ${family}`;
+  }
+
+  return `wazir ${family} ${thirdToken}`;
+}
+
+function extractCommandSubjects(content) {
+  const subjects = new Set();
+  const pattern = /`([^`\n]+)`/g;
+
+  for (const match of content.matchAll(pattern)) {
+    const codeSpan = match[1].trim();
+
+    if (!codeSpan.startsWith('wazir ')) {
+      continue;
+    }
+
+    const subject = normalizeCommandSubject(codeSpan);
+
+    if (subject) {
+      subjects.add(subject);
+    }
+  }
+
+  return subjects;
+}
+
+function extractLocalLinks(content) {
+  const links = [];
+  const pattern = /\[[^\]]+\]\(([^)]+)\)/g;
+
+  for (const match of content.matchAll(pattern)) {
+    const rawTarget = match[1].trim();
+
+    if (
+      !rawTarget ||
+      rawTarget.startsWith('#') ||
+      rawTarget.startsWith('http://') ||
+      rawTarget.startsWith('https://') ||
+      rawTarget.startsWith('mailto:')
+    ) {
+      continue;
+    }
+
+    links.push(rawTarget.split('#', 1)[0]);
+  }
+
+  return links;
+}
+
+function loadClaims(projectRoot) {
+  const claimsPath = path.join(projectRoot, 'docs', 'truth-claims.yaml');
+  const rawClaims = readYamlFile(claimsPath);
+
+  if (!Array.isArray(rawClaims)) {
+    throw new Error('docs/truth-claims.yaml must be a YAML array of claim objects');
+  }
+
+  const schema = readJsonFile(path.join(projectRoot, 'schemas', 'docs-claim.schema.json'));
+  const errors = [];
+  const seenIds = new Set();
+  const claims = [];
+
+  for (const claim of rawClaims) {
+    const validation = validateAgainstSchema(schema, claim);
+
+    if (!validation.valid) {
+      errors.push(`docs claim ${(claim && claim.id) || '<missing-id>'}: ${validation.errors.join('; ')}`);
+      continue;
+    }
+
+    if (seenIds.has(claim.id)) {
+      errors.push(`duplicate docs claim id: ${claim.id}`);
+      continue;
+    }
+
+    seenIds.add(claim.id);
+    claims.push(claim);
+  }
+
+  return { claimsPath, claims, errors };
+}
+
+export function validateDocsAtProjectRoot(projectRoot) {
+  const errors = [];
+  const { claimsPath, claims, errors: claimErrors } = loadClaims(projectRoot);
+  errors.push(...claimErrors);
+
+  const activeDocFiles = listActiveDocFiles(projectRoot);
+  const documentedCommandSubjects = new Set();
+
+  for (const filePath of activeDocFiles) {
+    const relativeFilePath = path.relative(projectRoot, filePath);
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    for (const subject of extractCommandSubjects(content)) {
+      documentedCommandSubjects.add(subject);
+    }
+
+    for (const linkTarget of extractLocalLinks(content)) {
+      const resolvedTarget = path.resolve(path.dirname(filePath), linkTarget);
+
+      if (!fs.existsSync(resolvedTarget)) {
+        errors.push(`${relativeFilePath}: local doc link target missing ${linkTarget}`);
+      }
+    }
+  }
+
+  const commandClaims = claims.filter((claim) => claim.claim_type === 'command');
+
+  for (const subject of documentedCommandSubjects) {
+    if (!commandClaims.some((claim) => claim.subject === subject)) {
+      errors.push(`missing docs truth claim for documented command: ${subject}`);
+    }
+  }
+
+  for (const claim of commandClaims) {
+    if (!SUPPORTED_COMMAND_SUBJECTS.has(claim.subject)) {
+      errors.push(`${claim.id}: unsupported command subject ${claim.subject}`);
+    }
+
+    if (!documentedCommandSubjects.has(claim.subject)) {
+      errors.push(`${claim.id}: undocumented command claim ${claim.subject}`);
+    }
+  }
+
+  for (const claim of claims) {
+    const absoluteSubjectPath = path.resolve(projectRoot, claim.subject);
+
+    if (claim.claim_type === 'path' || claim.claim_type === 'generated_file' || claim.claim_type === 'example' || claim.claim_type === 'host_quickstart') {
+      if (!fs.existsSync(absoluteSubjectPath)) {
+        errors.push(`${claim.id}: missing claimed path ${claim.subject}`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      exitCode: 1,
+      stderr: `Docs truth validation failed:\n- ${errors.join('\n- ')}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `Docs truth validation passed. Checked ${claims.length} claims across ${activeDocFiles.length} active docs.\n`,
+  };
+}
+

package/tooling/src/checks/runtime-surface.js

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readJsonFile } from '../loaders.js';
+
+const EXCLUDED_DOC_DIRS = new Set(['plans']);
+const EXCLUDED_DOC_FILES = new Set([
+  'terminology-policy.md',
+]);
+
+const FORBIDDEN_TEXT_PATTERNS = [
+  { label: '.agent-os path', regex: /\.agent-os\//g },
+  { label: 'tasks/input path', regex: /\btasks\/input\//g },
+  { label: 'tasks/clarified path', regex: /\btasks\/clarified\//g },
+  { label: 'legacy run wrapper', regex: /\/run-(clarifier|orchestrator|opus-reviewer)\b/g },
+  { label: 'legacy daemon binary', regex: /\bagent-os-(daemon|run|review|orchestrate)\b/g },
+  { label: 'legacy npx invocation', regex: /\bnpx agent-os-[a-z-]+\b/g },
+  { label: 'daemon workflow config', regex: /daemon\/WORKFLOW\.md/g },
+];
+
+const FORBIDDEN_DEPENDENCIES = new Set(['express', 'fastify', 'koa', 'socket.io']);
+const EXCLUDED_CHECK_PATHS = new Set([
+  'tooling/src/checks/runtime-surface.js',
+  'tooling/src/checks/brand-truth.js',
+]);
+
+function toProjectRelativePath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath).split(path.sep).join('/');
+}
+
+function walkMarkdownFiles(dirPath, files = []) {
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_DOC_DIRS.has(entry.name)) {
+        walkMarkdownFiles(path.join(dirPath, entry.name), files);
+      }
+      continue;
+    }
+
+    if (entry.name.endsWith('.md') && !EXCLUDED_DOC_FILES.has(entry.name)) {
+      files.push(path.join(dirPath, entry.name));
+    }
+  }
+
+  return files;
+}
+
+function walkFiles(dirPath, files = []) {
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const absolutePath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      walkFiles(absolutePath, files);
+      continue;
+    }
+
+    files.push(absolutePath);
+  }
+
+  return files;
+}
+
+function collectRuntimeSurfaceFiles(projectRoot) {
+  return [
+    path.join(projectRoot, 'README.md'),
+    path.join(projectRoot, 'CLAUDE.md'),
+    path.join(projectRoot, 'AGENTS.md'),
+    path.join(projectRoot, 'CHANGELOG.md'),
+    ...walkMarkdownFiles(path.join(projectRoot, 'docs')),
+    ...walkFiles(path.join(projectRoot, 'expertise')),
+    ...walkFiles(path.join(projectRoot, 'examples')),
+    ...walkFiles(path.join(projectRoot, 'roles')),
+    ...walkFiles(path.join(projectRoot, 'workflows')),
+    ...walkFiles(path.join(projectRoot, 'skills')),
+    path.join(projectRoot, 'hooks', 'README.md'),
+    path.join(projectRoot, 'hooks', 'session-start'),
+    path.join(projectRoot, 'templates', 'README.md'),
+    ...walkFiles(path.join(projectRoot, 'templates', 'artifacts')),
+    ...walkFiles(path.join(projectRoot, 'tooling', 'src')),
+    ...walkFiles(path.join(projectRoot, 'exports', 'hosts')),
+  ]
+    .filter((filePath) => fs.existsSync(filePath) && fs.statSync(filePath).isFile())
+    .filter((filePath) => !EXCLUDED_CHECK_PATHS.has(toProjectRelativePath(projectRoot, filePath)));
+}
+
+function normalizeAllowedLegacyReferences(content) {
+  return content
+    .replace(/archive\/legacy-agent-os\/[^\s)`]*/g, 'archive/<legacy>')
+    .replace(/archive\/v5\.1-agent-os-daemon\/[^\s)`]*/g, 'archive/<legacy>')
+    .replace(/migration\/v5\.1-agent-os-to-wazir\.md/g, 'migration/<legacy>');
+}
+
+function assertGlobalPatternConfiguration() {
+  for (const pattern of FORBIDDEN_TEXT_PATTERNS) {
+    if (!pattern.regex.global) {
+      throw new Error(`Runtime surface pattern "${pattern.label}" must use a global regex so lastIndex resets are reliable.`);
+    }
+  }
+}
+
+export function validateRuntimeSurfaceAtProjectRoot(projectRoot) {
+  assertGlobalPatternConfiguration();
+  const errors = [];
+  const packageJson = readJsonFile(path.join(projectRoot, 'package.json'));
+  const dependencyNames = new Set([
+    ...Object.keys(packageJson.dependencies ?? {}),
+    ...Object.keys(packageJson.devDependencies ?? {}),
+  ]);
+
+  if (Object.keys(packageJson.bin ?? {}).some((binName) => binName !== 'wazir')) {
+    errors.push('package.json: only the "wazir" bin is allowed on the active surface');
+  }
+
+  if (Object.values(packageJson.bin ?? {}).some((binPath) => String(binPath).includes('daemon'))) {
+    errors.push('package.json: active bin paths must not point at daemon entrypoints');
+  }
+
+  for (const dependencyName of dependencyNames) {
+    if (FORBIDDEN_DEPENDENCIES.has(dependencyName)) {
+      errors.push(`package.json: forbidden runtime dependency "${dependencyName}" is present on the active surface`);
+    }
+  }
+
+  for (const filePath of collectRuntimeSurfaceFiles(projectRoot)) {
+    const relativePath = path.relative(projectRoot, filePath);
+    const content = normalizeAllowedLegacyReferences(fs.readFileSync(filePath, 'utf8'));
+
+    for (const pattern of FORBIDDEN_TEXT_PATTERNS) {
+      pattern.regex.lastIndex = 0;
+
+      if (pattern.regex.test(content)) {
+        errors.push(`${relativePath}: contains forbidden runtime-surface pattern "${pattern.label}"`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      exitCode: 1,
+      stderr: `Runtime surface validation failed:\n- ${errors.join('\n- ')}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: 'Runtime surface validation passed.\n',
+  };
+}

package/tooling/src/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { runCaptureCommand } from './capture/command.js';
+import { runValidateCommand } from './commands/validate.js';
+import { runDoctorCommand } from './doctor/command.js';
+import { runExportCommand as runGeneratedExportCommand } from './export/command.js';
+import { runIndexCommand } from './index/command.js';
+import { runRecallCommand } from './recall/command.js';
+import { runStatusCommand } from './status/command.js';
+
+const COMMAND_FAMILIES = [
+  'export',
+  'validate',
+  'doctor',
+  'index',
+  'recall',
+  'status',
+  'capture'
+];
+
+const COMMAND_HANDLERS = {
+  export: runGeneratedExportCommand,
+  validate: runValidateCommand,
+  doctor: runDoctorCommand,
+  index: runIndexCommand,
+  recall: runRecallCommand,
+  status: runStatusCommand,
+  capture: runCaptureCommand,
+};
+
+export function parseArgs(argv) {
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) {
+    return {
+      command: null,
+      subcommand: null,
+      args: [],
+      help: true
+    };
+  }
+
+  const [command, maybeSubcommand, ...rest] = argv;
+  const hasSubcommand = maybeSubcommand && !maybeSubcommand.startsWith('-');
+
+  return {
+    command,
+    subcommand: hasSubcommand ? maybeSubcommand : null,
+    args: hasSubcommand ? rest : [maybeSubcommand, ...rest].filter(Boolean),
+    help: false
+  };
+}
+
+export function renderHelp() {
+  return [
+    'wazir',
+    '',
+    'Host-native engineering OS kit CLI',
+    '',
+    'Commands:',
+    ...COMMAND_FAMILIES.map((name) => `  - ${name}`)
+  ].join('\n');
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv);
+
+  if (parsed.help || !parsed.command) {
+    console.log(renderHelp());
+    return 0;
+  }
+
+  if (!COMMAND_FAMILIES.includes(parsed.command)) {
+    console.error(`Unknown command: ${parsed.command}`);
+    return 1;
+  }
+
+  const handler = COMMAND_HANDLERS[parsed.command];
+
+  if (!handler) {
+    console.error(`wazir ${parsed.command} is not implemented yet`);
+    return 2;
+  }
+
+  let result;
+
+  try {
+    result = handler(parsed);
+  } catch (error) {
+    console.error(error.message);
+    return 1;
+  }
+
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  return result.exitCode;
+}
+
+function isDirectExecution() {
+  if (!process.argv[1]) {
+    return false;
+  }
+
+  return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+}
+
+if (isDirectExecution()) {
+  process.exitCode = main();
+}