devfolio-page 0.1.0

package/dist/cli/commands/validate.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import { validatePortfolio, getPortfolioSummary, ValidationError, FileError, ParseError, } from '../helpers/validate.js';
+export async function validateCommand(file) {
+    console.log(chalk.dim(`Validating ${file}...\n`));
+    try {
+        const portfolio = validatePortfolio(file);
+        const summary = getPortfolioSummary(portfolio);
+        console.log(chalk.green('✓') + ` ${chalk.bold(file)} is valid\n`);
+        // Show summary
+        console.log(`  ${chalk.dim('Meta:')} ${summary.name}, ${summary.title}`);
+        // Build sections summary
+        const sections = [];
+        if (summary.experienceCount > 0) {
+            sections.push(`${summary.experienceCount} experience`);
+        }
+        if (summary.projectCount > 0) {
+            sections.push(`${summary.projectCount} project${summary.projectCount > 1 ? 's' : ''}`);
+        }
+        if (summary.skillCategoryCount > 0) {
+            sections.push(`${summary.skillCategoryCount} skill categor${summary.skillCategoryCount > 1 ? 'ies' : 'y'}`);
+        }
+        if (summary.writingCount > 0) {
+            sections.push(`${summary.writingCount} article${summary.writingCount > 1 ? 's' : ''}`);
+        }
+        if (summary.educationCount > 0) {
+            sections.push(`${summary.educationCount} education`);
+        }
+        if (sections.length > 0) {
+            console.log(`  ${chalk.dim('Sections:')} ${sections.join(', ')}`);
+        }
+        else {
+            console.log(`  ${chalk.dim('Sections:')} ${chalk.yellow('none (add some content!)')}`);
+        }
+        console.log(`  ${chalk.dim('Theme:')} ${summary.theme}`);
+        console.log();
+    }
+    catch (err) {
+        if (err instanceof ValidationError) {
+            console.log(chalk.red('✗') + ' Validation failed\n');
+            // Group errors by whether they have hints
+            const errorsWithHints = [];
+            const errorsWithoutHints = [];
+            for (const error of err.errors) {
+                if (error.hint) {
+                    errorsWithHints.push(error);
+                }
+                else {
+                    errorsWithoutHints.push(error);
+                }
+            }
+            // Show all errors
+            for (const error of err.errors) {
+                console.log(`  ${chalk.red('•')} ${chalk.yellow(error.path)} - ${error.message}`);
+            }
+            // Show hints for first error that has one
+            const firstHint = errorsWithHints[0];
+            if (firstHint?.hint) {
+                console.log();
+                console.log(chalk.dim('  Expected format:'));
+                const hintLines = firstHint.hint.split('\n');
+                for (const line of hintLines) {
+                    console.log(chalk.dim(`    ${line}`));
+                }
+            }
+            console.log();
+            process.exit(1);
+        }
+        if (err instanceof FileError) {
+            console.log(chalk.red('✗') + ` ${err.message}`);
+            process.exit(1);
+        }
+        if (err instanceof ParseError) {
+            console.log(chalk.red('✗') + ' YAML syntax error\n');
+            if (err.line !== undefined) {
+                console.log(`  ${chalk.dim('Line')} ${err.line + 1}: ${err.message}`);
+            }
+            else {
+                console.log(`  ${err.message}`);
+            }
+            console.log();
+            process.exit(1);
+        }
+        // Unknown error
+        throw err;
+    }
+}

package/dist/cli/helpers/validate.js

