all-hands-cli 0.1.0

package/.allhands/harness/src/lib/schema.ts

@@ -0,0 +1,418 @@
+/**
+ * Schema Validation Library
+ *
+ * Loads YAML schema definitions and validates frontmatter/content against them.
+ * Schemas are the single source of truth for file structure requirements.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parse as parseYaml } from 'yaml';
+import { minimatch } from 'minimatch';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface SchemaField {
+  type: 'string' | 'integer' | 'boolean' | 'date' | 'enum' | 'array' | 'object';
+  required?: boolean;
+  default?: unknown;
+  description?: string;
+  values?: string[]; // for enum type
+  items?: string; // for array type (item type)
+  properties?: Record<string, SchemaField>; // for object type
+}
+
+export interface BodySection {
+  name: string;
+  required: boolean;
+  description?: string;
+}
+
+export interface Schema {
+  frontmatter?: Record<string, SchemaField>;
+  fields?: Record<string, SchemaField>; // alternative to frontmatter for status.yaml
+  body?: {
+    description?: string;
+    sections?: BodySection[];
+  };
+}
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  expected?: string;
+  received?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+
+const schemaCache = new Map<string, Schema>();
+
+/**
+ * Get the schema directory path
+ * Path: harness/src/lib/ -> harness/src/ -> harness/ -> .allhands/ -> schemas/
+ */
+function getSchemaDir(): string {
+  return join(__dirname, '..', '..', '..', 'schemas');
+}
+
+/**
+ * Load a schema by type name
+ */
+export function loadSchema(type: string): Schema | null {
+  if (schemaCache.has(type)) {
+    return schemaCache.get(type)!;
+  }
+
+  const schemaPath = join(getSchemaDir(), `${type}.yaml`);
+  if (!existsSync(schemaPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(schemaPath, 'utf-8');
+    const schema = parseYaml(content) as Schema;
+    schemaCache.set(type, schema);
+    return schema;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List available schema types
+ */
+export function listSchemas(): string[] {
+  const schemaDir = getSchemaDir();
+  if (!existsSync(schemaDir)) {
+    return [];
+  }
+
+  return readdirSync(schemaDir)
+    .filter((f) => f.endsWith('.yaml'))
+    .map((f) => f.replace('.yaml', ''));
+}
+
+/**
+ * Validate a value against a field schema
+ */
+function validateField(
+  value: unknown,
+  field: SchemaField,
+  fieldName: string
+): ValidationError | null {
+  // Check required
+  if (field.required && (value === undefined || value === null)) {
+    return {
+      field: fieldName,
+      message: `Required field is missing`,
+      expected: field.type,
+      received: 'undefined',
+    };
+  }
+
+  // If not required and not present, use default or skip
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  // Type validation
+  switch (field.type) {
+    case 'string':
+      if (typeof value !== 'string') {
+        return {
+          field: fieldName,
+          message: `Expected string`,
+          expected: 'string',
+          received: typeof value,
+        };
+      }
+      break;
+
+    case 'integer':
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return {
+          field: fieldName,
+          message: `Expected integer`,
+          expected: 'integer',
+          received: typeof value,
+        };
+      }
+      break;
+
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        return {
+          field: fieldName,
+          message: `Expected boolean`,
+          expected: 'boolean',
+          received: typeof value,
+        };
+      }
+      break;
+
+    case 'date':
+      if (typeof value !== 'string' || isNaN(Date.parse(value))) {
+        return {
+          field: fieldName,
+          message: `Expected ISO 8601 date string`,
+          expected: 'date (ISO 8601)',
+          received: String(value),
+        };
+      }
+      break;
+
+    case 'enum':
+      if (!field.values?.includes(String(value))) {
+        return {
+          field: fieldName,
+          message: `Value must be one of: ${field.values?.join(', ')}`,
+          expected: field.values?.join(' | '),
+          received: String(value),
+        };
+      }
+      break;
+
+    case 'array':
+      if (!Array.isArray(value)) {
+        return {
+          field: fieldName,
+          message: `Expected array`,
+          expected: 'array',
+          received: typeof value,
+        };
+      }
+      if (field.items) {
+        const itemType = field.items;
+        const invalidItems = itemType === 'integer'
+          ? value.some(item => typeof item !== 'number' || !Number.isInteger(item))
+          : value.some(item => typeof item !== itemType);
+        if (invalidItems) {
+          return {
+            field: fieldName,
+            message: `Array contains non-${itemType} items`,
+            expected: `${itemType}[]`,
+            received: `mixed array`,
+          };
+        }
+      }
+      break;
+
+    case 'object':
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return {
+          field: fieldName,
+          message: `Expected object`,
+          expected: 'object',
+          received: typeof value,
+        };
+      }
+      // Validate nested properties if defined
+      if (field.properties) {
+        for (const [propName, propSchema] of Object.entries(field.properties)) {
+          const propValue = (value as Record<string, unknown>)[propName];
+          const error = validateField(propValue, propSchema, `${fieldName}.${propName}`);
+          if (error) {
+            return error;
+          }
+        }
+      }
+      break;
+  }
+
+  return null;
+}
+
+/**
+ * Validate frontmatter against a schema
+ */
+export function validateFrontmatter(
+  frontmatter: Record<string, unknown>,
+  schema: Schema
+): ValidationResult {
+  const errors: ValidationError[] = [];
+  const fields = schema.frontmatter || schema.fields || {};
+
+  for (const [fieldName, fieldSchema] of Object.entries(fields)) {
+    const error = validateField(frontmatter[fieldName], fieldSchema, fieldName);
+    if (error) {
+      errors.push(error);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Extract frontmatter from markdown content
+ */
+export function extractFrontmatter(content: string): {
+  frontmatter: Record<string, unknown> | null;
+  body: string;
+} {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return { frontmatter: null, body: content };
+  }
+
+  try {
+    const frontmatter = parseYaml(match[1]) as Record<string, unknown>;
+    return { frontmatter, body: match[2] };
+  } catch {
+    return { frontmatter: null, body: content };
+  }
+}
+
+/**
+ * Validate a file's content against its schema type
+ */
+export function validateFile(
+  content: string,
+  schemaType: string
+): ValidationResult {
+  const schema = loadSchema(schemaType);
+  if (!schema) {
+    return {
+      valid: false,
+      errors: [{ field: '_schema', message: `Unknown schema type: ${schemaType}` }],
+    };
+  }
+
+  const { frontmatter } = extractFrontmatter(content);
+  if (!frontmatter) {
+    return {
+      valid: false,
+      errors: [{ field: '_frontmatter', message: 'Missing or invalid frontmatter' }],
+    };
+  }
+
+  return validateFrontmatter(frontmatter, schema);
+}
+
+/**
+ * Apply defaults from schema to frontmatter
+ */
+export function applyDefaults(
+  frontmatter: Record<string, unknown>,
+  schema: Schema
+): Record<string, unknown> {
+  const result = { ...frontmatter };
+  const fields = schema.frontmatter || schema.fields || {};
+
+  for (const [fieldName, fieldSchema] of Object.entries(fields)) {
+    if (result[fieldName] === undefined && fieldSchema.default !== undefined) {
+      result[fieldName] = fieldSchema.default;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format validation errors for display
+ */
+export function formatErrors(result: ValidationResult): string {
+  if (result.valid) {
+    return 'Validation passed';
+  }
+
+  return result.errors
+    .map((e) => {
+      let msg = `• ${e.field}: ${e.message}`;
+      if (e.expected) msg += ` (expected: ${e.expected})`;
+      if (e.received) msg += ` (got: ${e.received})`;
+      return msg;
+    })
+    .join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema Type Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SchemaType = 'prompt' | 'alignment' | 'spec' | 'documentation' | 'solution' | 'validation-suite' | 'skill' | 'workflow';
+
+interface SchemaPattern {
+  pattern: string;
+  schemaType: SchemaType;
+}
+
+const SCHEMA_PATTERNS: SchemaPattern[] = [
+  { pattern: '.planning/**/prompts/*.md', schemaType: 'prompt' },
+  { pattern: '.planning/**/alignment.md', schemaType: 'alignment' },
+  { pattern: 'specs/**/*.spec.md', schemaType: 'spec' },
+  { pattern: 'specs/roadmap/**/*.spec.md', schemaType: 'spec' },
+  { pattern: 'docs/solutions/**/*.md', schemaType: 'solution' },
+  { pattern: 'docs/**/*.md', schemaType: 'documentation' },
+  { pattern: '.allhands/validation/*.md', schemaType: 'validation-suite' },
+  { pattern: '.allhands/skills/*/SKILL.md', schemaType: 'skill' },
+  { pattern: '.allhands/workflows/*.md', schemaType: 'workflow' },
+];
+
+/**
+ * Detect which schema type applies to a file path.
+ * Uses glob pattern matching against known schema patterns.
+ *
+ * @param filePath - Absolute or relative file path
+ * @param projectDir - Optional project root directory for relative path calculation
+ * @returns The detected schema type, or null if no schema applies
+ */
+export function detectSchemaType(filePath: string, projectDir?: string): SchemaType | null {
+  // Make path relative to project
+  let relativePath = filePath;
+  if (projectDir && filePath.startsWith(projectDir)) {
+    relativePath = filePath.slice(projectDir.length + 1);
+  }
+
+  for (const { pattern, schemaType } of SCHEMA_PATTERNS) {
+    if (minimatch(relativePath, pattern)) {
+      return schemaType;
+    }
+  }
+  return null;
+}
+
+/**
+ * Infer schema type from file path using string matching.
+ * Fallback method when glob patterns don't match.
+ *
+ * @param file - File path to analyze
+ * @returns The inferred schema type, or null if unknown
+ */
+export function inferSchemaType(file: string): SchemaType | null {
+  if (file.includes('/prompts/') || file.match(/prompt.*\.md$/i)) {
+    return 'prompt';
+  }
+  if (file.includes('alignment') || file.match(/alignment\.md$/i)) {
+    return 'alignment';
+  }
+  if (file.includes('/specs/') || file.endsWith('.spec.md')) {
+    return 'spec';
+  }
+  if (file.includes('/docs/solutions/') && file.endsWith('.md')) {
+    return 'solution';
+  }
+  if (file.includes('/docs/') && file.endsWith('.md')) {
+    return 'documentation';
+  }
+  if (file.includes('/validation/') && file.endsWith('.md')) {
+    return 'validation-suite';
+  }
+  if (file.includes('/skills/') && file.endsWith('SKILL.md')) {
+    return 'skill';
+  }
+  if (file.includes('/workflows/') && file.endsWith('.md')) {
+    return 'workflow';
+  }
+  return null;
+}

package/.allhands/harness/src/lib/schemas/agent-profile.ts

@@ -0,0 +1,141 @@
+/**
+ * Agent Profile Schema
+ *
+ * Zod schema for validating agent profile YAML files.
+ * Replaces the static YAML schema with runtime validation.
+ */
+
+import { z } from 'zod';
+import { TemplateVarNameSchema, validateTemplateString, type TemplateVarName } from './template-vars.js';
+
+/**
+ * Raw agent profile as parsed from YAML (snake_case)
+ */
+export const RawAgentProfileSchema = z.object({
+  name: z.string().min(1).describe('Agent identifier (also used as tmux window name)'),
+
+  flow: z.string().min(1).describe('Flow file name relative to .allhands/flows/'),
+
+  prompt_scoped: z
+    .boolean()
+    .default(false)
+    .describe('If true, multiple instances can run (one per prompt)'),
+
+  message_template: z
+    .string()
+    .optional()
+    .describe('Template string with ${VAR} interpolation'),
+
+  template_vars: z
+    .array(TemplateVarNameSchema)
+    .optional()
+    .describe('Required variables for message_template'),
+
+  // TUI integration
+  tui_action: z
+    .string()
+    .optional()
+    .describe('TUI action name that spawns this agent (e.g., "ideation", "compound")'),
+
+  tui_label: z
+    .string()
+    .optional()
+    .describe('Display label in TUI (defaults to capitalized name)'),
+
+  tui_requires_spec: z
+    .boolean()
+    .default(false)
+    .describe('If true, TUI action requires an active spec'),
+
+  non_coding: z
+    .boolean()
+    .default(false)
+    .describe('If true, agent is non-coding (affects some behaviors)'),
+});
+
+export type RawAgentProfile = z.infer<typeof RawAgentProfileSchema>;
+
+/**
+ * Normalized agent profile (camelCase, with defaults applied)
+ */
+export interface AgentProfile {
+  name: string;
+  flow: string;
+  promptScoped: boolean;
+  messageTemplate?: string;
+  templateVars: TemplateVarName[];
+  tuiAction?: string;
+  tuiLabel?: string;
+  tuiRequiresSpec: boolean;
+  nonCoding: boolean;
+}
+
+/**
+ * Transform raw YAML profile to normalized TypeScript interface
+ */
+export function normalizeProfile(raw: RawAgentProfile): AgentProfile {
+  return {
+    name: raw.name,
+    flow: raw.flow,
+    promptScoped: raw.prompt_scoped,
+    messageTemplate: raw.message_template,
+    templateVars: (raw.template_vars ?? []) as TemplateVarName[],
+    tuiAction: raw.tui_action,
+    tuiLabel: raw.tui_label,
+    tuiRequiresSpec: raw.tui_requires_spec,
+    nonCoding: raw.non_coding,
+  };
+}
+
+/**
+ * Validation result for an agent profile
+ */
+export interface ProfileValidation {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Validate an agent profile beyond basic schema validation.
+ * Checks:
+ * - Template variables in message_template match template_vars list
+ * - No unknown template variables
+ */
+export function validateProfileSemantics(profile: AgentProfile): ProfileValidation {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Validate message_template references
+  if (profile.messageTemplate) {
+    const templateCheck = validateTemplateString(profile.messageTemplate);
+
+    if (!templateCheck.valid) {
+      errors.push(`Invalid template variables in message_template: ${templateCheck.invalidVars.join(', ')}`);
+    }
+
+    // Check that all referenced vars are in template_vars
+    const referencedVars = profile.messageTemplate.match(/\$\{([^}]+)\}/g)?.map((m) => m.slice(2, -1)) ?? [];
+
+    for (const refVar of referencedVars) {
+      if (!profile.templateVars.includes(refVar as TemplateVarName)) {
+        warnings.push(`Template references ${refVar} but it's not in template_vars list`);
+      }
+    }
+
+    // Check for unused template_vars
+    for (const declaredVar of profile.templateVars) {
+      if (!referencedVars.includes(declaredVar)) {
+        warnings.push(`template_vars declares ${declaredVar} but it's not used in message_template`);
+      }
+    }
+  } else if (profile.templateVars.length > 0) {
+    warnings.push('template_vars defined but no message_template to use them');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}

package/.allhands/harness/src/lib/schemas/template-vars.ts

@@ -0,0 +1,138 @@
+/**
+ * Template Variables Registry
+ *
+ * Single source of truth for all template variables used in agent profiles.
+ * Provides type safety, runtime validation, and self-documentation.
+ */
+
+import { z } from 'zod';
+
+/**
+ * All valid template variables that can be used in agent message_template fields.
+ * Each variable has a Zod schema for validation and a description.
+ */
+export const TemplateVars = {
+  // Path variables
+  SPEC_PATH: z.string().describe('Path to spec file'),
+  ALIGNMENT_PATH: z.string().describe('Path to alignment doc'),
+  PROMPTS_FOLDER: z.string().describe('Path to prompts directory'),
+  PROMPT_PATH: z.string().describe('Path to specific prompt file'),
+  OUTPUT_PATH: z.string().describe('Output file path'),
+  PLANNING_FOLDER: z.string().describe('Path to .planning/{branch} directory'),
+
+  // Identifier variables
+  SPEC_NAME: z.string().describe('Current spec name'),
+  PROMPT_NUMBER: z
+    .string()
+    .regex(/^\d{2}$/)
+    .describe('Prompt number as two digits (01, 02, etc.)'),
+
+  // Branch/context variables
+  BRANCH: z.string().describe('Current git branch name'),
+
+  // Spec metadata variables
+  SPEC_TYPE: z
+    .string()
+    .describe('Spec type from frontmatter (milestone, investigation, optimization, refactor, documentation, triage)'),
+
+  // Workflow domain variables
+  WORKFLOW_DOMAIN_PATH: z
+    .string()
+    .describe('Path to workflow domain config file in .allhands/workflows/'),
+
+  // Emergent planner variables
+  HYPOTHESIS_DOMAINS: z
+    .string()
+    .describe('Comma-separated list of hypothesis domains from settings.json'),
+} as const;
+
+/**
+ * Union type of all valid template variable names
+ */
+export type TemplateVarName = keyof typeof TemplateVars;
+
+/**
+ * Array of all valid template variable names (for runtime checks)
+ */
+export const TEMPLATE_VAR_NAMES = Object.keys(TemplateVars) as TemplateVarName[];
+
+/**
+ * Context object passed to template resolution.
+ * All variables are optional - validation happens against profile requirements.
+ */
+export type TemplateContext = Partial<Record<TemplateVarName, string | null>>;
+
+/**
+ * Zod schema for validating a single template variable name
+ */
+export const TemplateVarNameSchema = z.enum(TEMPLATE_VAR_NAMES as [TemplateVarName, ...TemplateVarName[]]);
+
+/**
+ * Validate that a string is a valid template variable name
+ */
+export function isValidTemplateVar(name: string): name is TemplateVarName {
+  return TEMPLATE_VAR_NAMES.includes(name as TemplateVarName);
+}
+
+/**
+ * Validate a context object against required variables.
+ * Returns errors for missing or invalid variables.
+ */
+export function validateContext(
+  context: TemplateContext,
+  requiredVars: TemplateVarName[]
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  for (const varName of requiredVars) {
+    const value = context[varName];
+
+    // Reject undefined or empty string
+    if (value === undefined || value === '') {
+      errors.push(`Missing required template variable: ${varName}`);
+      continue;
+    }
+
+    // Validate value against the variable's schema
+    const schema = TemplateVars[varName];
+    const result = schema.safeParse(value);
+
+    if (!result.success) {
+      errors.push(`Invalid value for ${varName}: ${result.error.issues[0]?.message}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Get description for a template variable
+ */
+export function getTemplateVarDescription(name: TemplateVarName): string {
+  return TemplateVars[name].description ?? name;
+}
+
+/**
+ * Extract template variable references from a template string.
+ * Returns array of variable names found in ${VAR_NAME} patterns.
+ */
+export function extractTemplateVars(template: string): string[] {
+  const matches = template.matchAll(/\$\{([^}]+)\}/g);
+  return [...matches].map((m) => m[1]);
+}
+
+/**
+ * Validate that all variables referenced in a template are valid.
+ */
+export function validateTemplateString(template: string): { valid: boolean; invalidVars: string[] } {
+  const refs = extractTemplateVars(template);
+  const invalidVars = refs.filter((v) => !isValidTemplateVar(v));
+
+  return {
+    valid: invalidVars.length === 0,
+    invalidVars,
+  };
+}