@agent-foundry/studio 1.0.0

package/src/types/workspace.ts

@@ -0,0 +1,124 @@
+/**
+ * Workspace types
+ *
+ * Based on AF-studio-SPEC.md - Workspace is the runtime representation
+ * of a project being actively worked on in the Studio.
+ */
+
+/**
+ * Dev server status
+ */
+export type DevServerStatus = 'stopped' | 'starting' | 'running' | 'error';
+
+/**
+ * Dev server runtime state
+ */
+export interface DevServerState {
+  /** Current server status */
+  status: DevServerStatus;
+
+  /** Port number if running */
+  port?: number;
+
+  /** Full URL to access dev server */
+  url?: string;
+
+  /** Process ID of dev server */
+  pid?: number;
+
+  /** Last error message if status is 'error' */
+  lastError?: string;
+
+  /** Timestamp when server started */
+  startedAt?: string;
+}
+
+/**
+ * Workspace - runtime state of an active project in Studio
+ *
+ * This extends StudioProject with runtime-specific fields that are
+ * not persisted to the database.
+ */
+export interface Workspace {
+  /** Unique identifier (ULID recommended) */
+  id: string;
+
+  /** Human-readable workspace name */
+  name: string;
+
+  /** Local filesystem root path */
+  rootPath: string;
+
+  /** ISO timestamp of creation */
+  createdAt: string;
+
+  /** ISO timestamp of last update */
+  updatedAt: string;
+
+  /** Parent workspace ID if this is a fork */
+  parentWorkspaceId?: string;
+
+  /** Associated project ID in database (optional - may be local-only) */
+  projectId?: string;
+
+  /** Dev server runtime state */
+  devServer?: DevServerState;
+}
+
+/**
+ * Session - an agent interaction session within a workspace
+ * Based on OpenCode session model
+ */
+export interface Session {
+  /** Session ID */
+  id: string;
+
+  /** Associated workspace ID */
+  workspaceId: string;
+
+  /** Active agent (plan or build) */
+  agentId: 'plan' | 'build' | string;
+
+  /** Parent session ID if forked */
+  parentId?: string;
+
+  /** ISO timestamp of creation */
+  createdAt: string;
+
+  /** ISO timestamp of last activity */
+  lastActivityAt: string;
+}
+
+/**
+ * Viewport preset for responsive preview
+ */
+export interface ViewportPreset {
+  name: string;
+  width: number;
+  height: number;
+  deviceScaleFactor?: number;
+}
+
+/**
+ * Built-in viewport presets from SPEC
+ */
+export const VIEWPORT_PRESETS: ViewportPreset[] = [
+  { name: 'Desktop', width: 1280, height: 800 },
+  { name: 'iPhone SE', width: 375, height: 667, deviceScaleFactor: 2 },
+  { name: 'iPhone 14 Pro', width: 390, height: 844, deviceScaleFactor: 3 },
+  { name: 'iPad', width: 768, height: 1024, deviceScaleFactor: 2 },
+];
+
+/**
+ * Workspace runner command whitelist (for security)
+ */
+export const ALLOWED_SCRIPTS = [
+  'install',
+  'dev',
+  'build',
+  'test',
+  'lint',
+  'preview',
+] as const;
+
+export type AllowedScript = typeof ALLOWED_SCRIPTS[number];

package/src/utils/build.ts

