@automagik/genie 4.260331.6 → 4.260331.8

package/src/lib/manifest.ts

@@ -1,342 +0,0 @@
-/**
- * Manifest — Genie item manifest parsing, validation, and detection.
- *
- * Every registry item (agent, skill, app, board, workflow, stack, template, hook)
- * is described by a `genie.yaml` manifest. This module handles:
- * - Parsing YAML manifests into typed GenieManifest objects
- * - Validating manifests against type-specific rules
- * - Auto-detecting manifests from directory conventions (AGENTS.md, skill.md, etc.)
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import * as yaml from 'js-yaml';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export type ItemType = 'agent' | 'skill' | 'app' | 'board' | 'workflow' | 'stack' | 'template' | 'hook';
-
-const ITEM_TYPES: ItemType[] = ['agent', 'skill', 'app', 'board', 'workflow', 'stack', 'template', 'hook'];
-
-export interface StageConfig {
-  name: string;
-  label?: string;
-  gate: 'human' | 'agent' | 'human+agent';
-  action?: string;
-  auto_advance?: boolean;
-  roles?: string[];
-  color?: string;
-}
-
-export interface StackItem {
-  name: string;
-  type: ItemType;
-  source?: string;
-  inline?: boolean;
-  config?: Record<string, unknown>;
-}
-
-export interface GenieManifest {
-  name: string;
-  version: string;
-  type: ItemType;
-  description?: string;
-  author?: { name: string; url?: string };
-  agent?: { model?: string; promptMode?: string; roles?: string[]; entrypoint: string };
-  skill?: { triggers?: string[]; entrypoint: string };
-  app?: { runtime?: string; natsPrefix?: string; icon?: string; entrypoint: string };
-  board?: { stages: StageConfig[] };
-  workflow?: { cron: string; timezone?: string; command: string; run_spec?: Record<string, unknown> };
-  stack?: { items: StackItem[] };
-  dependencies?: string[];
-  tags?: string[];
-  category?: string;
-  license?: string;
-}
-
-interface ValidationResult {
-  valid: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-// ============================================================================
-// Parsing
-// ============================================================================
-
-/**
- * Parse a YAML string into a typed GenieManifest.
- *
- * Validates that required fields (name, type, version) are present and that
- * the type value is a recognized ItemType. Throws on invalid input.
- */
-function parseManifest(yamlContent: string): GenieManifest {
-  const raw = yaml.load(yamlContent);
-  if (!raw || typeof raw !== 'object') {
-    throw new Error('Manifest YAML is empty or not an object');
-  }
-
-  const obj = raw as Record<string, unknown>;
-
-  if (!obj.name || typeof obj.name !== 'string') {
-    throw new Error('Manifest is missing required field: name');
-  }
-  if (!obj.type || typeof obj.type !== 'string') {
-    throw new Error('Manifest is missing required field: type');
-  }
-  if (!obj.version || typeof obj.version !== 'string') {
-    throw new Error('Manifest is missing required field: version');
-  }
-
-  if (!ITEM_TYPES.includes(obj.type as ItemType)) {
-    throw new Error(`Invalid item type "${obj.type}". Must be one of: ${ITEM_TYPES.join(', ')}`);
-  }
-
-  return obj as unknown as GenieManifest;
-}
-
-// ============================================================================
-// Validation
-// ============================================================================
-
-const VALID_GATES = new Set(['human', 'agent', 'human+agent']);
-
-/**
- * Validate a manifest against type-specific rules.
- *
- * Checks required fields, type-specific sections, entrypoint file existence,
- * board stage structure, cron format, and stack item completeness.
- * Returns a ValidationResult with errors (blockers) and warnings (advisory).
- */
-export function validateManifest(manifest: GenieManifest, itemDir: string): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  // Required top-level fields
-  if (!manifest.name) errors.push('Missing required field: name');
-  if (!manifest.type) errors.push('Missing required field: type');
-  if (!manifest.version) errors.push('Missing required field: version');
-
-  if (manifest.type && !ITEM_TYPES.includes(manifest.type)) {
-    errors.push(`Invalid item type "${manifest.type}". Must be one of: ${ITEM_TYPES.join(', ')}`);
-  }
-
-  // Type-specific validation
-  const { type } = manifest;
-
-  // Warn if the type-specific section is missing
-  if (type && !manifest[type as keyof GenieManifest]) {
-    warnings.push(`Manifest type is "${type}" but no "${type}" section is defined`);
-  }
-
-  // Agent validation
-  if (manifest.agent) {
-    validateEntrypoint(manifest.agent.entrypoint, itemDir, 'agent', errors);
-  }
-
-  // Skill validation
-  if (manifest.skill) {
-    validateEntrypoint(manifest.skill.entrypoint, itemDir, 'skill', errors);
-  }
-
-  // App validation
-  if (manifest.app) {
-    validateEntrypoint(manifest.app.entrypoint, itemDir, 'app', errors);
-  }
-
-  // Board validation
-  if (manifest.board) {
-    validateStages(manifest.board.stages, errors);
-  }
-
-  // Workflow validation
-  if (manifest.workflow) {
-    validateCron(manifest.workflow.cron, errors);
-  }
-
-  // Stack validation
-  if (manifest.stack) {
-    validateStackItems(manifest.stack.items, errors);
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-/** Check that an entrypoint file exists on disk. */
-function validateEntrypoint(entrypoint: string | undefined, itemDir: string, section: string, errors: string[]): void {
-  if (!entrypoint) {
-    errors.push(`${section} section is missing required field: entrypoint`);
-    return;
-  }
-  const fullPath = join(itemDir, entrypoint);
-  if (!existsSync(fullPath)) {
-    errors.push(`${section} entrypoint not found: ${entrypoint} (expected at ${fullPath})`);
-  }
-}
-
-/** Validate board stage definitions. */
-function validateStages(stages: StageConfig[] | undefined, errors: string[]): void {
-  if (!stages || !Array.isArray(stages)) {
-    errors.push('board section is missing required field: stages');
-    return;
-  }
-  for (let i = 0; i < stages.length; i++) {
-    const stage = stages[i];
-    if (!stage.name) {
-      errors.push(`board.stages[${i}] is missing required field: name`);
-    }
-    if (!stage.gate) {
-      errors.push(`board.stages[${i}] is missing required field: gate`);
-    } else if (!VALID_GATES.has(stage.gate)) {
-      errors.push(`board.stages[${i}].gate "${stage.gate}" is invalid. Must be one of: human, agent, human+agent`);
-    }
-  }
-}
-
-/**
- * Validate a cron expression has 5 or 6 space-separated fields.
- * This is a basic format check, not full cron syntax validation.
- */
-function validateCron(cron: string | undefined, errors: string[]): void {
-  if (!cron) {
-    errors.push('workflow section is missing required field: cron');
-    return;
-  }
-  const fields = cron.trim().split(/\s+/);
-  if (fields.length < 5 || fields.length > 6) {
-    errors.push(`workflow.cron "${cron}" is invalid: expected 5 or 6 space-separated fields, got ${fields.length}`);
-  }
-}
-
-/** Validate stack item definitions. */
-function validateStackItems(items: StackItem[] | undefined, errors: string[]): void {
-  if (!items || !Array.isArray(items)) {
-    errors.push('stack section is missing required field: items');
-    return;
-  }
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i];
-    if (!item.type) {
-      errors.push(`stack.items[${i}] is missing required field: type`);
-    }
-    if (!item.source && !item.inline) {
-      errors.push(`stack.items[${i}] must have either "source" or "inline: true"`);
-    }
-  }
-}
-
-// ============================================================================
-// Detection
-// ============================================================================
-
-/**
- * Detect a manifest from a directory using a fallback chain.
- *
- * Detection order:
- * 1. `genie.yaml` — explicit manifest file
- * 2. `AGENTS.md` — infer agent manifest from YAML frontmatter
- * 3. `manifest.ts` — infer app manifest
- * 4. `skill.md` — infer skill manifest
- * 5. None found — return error
- */
-export async function detectManifest(
-  dir: string,
-): Promise<{ manifest: GenieManifest; source: string } | { error: string }> {
-  // 1. Explicit genie.yaml
-  const yamlPath = join(dir, 'genie.yaml');
-  if (existsSync(yamlPath)) {
-    try {
-      const content = readFileSync(yamlPath, 'utf-8');
-      const manifest = parseManifest(content);
-      return { manifest, source: 'genie.yaml' };
-    } catch (err) {
-      return { error: `Failed to parse genie.yaml: ${(err as Error).message}` };
-    }
-  }
-
-  const dirName = basename(dir);
-
-  // 2. AGENTS.md — infer agent manifest from frontmatter
-  const agentsPath = join(dir, 'AGENTS.md');
-  if (existsSync(agentsPath)) {
-    const manifest = inferAgentManifest(agentsPath, dirName);
-    return { manifest, source: 'AGENTS.md' };
-  }
-
-  // 3. manifest.ts — infer app manifest
-  const manifestTsPath = join(dir, 'manifest.ts');
-  if (existsSync(manifestTsPath)) {
-    const manifest: GenieManifest = {
-      name: dirName,
-      type: 'app',
-      version: '0.0.0',
-    };
-    return { manifest, source: 'manifest.ts' };
-  }
-
-  // 4. skill.md — infer skill manifest
-  const skillPath = join(dir, 'skill.md');
-  if (existsSync(skillPath)) {
-    const manifest: GenieManifest = {
-      name: dirName,
-      type: 'skill',
-      version: '0.0.0',
-    };
-    return { manifest, source: 'skill.md' };
-  }
-
-  // 5. Nothing found
-  return {
-    error:
-      'No manifest found. Create a genie.yaml or use a recognized file pattern (AGENTS.md, manifest.ts, skill.md).',
-  };
-}
-
-/**
- * Extract YAML frontmatter from a markdown file.
- *
- * Looks for content between `---` markers at the top of the file.
- * Returns the parsed object or null if no frontmatter is found.
- */
-function extractFrontmatter(filePath: string): Record<string, unknown> | null {
-  const content = readFileSync(filePath, 'utf-8');
-  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!match) return null;
-
-  try {
-    const parsed = yaml.load(match[1]);
-    if (parsed && typeof parsed === 'object') {
-      return parsed as Record<string, unknown>;
-    }
-  } catch {
-    // Frontmatter is not valid YAML — ignore
-  }
-  return null;
-}
-
-/** Build an agent manifest from AGENTS.md frontmatter. */
-function inferAgentManifest(agentsPath: string, dirName: string): GenieManifest {
-  const frontmatter = extractFrontmatter(agentsPath);
-
-  const name = (frontmatter?.name as string) || dirName;
-  const model = frontmatter?.model as string | undefined;
-  const roles = Array.isArray(frontmatter?.roles) ? (frontmatter.roles as string[]) : undefined;
-
-  const manifest: GenieManifest = {
-    name,
-    type: 'agent',
-    version: '0.0.0',
-  };
-
-  if (model || roles) {
-    manifest.agent = {
-      entrypoint: 'AGENTS.md',
-      ...(model && { model }),
-      ...(roles && { roles }),
-    };
-  }
-
-  return manifest;
-}

