@studio-foundation/cli 0.3.0-beta.1

package/src/commands/registry/install.ts

@@ -0,0 +1,222 @@
+import chalk from 'chalk';
+import { resolve } from 'node:path';
+import { mkdir, readFile } from 'node:fs/promises';
+import { RegistryClient } from '../../registry/client.js';
+import { RegistryLockfile } from '../../registry/lockfile.js';
+import { RegistryCache } from '../../registry/cache.js';
+import { syncRegistry } from './sync.js';
+import { findStudioDir } from '../../studio-dir.js';
+import { resolveDependencies } from '../../registry/resolver.js';
+import type { PackageMetadata, PackageType, RegistryIndex, Lockfile } from '../../registry/types.js';
+import { INSTALL_DIRS } from '../../registry/types.js';
+
+const SINGLE_FILE_EXTENSIONS: Partial<Record<PackageType, string>> = {
+  tool: '.tool.yaml',
+  pipeline: '.pipeline.yaml',
+  integration: '.integration.yaml',
+  agent: '.agent.yaml',
+  skill: '.skill.md',
+};
+
+const SHELL_EXEC_PATTERN = /execute:\s*\n\s+type:\s*shell/;
+
+interface InstallOptions {
+  studioDir?: string;
+  force?: boolean;
+  cwd?: string;
+  requiredBy?: string;
+  /** Skip interactive prompts (auto-accept). Use when called under a spinner. */
+  interactive?: boolean;
+  _depth?: number;
+  _metaCache?: Map<string, PackageMetadata>;
+}
+
+async function doInstallPackage(
+  nameAtVersion: string,
+  options: InstallOptions,
+  client: RegistryClient,
+  lockfile: RegistryLockfile,
+  index: RegistryIndex,
+  lockfileData: Lockfile,
+  metaCache: Map<string, PackageMetadata>,
+): Promise<void> {
+  const [name, requestedVersion] = nameAtVersion.split('@');
+  const studioDir = options.studioDir!;
+  const depth = options._depth ?? 0;
+  const indent = '  '.repeat(depth);
+
+  // Check already installed
+  const existing = await lockfile.get(name);
+  if (existing && !options.force) {
+    if (options.requiredBy) {
+      await lockfile.addRequiredBy(name, options.requiredBy);
+    }
+    if (depth === 0) {
+      console.log(chalk.yellow(`${name} v${existing.version} is already installed. Use --force to reinstall.`));
+    }
+    return;
+  }
+
+  const indexEntry = index.packages.find(p => p.name === name);
+  if (!indexEntry) throw new Error(`Package '${name}' not found in registry`);
+
+  const type = indexEntry.type as PackageType;
+
+  // Use cached metadata if available (populated by resolver's fetcher)
+  let meta = metaCache.get(name);
+  if (!meta) {
+    meta = await client.fetchMetadata(type, name) as PackageMetadata;
+    metaCache.set(name, meta);
+  }
+  const version = requestedVersion ?? meta.version;
+
+  console.log(`${indent}Installing ${depth > 0 ? 'dependency: ' : ''}${chalk.bold(name)} v${version} [${type}]...`);
+
+  let sha256: string;
+  const destBaseDir = resolve(studioDir, INSTALL_DIRS[type]);
+  await mkdir(destBaseDir, { recursive: true });
+
+  if (type === 'template' || type === 'plugin') {
+    const destDir = resolve(destBaseDir, name);
+    await mkdir(destDir, { recursive: true });
+    sha256 = await client.downloadDirectory(type, name, 'project', destDir);
+  } else {
+    const ext = SINGLE_FILE_EXTENSIONS[type] ?? '.yaml';
+    const filename = `${name}${ext}`;
+    const result = await client.downloadFile(type, name, filename, destBaseDir);
+    sha256 = result.sha256;
+
+    const content = await readFile(result.destPath, 'utf8');
+    if (SHELL_EXEC_PATTERN.test(content) && options.interactive !== false) {
+      const { confirm } = await import('@inquirer/prompts');
+      const proceed = await confirm({
+        message: chalk.yellow(`⚠ This package executes shell commands. Review ${result.destPath} before use. Install anyway?`),
+        default: false,
+      });
+      if (!proceed) {
+        const { unlink } = await import('node:fs/promises');
+        await unlink(result.destPath);
+        console.log('Installation cancelled.');
+        return;
+      }
+    }
+  }
+
+  if (meta.requires_binaries?.length) {
+    const { spawnSync } = await import('node:child_process');
+    for (const bin of meta.requires_binaries) {
+      const check = spawnSync('which', [bin], { encoding: 'utf8' });
+      if (check.status !== 0) {
+        console.log(chalk.yellow(`⚠ Warning: required binary '${bin}' not found in PATH`));
+      }
+    }
+  }
+
+  await lockfile.add(name, {
+    version,
+    type,
+    installed_at: new Date().toISOString().split('T')[0],
+    sha256,
+    required_by: options.requiredBy ? [options.requiredBy] : [],
+  });
+
+  console.log(`${indent}${chalk.green(`✓ Installed ${name} v${version}`)}`);
+
+  // Resolve and install dependencies
+  if (meta.dependencies) {
+    const graph = await resolveDependencies(
+      name,
+      meta,
+      index,
+      lockfileData,
+      (depName) => {
+        const depEntry = index.packages.find(p => p.name === depName);
+        const depType = (depEntry?.type ?? 'tool') as PackageType;
+        const cached = metaCache.get(depName);
+        if (cached) return Promise.resolve(cached);
+        return client.fetchMetadata(depType, depName).then(m => {
+          metaCache.set(depName, m as PackageMetadata);
+          return m as PackageMetadata;
+        });
+      },
+    );
+
+    for (const dep of graph.required) {
+      await doInstallPackage(
+        dep.name,
+        { studioDir, requiredBy: name, interactive: options.interactive, _depth: depth + 1 },
+        client,
+        lockfile,
+        index,
+        lockfileData,
+        metaCache,
+      );
+    }
+
+    if (depth === 0 && graph.recommended.length > 0) {
+      let install = options.interactive !== false;
+      if (options.interactive !== false) {
+        const names = graph.recommended.map(d => d.name).join(', ');
+        const { confirm } = await import('@inquirer/prompts');
+        install = await confirm({
+          message: `Install recommended packages? [${names}]`,
+          default: true,
+        });
+      }
+      if (install) {
+        for (const dep of graph.recommended) {
+          await doInstallPackage(
+            dep.name,
+            { studioDir, interactive: options.interactive, _depth: depth + 1 },
+            client,
+            lockfile,
+            index,
+            lockfileData,
+            metaCache,
+          );
+        }
+      }
+    }
+  }
+}
+
+export async function installPackage(nameAtVersion: string, options: InstallOptions = {}): Promise<void> {
+  const [name] = nameAtVersion.split('@');
+
+  const studioDir = options.studioDir ??
+    (await findStudioDir(options.cwd ?? process.cwd()) ?? resolve(process.cwd(), '.studio'));
+  const resolvedOptions = { ...options, studioDir };
+
+  const lockfile = new RegistryLockfile(studioDir);
+
+  // Sync cache and resolve package type
+  await syncRegistry({ force: false, silent: true });
+  const cache = new RegistryCache();
+  const index = await cache.read();
+  if (!index?.packages.find(p => p.name === name)) {
+    throw new Error(`Package '${name}' not found in registry`);
+  }
+
+  const client = new RegistryClient();
+  const lockfileData = await lockfile.read();
+  const metaCache = options._metaCache ?? new Map<string, PackageMetadata>();
+
+  await doInstallPackage(
+    nameAtVersion,
+    resolvedOptions,
+    client,
+    lockfile,
+    index,
+    lockfileData,
+    metaCache,
+  );
+}
+
+export async function installCommand(nameAtVersion: string, options: { force?: boolean } = {}): Promise<void> {
+  try {
+    await installPackage(nameAtVersion, options);
+  } catch (err) {
+    console.error(chalk.red(`Install failed: ${err instanceof Error ? err.message : err}`));
+    process.exit(1);
+  }
+}