@@ -0,0 +1,99 @@
+import { readFileSync } from 'fs';
+import yaml from 'js-yaml';
+import { portfolioSchema } from '../schemas/portfolio.schema.js';
+export class ValidationError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+        this.name = 'ValidationError';
+    }
+}
+export class FileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FileError';
+    }
+}
+export class ParseError extends Error {
+    line;
+    constructor(message, line) {
+        super(message);
+        this.line = line;
+        this.name = 'ParseError';
+    }
+}
+function getHintForError(path, message) {
+    if (path.includes('date') && message.includes('YYYY-MM')) {
+        return `date:
+      start: 2024-01
+      end: present`;
+    }
+    if (path.includes('email')) {
+        return 'email: you@example.com';
+    }
+    if (path.includes('url') || message.includes('URL')) {
+        return 'url: https://example.com';
+    }
+    if (path.includes('theme')) {
+        return "theme: srcl  # Options: srcl, modern, minimal, dark-academia";
+    }
+    if (path.includes('highlights') && message.includes('at least')) {
+        return `highlights:
+      - Your key achievement or responsibility`;
+    }
+    if (path.includes('tags') && message.includes('at least')) {
+        return 'tags: [TypeScript, React]';
+    }
+    return undefined;
+}
+export function validatePortfolio(yamlPath) {
+    // Read file
+    let content;
+    try {
+        content = readFileSync(yamlPath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            throw new FileError(`File not found: ${yamlPath}`);
+        }
+        throw new FileError(`Cannot read file: ${yamlPath}`);
+    }
+    // Parse YAML
+    let data;
+    try {
+        data = yaml.load(content);
+    }
+    catch (err) {
+        if (err instanceof yaml.YAMLException) {
+            throw new ParseError(`YAML syntax error: ${err.reason}`, err.mark?.line);
+        }
+        throw new ParseError('Failed to parse YAML');
+    }
+    // Validate against schema
+    const result = portfolioSchema.safeParse(data);
+    if (!result.success) {
+        const errors = result.error.issues.map((issue) => {
+            const path = issue.path.join('.');
+            const message = issue.message;
+            const hint = getHintForError(path, message);
+            return { path, message, hint };
+        });
+        throw new ValidationError('Portfolio validation failed', errors);
+    }
+    return result.data;
+}
+export function getPortfolioSummary(portfolio) {
+    return {
+        name: portfolio.meta.name,
+        title: portfolio.meta.title,
+        experienceCount: portfolio.sections.experience?.length ?? 0,
+        projectCount: portfolio.sections.projects?.length ?? 0,
+        skillCategoryCount: portfolio.sections.skills
+            ? Object.keys(portfolio.sections.skills).length
+            : 0,
+        writingCount: portfolio.sections.writing?.length ?? 0,
+        educationCount: portfolio.sections.education?.length ?? 0,
+        theme: portfolio.theme ?? 'srcl',
+    };
+}

package/dist/cli/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from './commands/init.js';
+import { validateCommand } from './commands/validate.js';
+import { renderCommand } from './commands/render.js';
+import { themesCommand } from './commands/themes.js';
+const program = new Command();
+program
+    .name('devfolio')
+    .description('Your portfolio as code. Version control it like software.')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Create a new portfolio.yaml with interactive prompts')
+    .action(initCommand);
+program
+    .command('validate <file>')
+    .description('Validate a portfolio YAML file')
+    .action(validateCommand);
+program
+    .command('render [file]')
+    .description('Generate static site from portfolio YAML')
+    .option('-t, --theme <theme>', 'Theme to use (defaults to YAML theme or srcl)')
+    .option('-o, --output <dir>', 'Output directory', './site')
+    .action((file, options) => renderCommand(file || 'portfolio.yaml', options));
+program
+    .command('themes')
+    .description('List available themes with examples')
+    .action(themesCommand);
+// Show welcome message if no arguments provided
+if (process.argv.length === 2) {
+    console.log();
+    console.log(chalk.cyan('┌─────────────────────────────────────────────────────────┐'));
+    console.log(chalk.cyan('│') + '  ' + chalk.bold('devfolio.page') + ' - Your portfolio as code                   ' + chalk.cyan('│'));
+    console.log(chalk.cyan('└─────────────────────────────────────────────────────────┘'));
+    console.log();
+    console.log(chalk.bold('Commands:'));
+    console.log();
+    console.log('  ' + chalk.cyan('devfolio init') + '              Create a new portfolio folder');
+    console.log('  ' + chalk.cyan('devfolio render') + '            Generate site (uses portfolio.yaml)');
+    console.log('  ' + chalk.cyan('devfolio themes') + '            List available themes');
+    console.log('  ' + chalk.cyan('devfolio validate') + ' <file>   Validate a portfolio YAML file');
+    console.log('  ' + chalk.cyan('devfolio --help') + '            Show all options');
+    console.log();
+    console.log(chalk.dim('Get started:'));
+    console.log(chalk.dim('  $ ') + 'devfolio init');
+    console.log();
+    process.exit(0);
+}
+program.parse();

