@fnet/cli 1.12.1 → 1.14.1

package/readme.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <b>Focus on functional code, let Flownet handle the rest</b>
+  <b>Give developers primitives. Trust them to compose. Make the tooling excellent.</b>
 </p>
 
 <p align="center">
@@ -14,285 +14,334 @@
   <a href="https://github.com/fnetai/cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/fnetai/cli.svg" alt="license"></a>
 </p>
 
-## Overview
+---
 
-Flownet is a low-level flow framework that separates **Core** (your business logic) from **Layers** (infrastructure, dev, build, runtime, and delivery). This separation allows developers to focus on functional code while Flownet automates the surrounding infrastructure. The `@fnet/cli` package provides command-line tools to create, build, and manage Flownet projects.
+## Why Flownet?
 
-Flownet provides primitives for composing workflows similar to how React provides components for UI development. It emphasizes a **schema-first approach** with **deterministic core**, enabling **multi-runtime portability**.
+Most developers spend the majority of their time on things that aren't their actual problem: build configuration, bundling, runtime wiring, deployment pipelines, service setup. The ratio of "infrastructure work" to "actual logic" is often 80/20 in the wrong direction.
 
-### Key Features
+Flownet exists to flip that ratio. It separates what you write (**Core**) from what surrounds it (**Layers**), then automates the Layers so you can focus on the Core.
 
-- **Core vs Layers Architecture**: Separate your business logic (Core) from infrastructure (Layers) for cleaner, more maintainable code
-- **Nodes & Flows**: Reusable functional units (Nodes) with explicit I/O schemas, orchestrated by Flows
-- **I/O Contracts**: Schema-first contracts define clear input/output expectations for deterministic behavior
-- **Automatic Dependency Detection**: Simplified dependency management across your project
-- **Multi-Runtime Support**: Deploy to Node.js, Bun, Deno, or Python - choose the best runtime for each task
-- **Language Agnostic**: Support for multiple programming languages (JavaScript, Python) in the same project
-- **Unified Interface**: Consistent commands across different project types
-- **Tag-Based Configuration**: Powerful conditional configuration with `--ftag` parameter
-- **Isolated Workspace**: All build artifacts and dependencies are kept in `.workspace` directory
-- **Binary System**: Compile, install, and manage CLI tools with the integrated binary system
-- **Project File Configuration**: Configure CLI features directly in your project files
-- **Fast Startup**: Pre-compiled binaries start much faster than interpreted scripts
+- **Core**: Your functional, minimal, deterministic logic and its I/O contracts
+- **Layers**: Dev experience, build pipelines, runtime wiring, delivery/packaging
 
-## Installation
+You write the Core. Flownet generates, manages, and updates the Layers automatically. Update all Layer infrastructure across every project by updating the CLI.
 
-```bash
-# Using npm
-npm install -g @fnet/cli
+| Project Type | Core (you write)  | Layers (Flownet handles)        |
+| ------------ | ----------------- | ------------------------------- |
+| CLI          | Command logic     | Binary + PATH/runtime + publish |
+| App          | UI/flows          | Bundling + hosting/CDN + deploy |
+| Component    | API/behavior      | ESM/CJS/types + publish         |
 
-# Using yarn
-yarn global add @fnet/cli
+This is the same philosophy that made React successful for UI: provide primitives, trust developers to compose, make the tooling excellent. Flownet applies it to the entire development lifecycle.
 
-# Using bun
-bun install -g @fnet/cli
+## What You Get
+
+```text
+@fnet/cli (npm package)
+    |
+    |- fnode ---------> Node/Classic Projects (fnode.yaml)
+    |                   Create, build, deploy reusable Nodes
+    |
+    |- fnet ----------> Workflow Projects (fnet.yaml)
+    |                   Create, build, deploy Flows
+    |
+    |- frun ----------> Unified Command Runner
+    |                   Auto-detect project type, run command groups
+    |                   Powered by @fnet/shell-flow
+    |
+    |- fbin ----------> Binary Management
+    |                   Compile JS to native binaries
+    |                   Install to ~/.fnet/bin/
+    |
+    '- fservice ------> Service Management
+                        Cross-platform system services
+                        (systemd, launchd, Windows Services)
 ```
 
-## Quick Start
+Five CLI tools that work together to cover the full development lifecycle: create, develop, build, distribute, and run as a service.
+
+## Installation
 
-### Create a New Project
+### Homebrew (recommended, macOS/Linux)
 
 ```bash
