@oaysus/cli 0.1.16 → 0.1.17

package/docs/README.md

@@ -0,0 +1,30 @@
+# Oaysus CLI Documentation
+
+This folder contains detailed documentation for the Oaysus CLI tool.
+
+## Documentation Index
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](./getting-started.md) | Installation and first steps |
+| [Theme Pack Commands](./theme-commands.md) | Building and managing component libraries |
+| [Site Commands](./site-commands.md) | Managing website pages and content |
+| [Component Guide](./components.md) | Building components with schemas |
+| [Schema Reference](./schemas.md) | Complete prop type reference |
+| [AI Workflows](./ai-workflows.md) | Using the CLI with AI assistants |
+
+## Quick Links
+
+- [Main Documentation](https://oaysus.com/docs)
+- [API Reference](https://oaysus.com/docs/cli)
+- [GitHub Issues](https://github.com/oaysus/cli/issues)
+
+## What is Oaysus?
+
+Oaysus is a visual page builder platform that enables:
+
+1. **Developers** to build reusable components in React, Vue, or Svelte
+2. **Marketing teams** to create and edit pages visually without code
+3. **Fast deployment** with pre-rendered pages served from global edge servers
+
+The CLI is the developer's primary interface for building and pushing components to Oaysus.

package/docs/ai-workflows.md

@@ -0,0 +1,207 @@
+# AI Workflows with Oaysus CLI
+
+The Oaysus CLI's `site pull` and `site publish` commands unlock powerful AI-assisted content workflows. By storing pages as JSON files locally, any AI assistant can read and modify them.
+
+## The AI-Powered Workflow
+
+```bash
+# Step 1: Pull all pages from your website
+oaysus site pull
+
+# Step 2: Use AI to make bulk changes
+# (See example prompts below)
+
+# Step 3: Validate the changes
+oaysus site validate
+
+# Step 4: Review changes in git diff
+
+# Step 5: Publish all changes
+oaysus site publish
+```
+
+## Example AI Prompts
+
+### Content Updates
+
+**Update brand messaging across all pages:**
+```
+"Update all hero sections to use our new tagline: 'Build faster, ship sooner'"
+```
+
+**Change pricing information:**
+```
+"Change the price from $99 to $149 on all pages that mention pricing"
+```
+
+**Add calls to action:**
+```
+"Add a newsletter signup CTA to the footer of every page"
+```
+
+### Bulk Modifications
+
+**Update testimonials:**
+```
+"Update all testimonial sections with these new customer quotes:
+- 'Oaysus saved us 10 hours per week' - Jane Doe, Marketing Lead
+- 'Our team loves the visual editor' - John Smith, CEO"
+```
+
+**Add new sections:**
+```
+"Add a FAQ section to the pricing page with these questions:
+1. What payment methods do you accept?
+2. Can I cancel anytime?
+3. Do you offer refunds?"
+```
+
+### Translations
+
+**Translate entire site:**
+```
+"Translate all page content to Spanish, keeping the same structure"
+```
+
+**Localize specific content:**
+```
+"Update the contact information to use our European office address on all pages"
+```
+
+### SEO Optimization
+
+**Update meta descriptions:**
+```
+"Generate unique, SEO-optimized meta descriptions for each page based on their content"
+```
+
+**Add structured data:**
+```
+"Add FAQ schema markup to all pages that have FAQ sections"
+```
+
+## Page JSON Structure
+
+Each page is stored as a JSON file that AI tools can easily parse and modify:
+
+```json
+{
+  "title": "About Us",
+  "slug": "/about",
+  "description": "Learn about our company and team",
+  "components": [
+    {
+      "type": "Hero",
+      "props": {
+        "headline": "Our Story",
+        "subtext": "Building the future of web development",
+        "buttonText": "Meet the Team",
+        "buttonLink": "/team"
+      }
+    },
+    {
+      "type": "FeatureGrid",
+      "props": {
+        "heading": "Our Values",
+        "features": [
+          {
+            "title": "Innovation",
+            "description": "Pushing boundaries every day"
+          },
+          {
+            "title": "Quality",
+            "description": "Excellence in everything we do"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Component Catalog
+
+After pulling, the `components.json` file contains all available components and their schemas. AI tools can reference this to understand what props are available:
+
+```json
+{
+  "Hero": {
+    "displayName": "Hero Section",
+    "props": {
+      "headline": { "type": "string" },
+      "subtext": { "type": "string" },
+      "buttonText": { "type": "string" },
+      "buttonLink": { "type": "string" },
+      "backgroundImage": { "type": "image" }
+    }
+  },
+  "FeatureGrid": {
+    "displayName": "Feature Grid",
+    "props": {
+      "heading": { "type": "string" },
+      "features": { "type": "array" }
+    }
+  }
+}
+```
+
+## Time Savings
+
+| Task | Manual Approach | AI-Assisted |
+|------|-----------------|-------------|
+| Update 10 page headlines | 30+ minutes | 2 minutes |
+| Add CTA to all pages | 45+ minutes | 3 minutes |
+| Translate 20 pages | Days | 30 minutes |
+| Update testimonials site-wide | 1 hour | 5 minutes |
+
+## Best Practices
+
+### 1. Pull Before Making Changes
+
+Always start with a fresh pull to ensure you have the latest content:
+
+```bash
+oaysus site pull --force
+```
+
+### 2. Validate Before Publishing
+
+Run validation to catch errors before they go live:
+
+```bash
+oaysus site validate
+```
+
+### 3. Use Git for Version Control
+
+Track changes and review diffs before publishing:
+
+```bash
+git diff pages/
+```
+
+### 4. Review AI Output
+
+Always review AI-generated changes before publishing. AI can make mistakes, especially with:
+- Proper nouns and brand names
+- Technical terminology
+- Numerical data
+
+### 5. Publish Incrementally
+
+For large changes, consider publishing one page at a time:
+
+```bash
+oaysus site publish pages/home.json
+oaysus site publish pages/about.json
+```
+
+## Integration with AI Coding Assistants
+
+The site commands work seamlessly with AI coding assistants like:
+
+- **Claude Code** - Can read, modify, and validate page JSON files
+- **GitHub Copilot** - Suggests edits based on context
+- **Cursor** - Full IDE integration with AI assistance
+
+Simply open your site project in your preferred editor and let AI help with bulk content changes.

package/docs/components.md

@@ -0,0 +1,210 @@
+# Building Components
+
+Components are the building blocks of Oaysus pages. Each component has two files: the code and a schema that defines editable props.
+
+## Component Structure
+
+```
+components/
+└── HeroBanner/
+    ├── index.tsx      # Component code
+    └── schema.json    # Prop definitions
+```
+
+## React Components
+
+### Example Component
+
+```tsx
+// components/HeroBanner/index.tsx
+interface HeroBannerProps {
+  headline: string;
+  subtext: string;
+  buttonText: string;
+  buttonLink: string;
+  backgroundImage?: string;
+}
+
+export default function HeroBanner({
+  headline = "Welcome",
+  subtext = "Build something amazing",
+  buttonText = "Get Started",
+  buttonLink = "/",
+  backgroundImage
+}: HeroBannerProps) {
+  return (
+    <section
+      className="py-24 px-6 text-white bg-cover bg-center"
+      style={{ backgroundImage: backgroundImage ? `url(${backgroundImage})` : undefined }}
+    >
+      <div className="max-w-4xl mx-auto text-center">
+        <h1 className="text-5xl font-bold mb-4">{headline}</h1>
+        <p className="text-xl mb-8 opacity-90">{subtext}</p>
+        <a
+          href={buttonLink}
+          className="inline-block bg-white text-gray-900 px-8 py-3 rounded-lg font-medium"
+        >
+          {buttonText}
+        </a>
+      </div>
+    </section>
+  );
+}
+```
+
+### Example Schema
+
+```json
+{
+  "displayName": "Hero Banner",
+  "category": "marketing",
+  "props": {
+    "headline": {
+      "type": "string",
+      "label": "Headline",
+      "default": "Welcome"
+    },
+    "subtext": {
+      "type": "string",
+      "label": "Subtext",
+      "default": "Build something amazing"
+    },
+    "buttonText": {
+      "type": "string",
+      "label": "Button Text",
+      "default": "Get Started"
+    },
+    "buttonLink": {
+      "type": "string",
+      "label": "Button Link",
+      "default": "/"
+    },
+    "backgroundImage": {
+      "type": "image",
+      "label": "Background Image"
+    }
+  }
+}
+```
+
+## Vue Components
+
+```vue
+<!-- components/FeatureGrid/index.vue -->
+<template>
+  <section class="py-16 px-6 bg-gray-50">
+    <div class="max-w-6xl mx-auto">
+      <h2 class="text-3xl font-bold text-center mb-12">{{ heading }}</h2>
+      <div class="grid md:grid-cols-3 gap-8">
+        <div
+          v-for="(feature, index) in features"
+          :key="index"
+          class="bg-white p-6 rounded-xl shadow-sm"
+        >
+          <h3 class="text-xl font-semibold mb-2">{{ feature.title }}</h3>
+          <p class="text-gray-600">{{ feature.description }}</p>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+interface Feature {
+  title: string;
+  description: string;
+}
+
+defineProps<{
+  heading: string;
+  features: Feature[];
+}>();
+</script>
+```
+
+## Svelte Components
+
+```svelte
+<!-- components/Testimonials/index.svelte -->
+<script lang="ts">
+  export let heading = 'What Our Customers Say';
+  export let testimonials: Array<{
+    quote: string;
+    author: string;
+    role: string;
+  }> = [];
+</script>
+
+<section class="py-16 px-6 bg-white">
+  <div class="max-w-4xl mx-auto">
+    <h2 class="text-3xl font-bold text-center mb-12">{heading}</h2>
+    <div class="grid md:grid-cols-2 gap-8">
+      {#each testimonials as testimonial}
+        <blockquote class="bg-gray-50 p-6 rounded-xl">
+          <p class="text-lg text-gray-700 mb-4 italic">
+            "{testimonial.quote}"
+          </p>
+          <footer>
+            <cite class="font-semibold not-italic">{testimonial.author}</cite>
+            <p class="text-gray-500 text-sm">{testimonial.role}</p>
+          </footer>
+        </blockquote>
+      {/each}
+    </div>
+  </div>
+</section>
+```
+
+## Best Practices
+
+### Use TypeScript
+
+Define prop interfaces to catch type mismatches between your component and schema.
+
+### Provide Defaults
+
+Components should render something meaningful even with default props.
+
+### Handle Missing Data
+
+Use conditional rendering for optional props like images:
+
+```tsx
+{backgroundImage && (
+  <img src={backgroundImage} alt="" />
+)}
+```
+
+### Use Tailwind CSS
+
+Oaysus supports Tailwind classes out of the box. Avoid custom CSS files that won't be loaded.
+
+### Keep Components Focused
+
+One component per concern. Don't build Swiss army knives with too many options.
+
+### Use Meaningful Categories
+
+Organize components with categories:
+- `marketing` - Landing page sections
+- `content` - Blog and article components
+- `navigation` - Headers, menus, breadcrumbs
+- `footer` - Footer sections
+- `social-proof` - Testimonials, reviews
+- `ecommerce` - Product displays, carts
+- `forms` - Contact forms, signups
+- `media` - Image galleries, videos
+
+## Component Categories
+
+Set the `category` field in your schema:
+
+```json
+{
+  "displayName": "Testimonials",
+  "category": "social-proof",
+  "props": { ... }
+}
+```
+
+Components are grouped by category in the page builder for easier discovery.

package/docs/getting-started.md

@@ -0,0 +1,90 @@
+# Getting Started with Oaysus CLI
+
+## Installation
+
+Install the Oaysus CLI globally using npm:
+
+```bash
+npm install -g @oaysus/cli
+```
+
+Requires Node.js 20 or higher.
+
+## Authentication
+
+Before pushing components, authenticate with your Oaysus account:
+
+```bash
+oaysus login
+```
+
+This opens a magic link flow:
+1. Enter your email address
+2. Check your inbox for the login link
+3. Click the link to complete authentication
+4. Select which website to work with
+
+Your credentials are stored locally and expire after 7 days.
+
+## Quick Start
+
+### Create a Theme Pack
+
+```bash
+# Create a new theme pack project
+oaysus theme init my-components
+
+# Navigate to the project
+cd my-components
+```
+
+The CLI will prompt you to:
+- Select a framework (React, Vue, or Svelte)
+- Name your project
+- Add a description
+
+### Project Structure
+
+After initialization, your project looks like this:
+
+```
+my-components/
+├── package.json
+├── components/
+│   └── Hero/
+│       ├── index.tsx      # Component code
+│       └── schema.json    # Editable props definition
+├── shared/                # Shared utilities
+└── README.md
+```
+
+### Push to Oaysus
+
+```bash
+oaysus theme push
+```
+
+The CLI will:
+1. Validate your component structure
+2. Build and bundle your components
+3. Upload to Oaysus cloud
+4. Make components available in the visual editor
+
+## Verify Your Setup
+
+Check your authentication status:
+
+```bash
+oaysus whoami
+```
+
+This shows:
+- Your email address
+- Current website selected
+- Token expiration time
+
+## Next Steps
+
+- [Theme Pack Commands](./theme-commands.md) - Full command reference
+- [Component Guide](./components.md) - Building effective components
+- [Schema Reference](./schemas.md) - All available prop types