@studio-foundation/cli 0.3.0-beta.1

package/src/commands/template/validate.ts

@@ -0,0 +1,175 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import * as yaml from 'js-yaml';
+import { spawnSync } from 'node:child_process';
+
+export interface ValidationResult {
+  valid: boolean;
+  structuralErrors: string[];
+  semanticErrors: string[];
+  warnings: string[];
+}
+
+interface StageDefinition {
+  name: string;
+  agent?: string;
+  contract?: string;
+}
+
+interface PipelineEntry {
+  group?: string;
+  stages?: StageDefinition[];
+  name?: string;
+  agent?: string;
+  contract?: string;
+}
+
+function collectStages(entries: PipelineEntry[]): StageDefinition[] {
+  const stages: StageDefinition[] = [];
+  for (const entry of entries) {
+    if (entry.group && Array.isArray(entry.stages)) {
+      stages.push(...entry.stages);
+    } else {
+      stages.push(entry as StageDefinition);
+    }
+  }
+  return stages;
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listYamlFiles(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir);
+    return entries.filter((e) => e.endsWith('.yaml') || e.endsWith('.yml'));
+  } catch {
+    return [];
+  }
+}
+
+export async function validateTemplateDir(templatePath: string): Promise<ValidationResult> {
+  const warnings: string[] = [];
+
+  // ── Level 1: Structural ──────────────────────────────────────────────
+
+  const structuralErrors: string[] = [];
+
+  if (!(await pathExists(templatePath))) {
+    return { valid: false, structuralErrors: [`Template directory not found: ${templatePath}`], semanticErrors: [], warnings };
+  }
+
+  const metaPath = join(templatePath, 'metadata.json');
+  try {
+    const raw = await readFile(metaPath, 'utf-8');
+    const meta = JSON.parse(raw) as Record<string, unknown>;
+    for (const field of ['name', 'version', 'description']) {
+      if (!meta[field]) structuralErrors.push(`metadata.json: missing required field '${field}'`);
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      structuralErrors.push('metadata.json: file not found');
+    } else {
+      structuralErrors.push(`metadata.json: ${(err as Error).message}`);
+    }
+  }
+
+  const pipelinesDir = join(templatePath, 'pipelines');
+
+  const agentsDir = join(templatePath, 'agents');
+  const agentFiles = (await listYamlFiles(agentsDir)).filter((f) => f.endsWith('.agent.yaml'));
+
+  const contractsDir = join(templatePath, 'contracts');
+
+  if (structuralErrors.length > 0) {
+    return { valid: false, structuralErrors, semanticErrors: [], warnings };
+  }
+
+  // ── Level 2: Semantic ────────────────────────────────────────────────
+
+  const semanticErrors: string[] = [];
+
+  const knownAgents = new Set(agentFiles.map((f) => basename(f, '.agent.yaml')));
+  const contractFiles = (await listYamlFiles(contractsDir)).filter((f) => f.endsWith('.contract.yaml'));
+  const knownContracts = new Set(contractFiles.map((f) => basename(f, '.contract.yaml')));
+
+  const allYamlDirs: [string, string][] = [
+    [pipelinesDir, 'pipelines'],
+    [agentsDir, 'agents'],
+    [contractsDir, 'contracts'],
+    [join(templatePath, 'tools'), 'tools'],
+  ];
+
+  const parsedPipelines: Array<{ file: string; parsed: Record<string, unknown> }> = [];
+
+  for (const [dir, label] of allYamlDirs) {
+    const files = await listYamlFiles(dir);
+    for (const file of files) {
+      const filePath = join(dir, file);
+      try {
+        const content = await readFile(filePath, 'utf-8');
+        const parsed = yaml.load(content);
+        if (parsed === null || parsed === undefined) {
+          semanticErrors.push(`${label}/${file}: YAML file is empty`);
+          continue;
+        }
+        if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+          semanticErrors.push(`${label}/${file}: YAML file must be a mapping (object)`);
+          continue;
+        }
+        if (label === 'pipelines') {
+          parsedPipelines.push({ file, parsed: parsed as Record<string, unknown> });
+        }
+      } catch (err) {
+        semanticErrors.push(`${label}/${file}: YAML parse error — ${(err as Error).message}`);
+      }
+    }
+  }
+
+  for (const { file, parsed } of parsedPipelines) {
+    if (!parsed || !Array.isArray(parsed.stages)) continue;
+    const stages = collectStages(parsed.stages as PipelineEntry[]);
+    for (const stage of stages) {
+      if (stage.contract && !knownContracts.has(stage.contract)) {
+        semanticErrors.push(
+          `pipelines/${file}: stage '${stage.name ?? '?'}' references contract '${stage.contract}' which does not exist in contracts/`
+        );
+      }
+      if (stage.agent && !knownAgents.has(stage.agent)) {
+        semanticErrors.push(
+          `pipelines/${file}: stage '${stage.name ?? '?'}' references agent '${stage.agent}' which does not exist in agents/`
+        );
+      }
+    }
+  }
+
+  if (semanticErrors.length > 0) {
+    return { valid: false, structuralErrors: [], semanticErrors, warnings };
+  }
+
+  // ── Level 3: Optional TypeScript compilation ─────────────────────────
+
+  const tsConfigPath = join(templatePath, 'tsconfig.json');
+  if (await pathExists(tsConfigPath)) {
+    // spawnSync is intentional: this is a CLI command, not a server.
+    // Blocking during tsc --noEmit is acceptable for a validation step.
+    const result = spawnSync('tsc', ['--noEmit'], { cwd: templatePath, encoding: 'utf-8' });
+    if (result.status !== 0) {
+      const output = (result.stdout ?? '') + (result.stderr ?? '');
+      semanticErrors.push(`TypeScript compilation failed:\n${output.trim()}`);
+    }
+  }
+
+  const prismaSchema = join(templatePath, 'prisma', 'schema.prisma');
+  if (await pathExists(prismaSchema)) {
+    warnings.push('prisma/schema.prisma found (migration testing not automated — run prisma validate manually)');
+  }
+
+  return { valid: semanticErrors.length === 0, structuralErrors: [], semanticErrors, warnings };
+}