package/src/commands/registry/publish.ts

@@ -0,0 +1,112 @@
+import chalk from 'chalk';
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import type { PackageMetadata } from '../../registry/types.js';
+import { REGISTRY_REPO } from '../../registry/types.js';
+
+const REQUIRED_METADATA_FIELDS = ['name', 'version', 'description', 'author', 'license', 'type'];
+
+export async function validatePublishPayload(packagePath: string): Promise<PackageMetadata> {
+  const absPath = resolve(packagePath);
+
+  if (!existsSync(absPath)) {
+    throw new Error(`Path does not exist: ${absPath}`);
+  }
+
+  const packageDir = dirname(absPath);
+  const metadataPath = resolve(packageDir, 'metadata.json');
+
+  if (!existsSync(metadataPath)) {
+    throw new Error(`metadata.json not found in ${packageDir}`);
+  }
+
+  const meta = JSON.parse(await readFile(metadataPath, 'utf8')) as Partial<PackageMetadata>;
+  const missing = REQUIRED_METADATA_FIELDS.filter(f => !(f in meta));
+  if (missing.length > 0) {
+    throw new Error(`Missing required metadata fields: ${missing.join(', ')}`);
+  }
+
+  return meta as PackageMetadata;
+}
+
+interface PublishOptions {
+  dryRun?: boolean;
+}
+
+export async function publishCommand(packagePath: string, options: PublishOptions = {}): Promise<void> {
+  try {
+    console.log('Validating package...');
+    const meta = await validatePublishPayload(packagePath);
+    console.log(chalk.green(`✓ ${meta.name} v${meta.version} [${meta.type}]`));
+
+    if (options.dryRun) {
+      console.log(chalk.gray('Dry run — skipping GitHub PR'));
+      return;
+    }
+
+    // Check gh CLI is available and authenticated
+    const ghCheck = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8' });
+    if (ghCheck.status !== 0) {
+      throw new Error('GitHub CLI not authenticated. Run: gh auth login');
+    }
+
+    const packageDir = dirname(resolve(packagePath));
+    const branchName = `${meta.type}-${meta.name}-v${meta.version}`;
+    const registryPath = `${meta.type}s/${meta.name}`;
+
+    console.log('Creating GitHub PR...');
+
+    // Fork the registry (idempotent)
+    spawnSync('gh', ['repo', 'fork', REGISTRY_REPO, '--clone=false'], {
+      encoding: 'utf8',
+    });
+
+    // Get the authenticated user's login for the fork URL
+    const userResult = spawnSync('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf8' });
+    const userLogin = userResult.stdout.trim();
+    if (!userLogin) throw new Error('Failed to get GitHub username');
+
+    // Clone fork to temp dir
+    const tmp = `/tmp/studio-registry-publish-${Date.now()}`;
+    const cloneResult = spawnSync('git', ['clone', `https://github.com/${userLogin}/registry.git`, tmp], {
+      encoding: 'utf8',
+    });
+    if (cloneResult.status !== 0) throw new Error(`Failed to clone fork: ${cloneResult.stderr}`);
+
+    // Create branch, copy files, push
+    spawnSync('git', ['-C', tmp, 'checkout', '-b', branchName], { encoding: 'utf8' });
+    spawnSync('cp', ['-r', packageDir, resolve(tmp, registryPath)], { encoding: 'utf8' });
+    spawnSync('git', ['-C', tmp, 'add', registryPath], { encoding: 'utf8' });
+    spawnSync('git', ['-C', tmp, 'commit', '-m', `[${meta.type}] ${meta.name} v${meta.version}`], {
+      encoding: 'utf8',
+    });
+    const pushResult = spawnSync('git', ['-C', tmp, 'push', '-u', 'origin', branchName], {
+      encoding: 'utf8',
+    });
+    if (pushResult.status !== 0) throw new Error(`Failed to push branch: ${pushResult.stderr}`);
+
+    // Open PR
+    const prResult = spawnSync('gh', [
+      'pr', 'create',
+      '--repo', REGISTRY_REPO,
+      '--title', `[${meta.type}] ${meta.name} v${meta.version}`,
+      '--body', `## ${meta.name}\n\n${meta.description}\n\n**Author:** ${meta.author}\n**License:** ${meta.license}\n**Version:** ${meta.version}`,
+      '--head', `${userLogin}:${branchName}`,
+    ], { encoding: 'utf8', cwd: tmp });
+
+    // Cleanup
+    spawnSync('rm', ['-rf', tmp]);
+
+    if (prResult.status === 0) {
+      const prUrl = prResult.stdout.trim();
+      console.log(chalk.green(`✓ PR opened: ${prUrl}`));
+    } else {
+      throw new Error(`Failed to create PR: ${prResult.stderr}`);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Publish failed: ${err instanceof Error ? err.message : err}`));
+    process.exit(1);
+  }
+}

package/src/commands/registry/remove.ts

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+import { rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { RegistryLockfile } from '../../registry/lockfile.js';
+import { findStudioDir } from '../../studio-dir.js';
+import { INSTALL_DIRS } from '../../registry/types.js';
+import type { PackageType } from '../../registry/types.js';
+
+interface RemoveOptions {
+  studioDir?: string;
+  cwd?: string;
+}
+
+const FILE_EXTENSIONS: Partial<Record<PackageType, string>> = {
+  tool: '.tool.yaml',
+  pipeline: '.pipeline.yaml',
+  integration: '.integration.yaml',
+  agent: '.agent.yaml',
+  skill: '.skill.md',
+};
+
+async function deletePackageFiles(studioDir: string, name: string, type: PackageType): Promise<void> {
+  const destDir = resolve(studioDir, INSTALL_DIRS[type]);
+  if (type === 'template' || type === 'plugin') {
+    const dirPath = resolve(destDir, name);
+    if (existsSync(dirPath)) await rm(dirPath, { recursive: true });
+  } else {
+    const ext = FILE_EXTENSIONS[type] ?? '.yaml';
+    const filePath = resolve(destDir, `${name}${ext}`);
+    if (existsSync(filePath)) await rm(filePath);
+  }
+}
+
+export async function removePackage(name: string, options: RemoveOptions = {}): Promise<void> {
+  const studioDir = options.studioDir ??
+    (await findStudioDir(options.cwd ?? process.cwd()) ?? resolve(process.cwd(), '.studio'));
+  const lockfile = new RegistryLockfile(studioDir);
+  const entry = await lockfile.get(name);
+  if (!entry) throw new Error(`'${name}' is not installed`);
+
+  // Block removal if another package depends on this one
+  const dependents = (entry.required_by ?? []).filter(d => d !== '');
+  if (dependents.length > 0) {
+    throw new Error(`'${name}' is required by: ${dependents.join(', ')}. Remove them first.`);
+  }
+
+  const type = entry.type as PackageType;
+  await deletePackageFiles(studioDir, name, type);
+  await lockfile.remove(name);
+  console.log(chalk.green(`✓ Removed ${name}`));
+
+  // Find orphans: packages whose required_by only contained 'name'
+  const data = await lockfile.read();
+  const orphans: string[] = [];
+  for (const [pkgName, pkgEntry] of Object.entries(data.installed)) {
+    const wasRequired = pkgEntry.required_by?.includes(name);
+    const otherRequirers = (pkgEntry.required_by ?? []).filter(r => r !== name);
+    if (wasRequired && otherRequirers.length === 0) {
+      orphans.push(pkgName);
+    }
+  }
+
+  if (orphans.length > 0) {
+    const { confirm } = await import('@inquirer/prompts');
+    const cleanup = await confirm({
+      message: `These packages are no longer needed: [${orphans.join(', ')}]. Remove them?`,
+      default: true,
+    });
+    if (cleanup) {
+      for (const orphan of orphans) {
+        // Strip the requirer reference so the protection check passes
+        await lockfile.removeRequiredBy(orphan, name);
+        await removePackage(orphan, { studioDir });
+      }
+    } else {
+      console.log(chalk.yellow(`Packages left installed: [${orphans.join(', ')}]`));
+    }
+  }
+}
+
+export async function removeCommand(name: string): Promise<void> {
+  try {
+    await removePackage(name);
+  } catch (err) {
+    console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+    process.exit(1);
+  }
+}

package/src/commands/registry/search.ts

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import { RegistryCache } from '../../registry/cache.js';
+import { syncRegistry } from './sync.js';
+import type { PackageEntry, PackageType } from '../../registry/types.js';
+
+export function searchPackages(
+  packages: PackageEntry[],
+  query?: string,
+  type?: PackageType | string,
+): PackageEntry[] {
+  let results = packages;
+
+  if (type) {
+    results = results.filter(p => p.type === type);
+  }
+
+  if (query) {
+    const q = query.toLowerCase();
+    results = results.filter(p =>
+      p.name.toLowerCase().includes(q) ||
+      p.description.toLowerCase().includes(q) ||
+      p.tags.some(t => t.toLowerCase().includes(q)),
+    );
+  }
+
+  return results;
+}
+
+function renderPackage(pkg: PackageEntry): void {
+  console.log(
+    `  ${chalk.bold(pkg.name)} ${chalk.gray(`v${pkg.version}`)} ${chalk.cyan(`[${pkg.type}]`)}`,
+  );
+  console.log(`    ${pkg.description}`);
+  if (pkg.tags.length > 0) {
+    console.log(`    ${chalk.gray(pkg.tags.join(', '))}`);
+  }
+}
+
+interface SearchOptions {
+  type?: string;
+}
+
+export async function searchCommand(query: string, options: SearchOptions = {}): Promise<void> {
+  await syncRegistry({ force: false, silent: true });
+  const cache = new RegistryCache();
+  const index = await cache.read();
+  if (!index) {
+    console.error(chalk.red('Failed to load registry. Run: studio registry sync'));
+    process.exit(1);
+  }
+
+  const results = searchPackages(index.packages, query, options.type as PackageType | undefined);
+
+  if (results.length === 0) {
+    console.log(chalk.yellow(`No packages found for "${query}"`));
+    return;
+  }
+
+  console.log(chalk.bold(`\n${results.length} package${results.length > 1 ? 's' : ''} found:\n`));
+  for (const pkg of results) {
+    renderPackage(pkg);
+    console.log();
+  }
+  console.log(chalk.gray(`Install: studio registry install <name>`));
+}
+
+export async function browseCommand(): Promise<void> {
+  await syncRegistry({ force: false, silent: true });
+  const cache = new RegistryCache();
+  const index = await cache.read();
+  if (!index) {
+    console.error(chalk.red('Failed to load registry. Run: studio registry sync'));
+    process.exit(1);
+  }
+
+  const sorted = [...index.packages].sort((a, b) => b.downloads - a.downloads);
+
+  console.log(chalk.bold(`\nStudio Community Registry — ${sorted.length} packages\n`));
+
+  const byType: Record<string, PackageEntry[]> = {};
+  for (const pkg of sorted) {
+    if (!byType[pkg.type]) byType[pkg.type] = [];
+    byType[pkg.type].push(pkg);
+  }
+
+  for (const [type, pkgs] of Object.entries(byType)) {
+    console.log(chalk.bold.underline(`${type}s`));
+    for (const pkg of pkgs) {
+      renderPackage(pkg);
+      console.log();
+    }
+  }
+}

package/src/commands/registry/sync.ts

@@ -0,0 +1,24 @@
+import chalk from 'chalk';
+import { RegistryCache } from '../../registry/cache.js';
+import { RegistryClient } from '../../registry/client.js';
+
+interface SyncOptions {
+  cacheDir?: string;
+  force?: boolean;
+  silent?: boolean;
+}
+
+export async function syncRegistry(options: SyncOptions = {}): Promise<void> {
+  const cache = new RegistryCache(options.cacheDir);
+
+  if (!options.force && await cache.isFresh()) {
+    if (!options.silent) console.log(chalk.gray('Registry index is up to date.'));
+    return;
+  }
+
+  if (!options.silent) process.stdout.write('Syncing registry... ');
+  const client = new RegistryClient();
+  const index = await client.fetchIndex();
+  await cache.write(index);
+  if (!options.silent) console.log(chalk.green(`✓ ${index.packages.length} packages`));
+}

package/src/commands/registry/update.ts

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+import { RegistryLockfile } from '../../registry/lockfile.js';
+import { RegistryCache } from '../../registry/cache.js';
+import { syncRegistry } from './sync.js';
+import { installPackage } from './install.js';
+import { findStudioDir } from '../../studio-dir.js';
+import { resolve } from 'node:path';
+
+interface OutdatedEntry {
+  name: string;
+  installed: string;
+  latest: string;
+  type: string;
+}
+
+interface UpdateOptions {
+  studioDir?: string;
+  cwd?: string;
+}
+
+export async function outdatedPackages(options: UpdateOptions = {}): Promise<OutdatedEntry[]> {
+  const studioDir = options.studioDir ??
+    (await findStudioDir(options.cwd ?? process.cwd()) ?? resolve(process.cwd(), '.studio'));
+  await syncRegistry({ force: false, silent: true });
+  const cache = new RegistryCache();
+  const index = await cache.read();
+  if (!index) return [];
+
+  const lockfile = new RegistryLockfile(studioDir);
+  const installed = await lockfile.list();
+  const results: OutdatedEntry[] = [];
+
+  for (const entry of installed) {
+    const latest = index.packages.find(p => p.name === entry.name);
+    if (latest && latest.version !== entry.version) {
+      results.push({ name: entry.name, installed: entry.version, latest: latest.version, type: entry.type });
+    }
+  }
+
+  return results;
+}
+
+export async function outdatedCommand(options: UpdateOptions = {}): Promise<void> {
+  const outdated = await outdatedPackages(options);
+  if (outdated.length === 0) {
+    console.log(chalk.green('All packages are up to date.'));
+    return;
+  }
+  console.log(chalk.bold('\nOutdated packages:\n'));
+  for (const pkg of outdated) {
+    console.log(`  ${chalk.bold(pkg.name)} ${chalk.red(pkg.installed)} → ${chalk.green(pkg.latest)} [${pkg.type}]`);
+  }
+  console.log(`\nRun: studio registry update <name>`);
+}
+
+export async function updateCommand(name: string): Promise<void> {
+  try {
+    await installPackage(name, { force: true });
+  } catch (err) {
+    console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+    process.exit(1);
+  }
+}