nova-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8b16c0ed1f907363ca8da83e0bd36e8757438840965d1eddd3001fee69e6dddd
+  data.tar.gz: d3f912358591fbd5d8774a3d55714d68ddbf7a2ccfe9c09043eeb5e5594237e7
+SHA512:
+  metadata.gz: 62388046c98ee1da35437edde0a9e870207295615188fe55446b1c2f35e87d8373a3e0b392efaa58cf9ff627f04237db0a31c16c4ab8f6e8b6fb83b1876b80fb
+  data.tar.gz: d2a1220a45dbc82b81eb4be522a8478114111d130fc276839181ba0a6edcc09d1297d82ff5252ddc747c5d05f593a4d8df2f0484c7b0dc954ada6c5bc8d06803

data/README.md

@@ -0,0 +1,115 @@
+# Nova
+
+Nova is a command-line tool that generates a standardized project structure for product development and documentation. It guides teams through a structured workflow from strategic planning to code generation in an AI-driven environment.
+
+## The Nova Process
+
+The Nova process guides product development through a series of steps, each building on the previous one to create a comprehensive plan for implementation:
+
+1. **Big Picture** → Define the strategic vision and goals
+2. **User Stories** → Break down the vision into specific user needs
+3. **Design System** → Establish the visual language and UI components
+4. **Prompts** → Create development prompts for implementation
+
+Each step has its own directory with specialized templates and examples to guide your work.
+
+## Installation
+
+To install the gem locally:
+
+```bash
+cd nova
+gem build nova-cli.gemspec
+gem install nova-cli-0.1.2.gem
+```
+
+Alternatively, you can run it directly:
+
+```bash
+chmod +x bin/nova
+./bin/nova new [app_name]
+```
+
+## Usage
+
+```bash
+# Create a new project structure
+nova new [app_name]
+
+# Show version
+nova version
+
+# Show help
+nova help
+```
+
+## Generated Structure
+
+When you run `nova new [app_name]`, it creates the following structure:
+
+```
+[project_name]/
+├── shape/
+│   ├── README.md
+│   ├── 1_big-picture/
+│   │   ├── README.md
+│   │   ├── prd_example.md
+│   │   ├── flowchart.md
+│   ├── 2_user-stories/
+│   │   ├── README.md
+│   │   └── example.md
+│   ├── 3_design-system/
+│   │   ├── README.md
+│   │   └── design_decisions.md
+│   ├── 4_prompts/
+│   │   ├── README.md
+│   │   └── example.md
+├── code/
+├── design-system/
+```
+
+- `shape/README.md`: Comprehensive documentation on how to structure product requirements and features
+- `shape/1_big-picture/`: High-level strategic documents that define the vision and direction
+- `shape/2_user-stories/`: User-focused requirements that capture specific needs and acceptance criteria
+- `shape/3_design-system/`: Visual language and UI component documentation to ensure consistency
+- `shape/4_prompts/`: Structured sequential tasks for AI-assisted implementation
+- `code/`: Directory for actual code implementation
+- `design-system/`: Directory for implemented design system code and assets
+
+## Best Practices
+
+- **Start with Why**: Always begin by understanding the strategic purpose behind the project
+- **Focus on User Value**: Keep the user's needs at the center of all planning
+- **Be Specific**: Include enough detail for implementation but avoid over-specification
+- **Maintain Traceability**: Ensure each document references related documents from previous steps
+- **Collaborate Across Disciplines**: Involve all relevant team members in the appropriate steps
+- **Iterate and Refine**: The process is not strictly linear - revisit and update documents as you learn
+- **Follow TDD**: Follow Test-Driven Development principles when implementing code
+
+## Working with AI
+
+The Nova framework is designed to work seamlessly with AI development assistants:
+
+1. Define your product requirements in the big picture section
+2. Break down functionality into user stories
+3. Establish a design system for consistency
+4. Write sequential development prompts in the prompts directory
+5. Share these prompts with AI assistants to generate implementation code
+
+## Mermaid Flowcharts
+
+Nova includes support for creating flowcharts using Mermaid syntax in Markdown. To view and edit these flowcharts in VS Code, you need to install the [Markdown Preview Mermaid Support](https://open-vsx.org/vscode/item?itemName=bierner.markdown-mermaid) extension:
+
+1. Open VS Code
+2. Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
+3. Search for "Markdown Preview Mermaid Support"
+4. Click Install
+
+You can also install it directly from the VS Marketplace:
+[Markdown Preview Mermaid Support](https://open-vsx.org/vscode/item?itemName=bierner.markdown-mermaid)
+
+With this extension installed, you'll be able to preview Mermaid diagrams in the `flowchart.md` file and any other Markdown files containing Mermaid syntax.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/nova

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/nova'
+
+Nova::CLI.start(ARGV)

data/lib/nova/cli.rb

@@ -0,0 +1,37 @@
+require 'optparse'
+require_relative 'generator'
+
+module Nova
+  class CLI
+    def self.start(args)
+      command = args.shift
+      case command
+      when 'new'
+        app_name = args.shift
+        if app_name.nil? || app_name.empty?
+          puts "Error: Please provide an app name"
+          puts "Usage: nova new [app_name]"
+          exit 1
+        end
+        Generator.new(app_name).generate
+      when 'version', '-v', '--version'
+        puts "Nova version #{Nova::VERSION}"
+      when 'help', '-h', '--help', nil
+        show_help
+      else
+        puts "Unknown command: #{command}"
+        show_help
+        exit 1
+      end
+    end
+
+    def self.show_help
+      puts "Nova - A CLI tool for generating project structures"
+      puts ""
+      puts "Usage:"
+      puts "  nova new [app_name]    # Create a new app with the specified name"
+      puts "  nova version           # Show the version"
+      puts "  nova help              # Show this help message"
+    end
+  end
+end

data/lib/nova/generator.rb

@@ -0,0 +1,170 @@
+require 'fileutils'
+require 'json'
+
+module Nova
+  class Generator
+    attr_reader :app_name
+
+    # Flat structure for all template files
+    # Each entry contains:
+    # - path: relative path where the file should be created
+    # - template: name of the template file to use (nil for directories)
+    # - type: optional type for special handling (e.g., 'prefixed_example')
+    FILES = [
+      # Main README
+      { path: 'shape/README.md', template: 'readme_template.md' },
+      
+      # 1_big-picture section
+      { path: 'shape/1_big-picture', template: nil }, # directory
+      { path: 'shape/1_big-picture/README.md', template: 'big_picture_readme_template.md' },
+      { path: 'shape/1_big-picture/prd_example.md', template: 'prd_example_template.md' },
+      { path: 'shape/1_big-picture/flowchart.md', template: 'flowchart_template.md' },
+      
+      # 2_user-stories section
+      { path: 'shape/2_user-stories', template: nil }, # directory
+      { path: 'shape/2_user-stories/README.md', template: 'user_stories_readme_template.md' },
+      { path: 'shape/2_user-stories/example.md', template: 'user_story_example.md' },
+      
+      # 3_design-system section
+      { path: 'shape/3_design-system', template: nil }, # directory
+      { path: 'shape/3_design-system/README.md', template: 'design_system_readme_template.md' },
+      { path: 'shape/3_design-system/design_decisions.md', template: 'design_decisions_example.md' },
+      
+      # 4_prompts section
+      { path: 'shape/4_prompts', template: nil }, # directory
+      { path: 'shape/4_prompts/README.md', template: 'prompts_readme_template.md' },
+      { path: 'shape/4_prompts/01_generate_app.md', template: 'prompts_examples/01_generate_app.md' },
+      { path: 'shape/4_prompts/02_generate_styleguide.md', template: 'prompts_examples/02_generate_styleguide.md' },
+      { path: 'shape/4_prompts/03_generate_static_pages.md', template: 'prompts_examples/03_generate_static_pages.md' },
+      { path: 'shape/4_prompts/04_authentication_feature.md', template: 'prompts_examples/04_authentication_feature.md' },
+      
+      # Code directory
+      { path: 'code', template: nil } # directory
+    ].freeze
+
+    def initialize(app_name)
+      @app_name = app_name
+    end
+
+    def generate
+      create_main_directories
+      create_all_files_and_directories
+      create_windsurfrules_file
+      create_cursorcontext_file
+      display_success_message
+    end
+
+    private
+
+    def create_main_directories
+      # These are the base directories that must exist before we create any files
+      FileUtils.mkdir_p(File.join(app_name, 'shape'))
+      FileUtils.mkdir_p(File.join(app_name, 'code'))
+    end
+
+    def create_all_files_and_directories
+      FILES.each do |file_entry|
+        path = File.join(app_name, file_entry[:path])
+        
+        if file_entry[:template].nil?
+          # This is a directory entry
+          create_directory(path)
+        else
+          # This is a file entry
+          create_file_from_template(path, file_entry[:template])
+        end
+      end
+    end
+    
+    def create_file_from_template(path, template_name)
+      # Ensure parent directory exists
+      FileUtils.mkdir_p(File.dirname(path))
+      
+      template_path = template_path_for(template_name)
+      content = File.read(template_path)
+      
+      write_file(path.sub("#{app_name}/", ''), content)
+    end
+
+    def create_windsurfrules_file
+      rules = ai_assistant_rules
+      content = rules.join("\n")
+      write_file('.windsurfrules', content)
+    end
+    
+    def create_cursorcontext_file
+      rules = ai_assistant_rules
+      content = JSON.pretty_generate({
+        "rules" => rules
+      })
+      write_file('.cursorcontext', content)
+    end
+    
+    def ai_assistant_rules
+      [
+        "The shape/ folder is where we collaborate to create product & feature documentation. shape/README.md clarifies how we document product & feature requirements and where to put stuff. Look at that file before writing documentation.",
+        "The code/ folder is where you write code. Do not write code unless I tell you to.",
+        "Important! Opt for the simplest version of any feature or requirement unless otherwise indicated.",
+        "Important! Any time a user requests a change to the product shape, even during coding, update the documentation in shape/",
+        "Be as concise as possible.",        
+        "Follow TDD whenever writing code. Unit tests for back-end using rspec and E2E tests for front-end using Cypress."        
+      ]
+    end
+
+    def display_success_message
+      puts "\nShape project created for #{app_name}!"
+      puts "\nDirectory structure:"
+      puts "  #{app_name}/"
+      puts "  ├── .windsurfrules"
+      puts "  ├── .cursorcontext"
+      puts "  ├── shape/"
+      puts "  │   ├── README.md"
+      puts "  │   ├── 1_big-picture/"
+      puts "  │   ├── 2_user-stories/"
+      puts "  │   ├── 3_design-system/"
+      puts "  │   ├── 4_prompts/"
+      puts "  └── code/"
+    end
+
+    # Utility methods
+    def create_directory(path)
+      FileUtils.mkdir_p(path) unless File.directory?(path)
+    end
+
+    def write_file(relative_path, content)
+      full_path = File.join(app_name, relative_path)
+      File.write(full_path, content)
+    end
+
+    def template_path_for(template_name)
+      File.expand_path("../templates/#{template_name}", __FILE__)
+    end
+    
+    # The following methods are maintained for backward compatibility with tests
+    # but they now leverage the new flat structure implementation
+    
+    def create_big_picture_files
+      create_files_for_path('shape/1_big-picture')
+    end
+    
+    def create_prompts_files
+      create_files_for_path('shape/4_prompts')
+    end
+    
+    def create_user_stories_files
+      create_files_for_path('shape/2_user-stories')
+    end
+    
+    # Method kept for backwards compatibility with tests
+    def create_shape_readme_file
+      file_entry = FILES.find { |f| f[:path] == 'shape/README.md' }
+      create_file_from_template(File.join(app_name, file_entry[:path]), file_entry[:template])
+    end
+    
+    def create_files_for_path(path_prefix)
+      FILES.select { |f| f[:path].start_with?(path_prefix) && f[:template] }.each do |file_entry|
+        create_file_from_template(File.join(app_name, file_entry[:path]), file_entry[:template])
+      end
+    end
+  end
+end

data/lib/nova/templates/big_picture_readme_template.md

@@ -0,0 +1,29 @@
+# 1. Big Picture
+
+This directory contains high-level strategic documents that define the background, vision, and goals of the project.
+
+## Purpose
+
+The Big Picture documents establish the foundation and direction for the entire project. They help stakeholders align on objectives and priorities before diving into more detailed planning.
+
+## Files in this Directory
+
+- **prd_example.md**: Defines a blueprint for the product.
+- **flowchart.md**: Visual representation of the application's user flow using Mermaid diagrams
+
+## How to Use
+
+1. Create a new PRD file at 1_big-picture/prd.md and use 1_big-picture/prd_example.md as a template
+2. Create visual application flows in flowchart.md to illustrate user journeys
+
+## Best Practices
+
+- Involve all key stakeholders in defining the Big Picture
+- Keep these documents high-level and focused on strategy (details come later)
+- Revisit and update these documents as the project evolves
+- Use clear, concise language that all stakeholders can understand
+- Use flowcharts to communicate complex user journeys visually
+
+## Next Steps
+
+After completing the Big Picture documents, move on to [2_user-stories](../2_user-stories) to begin breaking down the product into more detailed user stories.

data/lib/nova/templates/design_decisions_example.md

@@ -0,0 +1,85 @@
+# Design Decisions
+
+A concise guide to the application's visual style. Use these decisions consistently throughout the interface.
+
+## Color Palette
+
+**Primary Colors:**
+- Brand Primary: `#4A7AFF` - Main brand color, primary buttons
+- Brand Secondary: `#6C47FF` - Secondary actions, highlights
+
+**Neutral Colors:**
+- Black: `#000000` - Headings, text, icons
+- Dark Gray: `#333333` - Primary text
+- Medium Gray: `#666666` - Secondary text
+- Light Gray: `#CCCCCC` - Borders, dividers
+- Off-White: `#F5F5F5` - Backgrounds, cards
+- White: `#FFFFFF` - Page backgrounds
+
+**Semantic Colors:**
+- Success: `#4CAF50` - Confirmations, success states
+- Warning: `#FF9800` - Warnings, caution states
+- Error: `#F44336` - Errors, destructive actions
+- Info: `#2196F3` - Information, help text
+
+## Typography
+
+**Font Family:** Inter (with system fallbacks)
+
+**Text Styles:**
+- H1: 32px (2rem), bold (700), page titles
+- H2: 24px (1.5rem), bold (700), section headings
+- H3: 20px (1.25rem), semibold (600), subsection headings
+- Body: 16px (1rem), regular (400), main content
+- Small: 14px (0.875rem), regular (400), secondary text
+- Button: 16px (1rem), medium (500), button labels
+
+## Spacing
+
+- XS: 4px (0.25rem) - Minimal spacing, icons
+- Small: 8px (0.5rem) - Tight spacing, compact elements
+- Medium: 16px (1rem) - Standard spacing, form fields
+- Large: 24px (1.5rem) - Section padding, card padding
+- XL: 32px (2rem) - Section margins, page padding
+- 2XL: 48px (3rem) - Large separations
+
+## Border Radius
+
+- None: 0 - Tables, alerts
+- Small: 4px (0.25rem) - Inputs, buttons
+- Medium: 8px (0.5rem) - Cards, modals
+- Large: 16px (1rem) - Feature cards, profile images
+- Full: 9999px - Pills, badges, avatars
+
+## Key Components
+
+**Buttons:**
+- Primary: Brand Primary background, white text, small radius
+- Secondary: White background, Brand Primary text and border
+- Danger: Error color background, white text
+- Text: No background, Brand Primary text, no border
+
+**Inputs:**
+- White background, Medium Gray border (1px)
+- Small radius, black text
+- Focus: Brand Primary border (2px)
+
+**Cards:**
+- White background, medium radius
+- Optional Light Gray border, large padding
+- Medium shadow (0 4px 6px rgba(0, 0, 0, 0.1))
+
+**Navigation:**
+- Desktop: Horizontal navbar with Brand Primary highlights
+- Mobile: Hamburger menu with slide-out drawer
+
+## Accessibility
+
+- Text contrast ratio: 4.5:1 minimum
+- Clear focus states on interactive elements
+- Support text resizing to 200%
+
+## Technical Stack
+
+- CSS Framework: Tailwind CSS
+- Interactive Components: Flowbite

data/lib/nova/templates/design_system_readme_template.md

@@ -0,0 +1,22 @@
+# Design System
+
+The Design System directory contains the visual language and UI component documentation for your application. It builds on the PRD and user stories and provides a consistent framework for implementing the user interface.
+
+## Purpose
+
+A design system serves as a centralized resource for design guidelines, UI components, patterns, and principles. It ensures consistency, improves collaboration between designers and developers, and accelerates implementation.
+
+## Directory Structure
+
+The design system is organized as follows:
+
+```
+3_design-system/
+├── README.md (this file)
+└── design_decisions.md
+```
+
+## Design System Implementation
+
+1. **Review the PRD and user stories** to ensure visual consistency with the brand and planned user experience
+2. **Document design decisions** in the `design_decisions.md` file, including color palette, typography, spacing, and component styles

data/lib/nova/templates/flowchart_template.md

@@ -0,0 +1,72 @@
+# Application Page Flow
+
+This document provides a visual representation of the application's pages and the navigation paths between them.
+
+## Main Page Navigation
+
+```mermaid
+flowchart TD
+    HomePage --> LoginPage
+    HomePage --> SignupPage
+    HomePage --> AboutPage
+    HomePage --> FeaturesPage
+    
+    LoginPage --> DashboardPage
+    SignupPage --> VerificationPage
+    VerificationPage --> DashboardPage
+    
+    DashboardPage --> ProfilePage
+    DashboardPage --> SettingsPage
+    DashboardPage --> ProjectsPage
+    
+    ProjectsPage --> ProjectDetailPage
+    ProjectDetailPage --> TasksPage
+    ProjectDetailPage --> TeamPage
+    ProjectDetailPage --> DocumentsPage
+```
+
+## User Authentication Flow
+
+```mermaid
+flowchart TD
+    HomePage --> LoginPage
+    LoginPage --> DashboardPage
+    LoginPage --> ForgotPasswordPage
+    ForgotPasswordPage --> ResetPasswordPage
+    ResetPasswordPage --> LoginPage
+    
+    HomePage --> SignupPage
+    SignupPage --> VerificationPage
+    VerificationPage --> CompleteProfilePage
+    CompleteProfilePage --> DashboardPage
+```
+
+## Account Management Flow
+
+```mermaid
+flowchart TD
+    DashboardPage --> ProfilePage
+    ProfilePage --> EditProfilePage
+    
+    DashboardPage --> SettingsPage
+    SettingsPage --> SecurityPage
+    SettingsPage --> NotificationsPage
+    SettingsPage --> BillingPage
+    
+    SecurityPage --> ChangePasswordPage
+    BillingPage --> PaymentMethodsPage
+    BillingPage --> SubscriptionPage
+```
+
+## Notes
+
+- This flowchart represents the primary pages and navigation paths in the application
+- Focus on page-to-page transitions rather than detailed component interactions
+- Update this flowchart whenever new pages are added or navigation paths change
+
+## Best Practices
+
+- Keep page navigation intuitive and consistent
+- Minimize the number of clicks to reach important pages
+- Ensure users can easily navigate back to key pages (like Dashboard)
+- Use clear and descriptive page names in both the diagram and application

data/lib/nova/templates/prd_example_template.md

@@ -0,0 +1,41 @@
+# Product Requirements Document - [Product Name]
+
+## Brief Product Overview
+[Concise description of the product and the problem it solves for users and the business]
+
+## Objectives
+1. [Primary objective with measurable outcomes]
+2. [Secondary objective with measurable outcomes]
+3. [Additional objective with measurable outcomes]
+
+## End Users
+- **Primary User Persona**: [Detailed description of main target user]
+- **Secondary User Persona**: [Detailed description of secondary target user]
+
+## Approach Overview
+[Description of the product approach, core functionality, and how it will solve the stated problem]
+
+## Feature List
+1. **[Feature 1 Name]**
+   - Description: [What this feature does]
+   - Priority: [High/Medium/Low]
+   - Why it matters: [Why this feature is important]
+
+2. **[Feature 2 Name]**
+   - Description: [What this feature does]
+   - Priority: [High/Medium/Low]
+   - Why it matters: [Why this feature is important]
+
+3. **[Feature 3 Name]**
+   - Description: [What this feature does]
+   - Priority: [High/Medium/Low]
+   - Why it matters: [Why this feature is important]
+
+## Tech Stack
+- Back-end: Ruby on Rails 8 Server Rendered App
+- Front-end: ERB / Stimulus / Tailwind CSS / Flowbite
+- Testing: Rspec
+- Hosting: Heroku
+- Background jobs: Sidekiq
+- Emails: SendGrid
+- File Storage: s3