@portel/photon 1.2.0 → 1.4.0

package/README.md

@@ -7,7 +7,7 @@
 
 # Photon
 
-**Runtime that turns single-file TypeScript classes into production-ready MCP servers.**
+**Universal runtime that turns single-file TypeScript into MCP server, CLI, and more.**
 
 Photon TS files are Single file. Zero boilerplate. Pure business logic.
 
@@ -26,6 +26,21 @@ Photon TS files are Single file. Zero boilerplate. Pure business logic.
 
 Think of it like **NPM and Node, but for MCP**.
 
+### Write Once, Use Everywhere
+
+The same `.photon.ts` file automatically becomes:
+- 🤖 **MCP Server** - Tools for Claude Desktop, Cursor, and AI assistants
+- 💻 **CLI Tool** - Beautiful command-line interface for humans
+- 🔌 **Platform Integrations** - NCP, Lumina, and future runtimes
+
+```bash
+# Same file, multiple interfaces:
+photon mcp analytics              # Run as MCP server for AI
+photon cli analytics revenue      # Use as CLI tool for humans
+```
+
+**Zero extra code. Pure business logic. Infinite deployment targets.**
+
 ### The Photon Ecosystem Flywheel
 
 ![Photon Ecosystem](https://raw.githubusercontent.com/portel-dev/photon/refs/heads/main/assets/photon-ecosystem.png)
@@ -103,6 +118,28 @@ export default class Analytics {
 
 **40 lines. One file. Production-ready.**
 
+### Use It Everywhere
+
+That single file now works as both an **MCP server** and a **CLI tool**:
+
+```bash
+# As an MCP server (for AI assistants)
+photon mcp analytics
+# → Claude Desktop can now call revenue() as a tool
+
+# As a CLI (for humans)
+photon cli analytics revenue --startDate 2024-01-01 --endDate 2024-12-31
+# → Beautiful formatted output:
+# ┌────────────┬──────────┐
+# │ Date       │ Revenue  │
+# ├────────────┼──────────┤
+# │ 2024-01-01 │ $12,450  │
+# │ 2024-01-02 │ $15,320  │
+# └────────────┴──────────┘
+```
+
+**Same code. Same logic. Two interfaces. Zero duplication.**
+
 ---
 
 ## Why One File Changes Everything
@@ -139,6 +176,7 @@ photon mcp my-jira  # Works immediately
 ```
 
 **Use cases:**
+
 - Add company-specific authentication
 - Customize business logic
 - Merge multiple photons
@@ -149,6 +187,7 @@ photon mcp my-jira  # Works immediately
 Prompt injection attacks are the new supply-chain threat. A malicious MCP can manipulate AI responses to exfiltrate your entire conversation history—not just credentials.
 
 **One file = one audit:**
+
 - Read 40 lines, understand everything
 - No hidden code scattered across imports
 - Fork and verify in minutes, not hours
@@ -189,8 +228,27 @@ photon info
 # Install any photon (filesystem, git, postgres, mongodb, slack, etc.)
 photon add filesystem
 
-# Run as MCP server
-photon mcp filesystem
+# or else copy your own .photon.ts file to 
+# .photon folder in your user folder 
+
+# Call info command with mcp option
+photon info filesystem --mcp
+# Get client config json
+{
+  "filesystem": {
+    "command": "photon",
+    "args": [
+      "mcp",
+      "filesystem"
+    ],
+    "env": {
+      "FILESYSTEM_WORKDIR": "/Users/arul/Documents",
+      "FILESYSTEM_MAX_FILE_SIZE": "10485760",
+      "FILESYSTEM_ALLOW_HIDDEN": "false"
+    }
+  }
+}
+# Add to your client 
 ```
 
 ### Build Photons with AI
@@ -210,17 +268,6 @@ photon marketplace add your-org/your-photons
 photon add your-custom-tool
 ```
 
-### Integrate with Your MCP Client
-
-```bash
-# Get configuration for any MCP client
-photon info filesystem --mcp
-```
-
-Add the output to your MCP client's config file. **Consult your client's documentation** for setup instructions.
-
-**MCP clients include:** Claude Desktop, Cursor, Zed, Continue, Cline, and more.
-
 ---
 
 ## The Value Proposition
@@ -235,11 +282,173 @@ Add the output to your MCP client's config file. **Consult your client's documen
 | **Dependencies** | Manual npm install | Auto-installed from @dependencies |
 | **Hot Reload** | Configure yourself | Built-in with --dev |
 | **AI Context** | Scattered | Single file |
+| **CLI Interface** | Write separate code | Automatic from same code |
+| **Deployment Targets** | MCP only | MCP, CLI, NCP, Lumina, APIs... |
 
 [See detailed comparison →](COMPARISON.md)
 
 ---
 
+## CLI Interface
+
+Every photon automatically provides a beautiful CLI interface with zero additional code. The same business logic that powers your MCP tools becomes instantly available from the terminal.
+
+### Quick Example
+
+```bash
+# List all methods
+photon cli lg-remote
+
+# Call methods with natural syntax
+photon cli lg-remote volume 50
+photon cli lg-remote volume +5
+photon cli lg-remote channel 7
+photon cli lg-remote app netflix
+
+# Get method help
+photon cli lg-remote volume --help
+```
+
+### Beautiful Output Formats
+
+Photon automatically formats output based on data structure:
+
+**Tables** - Key-value pairs and flat objects:
+```bash
+$ photon cli lg-remote volume
+┌─────────┬────┐
+│ volume  │ 45 │
+├─────────┼────┤
+│ muted   │ no │
+├─────────┼────┤
+│ maxVol  │ 100│
+└─────────┴────┘
+```
+
+**Lists** - Arrays of items:
+```bash
+$ photon cli lg-remote apps
+• Netflix (netflix)
+• YouTube (youtube.leanback.v4)
+• HDMI1 (com.webos.app.hdmi1)
+• Disney+ (disney)
+```
+
+**Trees** - Hierarchical data (shown as formatted JSON)
+**Primitives** - Simple values displayed directly
+
+### Format System
+
+Photon uses a smart format system with 5 standard types:
+
+1. **`primitive`** - String, number, boolean
+2. **`table`** - Flat object or array of flat objects
+3. **`tree`** - Nested/hierarchical data
+4. **`list`** - Array of simple items
+5. **`none`** - No return value (void operations)
+
+**Hint the format** (optional):
+```typescript
+/**
+ * Get current volume
+ * @format table
+ */
+async volume() {
+  return this._request('ssap://audio/getVolume');
+}
+```
+
+**Auto-detection**: If no `@format` tag is provided, Photon automatically detects the best format based on the return value structure.
+
+### CLI Command Reference
+
+#### `photon cli <photon-name> [method] [args...]`
+
+**List all methods:**
+```bash
+photon cli lg-remote
+```
+
+**Call a method:**
+```bash
+# No parameters
+photon cli lg-remote status
+
+# Single parameter
+photon cli lg-remote volume 50
+
+# Multiple parameters
+photon cli lg-remote search query "breaking bad" limit 10
+
+# Relative adjustments
+photon cli lg-remote volume +5
+photon cli lg-remote channel +1
+```
+
+**Get method help:**
+```bash
+photon cli lg-remote volume --help
+```
+
+**Raw JSON output:**
+```bash
+photon cli lg-remote volume --json
+```
+
+### One Codebase, Multiple Interfaces
+
+The beauty of Photon's design: **improvements to business logic automatically work across all interfaces**.
+
+Write your logic once:
+```typescript
+async volume(params?: { level?: number | string } | number | string) {
+  // Handle relative adjustments
+  if (typeof level === 'string' && level.startsWith('+')) {
+    const delta = parseInt(level);
+    const current = await this._getCurrentVolume();
+    const newVolume = current + delta;
+    await this._setVolume(newVolume);
+  }
+  // ... rest of logic
+  return this._getCurrentVolume(); // Always return current state
+}
+```
+
+**Works everywhere:**
+- ✅ **MCP**: Claude Desktop, Cursor, etc.
+- ✅ **CLI**: `photon cli lg-remote volume +5`
+- ✅ **Future interfaces**: HTTP, WebSocket, etc.
+
+### Context-Aware Error Messages
+
+Photons can provide helpful, context-aware errors:
+
+```bash
+$ photon cli lg-remote channels
+❌ Error: TV channels not available. Currently on HDMI1.
+   Switch to a TV tuner input to access channels.
+```
+
+The same error quality appears in MCP tools—because it's the same code.
+
+### Exit Codes
+
+The CLI properly returns exit codes for automation:
+- **0**: Success
+- **1**: Error (tool execution failed, invalid parameters, etc.)
+
+Perfect for shell scripts and CI/CD:
+```bash
+if photon cli lg-remote volume 50; then
+  echo "Volume set successfully"
+else
+  echo "Failed to set volume"
+  exit 1
+fi
+```
+
+---
+
 ## How Photon Works
 
 ### Convention = Automation
@@ -453,6 +662,55 @@ photon mcp calculator --config
 - `--validate` - Validate configuration without running server
 - `--config` - Show configuration template and exit
 
+#### `photon cli <photon-name> [method] [args...]`
+Run photon methods directly from the command line.
+
+```bash
+# List all available methods
+photon cli calculator
+
+# Call a method with arguments
+photon cli calculator add 5 10
+
+# Get method-specific help
+photon cli calculator add --help
+
+# Output raw JSON instead of formatted output
+photon cli calculator add 5 10 --json
+```
+
+**Arguments:**
+- Arguments are automatically coerced to expected types (string, number, boolean)
+- Strings starting with `+` or `-` are preserved for relative adjustments
+- Arrays and objects can be passed as JSON strings
+
+**Options:**
+- `--help` - Show help for the photon or specific method
+- `--json` - Output raw JSON instead of formatted output
+
+**Exit Codes:**
+- `0` - Success
+- `1` - Error (invalid arguments, execution failure, etc.)
+
+**Examples:**
+
+```bash
+# Smart home control
+photon cli lg-remote volume 50
+photon cli lg-remote volume +5      # Relative adjustment
+photon cli lg-remote channel 7
+photon cli lg-remote app netflix
+
+# Database queries
+photon cli postgres query "SELECT * FROM users LIMIT 10"
+
+# File operations
+photon cli filesystem read-file path "/home/user/document.txt"
+
+# Git operations
+photon cli git commit message "feat: add new feature"
+```
+
 ### Inspect & Configure
 
 #### `photon info [name]`
@@ -901,46 +1159,6 @@ export default class MyPhoton {
 
 ---
 
-## Integration with MCP Clients
-
-Photon works with **any MCP client**:
-
-- **Claude Desktop** (Anthropic)
-- **Cursor** (IDE)
-- **Zed** (IDE)
-- **Continue** (VS Code extension)
-- **Cline** (VS Code extension)
-- ... and more
-
-### Setup
-
-```bash
-# Get configuration for your MCP client
-photon info <photon-name> --mcp
-```
-
-**Consult your MCP client's documentation** for:
-- Config file location
-- Configuration format
-- Setup instructions
-
-Example output:
-```json
-{
-  "analytics": {
-    "command": "photon",
-    "args": ["mcp", "analytics"],
-    "env": {
-      "ANALYTICS_HOST": "localhost",
-      "ANALYTICS_DATABASE": "company",
-      "ANALYTICS_PASSWORD": "secret"
-    }
-  }
-}
-```
-
----
-
 ## Examples
 
 The repository includes example photons in `examples/`:
@@ -1062,18 +1280,59 @@ photon upgrade <name> # Update specific photon
 
 ## Roadmap
 
-### ✅ Version 1.0 - MCP Servers (Available Now)
+### ✅ MCP Servers & CLI Interface (Available Now)
 
+**MCP Servers:**
 Build and run photons as MCP servers for AI assistants. Works with Claude Desktop, Cursor, Zed, Continue, Cline, and any MCP-compatible client.
 
-### 🔮 Future Versions
+**CLI Interface:**
+Run photon methods directly from the command line with beautiful formatted output. Every photon automatically becomes a CLI tool with zero additional code.
 
-Photon's framework-agnostic design enables future deployment targets:
+**Write once, deploy everywhere:** The same business logic powers both your MCP tools and CLI commands.
 
-- **CLI tools** - Run photons as terminal commands
-- **More targets** - Additional deployment options as the ecosystem grows
+### 🔌 Ecosystem Integrations
+
+Photon files are first-class citizens across multiple platforms:
+
+#### NCP - Intelligent MCP Orchestration
+
+[NCP](https://github.com/portel-dev/ncp) runs as an MCP client hosting many MCPs intelligently, while acting as an MCP server for any client. Photon files integrate seamlessly as context providers.
+
+```bash
+# Photons work natively with NCP
+ncp add analytics.photon.ts
+```
+
+NCP enables sophisticated MCP orchestration patterns, and `.photon.ts` files are designed to work seamlessly in this environment.
+
+#### Lumina - Anything API Server *(Coming Soon)*
+
+Turn any photon into a production API endpoint with zero configuration.
+
+```bash
+# Same photon, now an HTTP API
+lumina serve analytics.photon.ts
+# → POST /revenue with JSON params
+# → GET /status
+# → Full REST API from your photon methods
+```
+
+Lumina will make photons available as HTTP/WebSocket endpoints, enabling web apps, mobile clients, and traditional API consumers to use the same business logic.
+
+#### Future Platforms
+
+The `.photon.ts` format is designed to be consumed by any runtime:
+- WebSocket servers
+- Serverless functions (AWS Lambda, Cloudflare Workers)
+- Native desktop applications
+- Browser extensions
+- GraphQL servers
+
+**One file. Many platforms. Pure business logic.**
+
+---
 
-**The vision:** Write focused business logic once. As Photon evolves, deploy it to multiple targets.
+Photon's framework-agnostic design enables future deployment targets. More on the way.
 
 ---
 

package/dist/cli-alias.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI Alias Manager (Cross-Platform)
+ *
+ * Creates executable aliases for photons so they can be called directly
+ * Supports: Windows, macOS, Linux
+ * Example: Instead of `photon cli lg-remote discover`
+ *          Run: `lg-remote discover`
+ */
+/**
+ * Create a CLI alias for a photon (cross-platform)
+ */
+export declare function createAlias(photonName: string, aliasName?: string): Promise<void>;
+/**
+ * Remove a CLI alias (cross-platform)
+ */
+export declare function removeAlias(aliasName: string): Promise<void>;
+/**
+ * List all CLI aliases (cross-platform)
+ */
+export declare function listAliases(): Promise<void>;
+//# sourceMappingURL=cli-alias.d.ts.map

package/dist/cli-alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-alias.d.ts","sourceRoot":"","sources":["../src/cli-alias.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH;;GAEG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCvF;AAoFD;;GAEG;AACH,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBlE;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAqDjD"}