@wazir-dev/cli 1.0.0

package/tooling/src/command-options.js

@@ -0,0 +1,56 @@
+function normalizeOptionKey(name) {
+  return name.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+export function parseCommandOptions(args, schema = {}) {
+  const booleanOptions = new Set(schema.boolean ?? []);
+  const stringOptions = new Set(schema.string ?? []);
+  const positional = [];
+  const options = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    const optionName = arg.slice(2);
+    const normalizedKey = normalizeOptionKey(optionName);
+
+    if (booleanOptions.has(optionName)) {
+      options[normalizedKey] = true;
+      continue;
+    }
+
+    if (stringOptions.has(optionName)) {
+      const nextValue = args[index + 1];
+
+      if (!nextValue || nextValue.startsWith('--')) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+
+      options[normalizedKey] = nextValue;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return {
+    positional,
+    options,
+  };
+}
+
+export function parsePositiveInteger(value, optionName) {
+  const parsed = Number.parseInt(value, 10);
+
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${optionName} must be a positive integer`);
+  }
+
+  return parsed;
+}

package/tooling/src/commands/validate.js

@@ -0,0 +1,320 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { listYamlFiles, readJsonFile, readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { validateAgainstSchema } from '../schema-validator.js';
+import { validateDocsAtProjectRoot } from '../checks/docs-truth.js';
+import { validateBrandTruthAtProjectRoot } from '../checks/brand-truth.js';
+import { validateRuntimeSurfaceAtProjectRoot } from '../checks/runtime-surface.js';
+import { validateBranchName } from '../checks/branches.js';
+import { validateCommits } from '../checks/commits.js';
+import { validateChangelog } from '../checks/changelog.js';
+import { runDocsDriftCheck } from '../checks/docs-drift.js';
+
+function success(stdout) {
+  return { exitCode: 0, stdout: `${stdout}\n` };
+}
+
+function failure(stderr, exitCode = 1) {
+  return { exitCode, stderr: `${stderr}\n` };
+}
+
+function notImplemented(name) {
+  return failure(`${name} is not implemented yet`, 2);
+}
+
+function resolveRepoPath(projectRoot, relativePath) {
+  const absolutePath = path.resolve(projectRoot, relativePath);
+  const projectRelativePath = path.relative(projectRoot, absolutePath);
+  const escapesProjectRoot = (
+    projectRelativePath === '..' ||
+    projectRelativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(projectRelativePath)
+  );
+
+  return {
+    absolutePath,
+    escapesProjectRoot,
+  };
+}
+
+function workflowFileName(workflowId) {
+  return `${workflowId.replaceAll('_', '-')}.md`;
+}
+
+function createTermPattern(term) {
+  const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const startsWithWord = /^\w/.test(term);
+  const endsWithWord = /\w$/.test(term);
+  const prefix = startsWithWord ? '\\b' : '';
+  const suffix = endsWithWord ? '\\b' : '';
+  return new RegExp(`${prefix}${escaped}${suffix}`, 'i');
+}
+
+function collectDeclaredContentFiles(projectRoot, manifest) {
+  const files = [
+    ...manifest.roles.map((role) => path.join(projectRoot, 'roles', `${role}.md`)),
+    ...manifest.workflows.map((workflow) => path.join(projectRoot, 'workflows', workflowFileName(workflow))),
+  ];
+
+  return files;
+}
+
+export function validateManifestAtProjectRoot(projectRoot) {
+  const manifestPath = path.join(projectRoot, 'wazir.manifest.yaml');
+  const schemaPath = path.join(projectRoot, 'schemas', 'wazir-manifest.schema.json');
+  const manifest = readYamlFile(manifestPath);
+  const schema = readJsonFile(schemaPath);
+
+  if (manifest?.manifest_version === 1) {
+    return failure(
+      'Manifest version check failed:\n' +
+      '- manifest_version 1 is no longer supported; migrate to manifest_version 2\n' +
+      '- add required fields: project.description, versioning_policy, workflows, export_targets, prohibited_terms\n' +
+      '- prohibited_terms enforcement in v2 applies only to manifest-declared role and workflow files',
+    );
+  }
+
+  const result = validateAgainstSchema(schema, manifest);
+
+  if (!result.valid) {
+    return failure(`Manifest schema validation failed:\n- ${result.errors.join('\n- ')}`);
+  }
+
+  const missingPaths = Object.entries(manifest.paths)
+    .filter(([, relativePath]) => (
+      typeof relativePath === 'string' &&
+      !relativePath.startsWith('~') &&
+      !path.isAbsolute(relativePath) &&
+      !relativePath.includes('{')
+    ))
+    .map(([name, relativePath]) => ({
+      name,
+      relativePath,
+      ...resolveRepoPath(projectRoot, relativePath),
+    }));
+
+  const escapedPaths = missingPaths.filter(({ escapesProjectRoot }) => escapesProjectRoot);
+
+  if (escapedPaths.length > 0) {
+    return failure(`Manifest path check failed:\n- ${escapedPaths.map(({ name, relativePath }) => `${name}: ${relativePath} resolves outside the project root`).join('\n- ')}`);
+  }
+
+  const nonexistentPaths = missingPaths.filter(({ absolutePath }) => !fs.existsSync(absolutePath));
+
+  if (nonexistentPaths.length > 0) {
+    return failure(`Manifest path check failed:\n- ${nonexistentPaths.map(({ name, absolutePath }) => `${name}: missing ${absolutePath}`).join('\n- ')}`);
+  }
+
+  const missingRoleFiles = manifest.roles
+    .map((role) => path.join(projectRoot, 'roles', `${role}.md`))
+    .filter((filePath) => !fs.existsSync(filePath));
+
+  if (missingRoleFiles.length > 0) {
+    return failure(`Manifest role check failed:\n- ${missingRoleFiles.map((filePath) => path.relative(projectRoot, filePath)).join('\n- ')}`);
+  }
+
+  const missingWorkflowFiles = manifest.workflows
+    .map((workflow) => path.join(projectRoot, 'workflows', workflowFileName(workflow)))
+    .filter((filePath) => !fs.existsSync(filePath));
+
+  if (missingWorkflowFiles.length > 0) {
+    return failure(`Manifest workflow check failed:\n- ${missingWorkflowFiles.map((filePath) => path.relative(projectRoot, filePath)).join('\n- ')}`);
+  }
+
+  const invalidExportTargets = manifest.export_targets
+    .filter((target) => !manifest.hosts.includes(target));
+
+  if (invalidExportTargets.length > 0) {
+    return failure(`Manifest export target check failed:\n- ${invalidExportTargets.map((target) => `${target}: export target must also be declared in hosts`).join('\n- ')}`);
+  }
+
+  const prohibitedTermMatches = [];
+
+  for (const filePath of collectDeclaredContentFiles(projectRoot, manifest)) {
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    for (const term of manifest.prohibited_terms ?? []) {
+      if (createTermPattern(term).test(content)) {
+        prohibitedTermMatches.push(`${path.relative(projectRoot, filePath)}: contains prohibited term "${term}"`);
+      }
+    }
+  }
+
+  if (prohibitedTermMatches.length > 0) {
+    return failure(`Manifest prohibited term check failed:\n- ${prohibitedTermMatches.join('\n- ')}`);
+  }
+
+  return success('Manifest is valid.');
+}
+
+export function validateHooksAtProjectRoot(projectRoot) {
+  const manifestPath = path.join(projectRoot, 'wazir.manifest.yaml');
+  const manifest = readYamlFile(manifestPath);
+  const schemaPath = path.join(projectRoot, 'schemas', 'hook.schema.json');
+  const schema = readJsonFile(schemaPath);
+  const hooksDir = path.join(projectRoot, 'hooks', 'definitions');
+  const hookFiles = listYamlFiles(hooksDir);
+  const errors = [];
+  const actualHookIds = [];
+
+  for (const hookFile of hookFiles) {
+    const hook = readYamlFile(hookFile);
+    const hookFileId = path.basename(hookFile, path.extname(hookFile));
+    const validation = validateAgainstSchema(schema, hook);
+
+    if (!validation.valid) {
+      errors.push(`${hookFileId}: ${validation.errors.join('; ')}`);
+    }
+
+    if (!hook || typeof hook !== 'object' || Array.isArray(hook)) {
+      continue;
+    }
+
+    if (hook.id !== hookFileId) {
+      errors.push(`${hookFileId}: hook id "${hook.id}" does not match filename`);
+    }
+
+    for (const host of manifest.hosts) {
+      if (!hook.host_fallback?.[host]) {
+        errors.push(`${hookFileId}: missing host_fallback.${host}`);
+      }
+    }
+
+    actualHookIds.push(hook.id);
+  }
+
+  const missingRequiredHooks = manifest.required_hooks.filter((hookId) => !actualHookIds.includes(hookId));
+  const unexpectedHooks = actualHookIds.filter((hookId) => !manifest.required_hooks.includes(hookId));
+
+  if (missingRequiredHooks.length > 0) {
+    errors.push(`Missing required hook definitions: ${missingRequiredHooks.join(', ')}`);
+  }
+
+  if (unexpectedHooks.length > 0) {
+    errors.push(`Unexpected hook definitions not declared in manifest: ${unexpectedHooks.join(', ')}`);
+  }
+
+  if (errors.length > 0) {
+    return failure(`Hook validation failed:\n- ${errors.join('\n- ')}`);
+  }
+
+  return success(`Hooks are valid. Checked ${hookFiles.length} definition files.`);
+}
+
+function extractFlag(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1 || index + 1 >= args.length) return undefined;
+  return args[index + 1];
+}
+
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+export function runValidateCommand(parsed, context = {}) {
+  const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+
+  switch (parsed.subcommand) {
+    case 'manifest':
+      return validateManifestAtProjectRoot(projectRoot);
+    case 'hooks':
+      return validateHooksAtProjectRoot(projectRoot);
+    case 'artifacts':
+      return notImplemented('wazir validate artifacts');
+    case 'docs':
+      return validateDocsAtProjectRoot(projectRoot);
+    case 'brand':
+      return validateBrandTruthAtProjectRoot(projectRoot);
+    case 'runtime':
+      return validateRuntimeSurfaceAtProjectRoot(projectRoot);
+    case 'branches':
+      return validateBranchName(extractFlag(parsed.args, '--branch'), { cwd: projectRoot });
+    case 'commits':
+      return validateCommits({
+        base: extractFlag(parsed.args, '--base'),
+        head: extractFlag(parsed.args, '--head'),
+        cwd: projectRoot,
+      });
+    case 'changelog':
+      return validateChangelog(projectRoot, {
+        head: extractFlag(parsed.args, '--head'),
+        base: extractFlag(parsed.args, '--base'),
+        requireEntries: hasFlag(parsed.args, '--require-entries'),
+      });
+    case 'docs-drift':
+      return runDocsDriftCheck({
+        base: extractFlag(parsed.args, '--base'),
+        head: extractFlag(parsed.args, '--head'),
+        strict: hasFlag(parsed.args, '--strict'),
+        cwd: projectRoot,
+      });
+    default: {
+      if (parsed.subcommand != null) {
+        return failure(`Unknown validator: ${parsed.subcommand}\nUsage: wazir validate <manifest|hooks|docs|brand|runtime|branches|commits|changelog|docs-drift>`);
+      }
+
+      if (parsed.args.length > 0) {
+        return failure('Flags require a subcommand. Specify a subcommand, e.g.: wazir validate commits --base HEAD~5');
+      }
+
+      const hasGit = (() => {
+        try {
+          execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: projectRoot, stdio: 'pipe' });
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+      const hasBranch = hasGit && (() => {
+        try {
+          const name = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: projectRoot, encoding: 'utf8', stdio: 'pipe' }).trim();
+          return name !== 'HEAD';
+        } catch {
+          return false;
+        }
+      })();
+      const hasChangelog = fs.existsSync(path.join(projectRoot, 'CHANGELOG.md'));
+
+      const validators = [
+        { name: 'manifest', fn: () => validateManifestAtProjectRoot(projectRoot) },
+        { name: 'hooks', fn: () => validateHooksAtProjectRoot(projectRoot) },
+        { name: 'docs', fn: () => validateDocsAtProjectRoot(projectRoot) },
+        { name: 'brand', fn: () => validateBrandTruthAtProjectRoot(projectRoot) },
+        { name: 'runtime', fn: () => validateRuntimeSurfaceAtProjectRoot(projectRoot) },
+        { name: 'branches', fn: () => validateBranchName(undefined, { cwd: projectRoot }), available: hasBranch },
+        { name: 'commits', fn: () => validateCommits({ cwd: projectRoot }), available: hasGit },
+        { name: 'changelog', fn: () => validateChangelog(projectRoot, {}), available: hasChangelog },
+      ];
+
+      const lines = [];
+      let failed = false;
+
+      for (const { name, fn, available } of validators) {
+        if (available === false) {
+          lines.push(`SKIP ${name}: prerequisite not available`);
+          continue;
+        }
+        let result;
+        try {
+          result = fn();
+        } catch (error) {
+          failed = true;
+          lines.push(`FAIL ${name}: ${error.message}`);
+          continue;
+        }
+        const status = result.exitCode === 0 ? 'PASS' : 'FAIL';
+        if (result.exitCode !== 0) failed = true;
+        lines.push(`${status} ${name}: ${(result.stdout || result.stderr || '').trim()}`);
+      }
+
+      const output = lines.join('\n');
+      return failed ? failure(output) : success(output);
+    }
+  }
+}

package/tooling/src/doctor/command.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { resolveStateRoot } from '../state-root.js';
+import {
+  validateHooksAtProjectRoot,
+  validateManifestAtProjectRoot,
+} from '../commands/validate.js';
+
+function success(payload, options = {}) {
+  if (options.json) {
+    return {
+      exitCode: payload.healthy ? 0 : 1,
+      stdout: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+  }
+
+  const lines = payload.checks.map((check) => `${check.status.toUpperCase()} ${check.name}: ${check.detail}`);
+  return {
+    exitCode: payload.healthy ? 0 : 1,
+    stdout: `${lines.join('\n')}\n`,
+  };
+}
+
+export function runDoctorCommand(parsed, context = {}) {
+  try {
+    if (parsed.subcommand) {
+      return {
+        exitCode: 1,
+        stderr: 'Usage: wazir doctor [--json]\n',
+      };
+    }
+
+    const wantsJson = parsed.args.includes('--json');
+    const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+    const manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+    const defaultStateRoot = resolveStateRoot(projectRoot, manifest, {
+      cwd: context.cwd ?? process.cwd(),
+    });
+    const checks = [];
+
+    const manifestResult = validateManifestAtProjectRoot(projectRoot);
+    checks.push({
+      name: 'manifest',
+      status: manifestResult.exitCode === 0 ? 'pass' : 'fail',
+      detail: manifestResult.exitCode === 0 ? 'Manifest is valid.' : manifestResult.stderr.trim(),
+    });
+
+    const hooksResult = validateHooksAtProjectRoot(projectRoot);
+    checks.push({
+      name: 'hooks',
+      status: hooksResult.exitCode === 0 ? 'pass' : 'fail',
+      detail: hooksResult.exitCode === 0 ? 'Hook definitions are valid.' : hooksResult.stderr.trim(),
+    });
+
+    const defaultStateInsideRepo = !path.relative(projectRoot, defaultStateRoot).startsWith('..');
+    checks.push({
+      name: 'state-root',
+      status: defaultStateInsideRepo ? 'fail' : 'pass',
+      detail: defaultStateInsideRepo
+        ? `${defaultStateRoot} resolves inside the project root`
+        : `${defaultStateRoot} stays outside the project root`,
+    });
+
+    const missingHostExports = manifest.hosts.filter((host) => {
+      const exportPath = path.join(projectRoot, 'exports', 'hosts', host);
+      return !fs.existsSync(exportPath);
+    });
+    checks.push({
+      name: 'host-exports',
+      status: missingHostExports.length === 0 ? 'pass' : 'fail',
+      detail: missingHostExports.length === 0
+        ? 'All required host export directories exist.'
+        : `Missing export directories for: ${missingHostExports.join(', ')}`,
+    });
+
+    return success({
+      healthy: checks.every((check) => check.status === 'pass'),
+      project_root: projectRoot,
+      state_root_default: defaultStateRoot,
+      checks,
+    }, { json: wantsJson });
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stderr: `${error.message}\n`,
+    };
+  }
+}

package/tooling/src/export/command.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+
+import { findProjectRoot } from '../project-root.js';
+import {
+  validateHooksAtProjectRoot,
+  validateManifestAtProjectRoot,
+} from '../commands/validate.js';
+import {
+  buildHostExports,
+  checkHostExportDrift,
+} from './compiler.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`,
+  };
+}
+
+export function runExportCommand(parsed, context = {}) {
+  try {
+    const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+    const wantsJson = parsed.args.includes('--json');
+    const wantsCheck = parsed.args.includes('--check');
+
+    const manifestResult = validateManifestAtProjectRoot(projectRoot);
+    if (manifestResult.exitCode !== 0) {
+      return manifestResult;
+    }
+
+    const hooksResult = validateHooksAtProjectRoot(projectRoot);
+    if (hooksResult.exitCode !== 0) {
+      return hooksResult;
+    }
+
+    if (parsed.subcommand === 'build') {
+      const summary = buildHostExports(projectRoot);
+      return success(summary, {
+        json: wantsJson,
+        formatText: (value) => {
+          const warningSuffix = value.warnings?.length
+            ? ` Warnings: ${value.warnings.join('; ')}.`
+            : '';
+          return `Generated host exports for ${value.hosts.join(', ')}.${warningSuffix}`;
+        },
+      });
+    }
+
+    if (wantsCheck && !parsed.subcommand) {
+      const drifts = checkHostExportDrift(projectRoot);
+
+      if (drifts.length > 0) {
+        return failure(`Export drift detected:\n- ${drifts.join('\n- ')}`);
+      }
+
+      return success('Export drift check passed.');
+    }
+
+    return failure('Usage: wazir export build [--json] | wazir export --check', 2);
+  } catch (error) {
+    return failure(error.message);
+  }
+}