package/src/commands/templates.ts

@@ -0,0 +1,99 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { RegistryCache } from '../registry/cache.js';
+import { syncRegistry } from './registry/sync.js';
+
+const PROJECTS_TEMPLATES_DIR = resolve(import.meta.dirname, '../../templates/projects');
+
+export interface TemplateMetadata {
+  name: string;
+  version: string;
+  description: string;
+  author?: string;
+  tags?: string[];
+  type?: string;
+  studio_version?: string;
+  pipelines?: string[];
+  tools_included?: string[];
+}
+
+export async function listTemplates(): Promise<TemplateMetadata[]> {
+  // 1. Load local (bundled) templates
+  const localTemplates: TemplateMetadata[] = [];
+  try {
+    const entries = await readdir(PROJECTS_TEMPLATES_DIR, { withFileTypes: true });
+    const dirs = entries
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+
+    for (const dir of dirs) {
+      try {
+        const metaPath = join(PROJECTS_TEMPLATES_DIR, dir, 'metadata.json');
+        const meta = JSON.parse(await readFile(metaPath, 'utf-8')) as TemplateMetadata;
+        localTemplates.push(meta);
+      } catch {
+        // Skip malformed or missing metadata
+      }
+    }
+  } catch {
+    // templates dir missing — continue
+  }
+
+  // 2. Merge with registry templates (sync silently if stale, fall back gracefully)
+  const registryTemplates: TemplateMetadata[] = [];
+  try {
+    await syncRegistry({ force: false, silent: true });
+    const cache = new RegistryCache();
+    const index = await cache.read();
+    if (index) {
+      const localNames = new Set(localTemplates.map((t) => t.name));
+      for (const pkg of index.packages) {
+        if (pkg.type === 'template' && !localNames.has(pkg.name)) {
+          registryTemplates.push({
+            name: pkg.name,
+            version: pkg.version,
+            description: pkg.description,
+            author: pkg.author,
+            tags: pkg.tags,
+            studio_version: pkg.studio_version ?? undefined,
+          });
+        }
+      }
+    }
+  } catch {
+    // Registry unreachable — show local templates only
+  }
+
+  return [...localTemplates, ...registryTemplates];
+}
+
+export async function templatesCommand(action: string, _args: string[]): Promise<void> {
+  try {
+    switch (action) {
+      case 'list': {
+        const templates = await listTemplates();
+        if (templates.length === 0) {
+          console.log(chalk.yellow('No templates available.'));
+          return;
+        }
+        console.log('\nAvailable templates:\n');
+        const maxLen = Math.max(...templates.map((t) => t.name.length));
+        for (const t of templates) {
+          console.log(`  ${t.name.padEnd(maxLen + 2)}${chalk.gray(t.description)}`);
+        }
+        console.log('');
+        console.log(`Run: ${chalk.cyan('studio init --template <name>')}`);
+        console.log('');
+        break;
+      }
+      default:
+        console.error(`Unknown templates action: ${action}. Available: list`);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}

package/src/commands/tools.ts

@@ -0,0 +1,227 @@
+import { readdir, readFile, writeFile, unlink, mkdir, access } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { checkbox } from '@inquirer/prompts';
+import { loadConfig } from '../config.js';
+import { listAvailableToolTemplates, getBundledToolTemplate } from '@studio-foundation/runner';
+
+export function getToolsDir(studioDir: string): string {
+  return resolve(studioDir, 'tools');
+}
+
+export async function toolsAddDirect(
+  studioDir: string,
+  toolNames: string[]
+): Promise<{ installed: string[]; skipped: string[] }> {
+  const toolsDir = getToolsDir(studioDir);
+  await mkdir(toolsDir, { recursive: true });
+
+  const installed: string[] = [];
+  const skipped: string[] = [];
+
+  for (const name of toolNames) {
+    const templateContent = await getBundledToolTemplate(name);
+    if (!templateContent) {
+      const available = await listAvailableToolTemplates();
+      throw new Error(`Unknown tool '${name}'. Available: ${available.map((t) => t.name).join(', ')}`);
+    }
+
+    const destPath = resolve(toolsDir, `${name}.tool.yaml`);
+    const alreadyInstalled = await access(destPath).then(() => true).catch(() => false);
+    if (alreadyInstalled) {
+      skipped.push(name);
+      continue;
+    }
+
+    await writeFile(destPath, templateContent, 'utf-8');
+    installed.push(name);
+  }
+
+  return { installed, skipped };
+}
+
+export async function listAvailableTools(): Promise<{ name: string; description: string }[]> {
+  return listAvailableToolTemplates();
+}
+
+export async function listTools(toolsDir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(toolsDir);
+    return entries
+      .filter((f) => f.endsWith('.tool.yaml'))
+      .map((f) => f.replace('.tool.yaml', ''))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+async function resolveToolsDir(): Promise<string> {
+  const config = await loadConfig();
+  const studioDir = config.resolvedStudioDir;
+
+  if (!studioDir) {
+    console.error("Error: No .studio/ directory found. Run 'studio init' first.");
+    process.exit(1);
+  }
+
+  return getToolsDir(studioDir);
+}
+
+export async function toolsCommand(
+  action: string,
+  args: string[]
+): Promise<void> {
+  try {
+    switch (action) {
+      case 'list': {
+        const config = await loadConfig();
+        const studioDir = config.resolvedStudioDir;
+        if (!studioDir) {
+          console.error("Error: No .studio/ directory found. Run 'studio init' first.");
+          process.exit(1);
+        }
+        const toolsDir = getToolsDir(studioDir);
+        const tools = await listTools(toolsDir);
+
+        if (tools.length === 0) {
+          console.log(chalk.yellow('No tools installed.'));
+          console.log('  Run: studio tools add <name>');
+        } else {
+          console.log('\nInstalled tools:');
+          for (const t of tools) {
+            console.log(`  - ${t}`);
+          }
+        }
+
+        // Show installed plugins (from .studio/plugins/)
+        const { loadPlugins: loadPluginManifests } = await import('@studio-foundation/runner');
+        const pluginsDir = resolve(studioDir, 'plugins');
+        const manifests = await loadPluginManifests(pluginsDir);
+        if (manifests.length > 0) {
+          console.log('\nInstalled plugins:');
+          for (const m of manifests) {
+            const serverNames = Object.keys(m.mcpServers);
+            const skillCount = m.skills.length;
+            const parts: string[] = [];
+            if (serverNames.length > 0) parts.push(`MCP: ${serverNames.join(', ')}`);
+            if (skillCount > 0) parts.push(`${skillCount} skill${skillCount !== 1 ? 's' : ''}`);
+            console.log(`  - ${m.name}${parts.length > 0 ? ` (${parts.join('; ')})` : ''}`);
+          }
+        }
+        console.log('');
+        break;
+      }
+
+      case 'add': {
+        if (args.length === 0) {
+          // Wizard mode
+          const config = await loadConfig();
+          const studioDir = config.resolvedStudioDir;
+          if (!studioDir) {
+            console.error("Error: No .studio/ directory found. Run 'studio init' first.");
+            process.exit(1);
+          }
+
+          console.log('');
+          const available = await listAvailableToolTemplates();
+          const alreadyInstalled = await listTools(getToolsDir(studioDir));
+
+          const choices = available.map((t) => ({
+            value: t.name,
+            name: `${t.name} — ${t.description}`,
+            disabled: alreadyInstalled.includes(t.name) ? '(already installed)' : false,
+          }));
+
+          const selected: string[] = await checkbox({
+            message: 'Select tools to install:',
+            choices,
+          });
+
+          if (selected.length === 0) {
+            console.log('No tools selected.');
+            break;
+          }
+
+          console.log('\nInstalling tools...');
+          const { installed, skipped } = await toolsAddDirect(studioDir, selected);
+
+          for (const name of installed) {
+            console.log(chalk.green(`  ✓ ${name}.tool.yaml`));
+          }
+          for (const name of skipped) {
+            console.log(chalk.yellow(`  ⚠ ${name} already installed, skipping`));
+          }
+          console.log('');
+          console.log(`Done! ${installed.length} tool${installed.length !== 1 ? 's' : ''} installed.`);
+          break;
+        }
+
+        // Direct mode
+        const config = await loadConfig();
+        const studioDir = config.resolvedStudioDir!;
+
+        const { installed, skipped } = await toolsAddDirect(studioDir, args);
+
+        for (const name of installed) {
+          console.log(chalk.green(`  ✓ ${name}.tool.yaml`));
+        }
+        for (const name of skipped) {
+          console.log(chalk.yellow(`  ⚠ ${name} already installed, skipping`));
+        }
+        console.log('');
+        if (installed.length > 0) {
+          console.log(`Done! ${installed.length} tool${installed.length > 1 ? 's' : ''} installed.`);
+        } else {
+          console.log('No new tools installed.');
+        }
+        break;
+      }
+
+      case 'remove': {
+        const name = args[0];
+        if (!name) {
+          console.error('Usage: studio tools remove <name>');
+          process.exit(1);
+        }
+        const toolsDir = await resolveToolsDir();
+        const toolPath = resolve(toolsDir, `${name}.tool.yaml`);
+        try {
+          await unlink(toolPath);
+          console.log(chalk.green(`✓ Removed tool '${name}'`));
+        } catch {
+          console.error(`Error: Tool '${name}' not found`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'info': {
+        const name = args[0];
+        if (!name) {
+          console.error('Usage: studio tools info <name>');
+          process.exit(1);
+        }
+        const toolsDir = await resolveToolsDir();
+        const toolPath = resolve(toolsDir, `${name}.tool.yaml`);
+        try {
+          const content = await readFile(toolPath, 'utf-8');
+          console.log(content);
+        } catch {
+          console.error(`Error: Tool '${name}' not found.`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      default:
+        console.error(
+          `Unknown tools action: ${action}. Available: list, add, remove, info`
+        );
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}

package/src/commands/users.ts

@@ -0,0 +1,127 @@
+// cli/src/commands/users.ts
+import { randomBytes, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import chalk from 'chalk';
+import { findStudioDir } from '../studio-dir.js';
+import { UserStore } from '@studio-foundation/api/user-store';
+
+async function getStore(): Promise<{ store: UserStore; close: () => void }> {
+  const studioDir = await findStudioDir(process.cwd());
+  if (!studioDir) throw new Error('No .studio/ directory found. Run studio init first.');
+
+  const dbPath = join(studioDir, 'runs', 'runs.db');
+  await mkdir(join(studioDir, 'runs'), { recursive: true });
+  const store = new UserStore(dbPath);
+  return { store, close: () => store.close() };
+}
+
+export async function usersCommand(
+  subcommand: string,
+  args: string[],
+  options: { plan?: string },
+): Promise<void> {
+  switch (subcommand) {
+    case 'list': {
+      const { store, close } = await getStore();
+      try {
+        const users = store.listUsers();
+        if (users.length === 0) {
+          console.log(chalk.gray('No users found.'));
+        } else {
+          console.log(chalk.bold('Users:'));
+          for (const { email, plan, id } of users) {
+            console.log(`  ${chalk.cyan(email)} — plan: ${chalk.yellow(plan)} — id: ${chalk.gray(id)}`);
+          }
+        }
+      } finally {
+        close();
+      }
+      break;
+    }
+
+    case 'add': {
+      const email = args[0];
+      if (!email) {
+        console.error(chalk.red('Usage: studio users add <email> [--plan pro]'));
+        process.exit(1);
+      }
+      const { store, close } = await getStore();
+      try {
+        if (store.getUserByEmail(email)) {
+          console.error(chalk.red(`User ${email} already exists.`));
+          process.exit(1);
+        }
+        const apiKey = randomBytes(32).toString('hex');
+        const user = {
+          id: randomUUID(),
+          email,
+          plan: options.plan ?? 'free',
+          api_key: apiKey,
+          created_at: new Date().toISOString(),
+        };
+        store.saveUser(user);
+        console.log(chalk.green(`✓ User created: ${email} (plan: ${user.plan})`));
+        console.log(chalk.bold('API Key (shown only once):'));
+        console.log(chalk.yellow(apiKey));
+      } finally {
+        close();
+      }
+      break;
+    }
+
+    case 'remove': {
+      const email = args[0];
+      if (!email) {
+        console.error(chalk.red('Usage: studio users remove <email>'));
+        process.exit(1);
+      }
+      const { store, close } = await getStore();
+      try {
+        const user = store.getUserByEmail(email);
+        if (!user) {
+          console.error(chalk.red(`User ${email} not found.`));
+          process.exit(1);
+        }
+        store.deleteUser(user.id);
+        console.log(chalk.green(`✓ User ${email} deleted.`));
+      } finally {
+        close();
+      }
+      break;
+    }
+
+    case 'info': {
+      const email = args[0];
+      if (!email) {
+        console.error(chalk.red('Usage: studio users info <email>'));
+        process.exit(1);
+      }
+      const { store, close } = await getStore();
+      try {
+        const user = store.getUserByEmail(email);
+        if (!user) {
+          console.error(chalk.red(`User ${email} not found.`));
+          process.exit(1);
+        }
+        const today = new Date().toISOString().slice(0, 10);
+        const usage = store.getDailyUsage(user.id, today);
+        console.log(chalk.bold(`User: ${user.email}`));
+        console.log(`  Plan:       ${chalk.yellow(user.plan)}`);
+        console.log(`  ID:         ${chalk.gray(user.id)}`);
+        console.log(`  Created:    ${user.created_at}`);
+        console.log(chalk.bold(`Today (${today}):`));
+        console.log(`  Runs:       ${usage.runs_count}`);
+        console.log(`  Tokens:     ${usage.tokens_used}`);
+      } finally {
+        close();
+      }
+      break;
+    }
+
+    default:
+      console.error(chalk.red(`Unknown subcommand: ${subcommand}`));
+      console.error('Usage: studio users <list|add|remove|info>');
+      process.exit(1);
+  }
+}

package/src/commands/validate.ts

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import yaml from 'js-yaml';
+import type { OutputContract } from '@studio-foundation/contracts';
+import { validateSchema } from '@studio-foundation/engine';
+
+export async function validateCommand(
+  contractPath: string,
+  outputPath: string
+): Promise<void> {
+  try {
+    // Load contract YAML
+    const contractRaw = await readFile(resolve(contractPath), 'utf-8');
+    const contract = yaml.load(contractRaw) as OutputContract;
+
+    // Load output JSON
+    const outputRaw = await readFile(resolve(outputPath), 'utf-8');
+    const output: unknown = JSON.parse(outputRaw);
+
+    // Validate
+    const result = validateSchema(output, contract);
+
+    if (result.valid) {
+      console.log(chalk.green('✓ Valid'));
+    } else {
+      console.log(chalk.red('✗ Invalid'));
+      console.log('');
+      for (const error of result.errors) {
+        console.log(chalk.red(`  - ${error}`));
+      }
+    }
+
+    if (result.warnings.length > 0) {
+      console.log('');
+      for (const warning of result.warnings) {
+        console.log(chalk.yellow(`  ⚠ ${warning}`));
+      }
+    }
+
+    process.exit(result.valid ? 0 : 1);
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}