langctl 0.0.1 → 0.1.0

package/NPM_PUBLISH_GUIDE.md

@@ -0,0 +1,293 @@
+# 🚀 Publishing Langctl CLI to npm
+
+**Date:** January 5, 2026  
+**Package:** langctl  
+**Version:** 0.1.0
+
+---
+
+## ✅ Pre-Publish Checklist
+
+Before publishing, verify these items:
+
+- [x] Package name available: `langctl` ✅
+- [x] README.md complete with examples ✅
+- [x] package.json properly configured ✅
+- [x] .npmignore configured ✅
+- [x] TypeScript source code ready ✅
+- [x] License file present (MIT) ✅
+
+---
+
+## 📋 Step-by-Step Publishing Guide
+
+### Step 1: Verify npm Login
+
+Check if you're logged into npm:
+
+```bash
+npm whoami
+```
+
+**If not logged in:**
+
+```bash
+npm login
+```
+
+Enter your credentials:
+- Username
+- Password
+- Email
+- One-time password (if 2FA enabled)
+
+---
+
+### Step 2: Final Build & Test
+
+```bash
+cd /Users/siddharthsaxena/Documents/projects/langctl/langctl-cli
+
+# Clean previous build
+rm -rf dist/
+
+# Fresh build
+npm run build
+
+# Verify build succeeded
+ls -la dist/
+```
+
+**Expected:** You should see `.js` and `.d.ts` files in dist/
+
+---
+
+### Step 3: Test Package Locally
+
+Before publishing, test the package works:
+
+```bash
+# Link package globally for testing
+npm link
+
+# Test the CLI
+langctl --version
+langctl --help
+
+# If it works, unlink
+npm unlink -g langctl
+```
+
+---
+
+### Step 4: Dry Run (Recommended)
+
+See what will be published WITHOUT actually publishing:
+
+```bash
+npm pack --dry-run
+```
+
+This shows:
+- ✅ Files that will be included
+- ✅ Package size
+- ✅ No errors
+
+---
+
+### Step 5: Create Package Tarball (Optional)
+
+Create actual tarball to inspect:
+
+```bash
+npm pack
+```
+
+This creates: `langctl-0.1.0.tgz`
+
+**To inspect:**
+```bash
+tar -xzf langctl-0.1.0.tgz
+ls -la package/
+```
+
+**Clean up after:**
+```bash
+rm langctl-0.1.0.tgz
+rm -rf package/
+```
+
+---
+
+### Step 6: Publish to npm! 🚀
+
+**First time publishing (public package):**
+
+```bash
+npm publish --access public
+```
+
+**Expected output:**
+```
+npm notice 
+npm notice 📦  langctl@0.1.0
+npm notice === Tarball Contents === 
+npm notice 1.1kB LICENSE
+npm notice 2.3kB README.md
+npm notice 845B  package.json
+npm notice 15.2kB dist/...
+npm notice === Tarball Details === 
+npm notice name:          langctl
+npm notice version:       0.1.0
+npm notice package size:  XX.X kB
+npm notice unpacked size: XXX.X kB
+npm notice total files:   XX
+npm notice 
++ langctl@0.1.0
+```
+
+---
+
+### Step 7: Verify Publication
+
+**Check on npm:**
+1. Visit: https://www.npmjs.com/package/langctl
+2. Verify README displays correctly
+3. Check version number
+
+**Test installation:**
+```bash
+# In a different directory
+npx langctl@latest --version
+```
+
+---
+
+## 🎉 Success! Package Published
+
+Your CLI is now available globally at:
+- **npm:** https://www.npmjs.com/package/langctl
+- **Install:** `npm install -g langctl`
+- **Use:** `npx langctl`
+
+---
+
+## 📊 Post-Publish Tasks
+
+### Update Landing Page
+
+Add npm install instructions to langctl.com:
+
+```bash
+npm install -g langctl
+```
+
+### Update README (if needed)
+
+If you notice issues, you can publish patches:
+
+```bash
+# Fix README or other files
+# Bump version
+npm version patch  # 0.1.0 → 0.1.1
+
+# Rebuild and republish
+npm run build
+npm publish
+```
+
+### Monitor npm Stats
+
+Check download stats:
+- https://www.npmjs.com/package/langctl
+- https://npmtrends.com/langctl
+
+---
+
+## 🔧 Troubleshooting
+
+### Error: "You do not have permission to publish"
+
+**Solution:**
+```bash
+npm login
+npm whoami  # Verify correct account
+```
+
+### Error: "Package name already exists"
+
+**Solution:** The name is taken. Since you reserved it, make sure you're logged in correctly.
+
+### Error: "Must be logged in to publish"
+
+**Solution:**
+```bash
+npm login
+```
+
+### Build errors
+
+**Solution:**
+```bash
+rm -rf node_modules/ dist/
+npm install
+npm run build
+```
+
+---
+
+## 📈 Version Updates (Future)
+
+**Patch (bug fixes):** 0.1.0 → 0.1.1
+```bash
+npm version patch
+npm run build
+npm publish
+```
+
+**Minor (new features):** 0.1.0 → 0.2.0
+```bash
+npm version minor
+npm run build
+npm publish
+```
+
+**Major (breaking changes):** 0.1.0 → 1.0.0
+```bash
+npm version major
+npm run build
+npm publish
+```
+
+---
+
+## ✅ Final Checklist
+
+Before running `npm publish`:
+
+- [ ] Logged into npm (`npm whoami`)
+- [ ] Build succeeded (`npm run build`)
+- [ ] Local test passed (`npm link` + test commands)
+- [ ] Dry run clean (`npm pack --dry-run`)
+- [ ] Ready to publish! (`npm publish --access public`)
+
+---
+
+## 🎯 Quick Command Summary
+
+```bash
+# From langctl-cli directory:
+npm whoami                        # Verify login
+npm run build                     # Build TypeScript
+npm pack --dry-run                # Preview package
+npm publish --access public       # Publish!
+npx langctl@latest --version      # Verify
+```
+
+---
+
+**Good luck! You're about to publish your first npm package! 🚀**
+
+**Questions? Issues?**
+- npm support: https://www.npmjs.com/support
+- Package page: https://www.npmjs.com/package/langctl

