Metadata-Version: 2.4
Name: eforge
Version: 1.0.18
Summary: Observation layer, kernel graph system, production scaffolding, real-time events, and advanced indexing for unified architecture compiler
Project-URL: Repository, https://github.com/NT9V/forge
License: MIT
Keywords: architecture,codebase,compiler,developer-tools,graph,mapping,mcp,observation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: duckdb>=0.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: ruamel-yaml>=0.18
Provides-Extra: board
Requires-Dist: fastapi>=0.100; extra == 'board'
Requires-Dist: httpx>=0.24; extra == 'board'
Requires-Dist: uvicorn>=0.23; extra == 'board'
Provides-Extra: compiler
Requires-Dist: fastapi>=0.100; extra == 'compiler'
Requires-Dist: httpx>=0.24; extra == 'compiler'
Requires-Dist: mcp>=1.0; extra == 'compiler'
Requires-Dist: uvicorn>=0.23; extra == 'compiler'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: fastapi>=0.100; extra == 'full'
Requires-Dist: httpx>=0.24; extra == 'full'
Requires-Dist: mcp>=1.0; extra == 'full'
Requires-Dist: uvicorn>=0.23; extra == 'full'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# eforge

Observation layer and kernel graph system for the unified architecture compiler. Provides RGB-channel graph infrastructure, DuckDB storage, and observation graph management.

