Metadata-Version: 2.4
Name: lambdazen-local
Version: 0.2.3
Summary: LambdaZen Local — sync tool for LambdaZen concept repositories
License: Proprietary
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: simplejson>=3.17
Requires-Dist: mcp<2,>=1.27
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.22

# LambdaZen Local

**LambdaZen Local** is the official command-line tool for syncing [LambdaZen](https://lambdazen.com) concept repositories to and from your local file system. It works like Git for LambdaZen — clone a concept hierarchy, edit the unpacked files locally, then push your changes back to the cloud.

## Requirements

- Python 3.9 or later
- A LambdaZen account with API access (`LZ_API_KEY` and `LZ_CJS_TOKEN`)

## Installation

### pip (cross-platform)

```bash
pip install lambdazen-local
```

This installs two commands: `lzlocal` (CLI and MCP entry point) and `lzlocal-mcp` (MCP server directly).

### Windows standalone EXEs

Download `lzlocal.exe` and `lzlocalw.exe` and place them in the same directory on `%PATH%`.

| EXE | Purpose |
|---|---|
| `lzlocal.exe` | Console — CLI commands and MCP server. Behaves identically to the `lzlocal` pip script. |
| `lzlocalw.exe` | Windowed — GUI only. Launch directly to open the settings and project manager window. |

---

## Quick Start

### Step 1 — Create a workspace

A workspace is a directory that holds one or more cloned projects. Mark it once:

```bash
cd /path/to/my-workspace
lzlocal configure --workspace
```

### Step 2 — Save credentials

```bash
lzlocal configure --credentials
# Prompts:
#   Username (e.g. clouddev, cloudqa): clouddev
#   LZ_API_KEY: ...
#   LZ_CJS_TOKEN: ...
```

Pass values directly to skip interactive prompts:

```bash
lzlocal configure --credentials --user clouddev --api-key DEV_KEY --cjs-token DEV_TOKEN
```

Credentials are saved to the workspace `.env`. Multiple users can coexist — LambdaZen Local selects the right key based on the user segment in the repository URI (e.g. `/clouddev/myrepo/...` uses `LZ_API_KEY_CLOUDDEV`).

### Step 3 — Clone a repository

```bash
cd /path/to/my-workspace
lzlocal clone /clouddev/myrepo/rootuuid/
# clones into ./clouddev-myrepo/  (override with --dirname NAME)
```

### Step 4 — Edit and push

```bash
# Edit files inside my-workspace/clouddev-myrepo/files/
lzlocal push clouddev-myrepo/
```

---

## Credentials

All credentials live in the workspace `.env` file, written by `lzlocal configure --credentials` or the Windows GUI. There is no fallback to shell environment variables.

### Finding your credentials

Log in to [ide.lambdazen.com](https://ide.lambdazen.com) as the relevant user, then open the browser's developer tools.

**`LZ_API_KEY`** — looks like `<24 characters>|username`.

1. Open the **Network** tab
2. Visit any page showing a list of concepts
3. Find a request to a URL containing `/das/` and inspect its headers
4. Copy the value of the **Authorization** request header

**`LZ_CJS_TOKEN`** — looks like `<96 characters>|username`.

1. Open the **Application** tab
2. Under **Cookies**, select the IDE domain
3. Copy the value of the cookie named **`cjstoken`**

---

## Project Layout

After cloning, your project directory looks like this:

```
my-workspace/
  .env                ← workspace credentials and settings (managed by lzlocal configure)
  clouddev-myrepo/
    concepts/         ← raw concept JSON files downloaded from the cloud (do not edit)
    files/            ← unpacked, human-readable files (EDIT THESE)
    deps/             ← read-only dependency concepts referenced by your concepts
    concepts.csv      ← index mapping local UUIDs to cloud URIs (do not edit)
    files.csv         ← index mapping file paths to concepts (do not edit)
    .mcp.json         ← the two LambdaZen MCP servers (written on clone/pull)
    .claude/          ← Claude Code settings (written on clone/pull)
```

**Only edit files inside `files/`.** Everything else is managed automatically by `lzlocal`.

---

## Command Reference

### `--version` — Show the installed version

```bash
lzlocal --version
```

---

### `configure` — Configure lzlocal settings

#### Mark a directory as a workspace

```bash
lzlocal configure --workspace
```

Creates or updates a `.env` in the current directory with `LZLOCAL_DIR_TYPE=WORKSPACE`. Run this once in the directory that will hold your cloned projects.

#### Save credentials

```bash
lzlocal configure --credentials [--user USER] [--api-key KEY] [--cjs-token TOKEN]
```

Saves credentials to the workspace `.env` (the current directory if it is a workspace, or the parent if it is a project). Each value is prompted interactively if not supplied as a flag.

`--workspace` and `--credentials` can be combined in a single command.

---

### `clone` — Clone a repository from the cloud

```bash
lzlocal clone ROOT_URI [--dirname NAME] [--yes]
```

Downloads a full concept hierarchy from the cloud into a new subdirectory of the current workspace. Run from the workspace directory.

| Argument | Description |
|---|---|
| `ROOT_URI` | URI of the root concept, e.g. `/myuser/myrepo/rootuuid/` |
| `--dirname NAME` | Directory name for the cloned project (default: `<user>-<repo>`) |
| `--yes` / `-y` | Skip the confirmation prompt when cloning a production (non-dev/non-qa) repository |

**Example:**

```bash
cd /path/to/my-workspace
lzlocal clone /clouddev/myrepo/abc123/
# clones into ./clouddev-myrepo/
lzlocal clone /clouddev/myrepo/abc123/ --dirname my-project
# clones into ./my-project/
```

---

### `pull` — Pull latest changes from the cloud

```bash
lzlocal pull [CONCEPTS_PATH] [--ignore-conflicts]
```

Refreshes all concepts in an existing project with the latest versions from the cloud.

| Argument | Description |
|---|---|
| `CONCEPTS_PATH` | Local path to the project directory (default: current directory) |
| `--ignore-conflicts` | Overwrite local changes with cloud versions (use with care) |

```bash
cd ./clouddev-myrepo && lzlocal pull
lzlocal pull ./clouddev-myrepo
lzlocal pull ./clouddev-myrepo --ignore-conflicts
```

---

### `pull-concept` — Pull a single concept

```bash
lzlocal pull-concept CONCEPT_URI [--concepts-path PATH]
```

Downloads one concept, updates it in `concepts/`, and unpacks its files into `files/`. The concept must already exist in `concepts.csv`.

| Argument | Description |
|---|---|
| `CONCEPT_URI` | Cloud URI of the concept to refresh, e.g. `/myuser/myrepo/uuid/` |
| `--concepts-path PATH` | Local path to the project directory (default: current directory) |

```bash
cd ./clouddev-myrepo && lzlocal pull-concept /clouddev/myrepo/abc123/
lzlocal pull-concept /clouddev/myrepo/abc123/ --concepts-path ./clouddev-myrepo
```

---

### `push` — Push local changes to the cloud

```bash
lzlocal push [CONCEPTS_PATH] [--file FILE] [--ignore-conflicts]
```

Packs modified files back into concept JSONs and uploads changed concepts. `CONCEPTS_PATH` defaults to the current directory.

| Argument | Description |
|---|---|
| `--file FILE` | Push only this file (path relative to `files/`) |
| `--ignore-conflicts` | Overwrite cloud versions with local changes (use with care) |

```bash
cd ./clouddev-myrepo && lzlocal push
lzlocal push ./clouddev-myrepo --file "_Folder Name_/script.jsx"
lzlocal push ./clouddev-myrepo --ignore-conflicts
```

---

### `push-concept` — Push a single concept

```bash
lzlocal push-concept CONCEPT_URI [--concepts-path PATH] [--ignore-conflicts]
```

| Argument | Description |
|---|---|
| `CONCEPT_URI` | Cloud URI of the concept to push, e.g. `/myuser/myrepo/uuid/` |
| `--concepts-path PATH` | Local path to the project directory (default: current directory) |
| `--ignore-conflicts` | Overwrite cloud versions with local changes (use with care) |

```bash
cd ./clouddev-myrepo && lzlocal push-concept /clouddev/myrepo/abc123/
lzlocal push-concept /clouddev/myrepo/abc123/ --concepts-path ./clouddev-myrepo
```

---

### `diff` — Diff local vs cloud

```bash
lzlocal diff [CONCEPTS_PATH] [--quiet]
```

Compares every local concept against the cloud and reports what would change on push. Read-only.

| Argument | Description |
|---|---|
| `CONCEPTS_PATH` | Local path to the project directory (default: current directory) |
| `--quiet` / `-q` | Print only the mismatch count, not the full diff |

```bash
cd ./clouddev-myrepo && lzlocal diff
lzlocal diff ./clouddev-myrepo --quiet
```

---

### `local-diff` — Diff two local concept directories

```bash
lzlocal local-diff [SOURCE_PATH] TARGET_PATH [--quiet] [--reverse]
```

| Argument | Description |
|---|---|
| `SOURCE_PATH` | Local path to the source concepts directory (default: current directory) |
| `TARGET_PATH` | Local path to the target concepts directory |
| `--quiet` / `-q` | Print only the mismatch count |
| `--reverse` / `-r` | Swap source and target for the comparison |

```bash
cd ./project-dev && lzlocal local-diff ../project-qa
lzlocal local-diff ./project-dev ./project-qa --quiet
lzlocal local-diff ./project-dev ./project-qa --reverse
```

---

### `git-diff` — Diff local vs a git repository

```bash
lzlocal git-diff [CONCEPTS_PATH] GIT_PATH [--quiet] [--reverse]
```

| Argument | Description |
|---|---|
| `CONCEPTS_PATH` | Local path to the concepts directory (default: current directory) |
| `GIT_PATH` | Local path to the git repository |
| `--quiet` / `-q` | Print only the mismatch count |
| `--reverse` / `-r` | Swap diff direction |

```bash
cd ./clouddev-myrepo && lzlocal git-diff ./my-git-repo
lzlocal git-diff ./clouddev-myrepo ./my-git-repo --quiet
```

---

### `build` — Build webpack bundles from local concepts

```bash
lzlocal build [CONCEPTS_DIR] [--full] [--server] [--port PORT] [--verbose]
```

| Argument | Description |
|---|---|
| `--full` | Clean the build folder and perform a complete rebuild |
| `--server` | Start a local resource server and watch for file changes until Ctrl-C |
| `--port PORT` | Port for the local resource server (default: 8080) |
| `--verbose` | Print each resource request served by the local server |

`--full` and `--server` are mutually exclusive.

```bash
cd ./clouddev-myrepo && lzlocal build --full
lzlocal build ./clouddev-myrepo --server --port 9090
```

---

## Windows Standalone EXEs

The EXE distribution requires no Python install. Copy both files to the same directory on `%PATH%`.

### CLI (`lzlocal.exe`)

All CLI commands work identically to the pip `lzlocal` script:

```
lzlocal.exe configure --credentials
lzlocal.exe clone /clouddev/myrepo/rootuuid/
lzlocal.exe pull
lzlocal.exe push --file "folder/script.jsx"
lzlocal.exe diff --quiet
lzlocal.exe          ← shows help
```

### GUI (`lzlocalw.exe`)

Double-click `lzlocalw.exe` or run it from a terminal. It opens the LambdaZen Local project manager window where you can manage credentials, clone and pull projects, run push/diff/build, and open projects in Claude Code.

```
lzlocalw.exe
```

---

## MCP Servers

LambdaZen exposes its tooling to AI assistants such as Claude Code through **two MCP servers**. Both are written into a project's `.mcp.json` on every `clone` or `pull`.

| Server | Transport | Runs | Use it for |
|---|---|---|---|
| `lambdazen-local` | stdio | Locally, bound to one project folder | Sync and build: `lz_push`, `lz_pull`, `lz_diff`, `lz_build`, `configure_credentials`, … |
| `lambdazen-cloud` | Streamable HTTP | In the LambdaZen cloud | Index types, schema and search, concept CRUD, eval, help, logs, control register, skills |

#### `configure_credentials` MCP tool

Available in the `lambdazen-local` server. Saves credentials directly from a Claude Code session without leaving the editor:

```
configure_credentials(user="clouddev", api_key="...", cjs_token="...")
```

Writes `LZ_API_KEY_<USER>` and `LZ_CJS_TOKEN_<USER>` to the workspace `.env` and updates `.claude/settings.local.json`. **Restart Claude Code after calling this tool** for the credentials to take effect.

Full reference — tools, resources, skills, security model, configuration, troubleshooting:
[docs/LambdaZen-MCP-Servers.md](../docs/LambdaZen-MCP-Servers.md).

### Starting the local MCP server manually

**pip:**
```bash
lzlocal-mcp /path/to/project
```

**Windows EXE:**
```
lzlocal.exe mcp /path/to/project
```

The local server exposes three read-only resources alongside the sync tools:

| Resource | What it returns |
|---|---|
| `lzlocal://project/root-uri` | Root concept URI (e.g. `/user/repo/uuid/`) |
| `lzlocal://project/local-path` | Absolute path to this project on the local filesystem |
| `lzlocal://user` | LambdaZen user for this project (e.g. `clouddev`) |

---

## Typical Workflows

### Start a new project

```bash
mkdir my-workspace && cd my-workspace
lzlocal configure --workspace
lzlocal configure --credentials --user clouddev --api-key KEY --cjs-token TOKEN
lzlocal clone /clouddev/myrepo/rootuuid/
# edit files in clouddev-myrepo/files/
lzlocal push clouddev-myrepo/
```

### Daily sync cycle

```bash
lzlocal diff ./clouddev-myrepo       # check what's changed
lzlocal pull ./clouddev-myrepo       # get latest from cloud
# edit files ...
lzlocal push ./clouddev-myrepo       # upload to cloud
```

### Refresh a single concept without pulling everything

```bash
lzlocal pull-concept /clouddev/myrepo/someuuid/ --concepts-path ./clouddev-myrepo
```

### Compare dev and QA environments

```bash
lzlocal clone /clouddev/myrepo/rootuuid/
lzlocal clone /cloudqa/myrepo/rootuuid/
lzlocal local-diff ./clouddev-myrepo ./cloudqa-myrepo
```

---

## Conflict Handling

LambdaZen Local detects conflicts in two directions:

- **Pull conflicts** — the cloud has a newer version of a concept you have also modified locally. Use `--ignore-conflicts` to overwrite your local changes with the cloud version.
- **Push conflicts** — the cloud has a newer version of a concept than the one you started from. Use `--ignore-conflicts` to force-overwrite the cloud with your local version.

When a conflict is detected, the command exits with a non-zero status and prints the affected URIs.

---

## License

Proprietary — © LambdaZen Technology Corp. All rights reserved.