package/QUICK_PUBLISH.md

@@ -0,0 +1,64 @@
+# 🚀 PUBLISH LANGCTL - QUICK COMMANDS
+
+**Run these commands in order on YOUR MAC:**
+
+```bash
+# 1. Navigate to CLI directory
+cd /Users/siddharthsaxena/Documents/projects/langctl/langctl-cli
+
+# 2. Check npm login
+npm whoami
+
+# 3. If not logged in:
+npm login
+
+# 4. Build the package
+npm run build
+
+# 5. Test locally (optional but recommended)
+npm link
+langctl --version
+langctl --help
+npm unlink -g langctl
+
+# 6. Dry run to preview
+npm pack --dry-run
+
+# 7. PUBLISH! 🚀
+npm publish --access public
+
+# 8. Verify it worked
+npx langctl@latest --version
+```
+
+---
+
+## ✅ Expected Result
+
+After `npm publish`, you should see:
+
+```
++ langctl@0.1.0
+```
+
+Then check: https://www.npmjs.com/package/langctl
+
+---
+
+## 🎉 That's It!
+
+Your CLI is now installable worldwide:
+
+```bash
+npm install -g langctl
+```
+
+or
+
+```bash
+npx langctl --help
+```
+
+---
+
+**Full guide:** See `NPM_PUBLISH_GUIDE.md` for detailed instructions and troubleshooting.

package/README.md

@@ -1,57 +1,312 @@
-# Langctl
+# Langctl CLI
 
 > CLI-first translation management for developers
 
-🚧 **Coming Soon** - This package is currently in development.
+Langctl is a command-line tool that lets you manage translations directly from your terminal. Pull translations in multiple formats, sync with your projects, and integrate seamlessly into your CI/CD pipeline.
 
-## What is Langctl?
+## Installation
 
-Langctl is a modern translation management tool built for developers who want to:
-- Manage translations from the command line
-- Use AI-powered translations
-- Save money compared to enterprise tools
-- Integrate seamlessly with their development workflow
+```bash
+npm install -g langctl
+```
+
+Or use with npx:
+
+```bash
+npx langctl --help
+```
 
-## Features (Planned)
+## Quick Start
 
-- 🖥️ **CLI-First** - Manage translations from your terminal
-- 🤖 **AI-Powered** - Context-aware translations using advanced AI
-- 💰 **Affordable** - Starting free, pay only for what you use
-- ⚡ **Fast** - Setup in under 2 minutes
-- 🔧 **Framework Agnostic** - Works with Angular, React, Vue, and more
+### 1. Initialize Configuration
 
-## Installation (When Available)
+Run the interactive setup wizard to configure Langctl:
 
 ```bash
-npm install -g langctl
+langctl init
+```
+
+This will:
+- Configure Supabase connection (uses defaults)
+- Authenticate with your API key (get one from the dashboard)
+- Set your default language preference
+
+### 2. List Your Projects
+
+View all projects you have access to:
+
+```bash
+langctl projects list
 ```
 
-## Usage (When Available)
+### 3. Pull Translations
+
+Download translations for a project:
+
+```bash
+langctl pull <project-id> --language en --format json
+```
+
+## Commands
+
+### `langctl init`
+
+Interactive setup wizard to configure the CLI.
 
 ```bash
-# Initialize langctl in your project
 langctl init
+```
 
-# Scan for translation keys
-langctl scan
+### `langctl auth <api-key>`
 
-# Translate to multiple languages
-langctl translate --target es,fr,de --ai
+Authenticate with an API key from the dashboard.
 
-# Push to cloud
-langctl push
+```bash
+langctl auth lc_abc123...
 ```
 
-## Stay Updated
+### `langctl logout`
 