package/src/term-commands/install.ts

@@ -1,372 +0,0 @@
-/**
- * Install Command — `genie install <git-url>[@version]`
- *
- * Clones a git repository, detects/validates the manifest, registers in
- * app_store, and performs type-specific setup (cache regen, board creation, etc.).
- */
-
-import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, join } from 'node:path';
-import type { Command } from 'commander';
-import {
-  getItemFromStore,
-  regenerateAgentCache,
-  registerItemInStore,
-  removeItemFromStore,
-} from '../lib/agent-cache.js';
-import { getActor, recordAuditEvent } from '../lib/audit.js';
-import { getConnection, isAvailable } from '../lib/db.js';
-import { type GenieManifest, type StageConfig, detectManifest, validateManifest } from '../lib/manifest.js';
-
-const GENIE_HOME = process.env.GENIE_HOME ?? join(homedir(), '.genie');
-const ITEMS_DIR = join(GENIE_HOME, 'items');
-
-// ============================================================================
-// URL parsing
-// ============================================================================
-
-interface ParsedUrl {
-  url: string;
-  version?: string;
-  name: string;
-}
-
-/**
- * Parse a git install target like `github.com/user/repo@v1.2.0`
- * into its components.
- */
-function parseInstallTarget(target: string): ParsedUrl {
-  let url = target;
-  let version: string | undefined;
-
-  // Extract @version suffix
-  const atIdx = url.lastIndexOf('@');
-  if (atIdx > 0 && !url.slice(atIdx).includes('/')) {
-    version = url.slice(atIdx + 1);
-    url = url.slice(0, atIdx);
-  }
-
-  // Normalise bare github.com/user/repo → https://github.com/user/repo.git
-  if (!url.startsWith('http') && !url.startsWith('git@') && !url.startsWith('ssh://')) {
-    url = `https://${url}`;
-  }
-  if (url.startsWith('https://') && !url.endsWith('.git')) {
-    url = `${url}.git`;
-  }
-
-  // Derive name from repo URL
-  const name = basename(url, '.git');
-
-  return { url, version, name };
-}
-
-// ============================================================================
-// Git operations
-// ============================================================================
-
-function cloneRepo(url: string, dest: string, options: { shallow?: boolean; version?: string }): void {
-  const args = ['git', 'clone'];
-  if (options.shallow !== false) args.push('--depth', '1');
-  if (options.version) args.push('--branch', options.version);
-  args.push(url, dest);
-
-  execSync(args.join(' '), { stdio: 'pipe', timeout: 120_000 });
-}
-
-function cleanupDir(dir: string): void {
-  if (existsSync(dir)) {
-    rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-// ============================================================================
-// Type-specific registration
-// ============================================================================
-
-async function registerByType(manifest: GenieManifest, installPath: string): Promise<void> {
-  switch (manifest.type) {
-    case 'agent':
-      await regenerateAgentCache();
-      break;
-    case 'board':
-      await registerBoard(manifest);
-      break;
-    case 'workflow':
-      await registerWorkflow(manifest);
-      break;
-    case 'stack':
-      await installStack(manifest, installPath);
-      break;
-    // skill, app, template, hook — no extra registration needed beyond app_store
-  }
-}
-
-async function registerBoard(manifest: GenieManifest): Promise<void> {
-  if (!manifest.board?.stages) return;
-  if (!(await isAvailable())) return;
-
-  const sql = await getConnection();
-  const stages = manifest.board.stages.map((s, i) => ({
-    id: crypto.randomUUID(),
-    name: s.name,
-    label: s.label ?? s.name,
-    gate: s.gate,
-    action: s.action ?? null,
-    auto_advance: s.auto_advance ?? false,
-    roles: s.roles ?? ['*'],
-    color: s.color ?? '#94a3b8',
-    parallel: false,
-    on_fail: null,
-    position: i,
-    transitions: [],
-  }));
-
-  await sql`
-    INSERT INTO task_types (id, name, description, stages, is_builtin)
-    VALUES (
-      ${manifest.name},
-      ${manifest.name},
-      ${manifest.description ?? null},
-      ${sql.json(stages)},
-      false
-    )
-    ON CONFLICT (id) DO UPDATE SET
-      stages = EXCLUDED.stages,
-      description = EXCLUDED.description,
-      updated_at = now()
-  `;
-}
-
-async function registerWorkflow(manifest: GenieManifest): Promise<void> {
-  if (!manifest.workflow) return;
-  if (!(await isAvailable())) return;
-
-  const sql = await getConnection();
-  const wf = manifest.workflow;
-
-  await sql`
-    INSERT INTO schedules (id, name, cron_expression, timezone, command, run_spec, status)
-    VALUES (
-      ${`sched-${manifest.name}`},
-      ${manifest.name},
-      ${wf.cron},
-      ${wf.timezone ?? 'UTC'},
-      ${wf.command},
-      ${sql.json(wf.run_spec ?? {})},
-      'active'
-    )
-    ON CONFLICT (id) DO UPDATE SET
-      cron_expression = EXCLUDED.cron_expression,
-      timezone = EXCLUDED.timezone,
-      command = EXCLUDED.command,
-      run_spec = EXCLUDED.run_spec,
-      updated_at = now()
-  `;
-}
-
-async function handleInlineStackItem(
-  item: import('../lib/manifest.js').StackItem,
-  version: string,
-  tx: Awaited<ReturnType<typeof getConnection>>,
-): Promise<void> {
-  if (item.type === 'board' && item.config) {
-    await registerBoard({
-      name: item.name,
-      type: 'board',
-      version,
-      board: { stages: (item.config.stages ?? []) as StageConfig[] },
-    });
-  } else if (item.type === 'workflow' && item.config) {
-    await registerWorkflow({
-      name: item.name,
-      type: 'workflow',
-      version,
-      workflow: item.config as unknown as NonNullable<GenieManifest['workflow']>,
-    });
-  }
-  await tx`
-    INSERT INTO app_store (name, item_type, version, manifest)
-    VALUES (${item.name}, ${item.type}, ${version}, ${tx.json(item.config ?? {})})
-    ON CONFLICT (name) DO NOTHING
-  `;
-}
-
-async function handleExternalStackItem(
-  item: import('../lib/manifest.js').StackItem,
-  tx: Awaited<ReturnType<typeof getConnection>>,
-): Promise<string> {
-  if (!item.source) throw new Error(`Stack item "${item.name}" is missing source`);
-  const parsed = parseInstallTarget(item.source);
-  const itemDir = join(ITEMS_DIR, parsed.name);
-  mkdirSync(ITEMS_DIR, { recursive: true });
-  cloneRepo(parsed.url, itemDir, { version: parsed.version });
-
-  const detection = await detectManifest(itemDir);
-  if ('error' in detection) {
-    throw new Error(`Stack item "${item.name}" (${item.source}): ${detection.error}`);
-  }
-  const validation = validateManifest(detection.manifest, itemDir);
-  if (!validation.valid) {
-    throw new Error(`Stack item "${item.name}" validation failed: ${validation.errors.join(', ')}`);
-  }
-
-  await tx`
-    INSERT INTO app_store (name, item_type, version, git_url, install_path, manifest)
-    VALUES (
-      ${detection.manifest.name}, ${detection.manifest.type}, ${detection.manifest.version},
-      ${item.source}, ${itemDir}, ${tx.json(detection.manifest)}
-    )
-    ON CONFLICT (name) DO NOTHING
-  `;
-  await registerByType(detection.manifest, itemDir);
-  return parsed.name;
-}
-
-async function installStack(manifest: GenieManifest, _installPath: string): Promise<void> {
-  const stackItems = manifest.stack?.items;
-  if (!stackItems) return;
-  if (!(await isAvailable())) return;
-
-  const sql = await getConnection();
-  const installed: string[] = [];
-
-  try {
-    await sql.begin(async (tx: typeof sql) => {
-      for (const item of stackItems) {
-        if (item.inline) {
-          await handleInlineStackItem(item, manifest.version, tx);
-          installed.push(item.name);
-        } else if (item.source) {
-          const name = await handleExternalStackItem(item, tx);
-          installed.push(name);
-        }
-      }
-    });
-  } catch (err) {
-    // Rollback: clean up cloned dirs
-    for (const name of installed) {
-      cleanupDir(join(ITEMS_DIR, name));
-      await removeItemFromStore(name).catch(() => {});
-    }
-    throw err;
-  }
-}
-
-// ============================================================================
-// Install command
-// ============================================================================
-
-interface InstallOptions {
-  force?: boolean;
-  full?: boolean;
-}
-
-async function handleInstall(target: string, options: InstallOptions): Promise<void> {
-  const parsed = parseInstallTarget(target);
-  const installDir = join(ITEMS_DIR, parsed.name);
-
-  // Check for name conflict
-  const existing = await getItemFromStore(parsed.name).catch(() => null);
-  if (existing && !options.force) {
-    console.error(`Item "${parsed.name}" is already installed. Use --force to override.`);
-    process.exit(1);
-  }
-  if (existing && options.force) {
-    await removeItemFromStore(parsed.name).catch(() => {});
-    cleanupDir(installDir);
-  }
-
-  // Clone
-  mkdirSync(ITEMS_DIR, { recursive: true });
-  console.log(`Cloning ${parsed.url}${parsed.version ? ` @ ${parsed.version}` : ''}...`);
-  try {
-    cloneRepo(parsed.url, installDir, { shallow: !options.full, version: parsed.version });
-  } catch (err) {
-    cleanupDir(installDir);
-    console.error(`Clone failed: ${(err as Error).message}`);
-    process.exit(1);
-  }
-
-  // Detect manifest
-  const detection = await detectManifest(installDir);
-  if ('error' in detection) {
-    cleanupDir(installDir);
-    console.error(`Manifest detection failed: ${detection.error}`);
-    process.exit(1);
-  }
-
-  const { manifest, source } = detection;
-  console.log(`Detected ${manifest.type} manifest from ${source}`);
-
-  // Validate
-  const validation = validateManifest(manifest, installDir);
-  for (const w of validation.warnings) {
-    console.log(`  Warning: ${w}`);
-  }
-  if (!validation.valid) {
-    cleanupDir(installDir);
-    console.error(`Validation failed:\n${validation.errors.map((e) => `  - ${e}`).join('\n')}`);
-    process.exit(1);
-  }
-
-  // Register in app_store
-  try {
-    await registerItemInStore({
-      name: manifest.name,
-      itemType: manifest.type,
-      version: manifest.version,
-      description: manifest.description,
-      authorName: manifest.author?.name,
-      authorUrl: manifest.author?.url,
-      gitUrl: parsed.url,
-      installPath: installDir,
-      manifest: manifest as unknown as Record<string, unknown>,
-      tags: manifest.tags,
-      category: manifest.category,
-      license: manifest.license,
-      dependencies: manifest.dependencies,
-    });
-  } catch (err) {
-    cleanupDir(installDir);
-    console.error(`Registration failed: ${(err as Error).message}`);
-    process.exit(1);
-  }
-
-  // Type-specific registration
-  await registerByType(manifest, installDir);
-
-  // Audit
-  recordAuditEvent('item', manifest.name, 'item_installed', getActor(), {
-    type: manifest.type,
-    version: manifest.version,
-    source: parsed.url,
-    manifestSource: source,
-  }).catch(() => {});
-
-  console.log(`\nInstalled ${manifest.type} "${manifest.name}" v${manifest.version}`);
-  console.log(`  Source: ${parsed.url}`);
-  console.log(`  Path: ${installDir}`);
-}
-
-// ============================================================================
-// Command registration
-// ============================================================================
-
-export function registerInstallCommand(program: Command): void {
-  program
-    .command('install <target>')
-    .description('Install a genie item from a git URL (e.g. github.com/user/repo[@version])')
-    .option('--force', 'Override existing item with same name')
-    .option('--full', 'Full git clone instead of shallow')
-    .action(async (target: string, options: InstallOptions) => {
-      try {
-        await handleInstall(target, options);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`Error: ${message}`);
-        process.exit(1);
-      }
-    });
-}