-# Create a Node.js project
-fnode create my-node-project
+brew tap fnetai/tap
+brew install fnet
+```
 
-# Create a Python project
-fnode create my-python-project --runtime python
+Installs all 5 CLI tools (`frun`, `fbin`, `fservice`, `fnode`, `fnet`) as native binaries plus templates. No Node.js or npm required.
 
-# Create a Bun project
-fnode create my-bun-project --runtime bun
+### npm
 
-# Create a workflow project
-fnet create my-workflow-project
+```bash
+npm install -g @fnet/cli
 ```
 
-### Build and Run
+On first install, pre-compiled native binaries (`frun`, `fbin`, `fservice`) are downloaded for your platform. If the download fails, the JavaScript versions work as a fallback.
 
-```bash
-# Build the project
-frun build
-
-# Run the project
-fnode cli
+## Core Concepts
 
-# Execute a command group from project file
-frun <command-group> [--ftag <tags>]
-```
+### Nodes & Flows
 
-### Compile and Install
+**Nodes** are reusable functional units with explicit input/output schemas. Each Node has a deterministic, pure function at its core with clear I/O contracts. Think of them as the building blocks.
 
-```bash
-# Compile a JavaScript file to a binary
-fbin compile script.js -o my-tool
+**Flows** orchestrate Nodes and sub-Flows into workflows. They define how capabilities connect, transform, and execute - composition and control flow over the primitives that Nodes provide.
 
-# Install a compiled binary
-fbin install ./my-tool --name awesome-tool
+|             | fnode Project                   | fnet Project          |
+| ----------- | ------------------------------- | --------------------- |
+| Config file | `fnode.yaml`                    | `fnet.yaml`           |
+| Purpose     | Reusable Nodes, standalone apps | Workflow orchestration |
+| CLI         | `fnode`                         | `fnet`                |
+| Runtimes    | Node.js, Bun, Python            | Node.js, Bun          |
 
-# Install a CLI-enabled project
-cd my-project
-fnode install --yes
+### Schema-First & Multi-Runtime
 
-# Or use npm scripts in your project
-npm run compile
-npm run install-bin
+Flownet uses schema-first contracts (I/O schemas) to define clear expectations. This enables:
 
-# List installed binaries
-fbin list
+- **Multi-runtime portability**: Same Core logic deploys to Node.js, Bun, or Python
+- **Deterministic behavior**: Clear contracts across different runtimes
+- **Automatic validation**: Schemas drive type checking and validation
 
-# Uninstall a binary
-fbin uninstall awesome-tool --yes
+```text
+my-project/
+|- src/
+|  |- index.js          # JavaScript (Node.js / Bun)
+|  '- index.py          # Python
+|- fnode.yaml
+'- .workspace/           # Layers (managed by CLI, not your concern)
 ```
 
-## Core Concepts
+### Documentation That Never Lies
 
-### Nodes & Flows
+Flownet automatically generates BPMN 2.0 (Business Process Model and Notation) diagrams from your Flow definitions on every build. Your YAML is the single source of truth - diagrams are derived, never hand-maintained.
 
-**Nodes** are reusable functional units that encapsulate business logic with explicit input/output schemas. Each Node:
+- **Developers** read YAML (code-like, version controlled)
+- **Stakeholders** view BPMN (visual, business-friendly)
+- **Tools** analyze BPMN (process mining, compliance)
 
-- Has a deterministic, pure function at its core
-- Defines clear I/O contracts (input and output schemas)
-- Can be composed and reused across different Flows
-- Supports automatic dependency detection
+This solves the eternal problem of documentation going stale. With Flownet, it can't - diagrams regenerate on every `fnet build`.
 
-**Flows** orchestrate Nodes and sub-Flows to create complex workflows. Flows:
+### AI-Native: MCP Integration
 
-- Connect multiple Nodes with explicit data contracts
-- Enable multi-runtime portability through schema-first design
-- Support complex data transformations and conditional logic
-- Maintain deterministic behavior across different runtimes
+Every Flownet project can be exposed as an AI-compatible tool server via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Both `fnode` and `fnet` projects support MCP mode with STDIO and HTTP transports:
 
-### I/O Contracts
+```bash
+# Expose as MCP tool for Claude Desktop or any AI assistant
+fnode cli --cli-mode mcp
 
-Flownet uses schema-first contracts to define clear input and output expectations. This approach:
+# Or over HTTP for remote AI integrations
+fnet cli --cli-mode mcp --mcp-transport http --cli-port 3003
+```
 
