npm package: @scroppyisdead/savage-cli
Description: Savage is a React-centered framework inspired by Django's opinionated structure. It gives large applications a file-backed, feature-first workflow so teams can build with confidence that every feature is isolated, discoverable, and explicit about what it 
Latest version: 1.0.1

# Savage

Savage is a React-centered framework inspired by Django's opinionated structure. It gives large applications a file-backed, feature-first workflow so teams can build with confidence that every feature is isolated, discoverable, and explicit about what it shares.

## Vision

1. **Feature-first management** – Organize code, assets, and routing around features instead of technical slices. Each feature lives in a single folder that contains everything it owns.
2. **Explicit public contract** – Nothing is automatically exposed. You mark middleware, components, routes, or helpers as `public` so other features know what they can depend on.
3. **File-based organization with routing help** – Drive directory structure and (optional) routing conventions from the filesystem so large projects stay predictable.

## Core Concepts

- **Feature folders**: Each feature directory (e.g., `features/auth`) contains its UI, logic, styles, and metadata. Feature metadata defines the public contract and any exported routing.
- **Public surface**: Files named `public.*` or a `feature.config` entry describe exactly what is shareable—middleware, contexts, route handlers, utilities, etc.
- **Routing helpers**: Built-in utilities read the feature tree and produce route maps or wrappers so routing definitions stay close to their code.
- **Strict boundaries**: Imports across features are limited to declared public APIs, encouraging encapsulation and easier refactors.

## Routing & Lifecycle Automation

Feature-Org now scans every `feature.config` plus the matching `routes.tsx`, wraps each route with a `FeatureRuntimeWrapper`, and injects lifecycle hooks/policies so the runtime map stays declarative. Each feature’s metadata drives the React Router v6 tree, the lifecycle init/cleanup hooks run automatically when the route mounts/unmounts, and policy metadata is annotated so the rest of the framework can respond to auth/cache/telemetry hints.

## Feature Configuration

Every feature exposes a `feature.config` that outlines its name, versioned contract, routes, hooks, policies, and dependencies. See `FEATURE_CONFIG.md` for the full schema, examples, and CLI workflow that keeps these contracts enforced.

## Custom Templates

You can store multiple templates inside `templates/feature/<name>` and `templates/app/<name>` so teams can pull in Tailwind-ready, minimalist, or fully bespoke starters. Out of the box there’s a `default` scaffold plus a `tailwind` template that assumes Tailwind CSS classes—run `npm run savage -- generate <name> --template=tailwind` or `npm run create-app -- --template=tailwind --target=...` to copy those folders. Drop any extra template directories and document the naming convention so the CLI confidently grabs the right stack without having to delete `styles.css` manually.

## Feature Template

Use the starter in `templates/feature/` to see the structure the CLI will scaffold: placeholder `feature.config`, route helpers, public exports, lifecycle hooks, and a sample page. Copy or reference these files when building new indomitable feature folders so you keep the conventions consistent.

## CLI Commands

The CLI lives under `tooling/feature-org/` with `create-app` alongside it; caching data (contract snapshots) is stored in `.cache/feature-org/contracts`, which you can safely ignore. Once `js-yaml` and `semver` are installed (`npm install` after editing `package.json`), you can run `npm run savage -- <command>` (the `feature-org` script remains for compatibility):

- `generate <name> [--template=<name>]` copies from `templates/feature/<name>` (default: `default`) so you can bootstrap features with Tailwind, minimalist, or custom stacks instantly.
- `info [<name>] [--graph]` shows owners, dependencies, versions, exports, routes, and policies for every feature, and `--graph` emits dependency/consumer maps for architecture reviews.
- `test <name>` runs the contract-aware test harness: it loads the feature plus its declared dependencies, locates any `tests/` folders inside those features, and executes `vitest run --runInBand` against them (falls back to the whole suite if none exist).
- `check [--auto-bump] [--auto-describe]` enforces public import contracts, optionally bumps patch versions when exports change, and can auto-populate `feature.config`’s `public.exports` via `--auto-describe`.
New project? Run `npm run create-savage-app` and get prompted for Tailwind vs default before it calls the app scaffold internally. You can still call `npm run create-app -- --template=<name>` if you prefer to skip the prompt later.
- App authors may need shared providers (state, theme, API clients). Keep those in `src/core/providers` or similar, wrap `<App />` (or `<BrowserRouter>`) in `src/main.tsx`, and keep global state management outside of the feature folders. The framework leaves the choice of Redux/Zustand/context/etc. to you, but you can create helper providers in `src/core` to keep wiring consistent without scattering it across features.
- `set-default-template <app|feature> <name>` sets the default app or feature template so `npm run create-app` or `savage generate` uses that template when `--template` is omitted; defaults are stored in `.cache/feature-org/defaults.json`.