@@ -0,0 +1,199 @@
+/**
+ * Build utilities for Vite projects
+ *
+ * Provides helpers for running builds and collecting output files.
+ */
+
+import type { UploadFile } from '../oss/types';
+import type { ProjectConfig } from '../types/project';
+
+/**
+ * MIME type mapping for common file extensions
+ */
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.otf': 'font/otf',
+  '.map': 'application/json',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml',
+  '.webmanifest': 'application/manifest+json',
+};
+
+/**
+ * Get MIME type for a file based on extension
+ */
+export function getMimeType(filename: string): string {
+  const ext = filename.substring(filename.lastIndexOf('.')).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+/**
+ * Build command configuration
+ */
+export interface BuildConfig {
+  /** Working directory (project root) */
+  cwd: string;
+
+  /** Build command (default: "pnpm build") */
+  command?: string;
+
+  /** Environment variables to set */
+  env?: Record<string, string>;
+
+  /** Timeout in milliseconds (default: 5 minutes) */
+  timeout?: number;
+}
+
+/**
+ * Build result
+ */
+export interface BuildResult {
+  /** Whether build was successful */
+  success: boolean;
+
+  /** Output directory path */
+  outputDir: string;
+
+  /** Build output log */
+  log: string;
+
+  /** Error message if failed */
+  error?: string;
+
+  /** Build duration in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * Get the default build command based on project config
+ */
+export function getDefaultBuildCommand(config: ProjectConfig): string {
+  return config.buildCommand || 'pnpm build';
+}
+
+/**
+ * Get the output directory based on project config
+ */
+export function getOutputDir(config: ProjectConfig): string {
+  return config.outputDir || 'dist';
+}
+
+/**
+ * Convert a File object to UploadFile format
+ *
+ * @param file - File object from file input or FileList
+ * @param relativePath - Relative path within the bundle
+ */
+export function fileToUploadFile(file: File, relativePath: string): UploadFile {
+  return {
+    path: relativePath,
+    content: file,
+    contentType: file.type || getMimeType(file.name),
+  };
+}
+
+/**
+ * Calculate total size of files
+ */
+export function calculateTotalSize(files: UploadFile[]): number {
+  let total = 0;
+  for (const file of files) {
+    if (file.content instanceof Blob) {
+      total += file.content.size;
+    } else if (file.content instanceof ArrayBuffer) {
+      total += file.content.byteLength;
+    } else if (typeof file.content === 'string') {
+      total += new Blob([file.content]).size;
+    }
+  }
+  return total;
+}
+
+/**
+ * Format file size for display
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 B';
+
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const k = 1024;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${units[i]}`;
+}
+
+/**
+ * Validate that required files exist in the bundle
+ */
+export function validateBundle(files: UploadFile[]): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const paths = new Set(files.map(f => f.path));
+
+  // Check for index.html
+  if (!paths.has('index.html')) {
+    errors.push('Missing index.html - required for web deployment');
+  }
+
+  // Warn about large files
+  for (const file of files) {
+    let size = 0;
+    if (file.content instanceof Blob) {
+      size = file.content.size;
+    } else if (file.content instanceof ArrayBuffer) {
+      size = file.content.byteLength;
+    }
+
+    // Warn if file is larger than 10MB
+    if (size > 10 * 1024 * 1024) {
+      errors.push(`Large file detected: ${file.path} (${formatFileSize(size)})`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0 || !errors.some(e => e.includes('Missing')),
+    errors,
+  };
+}
+
+/**
+ * Files to exclude from upload (common patterns)
+ */
+export const EXCLUDE_PATTERNS = [
+  /^\.git\//,
+  /^node_modules\//,
+  /^\.DS_Store$/,
+  /^Thumbs\.db$/,
+  /\.map$/,  // Source maps (optional)
+  /^\.env/,
+];
+
+/**
+ * Check if a file should be excluded from upload
+ */
+export function shouldExclude(path: string, includeSourceMaps = false): boolean {
+  for (const pattern of EXCLUDE_PATTERNS) {
+    if (pattern.test(path)) {
+      // Allow source maps if requested
+      if (pattern.source === '\\.map$' && includeSourceMaps) {
+        continue;
+      }
+      return true;
+    }
+  }
+  return false;
+}

package/src/utils/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Utility functions for Studio
+ */
+
+export * from './build';
+export * from './manifest';

package/src/utils/manifest.ts

@@ -0,0 +1,224 @@
+/**
+ * WebApp Manifest utilities
+ *
+ * Generates manifest files for deployed web applications,
+ * compatible with Agent Foundry's app registry.
+ */
+
+import type { StudioProject } from '../types/project';
+import type { Deployment } from '../types/deployment';
+
+/**
+ * WebApp manifest structure for Agent Foundry
+ */
+export interface WebAppManifest {
+  /** Schema version */
+  schema: string;
+
+  /** App ID (e.g., "com.agentfoundry.myapp") */
+  id: string;
+
+  /** Display name */
+  name: string;
+
+  /** Short name for icons */
+  shortName?: string;
+
+  /** App description */
+  description?: string;
+
+  /** App version */
+  version: string;
+
+  /** Entry URL (index.html) */
+  entryUrl: string;
+
+  /** Icon URLs */
+  icons?: {
+    src: string;
+    sizes: string;
+    type?: string;
+  }[];
+
+  /** Theme color */
+  themeColor?: string;
+
+  /** Background color */
+  backgroundColor?: string;
+
+  /** Display mode */
+  display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+
+  /** Orientation preference */
+  orientation?: 'any' | 'portrait' | 'landscape';
+
+  /** Categories */
+  categories?: string[];
+
+  /** Agent Foundry specific metadata */
+  agentFoundry?: {
+    /** Creator user ID */
+    createdBy: string;
+
+    /** Deployment ID */
+    deploymentId: string;
+
+    /** Project ID */
+    projectId: string;
+
+    /** Framework used */
+    framework: string;
+
+    /** Build timestamp */
+    builtAt: string;
+
+    /** Bundle size in bytes */
+    bundleSize?: number;
+  };
+}
+
+/**
+ * Options for generating a manifest
+ */
+export interface ManifestOptions {
+  /** App ID prefix (default: "com.agentfoundry.studio") */
+  idPrefix?: string;
+
+  /** Theme color */
+  themeColor?: string;
+
+  /** Background color */
+  backgroundColor?: string;
+
+  /** Icon URL */
+  iconUrl?: string;
+
+  /** Categories */
+  categories?: string[];
+}
+
+/**
+ * Generate a WebApp manifest for a deployed project
+ *
+ * @param project - The Studio project
+ * @param deployment - The deployment record
+ * @param options - Optional manifest configuration
+ */
+export function generateManifest(
+  project: StudioProject,
+  deployment: Deployment,
+  options: ManifestOptions = {}
+): WebAppManifest {
+  const idPrefix = options.idPrefix ?? 'com.agentfoundry.studio';
+  const appId = `${idPrefix}.${project.slug}`;
+
+  const manifest: WebAppManifest = {
+    schema: 'agent-foundry.webapp.v1',
+    id: appId,
+    name: project.name,
+    shortName: project.slug,
+    description: project.description,
+    version: deployment.version,
+    entryUrl: deployment.ossUrl ?? `https://placeholder/${deployment.id}/index.html`,
+    display: 'standalone',
+    orientation: 'any',
+    themeColor: options.themeColor ?? '#000000',
+    backgroundColor: options.backgroundColor ?? '#ffffff',
+    categories: options.categories ?? ['tools', 'productivity'],
+    agentFoundry: {
+      createdBy: project.userId,
+      deploymentId: deployment.id,
+      projectId: project.id,
+      framework: project.framework,
+      builtAt: deployment.publishedAt ?? deployment.createdAt,
+      bundleSize: deployment.bundleSizeBytes,
+    },
+  };
+
+  if (options.iconUrl) {
+    manifest.icons = [
+      { src: options.iconUrl, sizes: '192x192', type: 'image/png' },
+      { src: options.iconUrl, sizes: '512x512', type: 'image/png' },
+    ];
+  }
+
+  return manifest;
+}
+
+/**
+ * Generate a standard web app manifest (PWA compatible)
+ */
+export function generateWebManifest(
+  project: StudioProject,
+  options: ManifestOptions = {}
+): Record<string, unknown> {
+  return {
+    name: project.name,
+    short_name: project.slug,
+    description: project.description,
+    start_url: '/',
+    display: 'standalone',
+    background_color: options.backgroundColor ?? '#ffffff',
+    theme_color: options.themeColor ?? '#000000',
+    icons: options.iconUrl
+      ? [
+          { src: options.iconUrl, sizes: '192x192', type: 'image/png' },
+          { src: options.iconUrl, sizes: '512x512', type: 'image/png' },
+        ]
+      : [],
+  };
+}
+
+/**
+ * Serialize manifest to JSON string
+ */
+export function serializeManifest(manifest: WebAppManifest): string {
+  return JSON.stringify(manifest, null, 2);
+}
+
+/**
+ * Parse manifest from JSON string
+ */
+export function parseManifest(json: string): WebAppManifest {
+  const parsed = JSON.parse(json);
+
+  // Validate schema
+  if (!parsed.schema || !parsed.schema.startsWith('agent-foundry.webapp.')) {
+    throw new Error('Invalid manifest: missing or invalid schema');
+  }
+
+  if (!parsed.id || !parsed.name || !parsed.version) {
+    throw new Error('Invalid manifest: missing required fields (id, name, version)');
+  }
+
+  return parsed as WebAppManifest;
+}
+
+/**
+ * Generate deployment URL path
+ *
+ * @param userId - User ID
+ * @param projectSlug - Project slug
+ * @param version - Deployment version
+ */
+export function generateDeploymentPath(
+  userId: string,
+  projectSlug: string,
+  version: string
+): string {
+  return `${userId}/${projectSlug}/${version}`;
+}
+
+/**
+ * Generate a unique deployment version based on timestamp
+ */
+export function generateVersionFromTimestamp(date: Date = new Date()): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hours = String(date.getHours()).padStart(2, '0');
+  const minutes = String(date.getMinutes()).padStart(2, '0');
+  const seconds = String(date.getSeconds()).padStart(2, '0');
+
+  return `${year}.${month}.${day}-${hours}${minutes}${seconds}`;
+}