-- Ensures deterministic behavior across different runtimes
-- Enables automatic validation and type checking
-- Facilitates multi-runtime portability
-- Improves code clarity and maintainability
+This means any Flownet project - a data processor, a CLI tool, a workflow - can become a tool that AI assistants discover, understand, and invoke. It's not a bolt-on feature; it's a first-class runtime mode alongside CLI, HTTP, WebSocket, and Pipeline modes.
 
-## Project Types
+## Quick Start
 
-Flownet supports two main project types:
+### Create a Project
 
-### fnode Project
+```bash
+# Node.js project (default runtime)
+fnode create --name my-project
 
-An **fnode project** (Flow Node Project) is a classic/node-style project that focuses on creating reusable Nodes or standalone applications. These projects:
+# Python project
+fnode create --name my-project --runtime python
 
-- Use `fnode.yaml` as their configuration file
-- Typically contain a single code file in the `src` directory
-- Can be built with different runtimes (Node.js, Python, Bun)
-- Support multiple programming languages simultaneously
-- Ideal for creating reusable components with explicit I/O contracts
+# Bun project
+fnode create --name my-project --runtime bun
 
-### fnet Project
+# Workflow project
+fnet create --name my-workflow
+```
 
-An **fnet project** (Flow Project) is a workflow-oriented project that focuses on orchestrating multiple Nodes and Flows. These projects:
+### Quick Test Projects
 
-- Use `fnet.yaml` as their configuration file
-- Define workflows that connect multiple Nodes and sub-Flows
-- Support complex data flows and transformations
-- Enable multi-runtime deployment strategies
-- Ideal for building complex business logic orchestrations
+Rapid prototyping without thinking about names:
 
-## CLI Tools
+```bash
+fnode express --yes  # Creates fnode-1, fnode-2, fnode-3...
+fnet express --yes   # Creates fnet-1, fnet-2, fnet-3...
+```
 
-Flownet provides five main CLI tools:
+### Build and Run
 
-- **`fnode`**: For Node/classic projects (uses `fnode.yaml`) - create and manage reusable Nodes
-- **`fnet`**: For Workflow projects (uses `fnet.yaml`) - create and manage Flows that orchestrate Nodes
-- **`frun`**: Unified interface that works with both project types (auto-detects project file)
-- **`fbin`**: Binary management system for installing, compiling, and managing CLI tools
-- **`fservice`**: Service management for deploying and running Flownet applications
+```bash
+frun build                          # Run 'build' command group
+fnode cli                           # Run as CLI
+frun <command-group> [--ftag <tags>] # Execute command group with tags
+frun list                           # List available command groups
+```
 
-## Multi-Language & Multi-Runtime Support
+## CLI Tools
 
-Flownet supports multiple programming languages and runtimes simultaneously within the same project:
+### fnode - Node/Classic Projects
 
-```text
-my-project/
-├── src/
-│   ├── index.js          # JavaScript implementation (used by Node.js and Bun)
-│   └── index.py          # Python implementation
-├── fnode.yaml            # Project configuration file
-└── .workspace/           # Build infrastructure (managed by CLI)
+```bash
+fnode create --name my-project       # Create a new project
+fnode build                          # Build the project
+fnode cli                            # Run as CLI
+fnode cli --cli-mode http            # Run as HTTP server
+fnode compile                        # Compile to binary
+fnode install                        # Install compiled binary
 ```
 
-### Supported Runtimes
+**Passthrough commands** execute tools in the project's `.workspace` context:
 
-- **Node.js**: JavaScript/TypeScript execution with full npm ecosystem support
-- **Bun**: Fast JavaScript runtime with improved performance
-- **Deno**: Secure JavaScript/TypeScript runtime with built-in tooling
-- **Python**: Python 3.x for data processing and scientific computing
+```bash
+fnode npm install lodash             # npm in workspace
+fnode node script.js                 # node in workspace
+fnode bun run dev                    # bun in workspace
+fnode python script.py               # python in workspace
+fnode cdk deploy                     # AWS CDK in workspace
+fnode aws s3 ls                      # AWS CLI in workspace
+```
 
-### Multi-Runtime Portability
+**Runtime modes** - one project, multiple deployment targets:
 
-Thanks to Flownet's schema-first approach and deterministic core:
+| Mode      | Command                          | Use case                          |
+| --------- | -------------------------------- | --------------------------------- |
+| CLI       | `fnode cli`                      | Terminal executable               |
+| HTTP      | `fnode cli --cli-mode http`      | REST API server                   |
+| WebSocket | `fnode cli --cli-mode websocket` | Real-time bidirectional           |
+| Pipeline  | `echo data \| fnode cli`         | Unix-style stdin/stdout streaming |
+| MCP       | `fnode cli --cli-mode mcp`       | AI-compatible tool server         |
 
-- Write your core logic once and deploy to multiple runtimes
-- Choose the best runtime for each specific use case
-- Migrate between runtimes without changing your business logic
-- Use JavaScript with Node.js for quick development, Python for data processing, and Bun for improved performance
+### fnet - Workflow Projects
 
-## Tag-Based Configuration
+```bash
+fnet create --name my-workflow       # Create a workflow project
+fnet build                           # Build (+ auto-generate BPMN)
+fnet npm install                     # npm in workspace
+fnet cdk deploy                      # AWS CDK in workspace
+```
 
-Both CLI tools support the `--ftag` parameter for powerful conditional configuration:
+### frun - Unified Command Runner
+
+Auto-detects project type and runs command groups. Powered by [`@fnet/shell-flow`](https://www.npmjs.com/package/@fnet/shell-flow).
 
 ```bash
