Skip to content

spec.md

Latest commit

 

History

History
219 lines (175 loc) · 6.17 KB

spec.md

File metadata and controls

219 lines (175 loc) · 6.17 KB

Create C1 App - NPM Package Specification

Overview

A CLI tool that creates a Next.js project, authenticates users with an API service, generates API keys, and stores them using dotenv.

Architecture

Core Components

  1. CLI Interface (bin/create-c1-app)

    • Entry point for the tool
    • Interactive prompts using inquirer
    • Progress indicators and user feedback

  2. Project Generator (src/generators/project.ts)

    • Creates Next.js project using create-next-app
    • Configures project structure
    • Installs additional dependencies

  3. Authentication Module (src/auth/authenticator.ts)

    • Handles user authentication flow
    • Manages session tokens
    • Validates credentials

  4. API Key Manager (src/api/keyManager.ts)

    • Generates API keys via authenticated API calls
    • Validates key permissions
    • Handles key refresh/rotation

  5. Environment Manager (src/env/envManager.ts)

    • Integrates with dotenv
    • Securely stores API keys
    • Manages environment configuration

Workflow

Step 1: Project Initialization

1. Prompt for project name and configuration
2. Create Next.js project using create-next-app
3. Navigate to project directory
4. Install additional dependencies (dotenv, API client)

Step 2: User Authentication (Optional)

1. Prompt for API service credentials (email/password or token)
2. Authenticate with API service
3. Store session token securely
4. Validate authentication status
Note: Skipped when --api-key flag is provided

Step 3: API Key Generation (Optional)

1. Use authenticated session to request API key
2. Specify key permissions/scopes if needed
3. Receive and validate API key
4. Handle any rate limiting or quota restrictions
Note: Skipped when --api-key flag is provided

Step 4: Environment Setup

1. Set up dotenv in project
2. Create .env file with API key
3. Add .env to .gitignore
4. Configure Next.js for environment variables

Dependencies

Core Dependencies

  • inquirer - Interactive CLI prompts
  • chalk - Terminal colors and styling
  • ora - Loading spinners
  • execa - Process execution
  • fs-extra - Enhanced file system operations

TypeScript Dependencies

  • typescript - TypeScript compiler
  • @types/node - Node.js type definitions
  • @types/inquirer - Inquirer type definitions
  • ts-node - TypeScript execution environment

Project Dependencies (installed in generated project)

  • dotenv - Environment variables
  • Custom API client library (if applicable)

File Structure

create-c1-app/
├── package.json
├── tsconfig.json              # TypeScript configuration
├── bin/
│   └── create-c1-app              # CLI entry point
├── src/
│   ├── index.ts               # Main orchestrator
│   ├── types/
│   │   └── index.ts           # TypeScript type definitions
│   ├── generators/
│   │   └── project.ts         # Next.js project creation
│   ├── auth/
│   │   └── authenticator.ts   # Authentication handling
│   ├── api/
│   │   └── keyManager.ts      # API key management
│   ├── env/
│   │   └── envManager.ts      # Environment setup
│   └── utils/
│       ├── logger.ts          # Logging utilities
│       ├── validation.ts      # Input validation
│       └── spinner.ts         # Progress indicators
├── dist/                      # Compiled JavaScript output
├── templates/
│   └── nextjs/                # Next.js templates/configs
└── README.md

Configuration Options

CLI Arguments

  • --project-name (-n) - Specify project name
  • --template (-t) - Next.js template (app/pages router)
  • --api-key (-k) - API key to use (skips authentication and key generation)
  • --debug (-d) - Enable debug logging

Environment Variables

  • CREATE_C1_APP_ENDPOINT - Default API endpoint
  • CREATE_C1_APP_TOKEN - Pre-existing auth token
  • CREATE_C1_APP_DEBUG - Enable debug logging

Security Considerations

  1. Credential Storage

    • Never store plaintext credentials
    • Use system keychain when possible
    • Temporary session tokens only

  2. API Key Protection

    • Set up with dotenv
    • Generate unique keys per project
    • Implement key rotation capabilities

  3. Network Security

    • Use HTTPS for all API calls
    • Validate SSL certificates
    • Implement request timeout/retry logic

Error Handling

Authentication Errors

  • Invalid credentials → Re-prompt with helpful message
  • Network errors → Retry with exponential backoff
  • Rate limiting → Wait and inform user

Project Creation Errors

  • Directory exists → Prompt for overwrite/rename
  • Permission errors → Suggest alternative location
  • Dependency installation fails → Provide manual steps

API Key Errors

  • Generation fails → Retry with user confirmation
  • Invalid permissions → Show available options
  • Quota exceeded → Display usage information

Testing Strategy

  1. Unit Tests

    • Each module independently tested
    • Mock external API calls
    • Validate input/output contracts

  2. Integration Tests

    • End-to-end tool flow
    • Real API interactions (test environment)
    • File system operations

  3. CLI Tests

    • Command parsing and validation
    • Interactive prompt flows
    • Error scenario handling

Future Enhancements

  1. Developer Experience
    • Auto-completion for bash/zsh
    • VS Code extension
    • Documentation generation
    • Usage analytics (opt-in)

Success Criteria

  1. ✅ Creates functional Next.js project
  2. ✅ Successfully authenticates users
  3. ✅ Generates valid API keys
  4. ✅ Stores credentials with dotenv
  5. ✅ Provides clear error messages
  6. ✅ Works across platforms (macOS, Linux, Windows)
  7. ✅ Complete in under 2 minutes for typical usage

Implementation Phases

Phase 1: Core Functionality

  • Basic CLI structure
  • Next.js project creation
  • Simple authentication flow

Phase 2: Security & Environment

  • dotenv integration
  • Secure credential storage
  • Environment validation

Phase 3: Polish & Testing

  • Error handling improvements
  • Comprehensive testing
  • Documentation and examples