social-light 0.0.1

package/.env.example

@@ -0,0 +1,7 @@
+# OpenAI API key for AI features
+OPENAI_API_KEY=your_openai_api_key
+
+# Bluesky credentials
+BLUESKY_HANDLE=your_handle.bsky.social
+BLUESKY_APP_PASSWORD=your_bluesky_app_password
+BLUESKY_SERVICE=https://bsky.social

package/.instructions/checklist.md

@@ -0,0 +1,45 @@
+# Social Light Project Checklist
+
+## Project Structure
+
+- [x] Create basic project structure
+- [x] Initialize package.json with dependencies
+- [x] Create main entry point (index.mjs)
+
+## Core Utilities
+
+- [x] Database utility (db.mjs)
+- [x] Configuration utility (config.mjs)
+- [x] AI utility (ai.mjs)
+- [x] Social media API wrapper (base.mjs)
+  - [x] Twitter/X implementation (twitter.mjs)
+  - [x] Bluesky implementation (bluesky.mjs)
+  - [x] TikTok implementation (tiktok.mjs)
+
+## CLI Commands
+
+- [x] Initialize command (init.mjs)
+- [x] Create post command (create.mjs)
+- [x] List unpublished posts command (unpublished.mjs)
+- [x] List published posts command (published.mjs)
+- [x] Edit post command (edit.mjs)
+- [x] Publish posts command (publish.mjs)
+
+## Web Server
+
+- [x] Express server setup
+- [x] API endpoints
+- [x] Basic web frontend
+
+## Social Media Integration
+
+- [x] Twitter API integration
+- [x] Bluesky API integration
+- [x] TikTok API integration
+- [x] Extensible platform API wrapper
+
+## Additional Features
+
+- [x] Continuous publishing mode
+- [x] Calendar visualization
+- [ ] Post analytics

package/.instructions/prd.md