-frun build --ftag dev --ftag local
+frun build                           # Run 'build' command group
+frun deploy                          # Run 'deploy' command group
+frun dev --ftag local                # Run with tags
+frun list                            # List available command groups
 ```
 
-This activates sections in your project file marked with `t::dev::` or `t::local::` tags:
+Define command groups in your project YAML:
 
 ```yaml
-# Base configuration
-name: my-project
+commands:
+  build:
+    usage: frun build
+    description: Build the project
+    steps:
+      - npm install
+      - npm run build
+
+  test:
+    usage: frun test
+    description: Run all tests
+    parallel:
+      - npm run test:unit
+      - npm run test:integration
+
+  dev:
+    usage: frun dev
+    description: Start dev servers
+    fork:
+      - npm run watch:css
+      - npm run watch:js
+      - npm run dev-server
+```
 
-# Development environment configuration
-t::dev::database:
-  url: "mongodb://localhost:27017"
+The `commands:` section is `@fnet/shell-flow` input schema in YAML format. This gives you sequential execution, parallel execution, background processes, environment variables, template variables (`{{var}}`), output capture, retry with exponential backoff, timeouts, and a full set of expression builtins (`json::`, `http::`, `file::`, `txt::`, `encode::`, `hash::`, `time::`, `capture::`, `pause::`, and more).
 
-# Production environment configuration
-t::prod::database:
-  url: "mongodb://production-server:27017"
-```
+### fbin - Binary Management
 
-## Binary System
+Compile JavaScript to native binaries and manage installations:
 
-Flownet includes a powerful binary system that makes it easy to create, distribute, and manage CLI tools:
+```bash
+fbin setup                           # Initialize the bin system
+fbin path                            # Add ~/.fnet/bin to PATH
+fbin compile script.js -o my-tool    # Compile JS to binary
+fbin install ./my-tool --name app    # Install a binary
+fbin list                            # List installed binaries
+fbin uninstall app --yes             # Remove a binary
+fbin backup                          # Backup binaries and shell config
+fbin restore                         # Restore from backup
+```
 
-### Binary System Features
+Pre-compiled binaries for all platforms are built via GitHub Actions and distributed through GitHub Releases.
 
-- **Fast Startup**: Pre-compiled binaries start much faster than interpreted scripts
-- **Cross-Platform Support**: Works on macOS, Linux, and Windows
-- **Multiple Shell Support**: Compatible with Bash, Zsh, Fish, PowerShell, and more
-- **Version Management**: Keeps track of binary versions and metadata
-- **Project Integration**: Easily compile and install CLI-enabled projects
-- **Automation Support**: All commands support the `--yes` flag for scripting
+### fservice - Service Management
 
-### Setup and Usage
+Deploy projects as system services across platforms:
 
 ```bash
-# Initialize the bin system
-fbin setup
-
-# Add bin directory to PATH
-fbin path
+fservice manifest create             # Create a service definition
+fservice register -d my-api          # Register with OS service manager
+fservice start my-api                # Start service
+fservice stop my-api                 # Stop service
+fservice restart my-api              # Restart service
+fservice status my-api               # Check status
+fservice list                        # List all services
+fservice unregister my-api           # Remove service
+```
 
-# Compile a JavaScript file to a binary
-fbin compile script.js -o my-tool
+**Supported platforms**: macOS (launchd), Linux (systemd), Windows (Windows Services)
 
-# Install a binary to the bin directory
-fbin install ./my-tool --name awesome-tool
+## Tag-Based Configuration
 
-# List installed binaries
-fbin list
+The `--ftag` parameter enables conditional configuration from a single project file:
 