-- 🌐 Website: [langctl.com](https://langctl.com)
-- 📧 Email: hello@langctl.com
-- 🐙 GitHub: [github.com/siddharthsaxena0/langctl](https://github.com/siddharthsaxena0/langctl)
+Clear authentication credentials.
 
-## License
+```bash
+langctl logout
+```
+
+### `langctl config`
+
+View current configuration.
+
+```bash
+langctl config
+```
+
+### `langctl projects list`
+
+Show all accessible projects.
+
+```bash
+langctl projects list
+```
+
+### `langctl pull <project-id>`
+
+Pull translations from a project.
+
+```bash
+langctl pull <project-id> [options]
+```
+
+**Options:**
+
+- `-l, --language <code>` - Language code to pull (default: en)
+- `-f, --format <type>` - Export format (default: json)
+  - `json` - Flat JSON (key-value pairs)
+  - `json-nested` - Nested JSON (organized by key structure)
+  - `ios` - iOS .strings format
+  - `android` - Android XML format
+  - `flutter` - Flutter ARB format
+- `-o, --output <path>` - Output file path (default: ./translations/<filename>)
+- `--no-published-only` - Include unpublished translations
+
+**Examples:**
+
+```bash
+# Pull English translations as JSON
+langctl pull abc-123 --language en --format json
+
+# Pull Spanish translations as iOS strings
+langctl pull abc-123 --language es --format ios
+
+# Pull all translations (including unpublished)
+langctl pull abc-123 --language en --no-published-only
+
+# Custom output path
+langctl pull abc-123 --language en --output ./locales/en.json
+```
+
+## Export Formats
+
+### JSON (Flat)
+
+Simple key-value pairs with dot notation.
+
+```json
+{
+  "home.welcome": "Welcome!",
+  "home.subtitle": "Get started with {{appName}}"
+}
+```
+
+### JSON (Nested)
+
+Organized by key structure.
+
+```json
+{
+  "home": {
+    "welcome": "Welcome!",
+    "subtitle": "Get started with {{appName}}"
+  }
+}
+```
+
+### iOS Strings
+
+Standard iOS .strings format.
+
+```
+"home.welcome" = "Welcome!";
+"home.subtitle" = "Get started with %1$@";
+```
+
+### Android XML
+
+Android resources XML format.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <string name="home.welcome">Welcome!</string>
+  <string name="home.subtitle">Get started with %1$s</string>
+</resources>
+```
+
+### Flutter ARB
+
+Application Resource Bundle format for Flutter.
+
+```json
+{
+  "@@locale": "en",
+  "home.welcome": "Welcome!",
+  "home.subtitle": "Get started with {appName}",
+  "@home.subtitle": {
+    "placeholders": {
+      "appName": {
+        "type": "String"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+Configuration is stored in `~/.langctl/config.json`:
+
+```json
+{
+  "supabaseUrl": "https://xxx.supabase.co",
+  "supabaseAnonKey": "eyJ...",
+  "apiKey": "lc_...",
+  "organizationId": "uuid",
+  "organizationName": "Company Name",
+  "defaultProject": "uuid",
+  "defaultLanguage": "en"
+}
+```
+
+## API Keys
+
+Generate API keys from the Langctl dashboard:
+
+1. Go to Settings → API Keys
+2. Click "Generate New Key"
+3. Copy the key (shown only once)
+4. Use it with `langctl auth <key>` or `langctl init`
+
+API keys are organization-scoped and provide access to all projects within that organization.
+
+## CI/CD Integration
+
+Example GitHub Actions workflow:
 
-MIT © Langctl
+```yaml
+name: Sync Translations
 
----
+on:
+  schedule:
+    - cron: '0 0 * * *' # Daily at midnight
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install Langctl
+        run: npm install -g langctl
+
+      - name: Configure Langctl
+        env:
+          LANGCTL_API_KEY: ${{ secrets.LANGCTL_API_KEY }}
+        run: langctl auth $LANGCTL_API_KEY
+
+      - name: Pull Translations
+        run: |
+          langctl pull ${{ secrets.PROJECT_ID }} --language en --format json
+          langctl pull ${{ secrets.PROJECT_ID }} --language es --format json
+
+      - name: Commit Changes
+        run: |
+          git config --global user.name "Langctl Bot"
+          git config --global user.email "bot@langctl.com"
+          git add translations/
+          git commit -m "chore: update translations" || echo "No changes"
+          git push
+```
+
+## Troubleshooting
+
+### "Not authenticated" error
+
+Run `langctl auth <api-key>` or `langctl init` to authenticate.
+
+### "Supabase not configured" error
+
+Run `langctl init` to configure Supabase connection.
+
+### "Project not found" error
+
+- Verify the project ID with `langctl projects list`
+- Check that your API key has access to the organization
+
+### Invalid API key format
+
+API keys should:
+- Start with `lc_`
+- Be 67 characters long
+- Be generated from the Langctl dashboard
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Test CLI
+node dist/index.js --help
+```
+
+## Support
+
+- **Documentation:** [langctl.com/docs](https://langctl.com/docs)
+- **Issues:** [github.com/siddharthsaxena0/langctl/issues](https://github.com/siddharthsaxena0/langctl/issues)
+- **Email:** hello@langctl.com
+
+## License
 
-**Note:** This is a placeholder package to reserve the name. The actual CLI tool is under development and will be released soon.
+MIT © Siddharth Saxena