Create-app honors the stored default (tailwind, default, etc.) so you don’t need to pass `--template` every time.

Document any new CLI flows in the README/plan so contributors know to keep these commands in sync with tooling.
## Suggested Foundations

1. **CLI scaffold** – Generate new feature folders, mark public exports, and optionally inject routes or middleware hooks from the command line.
2. **Public declaration file** – A small YAML/JSON manifest per feature that names the exports, middleware, and dependencies other features can consume.
3. **Routing+lazy loading helpers** – Automatically create route objects, lazy-loadable bundles, and metadata (title, layout) from the file tree.
4. **Middleware/magic guard** – Allow features to expose middleware-like utilities (e.g., `authenticate`) in a way other features can opt into when calling the public contract.
5. **Dev tooling** – Provide diagnostics that highlight missing contracts, private imports, or feature/route collisions.

## Target Use Cases

- Large React applications that need to scale teams without entangling shared code.
- Projects that want to enforce clear ownership of middleware, utilities, and routes.
- Teams that like Django-style structure but work in a React/JS ecosystem.

## Ideas to Elevate It Further

1. **Dependency graph visualization** – Show which features depend on which public exports so architecture reviews are faster.
2. **Static analysis for contracts** – Lint imports to ensure only declared public exports are consumed, with helpful errors for violations.
3. **Feature testing harness** – Build a lightweight runner that loads only the feature and its declared dependencies for unit/e2e tests.
4. **Plugin/extension points** – Let teams hook into build tools (Webpack, Vite, etc.) so Feature-Org metadata can shape bundling, code splitting, and caching.
5. **Shared component registry** – Offer a curated, versioned public component set that can be shared between features while still tracing ownership.

## Feature Discovery & Onboarding Helpers

Run `npm run savage -- info payments` (or view a dashboard) to read every feature's `feature.config`, see public exports, dependencies, middleware, owners, and routes. The system can emit a dependency graph, highlight missing contracts, and show what other features consume that feature. This gives new contributors a quick map of the architecture and explicit contact points.

## Lifecycle Hooks Example

Features declare lifecycle hooks alongside their public contract. Example `feature.config` excerpt:

```yaml
public:
  hooks:
    init: ./bootstrap.ts
    cleanup: ./teardown.ts
    guards:
      onRouteEnter: ./guards/logRoute.ts
      onRouteLeave: ./guards/revoke.ts
version: 1.2.0
```

The framework wires those callbacks into app bootstrap or routing so `init` runs when the feature loads, `cleanup` disposes resources, and route guard hooks replay automatically whenever the consumer activates those routes. Only declared hooks are callable by other features, enforcing the explicit contract.

## Config-driven Policies

Keep runtime expectations next to the feature:

```yaml
policies:
  auth: "strong"
  cache: "no-store"
  chunkHint: "feature"
  telemetryContext: "payments"
```

Build tooling reads these declarations to inject guards (based on `auth`), set service-worker/cache headers (`cache`), prefer chunk splitting strategies (`chunkHint`), and tag telemetry (`telemetryContext`) so performance/security defaults travel with the feature.

## Feature-aware Testing

`npm run savage -- test profile` spins up only `features/profile` plus its declared public dependencies, mocking private internals. Tests run faster and stay relevant because they can only touch public APIs, and the command verifies contracts before each run.

## Observability Integrations

Large apps need traceability. Every telemetry call (logs, metrics, traces) can be annotated with the owning feature name via simple wrappers that read `feature.config`. Observability tooling can then filter by feature, route errors to the right team, and measure the impact of a single feature without losing context in a sea of shared utilities.

## Versioned Contracts

Public exports include a version, and consuming features declare the version they depend on. The CLI warns when a dependency bumps a version or removes a contract, so breaking changes are visible before deployment and co-dependent teams can coordinate updates.

## Open Source & Contribution

Feature-Org is open source, free for anyone to take, use, modify, or extend. Feel free to open issues, submit pull requests, or build custom tooling on top of the framework. Suggested contribution steps:

1. Fork the repo, create a feature branch, and follow the established feature folder conventions.
2. Run existing checks (`npm run savage -- info`, `npm run savage -- test`, lint rules) to ensure contracts and imports stay clean.
3. Document new capabilities (routes, policies, hooks) in `README.md` or `PLAN_README.md` so the vision stays aligned.
4. Submit the PR with a clear description of what changed, why, and any version bump requirements for public contracts.

Everyone is welcome to make Feature-Org stronger—just keep contracts explicit, tests targeted, and documentation up to date.
This framework is about helping teams ship big React apps without losing track of what belongs where and what can be reused. Let me know if you want a sample feature layout, CLI spec, or tooling recommendations next.