Metadata-Version: 2.4
Name: namespaceforge
Version: 0.2.0
Summary: Salesforce metadata namespace auditing and fail-closed refactoring
Author: AbdelGahffar Zakaria
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/AbdelGahffarZakaria/NamespaceForge
Project-URL: Repository, https://github.com/AbdelGahffarZakaria/NamespaceForge
Project-URL: Issues, https://github.com/AbdelGahffarZakaria/NamespaceForge/issues
Project-URL: Changelog, https://github.com/AbdelGahffarZakaria/NamespaceForge/blob/main/namespaceforge-cli/CHANGELOG.md
Keywords: salesforce,metadata,namespace,cli,devops
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: defusedxml<1,>=0.7.1
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: jsonschema<5,>=4; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"

# NamespaceForge CLI

NamespaceForge audits and safely refactors namespace references in Salesforce metadata source. Version 0.2 inventories Apex, LWC, Aura, and XML metadata, resolves package-owned symbols, previews add/remove/replace operations, and can execute an approved plan with integrity checks, recoverable backups, and rollback support.

## Installation

Python 3.11 or newer is required.

```bash
cd namespaceforge-cli
python -m venv .venv
```

Windows:

```powershell
.venv\Scripts\activate
pip install -e ".[dev]"
```

Linux/macOS:

```bash
source .venv/bin/activate
pip install -e ".[dev]"
```

## Audit and planning

```bash
namespaceforge --help
namespaceforge --version
namespaceforge scan ../force-app/main/default
namespaceforge scan ../force-app/main/default --format json
namespaceforge audit ../force-app/main/default --namespace zPFX
namespaceforge audit ../force-app/main/default --format json --output report.json
namespaceforge audit ../force-app/main/default --fail-on-issues
namespaceforge plan replace ../force-app/main/default --from oldPFX --to zPFX
namespaceforge plan add ../force-app/main/default --namespace zPFX
namespaceforge plan remove ../force-app/main/default --namespace zPFX
```

All `plan` commands are strictly read-only. Review their safe, review, and protected classifications before authorizing a transformation.

## Applying transformations

Run the corresponding plan first, commit or otherwise preserve the current source state, then use an explicit apply command:

```bash
namespaceforge apply replace ../force-app/main/default --from oldPFX --to zPFX --yes
namespaceforge apply add ../force-app/main/default --namespace zPFX --yes
namespaceforge apply remove ../force-app/main/default --namespace zPFX --yes
```

Use `--backup-dir PATH` to select a persistent backup root outside the scanned tree. Without it, NamespaceForge uses `.namespaceforge/backups` at the Salesforce project or Git repository root when one can be discovered. Each successful run prints its unique manifest and backup paths.

Machine-readable transformation output is available without mixing diagnostics into JSON stdout:

```bash
namespaceforge apply replace ../force-app/main/default \
  --from oldPFX --to zPFX --yes --format json --output transform-report.json
```

### Fail-closed safety model

NamespaceForge applies a transformation only when all of these conditions hold:

- `--yes` explicitly authorizes source modification.
- The scan completed without unreadable files or scanner errors.
- The plan contains no `review` occurrences; protected declarations and comments remain untouched.
- Every target remains inside the resolved scan root and matches the content hash captured during planning.
- Backups and a prepared manifest are written outside the scanned tree before the first source write.
- Source bytes are checked again immediately before each atomic file replacement.

If a later write fails, already modified files are restored from the in-memory originals and the manifest records the rollback state. UTF-8 BOMs, CRLF/LF line endings, and file modes are preserved.

### Rollback

Restore a completed transformation using its manifest:

```bash
namespaceforge rollback .namespaceforge/backups/<run-id>/manifest.json --yes
```

Rollback verifies both the backup hash and each current source hash before writing anything. If a file was edited after the transformation, the entire rollback aborts without overwriting that work. Rollback is idempotent.

## Configuration

Create `namespaceforge.toml` in the working directory, or pass `--config PATH`:

```toml
[namespaceforge]
namespace = "zPFX"
source_path = "force-app/main/default"
exclude = ["**/.git/**", "**/node_modules/**"]

[audit]
fail_on_issues = false
minimum_confidence = 0.6
```

Without a path, commands use `force-app/main/default` or the configured `source_path`. CLI arguments override configuration values.

## Reports and schemas

Text reports are optimized for people. JSON reports use stable schema version `1.0`. Standalone Draft 2020-12 contracts are packaged for:

- scan reports
- audit reports
- read-only plan reports
- transformation results
- durable transformation manifests

The schemas remain accessible from `namespaceforge/schemas` through `importlib.resources` after wheel installation.

For source safety, any explicit `--output` report must resolve outside the scanned directory. NamespaceForge returns exit code 2 before transforming when an apply report targets the source tree.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Successful command |
| 1 | Warnings or errors found with `audit --fail-on-issues` |
| 2 | Invalid CLI usage, configuration, confirmation, or output path |
| 3 | Scan path missing or inaccessible |
| 4 | Unexpected internal failure |
| 5 | Transformation or rollback safely aborted |

## Development and release validation

```bash
pytest
pytest --cov=namespaceforge
python -m build
python -m pip install dist/namespaceforge-0.2.0-py3-none-any.whl
namespaceforge --version
```

Tests use isolated metadata trees and require no Salesforce org. CI runs on Windows and Linux with Python 3.11, 3.12, and 3.13.

## Demo

The tracked demo is outside `force-app`, so it cannot affect the managed package. Plan commands can run directly against it. To test an apply command, first copy the demo to an untracked temporary directory and transform only that copy.

```powershell
.\namespaceforge-cli\.venv\Scripts\namespaceforge.exe scan .\namespaceforge-cli\examples\demo-metadata
.\namespaceforge-cli\.venv\Scripts\namespaceforge.exe audit .\namespaceforge-cli\examples\demo-metadata --namespace zPFX
.\namespaceforge-cli\.venv\Scripts\namespaceforge.exe plan replace .\namespaceforge-cli\examples\demo-metadata --from oldPFX --to zPFX
```

## Current limitations

- Reference discovery remains token based; XML ownership extraction uses structured parsing with a recovery fallback.
- Apply commands intentionally refuse every review-required plan. There is no override for partial or ambiguous transformations.
- Unnamespaced custom tokens become high-confidence findings only when ownership can be established from declarations in the scanned tree.
- Third-party namespaces remain non-blocking unless the referenced symbol is owned by the scanned package.
- Dynamic Apex, generated JavaScript, encoded references, and uncommon metadata forms can require manual review or remain undiscovered.
- Source `<fullName>` declarations for objects, fields, and labels are protected and remain unmodified.
- Correct expected-namespace references are reported as informational findings.
- Always inspect the plan and use version control before applying a transformation.

## Roadmap

The next milestone is parser-backed Apex and JavaScript symbol resolution, followed by Salesforce API/OAuth integration and a VS Code workflow. Those capabilities provide the foundation for an AppExchange API or hybrid solution.
