Merge remote-tracking branch 'origin/main' into mcp

Author: jahvon

.execs/build.flow

@@ -80,7 +80,7 @@ executables:
         else
           echo "npm dependencies already installed"
         fi
-        npm run generate-types
+        npm run generate-ts
 
   - verb: generate
     name: backend

.execs/desktop.flow

@@ -1,2 +1,3 @@
 # yaml-language-server: $schema=https://flowexec.io/schemas/flowfile_schema.json
+namespace: desktop
 imports: ["../desktop/package.json"]

.execs/setup.flow

@@ -18,14 +18,6 @@ executables:
       dir: //
       cmd: go install ./...
 
-  - verb: install
-    name: npm
-    aliases: [node, modules]
-    tags: [npm, desktop]
-    exec:
-      dir: //desktop
-      cmd: npm install
-
   - verb: start
     name: site
     aliases: [docs]

.execs/test.flow

@@ -2,7 +2,6 @@
 tags: [development, test]
 executables:
   - verb: test
-    name: all
     description: Run all Go tests (unit + e2e) in parallel
     parallel:
       failFast: false

.execs/validate.flow

@@ -6,8 +6,8 @@ executables:
     serial:
       execs:
         - ref: generate
-        - ref: lint go
-        - ref: test all
+        - ref: lint
+        - ref: test
         - ref: validate generated
         - cmd: echo "✅ All development checks passed"
 
@@ -17,6 +17,11 @@ executables:
     exec:
       dir: //
       cmd: |
+        if [ "$CI" = "" ]; then
+          echo "Skipping diff validation"
+          exit 0
+        fi
+        
         echo "Checking for uncommitted generated files..."
 
         if [ -n "$(git status --porcelain)" ]; then
@@ -30,6 +35,11 @@ executables:
           echo "✅ All generated files are up to date"
         fi
 
+  - verb: lint
+    parallel:
+      execs:
+        - ref: lint go
+
   - verb: lint
     name: go
     aliases: [cli]

.gitignore

@@ -23,6 +23,8 @@ executable_output.txt
 # IDE
 .idea
 
