Metadata-Version: 2.4
Name: fab-dev
Version: 0.1.1
Summary: Developer CLI for Fabric feature-branch workspace provisioning.
Author-email: Andrea Montanari <andrea.montanari92@gmail.com>
Maintainer-email: Andrea Montanari <andrea.montanari92@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/andreamontanari/fabric-development-workflows.git
Keywords: fabric,microsoft,development,workflow,versioning
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: black>=26.0; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Microsoft Fabric - Development Worfklows CLI


[![PyPi version](https://badgen.net/pypi/v/fab-dev/)](https://pypi.org/project/fab-dev/)
[![Python versions](https://img.shields.io/pypi/pyversions/fab-dev)](https://pypi.org/project/fab-dev/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

The Development Workflows CLI for Microsoft Fabric (fab-dev) is designed to support git-based development tasks on top of Fabric.

![Fabric Development Workflows](https://raw.githubusercontent.com/andreamontanari/fabric-development-workflows/main/header_repository.png)

## Quick start

```bash
# Install the CLI
pip install fab-dev

# Authenticate
fab-dev auth login                           # authenticate yourself

# Start developing on Fabric
fab-dev create my_feature --dev-branch dev       # creates a workspace attached to a feature branch cut from dev branch
fab-dev sync push <workspace-id|workspace-url|workspace-name>     # push changes in the branch
fab-dev sync pull <workspace-id|workspace-url|workspace-name>     # downloads latest changes in workspace
fab-dev pr create                                                 # opens a Pull Request
```


## ✨ Key Features

### 🌱 Feature Branch Provisioning
- Create a feature branch and provision a corresponding Fabric workspace in one command.
- Validate branch ancestry against a configurable dev baseline.
- Reuse an existing target workspace when rerunning to keep workflows idempotent.

### 🔑 Built-In Authentication Commands
- Use `fab-dev auth login` for interactive user, service principal, or managed identity sign-in.
- Use `fab-dev auth status` to verify token availability and inspect active account/tenant.
- Use `fab-dev auth logout` to clear local auth context and reset CLI token cache.

### 🔄 Git-Aware Workspace Sync
- Pull branch snapshots into a workspace with conflict-aware behavior.
- Push workspace changes back to the connected branch with an optional message.
- Inspect sync status in human-readable or JSON format.

### 🔐 Access and Governance Defaults
- Grant or revoke users and groups by role.
- Assign branch creator as workspace admin during provisioning.
- Support user/group identity mapping for enterprise directory scenarios.

### 🧹 Lifecycle Cleanup
- Remove feature workspaces safely when a branch is done.
- Optionally delete the feature branch from origin and local repo.
- Keep cleanup idempotent so repeated execution does not fail on missing resources.

### 🤝 PR Flow Integration
- Open pull requests to merge feature branches into dev.
- Works with GitHub and Azure DevOps remotes.

### 🧱 Environment Scaffolding
- Bootstrap baseline environments (`dev,test,prod`) in one run.
- Create/reuse environment branches and mapped Fabric workspaces using deterministic naming.
- Keep prod/main protected by default (no auto-sync unless explicitly enabled).

## 📦 Installation

### Prerequisites
- Python 3.11+
- A Microsoft Fabric tenant and capacity
- A repository using a dev branch model (for example `dev` and `feat/*`)
- A dev workspace attached to that capacity and `dev` repository
- Multiple developers working from a `dev` branch

### Install from local source
```bash
pip install -e .
```

### Verify installation
```bash
fab-dev --help
fab-dev --version
```

### Developer tooling (formatting)
This repository uses `black` as the Python formatter.

```bash
# Install dev tools
pip install -r requirements-dev.txt

# Run formatter manually
black .

# Install git pre-commit hook (auto-format on commit)
pre-commit install
```

After `pre-commit install`, every local commit runs Black automatically.

## 🔐 Authentication

Current CLI operations authenticate using one of the following:
- `FABRIC_ACCESS_TOKEN`, or
- an authenticated Azure CLI session via `az login`

CLI auth commands:
- `fab-dev auth login`
- `fab-dev auth status [--json]`
- `fab-dev auth logout`

For pull request creation:
- GitHub: `FAB_DEV_GITHUB_TOKEN` (or `GITHUB_TOKEN` / `GH_TOKEN`) or `gh auth login`
- Azure DevOps: `FAB_DEV_AZDO_PAT` (or `AZURE_DEVOPS_EXT_PAT`) or `az login`

## 🎯 Usage Examples

### Authenticate and Verify Session
```bash
# Interactive sign-in
fab-dev auth login

# Service principal sign-in
fab-dev auth login -u <client_id> -p <client_secret> --tenant <tenant_id>

# Managed identity sign-in
fab-dev auth login --identity

# Verify current auth/session details
fab-dev auth status --json

# Sign out local auth context
fab-dev auth logout
```

### Create and Provision
```bash
# Create from short feature name (expands to feat/my_feature)
fab-dev create my_feature --dev-branch dev

# Create from explicit branch name
fab-dev create feat/my_feature

# Override creator/capacity and grant access during create
fab-dev create my_feature \
  --creator alice@contoso.com \
  --capacity-id <fabric-capacity-guid> \
  --add-user alice@contoso.com:Contributor \
  --add-group data-eng:Viewer
```

### Sync Workspace and Branch
```bash
# Check git sync status
fab-dev sync status <workspace-id|workspace-url|workspace-name>

# Pull latest branch snapshot into workspace
fab-dev sync pull <workspace-id|workspace-url|workspace-name>

# Pull and overwrite pending local workspace changes
fab-dev sync pull <workspace-id|workspace-url|workspace-name> --force

# Push workspace changes to branch
fab-dev sync push <workspace-id|workspace-url|workspace-name> --message "Update notebook"

# Push workspace changes with positional quoted message
fab-dev sync push <workspace-id|workspace-url|workspace-name> "Update notebook"
```

### Manage Access
```bash
# Grant role assignments
fab-dev access grant <workspace-ref> --user alice@contoso.com:Contributor --group data-eng:Viewer

# Revoke assignments
fab-dev access revoke <workspace-ref> --group data-eng
```

### Open Pull Requests
```bash
# Create PR from current branch to dev
fab-dev pr create

# Customize PR target/title/body
fab-dev pr create --target-branch dev --title "Add customer churn notebook" --body "Implements feature workflow"
```


### Scaffold Environment Baseline
Prerequisites for scaffold:
0. Authenticate by running `fab-dev auth login`
1. Clone the repository and change directory into the local clone.
2. Resolve the Fabric capacity ID (GUID), or use capacity name.
   - Open an existing workspace on that capacity.
   - Copy the workspace ID from URL `/groups/<workspaceId>`.
   - Run `fab-dev sync status <workspace-id|workspace-url|workspace-name> --json`.
   - Use the `capacityId` field from output.

```bash
# Dry-run scaffold plan
fab-dev scaffold init --capacity-id <fabric-capacity-guid> --workspace-prefix contoso --dry-run

# Interactive scaffold: enter capacity ID or capacity name, choose env profile
# (dev/test/prod | dev/prod | dev only), then enter branch names and workspace prefix
fab-dev scaffold init

# Non-interactive scaffold env branches and workspaces (prod maps to main)
fab-dev scaffold init \
  --capacity-id <fabric-capacity-guid> \
  --workspace-prefix contoso \
  --env-branches dev,test,prod \
  --non-interactive \
  --yes

# Use capacity name as alternative input
fab-dev scaffold init \
  --capacity-name "Contoso Capacity" \
  --workspace-prefix contoso \
  --yes

# Allow remapping existing workspace branch links and prod sync
fab-dev scaffold init \
  --capacity-id <fabric-capacity-guid> \
  --workspace-prefix contoso \
  --rebind \
  --sync-prod \
  --yes
```

Notes:
- Workspace mapping is deterministic: `<workspace-prefix>-<env>`.
- If prefix contains spaces, env suffix is appended with a space (example: `Scaffolding Try dev`).
- If prefix uses `_` separators, env suffix uses `_` (example: `scaffolding_try_dev`).
- Interactive runs always show a dry-run review phase (including planned workspace names) before execution.
- Review phase includes a topology diagram (`repo -> branch -> workspace -> capacity`) for each environment.
- If `main` does not exist, scaffold bootstraps it with a minimal commit before creating env branches.
- If a workspace already exists but is mapped to a different branch, scaffold fails unless `--rebind` is provided.
- `prod` maps to `main` by default and is protected from auto-sync unless `--sync-prod` is set.


### Cleanup
```bash
# Cleanup workspace resolved from current feature branch
fab-dev cleanup --yes

# Cleanup specific feature and delete branch locally/remotely
fab-dev cleanup feat/my_feature --yes --delete-branch

# Cleanup explicit workspace reference
fab-dev cleanup --workspace-ref <workspace-id|workspace-url|workspace-name> --yes
```

## 🧭 Command Groups

| Command | Purpose |
|---|---|
| `auth login` | Authenticate for Fabric operations |
| `auth status` | Show current authentication status and token source |
| `auth logout` | Clear local authentication context |
| `create` | Create/publish feature branch and provision Fabric workspace |
| `sync pull` | Pull connected branch snapshot into workspace |
| `sync push` | Push workspace changes to connected branch |
| `sync status` | Show workspace sync status |
| `access grant` | Grant users/groups roles in workspace |
| `access revoke` | Revoke users/groups from workspace |
| `workspace list` | List visible workspaces |
| `pr create` | Create pull request in git provider |
| `cleanup` | Delete feature workspace and optionally branch |
| `scaffold init` | Bootstrap env branches and mapped Fabric workspaces |
| `help` | Show command-specific help |

## ⚙️ Configuration

### Common flags
- `--dev-branch` controls the baseline branch for create/cleanup flows (default `dev`).
- `--feature-prefix` controls feature branch naming (default `feat/`).
- `--workspace-prefix` provides fallback workspace naming when discovery is unavailable.

### Environment variables
- `FABRIC_ACCESS_TOKEN`
- `FABRIC_CAPACITY_ID`
- `FABRIC_WORKSPACE_PREFIX`
- `FABRIC_AZ_CLI_PATH`
- `FAB_DEV_AZ_SUBSCRIPTION`
- `FABRIC_PRINCIPAL_MAP_JSON`
- `FABRIC_USER_MAP_JSON`
- `FABRIC_GROUP_MAP_JSON`
- `FAB_DEV_GITHUB_TOKEN`
- `GITHUB_TOKEN`
- `GH_TOKEN`
- `FAB_DEV_AZDO_PAT`
- `AZURE_DEVOPS_EXT_PAT`

## 🏗️ Architecture Notes

Current implementation is REST-first for deterministic request/response control and predictable automation behavior.

For a visual overview of branch-to-workspace relationships, open [workspace-topology.html](./workspace-topology.html).

[![Visual workflow preview](https://raw.githubusercontent.com/andreamontanari/fabric-development-workflows/main/workspace-topology-preview.png)](./workspace-topology.html)

- Runtime entrypoint: `fab_dev/main.py`
- Parser wiring: `fab_dev/core/parser_setup.py`
- Command parsers: `fab_dev/parsers/`
- Command handlers: `fab_dev/commands/`
- Existing implementation core: `fab_dev/cli.py`

## 🛡️ Operational Design Principles

- Deterministic workspace naming and branch-to-workspace mapping
- Idempotent command behavior for retries and reruns
- Least-privilege access assignment defaults
- Capacity-aware provisioning and safe failure handling
- Auditable lifecycle operations (provision, sync, cleanup)

## 📄 Project Status

This repository is focused on the first production-ready iteration of the `fab-dev`workflow.
Near-term evolution typically includes provider abstraction options and expanded parity tests for alternative execution paths.

## 🤝 Contributing

We welcome contributions from the community. Whether you are fixing bugs, adding features, improving documentation, or helping other users, your contributions are valuable.

### Quick Start Contributing

1. **Check existing issues** - Look for issues labeled `help-wanted`.
2. **Read our guidelines** - See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed instructions.
3. **Fork and clone** - Set up your development environment.
4. **Create a pull request** - Link it to the related issue.

Before contributing, please review our [Contributing Guidelines](./CONTRIBUTING.md) and [Code of Conduct](./CODE_OF_CONDUCT.md).

## 🆘 Support & Community

### Getting Help

- **GitHub Issues** - Bug reports and feature requests
- **GitHub Discussions** - Questions and community support
- **Documentation** - Usage guidance and examples in this repository
- **Microsoft Community** - Connect with other Fabric developers: https://community.fabric.microsoft.com/t5/Developer/bd-p/Developer

### Feature Requests

- **GitHub Issues** - Technical feature requests
- **Fabric Ideas Portal** - Product-level feature suggestions: https://ideas.fabric.microsoft.com/

### Enterprise Support

- Contact your Microsoft account manager.
- **Microsoft Fabric Support** - Official support: https://support.fabric.microsoft.com/

## 🔄 Release Notes

See [VERSIONING.md](./VERSIONING.md) for versioning policy and release workflow details.

## 📄 License

This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.