-# Uninstall a binary
-fbin uninstall awesome-tool
+```bash
+frun build --ftag dev --ftag local
 ```
 
-### Project Integration
-
-The binary system integrates seamlessly with Flownet projects:
+```yaml
+name: my-project
 
-```bash
-# Compile and install a CLI-enabled fnode project
-fnode compile
-fnode install
+database:
+  port: 5432
 
-# Compile and install a CLI-enabled fnet project
-fnet compile
-fnet install
+t::dev::database:
+  url: "mongodb://localhost:27017"
 
-# Using npm scripts in your project
-npm run compile
-npm run install-bin
+t::prod::database:
+  url: "mongodb://production-server:27017"
 ```
 
-This makes it easy to distribute your Flownet projects as standalone CLI tools.
+One file, multiple environments. Tags enable environment-specific commands, feature flags, and platform-specific configurations.
 
-### CLI Configuration in Project Files
+## Project Structure
 
-You can configure CLI features directly in your project files:
+```text
+my-project/
+|- src/                  # Core - your code
+|- fnode.yaml            # or fnet.yaml - project configuration
+|- .workspace/           # Layers - managed by CLI
+'- .fnet/                # Local configuration
+```
 
-```yaml
-# In fnode.yaml or fnet.yaml
-name: my-project
+**Global directories**:
 
-features:
-  # For fnode projects
-  s::runtime.type: node  # or python, bun
+- `~/.fnet/bin/` - Installed binaries
+- `~/.fnet/services/` - Service definitions
 
-  # CLI configuration
-  cli:
-    enabled: true
-    bin: custom-bin-name  # Name of the binary (defaults to project name)
-    installable: true     # Enable 'fnode install' or 'fnet install' command
-```
+## Comparison
+
+| Aspect         | Traditional Workflow Engines | Flownet                           |
+| -------------- | ---------------------------- | --------------------------------- |
+| Syntax         | Proprietary DSL              | YAML + JavaScript                 |
+| Development    | Special IDE required         | Any IDE (VS Code, etc.)           |
+| Debugging      | Limited or proprietary       | Standard (Chrome DevTools)        |
+| Testing        | Proprietary tools            | Standard test frameworks          |
+| Visualization  | Manual diagram creation      | Auto-generated BPMN               |
+| Runtime        | Vendor-specific              | Multi-runtime (Node/Bun/Python)   |
+| Learning Curve | Steep (new DSL + tools)      | Gentle (YAML + JavaScript)        |
+| Flexibility    | Opinionated, limited         | Primitives, compose freely        |
+| Ecosystem      | Vendor packages              | npm ecosystem                     |
+| AI Integration | Separate system              | Built-in MCP mode                 |
 
-This configuration will:
+## License
 
-1. Enable CLI functionality for your project
-2. Set the binary name to `custom-bin-name`
-3. Add `compile` and `install-bin` scripts to your package.json
-4. Allow you to install the binary with `fnode install` or `npm run install-bin`
+MIT

package/scripts/postinstall.js

@@ -10,14 +10,18 @@
  * The JS-based CLI commands will still work as fallback.
  */
 
-import { createWriteStream, mkdirSync, chmodSync, existsSync, unlinkSync } from 'fs';
-import { join } from 'path';
+import { createWriteStream, mkdirSync, chmodSync, existsSync, unlinkSync, cpSync } from 'fs';
+import { join, dirname } from 'path';
 import { homedir, platform, arch } from 'os';
 import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO = 'fnetai/cli';
-const BINARIES = ['frun', 'fbin', 'fservice'];
+const BINARIES = ['frun', 'fbin', 'fservice', 'fnode', 'fnet'];
 const INSTALL_DIR = join(homedir(), '.fnet', 'bin');
+const TEMPLATE_SRC = join(__dirname, '..', 'template');
+const TEMPLATE_DEST = join(homedir(), '.fnet', 'template');
 
 function getPlatform() {
   const p = platform();
@@ -125,8 +129,19 @@ async function main() {
     }
   }
 
+  // Copy templates to ~/.fnet/template/
+  try {
+    if (existsSync(TEMPLATE_SRC)) {
+      cpSync(TEMPLATE_SRC, TEMPLATE_DEST, { recursive: true, force: true });
+      console.log(`    ✓ templates`);
+      installed++;
+    }
+  } catch {
+    // Fail silently
+  }
+
   if (installed > 0) {
-    console.log(`\n  ${installed} binary installed to ${INSTALL_DIR}`);
+    console.log(`\n  ${installed} items installed to ~/.fnet/`);
 
     // Check PATH
     const pathDirs = (process.env.PATH || '').split(':');