@@ -0,0 +1,182 @@
+Here's a **Product Requirements Document (PRD)** for your CLI + Web hybrid AI-powered social scheduling tool, named **Social Light**.
+
+---
+
+## 📄 Product Requirements Document (PRD)
+
+### Product Name
+
+**Social Light**
+
+### Overview
+
+**Social Light** is a command-line tool and optional local web server that helps users manage and schedule social media posts. It leverages AI to assist with post generation, scheduling, and cross-platform publishing.
+
+---
+
+### Goals
+
+- Provide a fast, scriptable, and extensible CLI for content creation and scheduling.
+- Allow an optional local web interface for reviewing/editing posts and calendars.
+- Support AI-powered assistance for titles, publish dates, and content suggestions.
+- Manage state using a local SQLite database and a user-scoped JSON settings file.
+- Support for scheduling and publishing to multiple platforms (e.g., Twitter, Bluesky, TikTok).
+
+---
+
+### Interfaces
+
+#### CLI (Primary)
+
+Command-line tool with subcommands (inspired by Git/Heroku-style commands).
+
+#### Web UI (Optional)
+
+Local web interface launched with `social-light server` to browse, create, and edit posts.
+
+---
+
+### Initial Setup
+
+#### `social-light init`
+
+- Creates a JSON config file at `$HOME/.social-light/config.json`
+- Config includes:
+
+  ```json
+  {
+    "dbPath": "~/.social-light/social-light.db",
+    "defaultPlatforms": [],
+    "aiEnabled": true
+  }
+  ```
+
+- Creates SQLite DB file and necessary tables (posts, logs, etc.)
+
+---
+
+### Post Data Model (SQLite)
+
+| Field        | Type     | Description                       |
+| ------------ | -------- | --------------------------------- |
+| id           | INTEGER  | Primary key                       |
+| title        | TEXT     | Title of the post                 |
+| content      | TEXT     | Full post content                 |
+| platforms    | TEXT     | Comma-separated list of platforms |
+| publish_date | DATE     | Scheduled publish date            |
+| published    | BOOLEAN  | Whether the post is published     |
+| created_at   | DATETIME | Timestamp of creation             |
+| updated_at   | DATETIME | Timestamp of last edit            |
+
+---
+
+### CLI Commands
+
+#### `social-light create`
+
+Two modes:
+
+1. **Prompt-based (interactive)**
+
+   ```
+   > This is my first post!
+   enter a title? (leave blank for AI to figure it out)>
+   enter a publish date? (leave blank for AI to figure it out)>
+   where would you like to publish this post?
+   - [x] Twitter
+   - [ ] Bluesky
+   - [ ] TikTok
+   ```
+
+2. **File-based**
+
+   ```bash
+   social-light create --file my_post.txt
+   ```
+
+AI will infer:
+
+- Title (from content)
+- Date (based on historical post frequency and current date)
+
+#### `social-light unpublished`
+
+Lists all unpublished posts:
+
+```
+[index] [date] [title] [truncated content...]
+```
+
+#### `social-light published`
+
+Lists published posts:
+
+```
+[index] [date] [title] [truncated content...]
+```
+
+#### `social-light edit [index]`
+
+- Edits a draft post by index
+- Opens `$EDITOR` or prompts inline
+- Title/content/platform/date editable
+
+#### `social-light publish`
+
+- Publishes all eligible posts (date <= today)
+- Marks them as `published = true`
+
+#### `social-light publish --continuous`
+
+- Polls continuously (e.g., every 60s)
+- Checks for publishable posts and posts them
+
+#### `social-light server`
+
+- Launches local web UI
+- React frontend served via Express or Vite backend
+- Allows post browsing, editing, calendar view, platform settings
+
+---
+
+### AI Integration
+
+- **AI Title Inference:** Uses first lines + intent classification
+- **AI Date Prediction:** Based on user's post cadence
+- **Optional Caption Enhancement:** Suggestions on tone, hashtags, or trending topics
+
+Uses the [`ai`](https://www.npmjs.com/package/ai) npm package (OpenAI wrapper).
+
+---
+
+### Tech Stack
+
+- **CLI:** Node.js, `yargs`, `ora`, `inquirer`, `fs-extra`, `chalk`
+- **AI:** [`ai`](https://www.npmjs.com/package/ai)
+- **DB:** SQLite via `better-sqlite3` or `knex`
+- **Config:** JSON in `$HOME/.social-light/config.json`
+- **Server (optional):** Express + React (via Vite), Tailwind for UI
+- **Scheduler:** Node cron jobs or `setInterval` for continuous mode
+
+---
+
+### Stretch Goals
+
+- 🗓️ **Monthly Calendar Generator:** Visual calendar view with post slots
+- ✍️ **Caption Generator:** Suggests captions per platform
+- 🎨 **Image Generator:** AI-based content visuals from prompts
+- 📹 **Video Stitcher:** Combine images/sound for TikTok/IG Reels
+
+---
+
+### Success Criteria
+
+- Can create, edit, and publish posts via CLI
+- AI assistance enhances workflow (for title/date at minimum)
+- Local DB reliably stores and syncs post state
+- Posts appear and update correctly in the optional web UI
+- User can run `--continuous` publish mode reliably
+
+---
+
+Would you like help scaffolding the CLI file structure or database schema next?

package/.instructions/summary.md

@@ -0,0 +1,122 @@
+# Social Light Project Development Summary
+
+## Project Overview
+
+We developed "Social Light," a Node.js CLI and web application for AI-powered social media post scheduling. The application allows users to create, schedule, and publish content to multiple social media platforms using a command-line interface or a web UI.
+
+## Key Features Implemented
+
+- Command-line interface with multiple commands (init, create, edit, publish, etc.)
+- Web interface using Express and vanilla JavaScript
+- SQLite database for local data storage
+- OpenAI-powered AI features for title generation and date suggestions
+- Social media platform integrations for Twitter, Bluesky, and TikTok
+- Continuous posting mode for scheduled content
+- Calendar visualization
+
+## Project Architecture
+
+### Core Directory Structure
+
+```
+social-light/
+├── src/
+│   ├── commands/       # CLI command implementations
+│   ├── utils/          # Utility modules
+│   │   ├── social/     # Social media platform APIs
+│   │   ├── ai.mjs      # AI utilities
+│   │   ├── config.mjs  # Configuration utilities
+│   │   └── db.mjs      # Database utilities
+│   ├── server/         # Web server and UI
+│   │   ├── client/     # Client-side web interface
+│   │   └── index.mjs   # Express server
+│   └── index.mjs       # Main CLI entry point
+└── package.json        # Project configuration
+```
+
+### Technical Components
+
+#### CLI Commands
+
+- **init**: Initializes configuration and database
+- **create**: Creates new posts with AI assistance
+- **unpublished**: Lists unpublished posts
+- **published**: Lists published posts
+- **edit**: Edits existing posts
+- **publish**: Publishes eligible posts, with continuous mode option
+- **server**: Starts web interface
+
+#### Database
+
+- SQLite database for post storage
+- Automatic table creation and initialization
+- Functions for CRUD operations on posts
+
+#### Social Media Integration
+
+- Extensible platform API with a base class and factory pattern
+- Twitter/X integration using their official API
+- Bluesky integration using the AT Protocol
+- TikTok integration using Content Posting API
+- Graceful handling of unsupported platforms (Instagram, LinkedIn)
+
+#### AI Features
+
+- Title generation from post content
+- Smart publish date suggestions based on posting history
+- Content enhancement for platform optimization
+
+## Technical Challenges Addressed
+
+1. **Database Initialization**: Implemented auto-initialization of SQLite database to prevent "no such table" errors
+2. **Editor Issues**: Replaced external editor invocation with multiline terminal input
+3. **API Key Management**: Created extensive documentation for API setup and management
+4. **Platform Errors**: Fixed constant variable reassignment error in social API implementation
+5. **Unsupported Platforms**: Added graceful handling for platforms without implementation
+
+## Environment Variables Required
+
+```
+# OpenAI API for AI features
+OPENAI_API_KEY=your_openai_api_key
+
+# Twitter/X credentials
+TWITTER_API_KEY=your_twitter_api_key
+TWITTER_API_SECRET=your_twitter_api_secret
+TWITTER_ACCESS_TOKEN=your_twitter_access_token
+TWITTER_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret
+
+# Bluesky credentials
+BLUESKY_HANDLE=your_handle.bsky.social
+BLUESKY_APP_PASSWORD=your_bluesky_app_password
+
+# TikTok credentials
+TIKTOK_CLIENT_KEY=your_tiktok_client_key
+TIKTOK_CLIENT_SECRET=your_tiktok_client_secret
+TIKTOK_ACCESS_TOKEN=your_tiktok_access_token
+```
+
+## Modern JavaScript Features Used
+
+- ES Modules with dynamic imports
+- Top-level await
+- Destructuring assignments
+- Async/await throughout codebase
+- Template literals
+- Arrow functions
+- Optional chaining and nullish coalescing
+
+## Documentation Created
+
+- README.md with usage instructions
+- API_SETUP.md with detailed API integration instructions
+- Inline JSDoc documentation for all functions
+
+## Future Expansion Possibilities
+
+- Additional social platform integrations
+- Enhanced analytics features
+- Image and video generation capabilities
+- Advanced scheduling algorithms
+
+The application is designed with extensibility in mind, using modular architecture and factory patterns to make adding new features straightforward.

package/README.md

@@ -0,0 +1,196 @@
+# Social Light
+
+<img src="https://raw.githubusercontent.com/johnhenry/social-light/main/src/server/client/logo.jpg" alt="social light logo" style="height:256px">
+
+An AI-powered social media scheduling tool for Bluesky with CLI and web interface. More platforms coming soon!
+
+## Features
+
+- **CLI Interface**: Create, manage, and publish posts directly from your terminal
+- **Web Interface**: Optional local web server for a visual post management experience
+- **AI Assistance**: Automatic title generation, date suggestions, and content enhancement
+- **Bluesky Integration**: Publish to Bluesky with ease
+- **Scheduling**: Schedule posts ahead of time with smart AI date suggestions
+- **Continuous Publishing**: Run in daemon mode to automatically publish scheduled posts
+
+## Prerequesites
+
+### Software
+
+[Node.js/npm](https://nodejs.org) must be installed on your system
+
+> [!WARNING]  
+> There's a know issues with the latest version of Node.js (v23) and 'better-sqlite3'. Please use Node.js v22 (LTS) or lower.
+
+## Accounts
+
+You will need an account on [blue sky](https://bsky.app) and an [OpenAI](https://openai.com) account to use the AI features.
+
+## Installation
+
+### From NPM
+
+```bash
+npm install -g social-light
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/social-light.git
+cd social-light
+
+# Install dependencies
+npm install
+
+# Make the CLI executable
+chmod +x src/index.mjs
+npm link
+```
+
+## CLI Usage
+
+### Initialize social-light
+
+```bash
+social-light init
+```
+
+This will:
+
+- Create a configuration file at `~/.social-light/config.json`
+- Initialize a SQLite database at `~/.social-light/social-light.db`
+- Collect your Bluesky credentials
+- Collect your Open AI credentials
+
+### Create a Post
+
+```bash
+social-light create
+```
+
+This will guide you through creating a new post with:
+
+- Interactive content editor
+- AI-powered title suggestions
+- Smart publish date recommendations
+- Platform selection
+
+### Manage Posts
+
+```bash
+# List unpublished posts
+social-light unpublished
+
+# List published posts
+social-light published
+
+# Edit a post by index
+social-light edit 1
+```
+
+### Publish Posts
+
+```bash
+# Publish all eligible posts
+social-light publish
+
+# Run in continuous mode (daemon)
+social-light publish --continuous
+```
+
+### Web Interface
+
+Open the web interface to manage post visually
+
+<img src="https://raw.githubusercontent.com/johnhenry/social-light/main/server.png" alt="server" style="height:256px">
+
+```bash
+# Start the web server
+social-light server
+
+# Specify a custom port
+social-light server --port 8080
+```
+
+## Web Interface
+
+The web interface provides a visual way to:
+
+- View all your scheduled and published posts
+- Create and edit posts with a rich text editor
+- See a calendar view of your posting schedule
+- Manually publish posts with a single click
+
+Access the web interface at `http://localhost:3000` (or your specified port) after starting the server.
+
+## Configuration
+
+Configuration is stored in `~/.social-light/config.json` and can be modified directly or through the initialization process.
+
+### Example Config
+
+```json
+{
+  "dbPath": "~/.social-light/social-light.db",
+  "defaultPlatforms": ["Bluesky"],
+  "aiEnabled": true
+}
+```
+
+### Platform Setup
+
+To publish to Bluesky, you'll need to set up your credentials:
+
+#### Bluesky
+
+## AI Features
+
+To use AI features, you need an OpenAI API key:
+
+```
+OPENAI_API_KEY=your_openai_api_key
+```
+
+AI features include:
+
+- Title generation based on post content
+- Smart publish date suggestions based on your posting history
+- Content enhancement for platform-specific optimization
+
+## Development
+
+### Project Structure
+
+```
+social-light/
+├── src/
+│   ├── commands/        # CLI command implementations
+│   ├── utils/           # Utility modules
+│   │   ├── social/      # Social media platform APIs
+│   │   ├── ai.mjs       # AI utilities
+│   │   ├── config.mjs   # Configuration utilities
+│   │   └── db.mjs       # Database utilities
+│   ├── server/          # Web server and UI
+│   │   ├── client/      # Client-side web interface
+│   │   └── index.mjs    # Express server
+│   └── index.mjs        # Main CLI entry point
+└── package.json         # Project configuration
+```
+
+### Technologies Used
+
+- **Node.js** with ES Modules
+- **SQLite** for local database storage
+- **Express** for the web server
+- **OpenAI API** for AI-powered features
+- **Bluesky AT Protocol** for social media integration
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/bin/socialite

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+# Get the directory of the script
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Run the Node.js application
+node "$DIR/../src/index.mjs" "$@"