Metadata-Version: 2.4
Name: open-workspace-builder
Version: 1.18.2
Summary: Scaffold, maintain, and secure AI coding workspaces
Author: originalrgsec
License-Expression: MIT
Project-URL: Homepage, https://github.com/originalrgsec/open-workspace-builder
Project-URL: Repository, https://github.com/originalrgsec/open-workspace-builder
Project-URL: Issues, https://github.com/originalrgsec/open-workspace-builder/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: himitsubako>=0.9.0
Provides-Extra: llm
Requires-Dist: litellm<=1.83.0,>=1.40.0; extra == "llm"
Provides-Extra: security
Requires-Dist: pyyaml>=6.0; extra == "security"
Requires-Dist: litellm<=1.83.0,>=1.40.0; extra == "security"
Provides-Extra: keyring
Requires-Dist: himitsubako[keychain]>=0.9.0; extra == "keyring"
Provides-Extra: secrets
Requires-Dist: himitsubako[keychain]>=0.9.0; extra == "secrets"
Provides-Extra: audit
Requires-Dist: pip-audit>=2.7.0; extra == "audit"
Provides-Extra: sbom
Requires-Dist: cyclonedx-python-lib<11,>=9.0; extra == "sbom"
Provides-Extra: sast
Requires-Dist: semgrep>=1.50.0; extra == "sast"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: sheets
Requires-Dist: google-api-python-client>=2.0; extra == "sheets"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "sheets"
Provides-Extra: xlsx
Requires-Dist: xlsxwriter>=3.0; extra == "xlsx"
Provides-Extra: hooks
Requires-Dist: pre-commit>=3.0; extra == "hooks"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: semgrep>=1.50.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: pyright<2.0,>=1.1; extra == "dev"
Dynamic: license-file

# owb — Open Workspace Builder

An open-source internal developer platform (IDP) for AI coding assistants, with built-in policy-as-code and supply chain security for the workspace itself.