**Trust:** eforge provides the observation layer and kernel graph system for the unified architecture compiler. The full compiler with high-level retrieval surfaces requires the monorepo or compiler extras. See [TRUST.md](https://github.com/NT9V/forge/blob/main/docs/TRUST.md) and [NORTH_STAR.md](https://github.com/NT9V/forge/blob/main/docs/NORTH_STAR.md) in the repository.

## Install

```bash
pip install eforge
```

Base installation includes core system and essential commands.

| Install | What you get |
|---------|----------------|
| `pip install eforge` | Core observation system + 13 commands (init, task, node, schema, etc.) + QOL features (completion, aliases, git integration) + production scaffolding |
| `pip install eforge[compiler]` | Full compiler with all retrieval surfaces (query, impact, orient, discover, map, trace, inspect) |
| `pip install eforge[mcp]` | MCP server for AI agent integration |
| `pip install eforge[board]` | Web dashboard |
| `pip install eforge[full]` | Complete feature set |

## Project bootstrap

**Unified storage** — all project data under `.eforge/`:

| Storage | Directory | Created by |
|---------|-----------|------------|
| Unified storage | `.eforge/` (manifest, tasks, observations, schemas, etc.) | `eforge init` |

```bash
cd your-project
eforge init                    # creates .eforge/ unified storage
eforge node add "Auth" -y      # observation graph
eforge task add --title "..." -y   # creates .eforge/tasks/ on first use

# Full compiler features (requires monorepo or [compiler] extra):
eforge query                    # graph query
eforge impact                   # impact analysis
eforge orient                   # project understanding
eforge discover                 # codebase discovery
eforge map                      # project mapping
eforge scaffold generate        # code generation (with [scaffold] extra)
```

Legacy repos may have `.forge/` storage; run `eforge migrate` to migrate to unified `.eforge/` storage.

## No setup needed

After `eforge init`, add nodes anytime:

```bash
eforge node add "AuthSystem" --kind concept/feature -y
eforge node add "auth.py" --kind core/file \
  --file src/auth.py -y
eforge node link "AuthSystem" "auth.py" \
  --rel housed-in \
  --note "core auth logic" -y
eforge node show "AuthSystem"
```

## Commands

**Getting Started:**
```text
eforge init     create .eforge/ unified storage
eforge node add  add observation nodes to graph
eforge schema list available schemas
eforge task list show project tasks
```

**Graph Operations (PyPI):**
```text
eforge node add  add observation nodes
eforge node list  list observation nodes
eforge node show  show node details
eforge node link  link nodes with relationships
eforge node edit  edit node properties
```

**Graph Operations (Compiler Extras):**
```text
eforge query     query nodes from declaration graph
eforge inspect   progressive node inspection
eforge map       print project map (markdown/mermaid/json)
eforge trace     trace dependency graph
eforge impact    show impact radius for manifest node
eforge search    search manifest graph by name, id, or domain
```

**Core Compiler (Requires Monorepo or Compiler Extras):**
```text
eforge verify    structural verification
eforge scan      scan project to detect framework
eforge reality   validate manifest vs import reality
eforge manifest  manage manifest graph
eforge intent    manage intent graph
```

**Observation Layer:**
```text
eforge node      add, show, list, find, link, note, tag, mark, edit, inspect
eforge schema    list, show, create, edit, validate, copy, restore
eforge task      list, add, done, show, update
eforge error     lookup (<CODE>), --list, --search, --stats
```

**Advanced Tools (Requires Monorepo or Compiler Extras):**
```text
eforge scaffold  code generation (with [scaffold] extra)
eforge audit     EGMP workflow for evidence-gated reviews
eforge registry  template registry operations
eforge projects  workspace project management
eforge prefab    manage architectural prefab templates
```

**Storage Migration:**
```text
eforge migrate   migrate .forge/ to .eforge/ unified storage
```

**Configuration:**
```text
eforge config    get, set, show, validate, reset
```

**QOL Features:**
```text
eforge completion    shell completion (bash/zsh/fish)
eforge alias         command aliases for efficiency
eforge git           git integration (status, branch, commit info)
eforge node git-link link nodes to git commits/branches
```

**Task Git Integration:**
```text
eforge task add --git-commit HASH    link task to git commit
eforge task add --git-branch NAME    associate task with branch
eforge task add --issue-url URL       link to external issue tracker
```

**MCP Server (AI Agent Integration):**
```text
eforge mcp    start MCP server (requires [mcp] extra)
```

See [MCP.md](https://github.com/NT9V/forge/blob/main/docs/MCP.md) for MCP server documentation.

Workflows: [WORKFLOWS.md](https://github.com/NT9V/forge/blob/main/docs/WORKFLOWS.md).
Trust ladder: [TRUST.md](https://github.com/NT9V/forge/blob/main/docs/TRUST.md).
Architecture: [NORTH_STAR.md](https://github.com/NT9V/forge/blob/main/docs/NORTH_STAR.md).

## Your own schemas

eforge ships with built-in schemas for common node types.
Add project-specific schemas:

```bash
eforge schema create game/canvas
```

This creates `.eforge/schemas/domain/game/canvas.yaml`.
Your schema is immediately available:

```bash
eforge node add "PixelCanvas" --kind game/canvas
# SchemaPrompt uses YOUR schema properties
```

## Storage Migration

If you have legacy `.forge/` storage, migrate to unified `.eforge/` storage:

```bash
eforge migrate                      # migrate .forge/ to .eforge/
eforge migrate --dry-run           # preview migration without changes
eforge migrate --backup           # create backup before migration
```

The migration tool includes:
- Dry-run mode for preview
- Automatic backup creation
- Conflict detection and resolution
- Validation after migration

Schema search order:

1. `.eforge/schemas/` (your project)
2. forge built-ins

Built-in kinds: `concept/feature`, `core/file`, `ui/screen`, `ui/variant`,
`ui/component`, `architecture/session`, `architecture/boundary`, `data/model`,
`data/table`, `data/rpc`, `code/class`, `code/function`, `code/module`

## Node types

```text
concept/feature planned features, systems, capabilities
core/file       source files
```

## Relationship types

```text
housed-in       concept → file
relates-to      concept → concept
depends-on      A needs B
implements      code implements concept
raises          code raises error
```

## Storage

```text
.eforge/schemas/              project type schemas
.eforge/observations/
  nodes/                      one yaml per node
  .cache/                     SQLite index (auto-rebuilt)
.forge/manifest.yaml          declaration graph (not created by eforge init)
.forge/tasks/                 work items (created on first task add)
```

## No AI required

Works without any AI assistant.
Map your codebase manually, one node at a time.
