@automagik/genie 4.260331.5 → 4.260331.7

package/src/term-commands/export.ts

@@ -9,7 +9,6 @@
  *   genie export projects           — Projects
  *   genie export schedules [name]   — Schedules with run_spec
  *   genie export agents             — Agents, templates, checkpoints
- *   genie export apps               — App store (KhalOS, graceful skip)
  *   genie export comms              — Conversations, messages, mailbox
  *   genie export config             — OS config (KhalOS, graceful skip)
  */
@@ -374,18 +373,6 @@ export function registerExportCommands(program: Command): void {
     },
   );
 
-  // genie export apps
-  sharedOpts(exp.command('apps').description('Export app store (graceful skip if missing)')).action(
-    async (options: ExportOptions) => {
-      try {
-        await runExport(['apps'], 'partial', (sql) => exportGroup(sql, 'apps'), options);
-      } catch (error) {
-        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
-        process.exit(1);
-      }
-    },
-  );
-
   // genie export comms
   sharedOpts(exp.command('comms').description('Export conversations, messages, mailbox')).action(
     async (options: ExportOptions) => {

package/src/term-commands/msg.ts

@@ -526,6 +526,14 @@ export function registerSendInboxCommands(program: Command): void {
     .option('--to <agent>', 'Recipient agent name (default: team-lead)', 'team-lead')
     .option('--from <sender>', 'Sender ID (auto-detected from context)')
     .option('--team <name>', 'Explicit team context for sender/recipient resolution')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  genie send 'start task #3' --to engineer         # Message a specific agent
+  genie send 'status update' --to team-lead         # Report to team lead
+  genie send 'deploy ready' --team my-feature       # Message within team context`,
+    )
     .action(async (body: string, options: { to: string; from?: string; team?: string }) => {
       try {
         await handleSend(body, options);

package/src/term-commands/team.ts

@@ -29,6 +29,14 @@ export function registerTeamNamespace(program: Command): void {
     .option('--tmux-session <name>', 'Tmux session to place team window in (default: derived from repo path)')
     .option('--session <name>', 'Alias for --tmux-session (deprecated)')
     .option('--no-spawn', 'Create team and copy wish without spawning the leader (useful for testing)')
+    .addHelpText(
+      'after',
+      `
+Examples:
+  genie team create my-feature --repo .                          # Create team in current repo
+  genie team create my-feature --repo . --wish my-feature-slug   # Create team with a wish
+  genie team create hotfix --repo . --branch main                # Create from main branch`,
+    )
     .action(
       async (
         name: string,

package/src/lib/agent-cache.ts

@@ -1,282 +0,0 @@
-/**
- * Agent Cache — Maintains agent-directory.json as a cache of app_store agents.
- *
- * Also provides generic CRUD helpers for the `app_store` table (register,
- * remove, update, get, list). The cache file is a denormalised snapshot
- * written to GENIE_HOME so that non-PG consumers (hooks, shell scripts)
- * can read agent metadata without a database connection.
- *
- * Best-effort: DB failures never block the CLI.
- */
-
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { getActor, recordAuditEvent } from './audit.js';
-import { getConnection, isAvailable } from './db.js';
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-const GENIE_HOME = process.env.GENIE_HOME ?? join(homedir(), '.genie');
-const CACHE_FILE = 'agent-directory.json';
-const CACHE_BACKUP = 'agent-directory.json.bak';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/** Denormalised cache entry written to agent-directory.json. */
-interface CacheEntry {
-  name: string;
-  dir: string;
-  repo?: string;
-  promptMode: string;
-  model?: string;
-  roles?: string[];
-  registeredAt: string;
-}
-
-/** Row shape returned by SELECT * FROM app_store. */
-export interface StoreRow {
-  id: string;
-  name: string;
-  item_type: string;
-  version: string;
-  description: string | null;
-  author_name: string | null;
-  author_url: string | null;
-  git_url: string | null;
-  install_path: string | null;
-  manifest: Record<string, unknown>;
-  approval_status: string;
-  tags: string[];
-  category: string | null;
-  license: string | null;
-  dependencies: string[];
-  installed_at: string;
-  updated_at: string;
-}
-
-/** Insert payload for registerItemInStore. */
-interface StoreInsert {
-  name: string;
-  itemType: string;
-  version?: string;
-  description?: string;
-  authorName?: string;
-  authorUrl?: string;
-  gitUrl?: string;
-  installPath?: string;
-  manifest?: Record<string, unknown>;
-  tags?: string[];
-  category?: string;
-  license?: string;
-  dependencies?: string[];
-}
-
-// ============================================================================
-// Cache regeneration
-// ============================================================================
-
-/**
- * Rebuild agent-directory.json from all `item_type = 'agent'` rows in app_store.
- *
- * Silently returns if the database is unavailable — the stale cache (if any)
- * remains on disk until the next successful regeneration.
- */
-export async function regenerateAgentCache(): Promise<void> {
-  try {
-    if (!(await isAvailable())) return;
-
-    const sql = await getConnection();
-    const rows = await sql`
-      SELECT name, install_path, manifest, installed_at
-      FROM app_store
-      WHERE item_type = 'agent'
-      ORDER BY name
-    `;
-
-    const entries: CacheEntry[] = rows.map((r: Record<string, unknown>) => {
-      const manifest = (r.manifest ?? {}) as Record<string, unknown>;
-      const entry: CacheEntry = {
-        name: r.name as string,
-        dir: (r.install_path as string) ?? '',
-        promptMode: (manifest.promptMode as string) ?? 'append',
-        registeredAt: r.installed_at ? new Date(r.installed_at as string).toISOString() : new Date().toISOString(),
-      };
-      if (manifest.repo) entry.repo = manifest.repo as string;
-      if (manifest.model) entry.model = manifest.model as string;
-      if (Array.isArray(manifest.roles) && manifest.roles.length > 0) {
-        entry.roles = manifest.roles as string[];
-      }
-      return entry;
-    });
-
-    writeFileSync(join(GENIE_HOME, CACHE_FILE), JSON.stringify(entries, null, 2));
-  } catch {
-    // Best effort — never block the CLI on cache regeneration failure
-  }
-}
-
-// ============================================================================
-// One-time migration from JSON → PG
-// ============================================================================
-
-/**
- * Migrate the legacy agent-directory.json into the app_store table.
- *
- * Idempotent: skips if the backup file already exists (meaning migration
- * already ran) or if the source file is missing (nothing to migrate).
- * Uses ON CONFLICT (name) DO NOTHING so partially-completed runs are safe.
- */
-export async function migrateAgentDirectory(): Promise<void> {
-  const sourcePath = join(GENIE_HOME, CACHE_FILE);
-  const backupPath = join(GENIE_HOME, CACHE_BACKUP);
-
-  // Already migrated or nothing to migrate
-  if (existsSync(backupPath) || !existsSync(sourcePath)) return;
-
-  try {
-    const raw = readFileSync(sourcePath, 'utf-8');
-    const entries: CacheEntry[] = JSON.parse(raw);
-    if (!Array.isArray(entries) || entries.length === 0) return;
-
-    const sql = await getConnection();
-
-    for (const entry of entries) {
-      const manifest: Record<string, unknown> = {};
-      if (entry.promptMode) manifest.promptMode = entry.promptMode;
-      if (entry.model) manifest.model = entry.model;
-      if (entry.roles) manifest.roles = entry.roles;
-      if (entry.repo) manifest.repo = entry.repo;
-
-      await sql`
-        INSERT INTO app_store (name, item_type, version, install_path, manifest)
-        VALUES (${entry.name}, 'agent', '0.0.0', ${entry.dir ?? null}, ${sql.json(manifest)})
-        ON CONFLICT (name) DO NOTHING
-      `;
-    }
-
-    renameSync(sourcePath, backupPath);
-
-    await recordAuditEvent('item', 'migration', 'agent_directory_migrated', getActor(), {
-      count: entries.length,
-    });
-  } catch {
-    // Best effort — migration can be retried on the next run
-  }
-}
-
-// ============================================================================
-// CRUD helpers for app_store
-// ============================================================================
-
-/**
- * Insert a new item into the app_store. Returns the generated id.
- *
- * Throws if an item with the same name already exists — callers should
- * check beforehand or use `--force` to remove + re-insert.
- */
-export async function registerItemInStore(item: StoreInsert): Promise<string> {
-  const sql = await getConnection();
-
-  const rows = await sql`
-    INSERT INTO app_store (
-      name, item_type, version, description,
-      author_name, author_url, git_url, install_path,
-      manifest, tags, category, license, dependencies
-    ) VALUES (
-      ${item.name},
-      ${item.itemType},
-      ${item.version ?? '0.0.0'},
-      ${item.description ?? null},
-      ${item.authorName ?? null},
-      ${item.authorUrl ?? null},
-      ${item.gitUrl ?? null},
-      ${item.installPath ?? null},
-      ${sql.json(item.manifest ?? {})},
-      ${item.tags ?? []},
-      ${item.category ?? null},
-      ${item.license ?? null},
-      ${item.dependencies ?? []}
-    )
-    RETURNING id
-  `;
-
-  if (rows.length === 0) {
-    throw new Error(`Failed to insert item "${item.name}" — no id returned.`);
-  }
-
-  return rows[0].id as string;
-}
-
-/**
- * Delete an item from the app_store by name.
- *
- * @returns true if an item was deleted, false if no matching item was found.
- */
-export async function removeItemFromStore(name: string): Promise<boolean> {
-  const sql = await getConnection();
-  const result = await sql`DELETE FROM app_store WHERE name = ${name}`;
-  return result.count > 0;
-}
-
-/**
- * Update an existing item in the app_store by name.
- * Only provided fields are updated; updated_at is always set to now().
- *
- * @returns true if the item was updated, false if no matching item was found.
- */
-export async function updateItemInStore(name: string, updates: Partial<StoreInsert>): Promise<boolean> {
-  const sql = await getConnection();
-
-  const s: Record<string, unknown> = {};
-  if (updates.name !== undefined) s.name = updates.name;
-  if (updates.itemType !== undefined) s.item_type = updates.itemType;
-  if (updates.version !== undefined) s.version = updates.version;
-  if (updates.description !== undefined) s.description = updates.description;
-  if (updates.authorName !== undefined) s.author_name = updates.authorName;
-  if (updates.authorUrl !== undefined) s.author_url = updates.authorUrl;
-  if (updates.gitUrl !== undefined) s.git_url = updates.gitUrl;
-  if (updates.installPath !== undefined) s.install_path = updates.installPath;
-  if (updates.manifest !== undefined) s.manifest = sql.json(updates.manifest);
-  if (updates.tags !== undefined) s.tags = updates.tags;
-  if (updates.category !== undefined) s.category = updates.category;
-  if (updates.license !== undefined) s.license = updates.license;
-  if (updates.dependencies !== undefined) s.dependencies = updates.dependencies;
-
-  if (Object.keys(s).length === 0) return false;
-
-  s.updated_at = sql`now()`;
-  const result = await sql`UPDATE app_store SET ${sql(s)} WHERE name = ${name}`;
-  return result.count > 0;
-}
-
-/**
- * Fetch a single item from the app_store by name.
- *
- * @returns the row or null if not found.
- */
-export async function getItemFromStore(name: string): Promise<StoreRow | null> {
-  const sql = await getConnection();
-  const rows = await sql`SELECT * FROM app_store WHERE name = ${name}`;
-  return rows.length > 0 ? (rows[0] as unknown as StoreRow) : null;
-}
-
-/**
- * List items from the app_store, optionally filtered by item_type.
- *
- * @param itemType - When provided, only rows matching this type are returned.
- * @returns rows ordered by name.
- */
-export async function listItemsFromStore(itemType?: string): Promise<StoreRow[]> {
-  const sql = await getConnection();
-
-  const rows = itemType
-    ? await sql`SELECT * FROM app_store WHERE item_type = ${itemType} ORDER BY name`
-    : await sql`SELECT * FROM app_store ORDER BY name`;
-
-  return rows as unknown as StoreRow[];
-}

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;
-}