package/dist/cli/postinstall.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import chalk from 'chalk';
+// Use stderr so output isn't suppressed during global installs
+const log = (msg = '') => process.stderr.write(msg + '\n');
+log();
+log(chalk.cyan('┌─────────────────────────────────────────────────────────┐'));
+log(chalk.cyan('│') + '  ' + chalk.bold('devfolio.page') + ' installed successfully!                      ' + chalk.cyan('│'));
+log(chalk.cyan('│') + '  Your portfolio as code.                                ' + chalk.cyan('│'));
+log(chalk.cyan('└─────────────────────────────────────────────────────────┘'));
+log();
+log(chalk.bold('Available commands:'));
+log();
+log('  ' + chalk.cyan('devfolio init') + '              Create a new portfolio folder');
+log('  ' + chalk.cyan('devfolio render') + '            Generate static site from YAML');
+log('  ' + chalk.cyan('devfolio validate') + ' <file>  Validate a portfolio YAML file');
+log('  ' + chalk.cyan('devfolio --help') + '           Show all options');
+log();
+log(chalk.dim('Get started:'));
+log(chalk.dim('  $ ') + 'devfolio init');
+log();

package/dist/cli/schemas/portfolio.schema.js

@@ -0,0 +1,299 @@
+import { z } from 'zod';
+// =============================================================================
+// Common Validators
+// =============================================================================
+// Custom date format validator (YYYY-MM or YYYY-MM-DD)
+const dateFormat = z
+    .string()
+    .regex(/^\d{4}-\d{2}(-\d{2})?$/, 'Date must be in YYYY-MM or YYYY-MM-DD format');
+// Date that can also be "present"
+const dateOrPresent = z.union([dateFormat, z.literal('present')]);
+// URL validation with auto-fix for missing protocol
+const urlString = z
+    .string()
+    .transform((val) => {
+    // Auto-add https:// if no protocol specified
+    if (val && !val.match(/^https?:\/\//)) {
+        return `https://${val}`;
+    }
+    return val;
+})
+    .pipe(z.string().url('Must be a valid URL'));
+// Optional URL that's less strict (for image paths, etc.)
+const urlOrPath = z.string().min(1, 'Path or URL is required');
+// =============================================================================
+// Content Section Schemas (for rich project pages)
+// =============================================================================
+const overviewSectionSchema = z.object({
+    type: z.literal('overview'),
+    content: z.string().min(1, 'Overview content is required'),
+});
+const imageSectionSchema = z.object({
+    type: z.literal('image'),
+    src: urlOrPath,
+    caption: z.string().optional(),
+    alt: z.string().optional(),
+});
+const gallerySectionSchema = z.object({
+    type: z.literal('gallery'),
+    images: z
+        .array(z.object({
+        src: urlOrPath,
+        caption: z.string().optional(),
+        alt: z.string().optional(),
+    }))
+        .min(1, 'Gallery must have at least one image'),
+});
+const demoSectionSchema = z.object({
+    type: z.literal('demo'),
+    title: z.string().optional(),
+    embed: z.string().min(1, 'Demo embed code is required'),
+});
+const codeSectionSchema = z.object({
+    type: z.literal('code'),
+    title: z.string().optional(),
+    language: z.string().min(1, 'Code language is required'),
+    code: z.string().min(1, 'Code content is required'),
+});
+const metricsSectionSchema = z.object({
+    type: z.literal('metrics'),
+    data: z
+        .array(z.object({
+        label: z.string().min(1, 'Metric label is required'),
+        value: z.string().min(1, 'Metric value is required'),
+    }))
+        .min(1, 'At least one metric is required'),
+});
+const outcomesSectionSchema = z.object({
+    type: z.literal('outcomes'),
+    content: z.string().min(1, 'Outcomes content is required'),
+});
+const processSectionSchema = z.object({
+    type: z.literal('process'),
+    content: z.string().min(1, 'Process content is required'),
+});
+const interactiveSectionSchema = z.object({
+    type: z.literal('interactive'),
+    title: z.string().optional(),
+    embed_type: z.enum(['iframe', 'embed']),
+    url: urlString,
+});
+const contentSectionSchema = z.discriminatedUnion('type', [
+    overviewSectionSchema,
+    imageSectionSchema,
+    gallerySectionSchema,
+    demoSectionSchema,
+    codeSectionSchema,
+    metricsSectionSchema,
+    outcomesSectionSchema,
+    processSectionSchema,
+    interactiveSectionSchema,
+]);
+// =============================================================================
+// Project Schemas
+// =============================================================================
+// Simple project schema (backwards compatible)
+const simpleProjectSchema = z.object({
+    name: z.string().min(1, 'Project name is required'),
+    url: urlString.optional(),
+    description: z.string().min(1, 'Project description is required'),
+    tags: z.array(z.string()).min(1, 'At least one tag is required'),
+    featured: z.boolean().optional(),
+});
+// Rich project schema (for case studies)
+const richProjectSchema = z.object({
+    id: z.string().min(1, 'Project ID (URL slug) is required'),
+    title: z.string().min(1, 'Project title is required'),
+    subtitle: z.string().optional(),
+    featured: z.boolean().optional(),
+    thumbnail: urlOrPath,
+    hero: urlOrPath.optional(),
+    meta: z.object({
+        year: z.union([z.string(), z.number()]),
+        role: z.string().min(1, 'Role is required'),
+        timeline: z.string().optional(),
+        tech: z.array(z.string()).min(1, 'At least one technology is required'),
+        links: z
+            .object({
+            github: urlString.optional(),
+            demo: urlString.optional(),
+            live: urlString.optional(),
+            case_study: urlString.optional(),
+        })
+            .optional(),
+    }),
+    sections: z.array(contentSectionSchema).min(1, 'At least one section is required'),
+});
+// =============================================================================
+// Experience & Education Schemas
+// =============================================================================
+const experienceSchema = z.object({
+    company: z.string().min(1, 'Company name is required'),
+    role: z.string().min(1, 'Role is required'),
+    date: z.object({
+        start: dateFormat,
+        end: dateOrPresent,
+    }),
+    location: z.string().optional(),
+    description: z.string().optional(),
+    highlights: z.array(z.string()).min(1, 'At least one highlight is required'),
+});
+const educationSchema = z.object({
+    institution: z.string().min(1, 'Institution name is required'),
+    degree: z.string().min(1, 'Degree is required'),
+    date: z.object({
+        start: dateFormat,
+        end: dateFormat,
+    }),
+    location: z.string().optional(),
+    description: z.string().optional(),
+    highlights: z.array(z.string()).optional(),
+});
+// =============================================================================
+// Skills Schemas
+// =============================================================================
+// Simple skills schema (backwards compatible) - dynamic categories
+const simpleSkillsSchema = z.record(z.string(), z.array(z.string()).min(1, 'Each skill category needs at least one skill'));
+// Rich skills schema with details
+const richSkillsSchema = z.object({
+    categories: z.array(z.object({
+        name: z.string().min(1, 'Category name is required'),
+        level: z.enum(['beginner', 'proficient', 'expert']).optional(),
+        items: z.array(z.object({
+            name: z.string().min(1, 'Skill name is required'),
+            years: z.number().optional(),
+            icon: z.string().optional(),
+            note: z.string().optional(),
+        })),
+    })),
+});
+// =============================================================================
+// Writing Schema
+// =============================================================================
+const writingSchema = z.object({
+    title: z.string().min(1, 'Article title is required'),
+    url: urlString,
+    date: dateFormat,
+    description: z.string().optional(), // Backwards compatible
+    excerpt: z.string().optional(),
+    cover: urlOrPath.optional(),
+    publication: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    featured: z.boolean().optional(),
+});
+// =============================================================================
+// New Content Types
+// =============================================================================
+const experimentSchema = z.object({
+    title: z.string().min(1, 'Experiment title is required'),
+    description: z.string().min(1, 'Experiment description is required'),
+    image: urlOrPath.optional(),
+    github: urlString.optional(),
+    demo: urlString.optional(),
+    tags: z.array(z.string()).min(1, 'At least one tag is required'),
+});
+const testimonialSchema = z.object({
+    quote: z.string().min(1, 'Quote is required'),
+    author: z.string().min(1, 'Author name is required'),
+    company: z.string().optional(),
+    role: z.string().optional(),
+    image: urlOrPath.optional(),
+});
+const timelineItemSchema = z.object({
+    year: z.union([z.string(), z.number()]),
+    title: z.string().min(1, 'Timeline item title is required'),
+    description: z.string().min(1, 'Timeline item description is required'),
+    image: urlOrPath.optional(),
+});
+// =============================================================================
+// Settings & Layout Schemas
+// =============================================================================
+const settingsSchema = z.object({
+    show_grid: z.boolean().optional(),
+    enable_hotkeys: z.boolean().optional(),
+    color_scheme: z.enum(['dark', 'light']).optional(),
+    animate: z.enum(['none', 'subtle', 'full']).optional(),
+});
+const layoutSchema = z.object({
+    homepage_style: z.enum(['hero', 'grid', 'minimal']).optional(),
+    project_layout: z.enum(['case-study', 'grid', 'list']).optional(),
+    show_experiments: z.boolean().optional(),
+    show_timeline: z.boolean().optional(),
+});
+// =============================================================================
+// Main Portfolio Schema
+// =============================================================================
+export const portfolioSchema = z.object({
+    // Core metadata
+    meta: z.object({
+        name: z.string().min(1, 'Name is required'),
+        title: z.string().min(1, 'Professional title is required'),
+        tagline: z.string().optional(),
+        location: z.string().min(1, 'Location is required'),
+        timezone: z.string().optional(),
+        avatar: urlOrPath.optional(),
+        hero_image: urlOrPath.optional(),
+    }),
+    // Contact information
+    contact: z.object({
+        email: z.string().email('Must be a valid email address'),
+        website: urlString.optional(),
+        github: z.string().optional(),
+        linkedin: z.string().optional(),
+        twitter: z.string().optional(),
+    }),
+    // Bio (required for backwards compatibility)
+    bio: z.string().min(10, 'Bio should be at least 10 characters'),
+    // Extended about section (optional)
+    about: z
+        .object({
+        short: z.string().min(1, 'Short bio is required'),
+        long: z.string().min(1, 'Long bio is required'),
+    })
+        .optional(),
+    // Sections (backwards compatible structure)
+    sections: z.object({
+        experience: z.array(experienceSchema).optional(),
+        projects: z.array(simpleProjectSchema).optional(),
+        skills: simpleSkillsSchema.optional(),
+        writing: z.array(writingSchema).optional(),
+        education: z.array(educationSchema).optional(),
+    }),
+    // Rich projects (new structure for case studies)
+    projects: z.array(richProjectSchema).optional(),
+    // New content types
+    experiments: z.array(experimentSchema).optional(),
+    testimonials: z.array(testimonialSchema).optional(),
+    timeline: z.array(timelineItemSchema).optional(),
+    // Theme selection
+    theme: z.enum(['srcl', 'modern', 'minimal', 'dark-academia']).optional(),
+    // Layout configuration
+    layout: layoutSchema.optional(),
+    // Settings
+    settings: settingsSchema.optional(),
+});
+// =============================================================================
+// Helper Functions
+// =============================================================================
+// Format Zod errors nicely
+export function formatValidationErrors(error) {
+    return error.issues.map((issue) => {
+        const path = issue.path.join('.');
+        return `${path}: ${issue.message}`;
+    });
+}
+// Get a user-friendly name for a section type
+export function getSectionTypeName(type) {
+    const names = {
+        overview: 'Overview',
+        image: 'Image',
+        gallery: 'Gallery',
+        demo: 'Demo',
+        code: 'Code Block',
+        metrics: 'Metrics',
+        outcomes: 'Outcomes',
+        process: 'Process',
+        interactive: 'Interactive Embed',
+    };
+    return names[type] || type;
+}