[![PyPI](https://img.shields.io/pypi/v/open-workspace-builder)](https://pypi.org/project/open-workspace-builder/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tests: 1561](https://img.shields.io/badge/tests-1561%20passed-brightgreen)](tests/)

OWB is designed for individual developers who use AI coding assistants daily. It is not a team collaboration tool, a hosted service, or a SaaS platform.

**Workspace as a platform.** `owb init` scaffolds a structured workspace from a single command: Obsidian knowledge vault, context files, development rules, custom skills, and a workspace config entry point. An interactive wizard handles model selection, vault structure, and security settings. Drift detection and interactive migration keep the workspace current as projects evolve.

**Policy as code.** Security and development policies are expressed as machine-readable rules enforced automatically. Inline rules govern dependency installation, coding standards, and TDD workflow. Pre-commit hooks run secrets scanning (gitleaks), linting (ruff), SAST (Semgrep), and vulnerability scanning (Trivy). A three-layer security scanner with 58 attack signatures blocks prompt injection, data exfiltration, and MCP manipulation before content reaches your sessions.

**Supply chain security.** Every dependency and content update passes through a security gate. Package quarantine (7-day aging), pre-install SCA (pip-audit + GuardDog), license auditing, OSS health scoring, suppression monitoring, and content provenance tracking protect the workspace from compromised packages and malicious upstream changes.

OWB also serves as a shared core library. Downstream packages (like vendor-specific wrappers) depend on OWB for engine, security, and configuration infrastructure, then overlay their own defaults.

## Quick Start

```bash
pip install open-workspace-builder

# First run launches an interactive setup wizard
owb init

# Generate config from an existing Obsidian vault
owb init --from-vault ~/path/to/vault

# Skip the wizard and use defaults
owb init --no-wizard

# Scaffold to a specific directory
owb init --target ~/my-workspace

# Preview without writing anything
owb init --dry-run
```

This creates an `output/` directory (or your chosen target) containing:

```
output/
├── .ai/
│   └── WORKSPACE.md              # Workspace config entry point
├── .skills/
│   └── skills/                   # Custom skills
├── Context/
│   ├── about-me.md               # Template — your background
│   ├── brand-voice.md            # Template — your writing style
│   ├── working-style.md          # Template — your preferences
│   └── Obsidian/                 # Knowledge vault with 18 note templates
│       ├── _bootstrap.md
│       ├── _index.md
│       ├── _templates/
│       ├── self/, research/, projects/, decisions/, code/, business/
│       └── ...
```

ECC (Everything Claude Code) agent/command/rule installation is disabled by default. Enable it by setting `ecc.enabled: true` in your config file.

**Already have a vault?** See the [First Run Guide](docs/howto-first-run.md) for a step-by-step walkthrough of running OWB against an existing Obsidian vault, including how to safely test on a copy before touching the live vault.

## Configuration

OWB uses a three-layer configuration system:

1. **Built-in defaults** — sensible values that work out of the box
2. **User config file** — `~/.owb/config.yaml` (auto-detected) or any file via `--config`
3. **CLI flags** — override any config value from the command line

Any key you omit falls back to the layer below. See [`config.example.yaml`](config.example.yaml) for the full schema with comments.

Key sections:

| Section | Controls |
|---------|----------|
| `vault` | Obsidian vault name, parent directory, assistant name, templates |
| `ecc` | ECC catalog enabled/disabled, target directory, agent/command/rule lists |
| `skills` | Which custom skills to install |
| `agent_config` | Workspace config file directory and filename |
| `models` | Per-operation LLM model strings (LiteLLM provider/model format) |
| `security` | Active pattern sets, scanner layer selection |
| `trust` | Trust tier policy selection |
| `marketplace` | Output format (generic, anthropic, openai) |
| `paths` | Config, data, and credentials directory paths |
| `context_templates` | Whether to deploy personal context files |

The setup wizard (`owb init` on first run) generates `~/.owb/config.yaml` interactively. Subsequent runs load it automatically.

## Commands

### `owb init` — Scaffold a Workspace

Creates the full directory structure. On first run, launches an interactive wizard to configure your model provider, vault structure, and security settings. Use `--config` to provide a pre-written config, `--from-vault` to generate config from an existing Obsidian vault, or `--no-wizard` to skip the wizard and use defaults.

### `owb diff` — Detect Drift

Compares an existing workspace against the reference state and reports what is missing, outdated, or modified.

```bash
owb diff ./output                 # prints human-readable report
owb diff ./output -o report.json  # also writes JSON for automation
```

### `owb migrate` — Update a Workspace

Brings an existing workspace up to date. Reviews each changed file interactively (or use `--accept-all` for batch mode). Files that fail security scanning are blocked.

```bash
owb migrate ./output              # interactive review
owb migrate ./output --accept-all # batch mode
owb migrate ./output --dry-run    # preview without writing
```

### `owb ecc update` — Sync Upstream ECC Content

Fetches the latest Everything Claude Code catalog, diffs against your vendored copy, runs the security scanner, and lets you accept or reject each update.

```bash
owb ecc update                    # interactive review
owb ecc update --accept-all       # auto-accept clean files
owb ecc status                    # show pinned commit, flag history
```

### `owb security scan` — Three-Layer Content Scanner

```bash
owb security scan ./path          # scan file or directory
owb security scan ./path --layers 1,2   # structural + pattern only
owb security scan ./path -o report.json # write JSON report
```

### `owb update` — Multi-Source Content Update

Updates content from named upstream sources. Replaces the single-source `owb ecc update` path with a config-driven pipeline supporting arbitrary sources.

```bash
owb update ecc                    # update ECC source
owb update <source>               # update any configured source
owb ecc update                    # backward-compatible alias
```

### `owb eval` — Skill Evaluation

Evaluates skills using a multi-stage pipeline: classify, generate tests, execute against baseline and candidate, score, and decide.

```bash
owb eval ./path/to/skill          # evaluate a new skill
owb eval ./path/to/skill --compare  # compare against existing version
```

### `owb metrics` — Token Tracking and Cost Analysis

```bash
owb metrics tokens                              # consumption report
owb metrics tokens --format json --since 20260301  # filtered JSON
owb metrics export --format gsheets --sheet-id ID  # export to Sheets
owb metrics record --story OWB-S076             # record to local ledger
owb metrics sync --sheet-id ID                  # record + export
owb metrics forecast                            # monthly cost projection
owb metrics budget-check --threshold 200        # budget alert (exit 2 if over)
owb metrics by-story                            # cost per story ID
```

Requires `[sheets]` extra for Google Sheets or `[xlsx]` for Excel export.

## Phase Model

OWB uses a [phase model](docs/concepts/phases.md) to describe workspace maturity. Phase 0 (cold start) and Phase 1 (interactive sessions) are fully operational and represent the project's scope ceiling. The codebase is model-agnostic through LiteLLM, supporting any provider that speaks the protocol. Phase 2 and Phase 3 have been extracted to a separate Volcanix commercial product (see DRN-066).

## Security Scanner

The scanner uses a defense-in-depth approach to catch malicious content in workspace files.

| Layer | Method | What It Catches |
|-------|--------|-----------------|
| **1 — Structural** | File type, size, encoding analysis | Binary files, executables, oversized files, zero-width characters, RTL overrides, homoglyphs |
| **2 — Pattern** | Regex matching against registry patterns | Shell injection, credential harvesting, data exfiltration, prompt injection, known-malicious signatures |
| **3 — Semantic** | LLM analysis via configured model | Behavioral manipulation, social engineering, stealth language, obfuscated payloads, self-modification |

Patterns are loaded from the extensible registry. The default set (`owb-default`) includes 58 patterns across 12 categories. Add custom pattern files to the registry overlay directory for project-specific rules.

Layer 3 requires a configured model in `models.security_scan` and the `llm` extra:

```bash
pip install "open-workspace-builder[llm]"
```

Without the extra, layers 1 and 2 still provide coverage for the most common attack patterns.

## Using as a Library

OWB is designed to be used as a dependency by downstream packages. A vendor-specific wrapper can:

1. Depend on `open-workspace-builder>=0.1.0`
2. Provide a pre-baked config YAML with vendor-specific defaults
3. Register its own CLI entry point that sets `cli_name` in the Click context
4. Use OWB's evaluator, sources, and security infrastructure directly, or add vendor-specific modules on top

OWB's config system resolves paths based on the CLI name, so `cwb` loads from `~/.cwb/config.yaml` while `owb` loads from `~/.owb/config.yaml`. The `claude_md` YAML key is accepted as a backward-compatible alias for `agent_config`.

## Development

```bash
git clone https://github.com/originalrgsec/open-workspace-builder.git
cd open-workspace-builder
uv sync --all-extras

# Run tests (1253 tests)
uv run pytest tests/

# Lint
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
```

## License

[MIT](LICENSE)