+.claude/*
+
 # build files
 .bin
 flow

CLAUDE.md

@@ -0,0 +1,108 @@
+# flow repo LLM Context
+
+## Project Overview
+
+**flow** is a workflow automation hub that helps with organizing automation across multiple projects (workspaces) with built-in secrets, templates, and cross-workspace composition. Users define workflows in YAML flow files, discover them visually, and run them anywhere.
+
+This is the main repository for the flow CLI tool and desktop application, written in Go with additional desktop components in Rust/React/TypeScript.
+
+## Repository Structure
+
+```
+flow/
+├── cmd/                # CLI entry point and command handlers
+├── internal/           # Core application logic
+│   ├── cache/          # Executable and workspace caching logic  
+│   ├── context/        # Global application context
+│   ├── io/             # Terminal user interface and I/O
+│   ├── runner/         # Executable execution engine
+│   ├── services/       # Business logic services
+│   ├── templates/      # Templating system for workflows
+│   └── vault/          # Secret management
+├── types/              # Generated Go types from YAML schemas
+├── tests/              # CLI end-to-end test suite
+├── docs/               # Documentation (hosted at flowexec.io)
+├── desktop/            # Desktop application (Tauri + React + TypeScript)
+│   ├── src/            # React frontend code
+│   ├── src-tauri/      # Rust backend code
+│   └── scripts/        # Build and type generation scripts
+└── tools/              # Code generation and build tools
+```
+
+## Key Technologies & Frameworks
+
+### Go CLI Application
+- **Language**: Go 1.24+ (see go.mod:3)
+- **CLI Framework**: Cobra (github.com/spf13/cobra)
+- **TUI Framework**: Custom tuikit (github.com/flowexec/tuikit) based on github.com/charmbracelet/bubbletea 
+- **Testing**: Ginkgo BDD framework (github.com/onsi/ginkgo/v2)
+
+### Desktop Application  
+- **Frontend**: React 18 with TypeScript
+- **UI Library**: Mantine v8 (@mantine/core)
+- **Backend**: Rust with Tauri v2
+- **Build Tool**: Vite
+- **Testing**: Vitest with Storybook for component development
+
+## Development Workflow
+
+The project uses **flow itself** for development automation. Key commands:
+
+```bash
+# Build the CLI binary
+flow build binary ./bin/flow
+
+# Run all validation (tests, linting, code generation)
+flow validate
+
+# Run specific checks
+flow test                 # All tests
+flow generate             # Code generation  
+flow lint                 # Linting only
+flow install tools        # Install/update Go tools
+```
+
+These "executables" are defined in the flow files in the `.execs` directory.
+
+## Go Testing Strategy
+
+- **Go Tests**: Uses Ginkgo BDD framework for both unit and e2e tests
+- **Location**: Unit tests in `internal/*_test.go`, e2e tests in `tests/`
+- **Run Command**: `flow test` or standard `go test`
+- **Focusing test**: `FDescribe`, `FIt`, `FEntry`, etc. should be used temporarily to filter when troubleshooting / writing tests
+
+## Code Generation
+
+The project heavily uses code generation:
+
+1. **Go Types**: Generated from YAML schemas in `types/*/schema.yaml` using go-jsonschema
+2. **Documentation**: CLI and type docs auto-generated from the go schema definitions
+3. **TypeScript and Rust Types**: Generated for desktop app from JSON schemas that docgen creates
+
+**Important**: Always edit schema files, not generated code!
+
+## Configuration Files
+
+- **flow.yaml**: Workspace configuration for the flow repo itself
+- **go.mod**: Go dependencies and version (Go 1.24+)
+- **desktop/package.json**: Node.js dependencies for desktop app
+- **desktop/src-tauri/tauri.conf.json**: Tauri desktop app configuration
+- **.execs/**: flow development workflows (executables)
+
+## Development Setup
+
+1. **Prerequisites**: Go 1.24+, flow CLI installed
+2. **Setup**: `flow workspace add flow . --set`
+3. **Dependencies**: `flow install tools`
+4. **Verification**: `flow validate`
+
+## Important Context for Claude Code Sessions
+
+- **Testing**: Always use `flow test` or `go test` - Ginkgo is the testing framework
+- **Linting**: Use `flow lint` for Go linting
+- **Code Gen**: Run `flow generate` after schema changes
+- **Desktop**: The `desktop/` directory is a separate Tauri/React app
+  - Use `flow build desktop` to build the Tauri app
+  - Code should be written in a way that would enable easy testing in the future
+- **Documentation**: Lives in `docs/` and is hosted at flowexec.io
+- **Build**: Use `flow build binary ./bin/flow` for development CLI builds

cmd/internal/browse.go

@@ -12,6 +12,7 @@ import (
 	"github.com/flowexec/flow/internal/io"
 	execIO "github.com/flowexec/flow/internal/io/executable"
 	"github.com/flowexec/flow/internal/io/library"
+	"github.com/flowexec/flow/internal/logger"
 	"github.com/flowexec/flow/types/executable"
 )
 
@@ -32,7 +33,7 @@ func RegisterBrowseCmd(ctx *context.Context, rootCmd *cobra.Command) {
 			),
 		Args: cobra.MaximumNArgs(2),
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-			execList, err := ctx.ExecutableCache.GetExecutableList(ctx.Logger)
+			execList, err := ctx.ExecutableCache.GetExecutableList()
 			if err != nil {
 				return nil, cobra.ShellCompDirectiveError
 			}
@@ -63,7 +64,7 @@ func browseFunc(ctx *context.Context, cmd *cobra.Command, args []string) {
 		return
 	}
 
-	listMode := flags.ValueFor[bool](ctx, cmd, *flags.ListFlag, false)
+	listMode := flags.ValueFor[bool](cmd, *flags.ListFlag, false)
 	if listMode || !TUIEnabled(ctx, cmd) {
 		listExecutables(ctx, cmd, args)
 		return
@@ -73,42 +74,41 @@ func browseFunc(ctx *context.Context, cmd *cobra.Command, args []string) {
 }
 
 func executableLibrary(ctx *context.Context, cmd *cobra.Command, _ []string) {
-	logger := ctx.Logger
 	if !TUIEnabled(ctx, cmd) {
-		logger.FatalErr(errors.New("interactive discovery requires an interactive terminal"))
+		logger.Log().FatalErr(errors.New("interactive discovery requires an interactive terminal"))
 	}
 
-	wsFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterWorkspaceFlag, false)
+	wsFilter := flags.ValueFor[string](cmd, *flags.FilterWorkspaceFlag, false)
 	switch wsFilter {
 	case ".":
 		wsFilter = ctx.Config.CurrentWorkspace
 	case executable.WildcardWorkspace:
 		wsFilter = ""
 	}
 
-	nsFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterNamespaceFlag, false)
-	allNs := flags.ValueFor[bool](ctx, cmd, *flags.AllNamespacesFlag, false)
+	nsFilter := flags.ValueFor[string](cmd, *flags.FilterNamespaceFlag, false)
+	allNs := flags.ValueFor[bool](cmd, *flags.AllNamespacesFlag, false)
 	switch {
 	case allNs && nsFilter != "":
-		logger.PlainTextWarn("cannot use both --all and --namespace flags, ignoring --namespace")
+		logger.Log().PlainTextWarn("cannot use both --all and --namespace flags, ignoring --namespace")
 		fallthrough
 	case allNs:
 		nsFilter = executable.WildcardNamespace
 	case nsFilter == ".":
 		nsFilter = ctx.Config.CurrentNamespace
 	}
 
-	verbFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterVerbFlag, false)
-	tagsFilter := flags.ValueFor[[]string](ctx, cmd, *flags.FilterTagFlag, false)
-	subStr := flags.ValueFor[string](ctx, cmd, *flags.FilterExecSubstringFlag, false)
+	verbFilter := flags.ValueFor[string](cmd, *flags.FilterVerbFlag, false)
+	tagsFilter := flags.ValueFor[[]string](cmd, *flags.FilterTagFlag, false)
+	subStr := flags.ValueFor[string](cmd, *flags.FilterExecSubstringFlag, false)
 
-	allExecs, err := ctx.ExecutableCache.GetExecutableList(logger)
+	allExecs, err := ctx.ExecutableCache.GetExecutableList()
 	if err != nil {
-		logger.FatalErr(err)
+		logger.Log().FatalErr(err)
 	}
-	allWs, err := ctx.WorkspacesCache.GetWorkspaceConfigList(logger)
+	allWs, err := ctx.WorkspacesCache.GetWorkspaceConfigList()
 	if err != nil {
-		logger.FatalErr(err)
+		logger.Log().FatalErr(err)
 	}
 
 	runFunc := func(ref string) error { return runByRef(ctx, cmd, ref) }
@@ -128,32 +128,31 @@ func executableLibrary(ctx *context.Context, cmd *cobra.Command, _ []string) {
 }
 
 func listExecutables(ctx *context.Context, cmd *cobra.Command, _ []string) {
-	logger := ctx.Logger
-	wsFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterWorkspaceFlag, false)
+	wsFilter := flags.ValueFor[string](cmd, *flags.FilterWorkspaceFlag, false)
 	if wsFilter == "." {
 		wsFilter = ctx.Config.CurrentWorkspace
 	}
 
-	nsFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterNamespaceFlag, false)
-	allNs := flags.ValueFor[bool](ctx, cmd, *flags.AllNamespacesFlag, false)
+	nsFilter := flags.ValueFor[string](cmd, *flags.FilterNamespaceFlag, false)
+	allNs := flags.ValueFor[bool](cmd, *flags.AllNamespacesFlag, false)
 	switch {
 	case allNs && nsFilter != "":
-		logger.PlainTextWarn("cannot use both --all and --namespace flags, ignoring --namespace")
+		logger.Log().PlainTextWarn("cannot use both --all and --namespace flags, ignoring --namespace")
 		fallthrough
 	case allNs:
 		nsFilter = executable.WildcardNamespace
 	case nsFilter == ".":
 		nsFilter = ctx.Config.CurrentNamespace
 	}
 
-	verbFilter := flags.ValueFor[string](ctx, cmd, *flags.FilterVerbFlag, false)
-	tagsFilter := flags.ValueFor[[]string](ctx, cmd, *flags.FilterTagFlag, false)
-	outputFormat := flags.ValueFor[string](ctx, cmd, *flags.OutputFormatFlag, false)
-	substr := flags.ValueFor[string](ctx, cmd, *flags.FilterExecSubstringFlag, false)
+	verbFilter := flags.ValueFor[string](cmd, *flags.FilterVerbFlag, false)
+	tagsFilter := flags.ValueFor[[]string](cmd, *flags.FilterTagFlag, false)
+	outputFormat := flags.ValueFor[string](cmd, *flags.OutputFormatFlag, false)
+	substr := flags.ValueFor[string](cmd, *flags.FilterExecSubstringFlag, false)
 
-	allExecs, err := ctx.ExecutableCache.GetExecutableList(logger)
+	allExecs, err := ctx.ExecutableCache.GetExecutableList()
 	if err != nil {
-		logger.FatalErr(err)
+		logger.Log().FatalErr(err)
 	}
 	filteredExec := allExecs
 	filteredExec = filteredExec.
@@ -168,17 +167,15 @@ func listExecutables(ctx *context.Context, cmd *cobra.Command, _ []string) {
 		view := execIO.NewExecutableListView(ctx, filteredExec, runFunc)
 		SetView(ctx, cmd, view)
 	} else {
-		execIO.PrintExecutableList(logger, outputFormat, filteredExec)
+		execIO.PrintExecutableList(outputFormat, filteredExec)
 	}
 }
 
 func viewExecutable(ctx *context.Context, cmd *cobra.Command, args []string) {
-	logger := ctx.Logger
-
 	verbStr := args[0]
 	verb := executable.Verb(verbStr)
 	if err := verb.Validate(); err != nil {
-		logger.FatalErr(err)
+		logger.Log().FatalErr(err)
 	}
 
 	var execID string
@@ -195,26 +192,26 @@ func viewExecutable(ctx *context.Context, cmd *cobra.Command, args []string) {
 	}
 	ref := executable.NewRef(execID, verb)
 
-	exec, err := ctx.ExecutableCache.GetExecutableByRef(logger, ref)
+	exec, err := ctx.ExecutableCache.GetExecutableByRef(ref)
 	if err != nil && errors.Is(cache.NewExecutableNotFoundError(ref.String()), err) {
-		logger.Debugf("Executable %s not found in cache, syncing cache", ref)
-		if err := ctx.ExecutableCache.Update(logger); err != nil {
-			logger.FatalErr(err)
+		logger.Log().Debugf("Executable %s not found in cache, syncing cache", ref)
+		if err := ctx.ExecutableCache.Update(); err != nil {
+			logger.Log().FatalErr(err)
 		}
-		exec, err = ctx.ExecutableCache.GetExecutableByRef(logger, ref)
+		exec, err = ctx.ExecutableCache.GetExecutableByRef(ref)
 	}
 	if err != nil {
-		logger.FatalErr(err)
+		logger.Log().FatalErr(err)
 	} else if exec == nil {
-		logger.Fatalf("executable %s not found", ref)
+		logger.Log().Fatalf("executable %s not found", ref)
 	}
 
-	outputFormat := flags.ValueFor[string](ctx, cmd, *flags.OutputFormatFlag, false)
+	outputFormat := flags.ValueFor[string](cmd, *flags.OutputFormatFlag, false)
 	if TUIEnabled(ctx, cmd) {
 		runFunc := func(ref string) error { return runByRef(ctx, cmd, ref) }
 		view := execIO.NewExecutableView(ctx, exec, runFunc)
 		SetView(ctx, cmd, view)
 	} else {
-		execIO.PrintExecutable(logger, outputFormat, exec)
+		execIO.PrintExecutable(outputFormat, exec)
 	}
 }