# Package Catalogue

> How Strutvane is built for 100+ packages, how one catalogue feeds the installer, node strut install and these docs, and the status of every first-party package (in development, planned, shelved or retired).

Source: https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/catalogue/

Strutvane's core is small on purpose. Everything else (a log viewer, billing, search, charts) is a **package**: a separate npm package that adds one feature to your app and installs itself completely with one command. There will be **more than 100** of them over time, so everything that deals with "the list of packages" is driven by data, not by code that names each package.

> **Coming from Laravel?**
> `node strut install:billing` is like `composer require laravel/cashier` followed by `php artisan cashier:install`, in one step: it adds the package, its config, `.env` keys, migrations, routes and screens. `node strut add` is an interactive picker over the whole catalogue, and the installer's "Extra features" question is the same picker at project creation. First-party packages are `@strutvane/<name>`; community packages are `strutvane-<name>`, like Spatie's packages next to Laravel's own.

> **Coming in 0.2**
> The package manifest and the catalogue index are part of phase 1 (0.2). The installer side (question 22 reading a catalogue, filtering it and asking packages' follow-up questions) is proven in a prototype (spike 13, with a 33-entry sample catalogue of packages that don't exist yet). `node strut install:<name>`, `node strut add`, the hub's catalogue build and the conformance kits are designed, not built yet. No package below is released.

## The smallest example

Add a package to an app you already have:

```bash
node strut install:log-viewer
```

**What it will do** (something like this; the exact wording isn't final):

```text
  ✔ Added @strutvane/log-viewer with npm
  ✔ Registered its provider in bootstrap/providers.ts
  ✔ Added its sidebar entry (Logs)

  Next: open http://localhost:3000/_strutvane/logs
```

With Docker, type the same command on your computer: like every `node strut` command, it runs inside the app container. See [Docker](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/docker/).

## Three ways in, one installer

Every way of adding a package runs the same **installer protocol** (the fixed steps every package follows to install itself), so the result is identical whichever you use:

| Way | When you'd use it |
|---|---|
| Installer question 22, "Extra features" | While creating the app with `npm create strutvane@latest` |
| `node strut install:<name>` | You know the package you want |
| `node strut add` | You want to browse or search the catalogue |

**Install order never changes the result:** installing billing before search gives the same app as search before billing.

### What `install:<name>` does

1. Adds the package with npm.
2. Asks the package's own follow-up questions, if it has any (billing asks "Stripe or Paddle?").
3. Writes its config file (`config/<name>.ts`) and adds its `.env` keys, with secrets generated into `.env` only, never into `.env.example`.
4. Copies its migrations into `database/migrations/`, where they become ordinary migrations of your app.
5. Registers its provider in `bootstrap/providers.ts`, which adds its routes, commands, screens and sidebar entries.

## Choosing packages while you create the app

Question 22 never shows a flat list of 100+ packages. It shows a short **popular** list, grouped, then offers to search the rest:

```text
? Extra features? (popular first; space to toggle, enter to confirm)
  Operations     log viewer (selected), queue dashboard, inspector, health
  Data           charts and dashboards, search, import/export, API explorer
  Back office    activity log, settings, media library, PDF, privacy, backups
  Integrations   feature flags, webhooks, GraphQL, realtime, notification channels
  Money          billing, invoicing
  AI             AI SDK, MCP server
? Search the full catalogue for more? (7 more packages)
```

(The groups are from the blueprint; the screen above is a sketch of the prototype's two prompts.)

- The **log viewer** is pre-selected.
- Only packages that are **published** and **compatible** with the framework version being installed are offered. That's why the list grows release by release without the installer changing.
- When you pick a package that has follow-up questions, they come right after, in both Recommended and Custom mode.

The same choices as flags, for CI or scripts:

```bash
npm create strutvane@latest my-app -- --features log-viewer,billing,search --feature-option billing.provider=paddle --yes
```

`--features none` picks nothing. `--feature-option <id>.<question>=<value>` answers a picked package's follow-up question; leave it out to take the package's default.

## How it works: one manifest, one index

### One manifest per package

Every package describes itself in a `strutvane` block in its own `package.json`. Reading it runs no code.

> **Coming in 0.2**
> The fields are decided; the exact shape below is a sketch and not final.

```json title="package.json"
{
  "name": "@strutvane/billing",
  "version": "0.2.0",
  "peerDependencies": { "@strutvane/framework": "^0.2" },
  "strutvane": {
    "id": "billing",
    "name": "Billing",
    "description": "Subscriptions, plans and a customer portal",
    "category": "money",
    "tags": ["subscriptions", "stripe", "paddle"],
    "framework": "^0.2",
    "installs": {
      "config": ["config/billing.ts"],
      "env": ["BILLING_PROVIDER"],
      "migrations": true,
      "routes": true,
      "screens": true,
      "sidebar": ["Billing"]
    },
    "questions": [
      {
        "id": "provider",
        "label": "Billing: which payment provider?",
        "default": "stripe",
        "choices": [
          { "value": "stripe", "label": "Stripe" },
          { "value": "paddle", "label": "Paddle (merchant of record)" }
        ]
      }
    ],
    "docs": "https://vishwajit-vm.github.io/strutvane-docs/docs/latest/packages/billing/"
  }
}
```

Follow-up questions are **declarative**: a label, choices and a default, as data. Nothing from a package runs before it is installed.

### One catalogue index

CI in the Strutvane hub builds one file, `catalogue.json`, from the published manifests. The installer, `node strut install`, `node strut add`, the package pages of these docs and the AI agent tools all read that one file, so a new package appears everywhere with no code change.

The index is treated as **untrusted input**. In the prototype:

- an entry with a bad shape is skipped, never offered;
- package names must be `@strutvane/<name>` or `strutvane-<name>`, so a name can't sneak in a path like `../`;
- a follow-up question that asks for a key, secret, token or password is refused: secrets are never typed into the installer, they go into `.env` later.

### One conformance kit per kind of package

Before a package can be listed, its CI must pass:

- the **installer-protocol test** (it installs itself completely, in any order);
- the **security attack kit** for its surface (for example tenancy, uploads or injection tests);
- a type-check against the current framework.

Designs also pass `designConformance()` (see [Designs](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/designs/)).

### Versions

- The **core train** moves in lockstep before 1.0: framework, auth, ui, the first-party designs, create-strutvane and the app skeleton all release the same version.
- **Add-ons** release on their own version numbers, with a peer range on the framework (`^0.2`). The catalogue records which add-on versions work with which framework line.

### Community packages

Community packages are named `strutvane-<name>`, use the same manifest and get a **verified** badge in the catalogue once they pass the same kits.

## Every first-party package

These cards come from **one data file** (`src/data/packages.json` in the docs repository). The same file feeds this page, its Markdown export and the release notes, so a package can never be "planned" here and "retired" somewhere else. Every card says its **status** in words:

| Status | What it means |
|---|---|
| **Available** | Released on npm, with a stable version on `latest`. Nothing is available yet: 0.2 hasn't been released. |
| **Preview** | Published for trying out (the `next` dist-tag); it may still change. |
| **In development** | Being built for the current line (phase 1, which is 0.2). |
| **Planned** | On the roadmap for a later phase. The installer offers it only once it's published. |
| **Shelved** | Explored, then put aside. It may come back later. |
| **Retired** | No longer part of Strutvane. The card says what to use instead. |

A **phase** is a step of the roadmap: phase 1 is 0.2, phase 2 is 0.3, phase 3 leads to 1.0, and phases 4 to 8 come after 1.0. Use the two filters to narrow the list; each card links to its docs page and repository when they exist. Link to one package with its anchor, for example [`#pkg-auth`](#pkg-auth).

### Core

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/auth`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/authentication/) | Sign-in, registration, password reset, email verification, 2FA, passkeys, API tokens, teams and impersonation. | In development, Phase 1 |
| [`create-strutvane`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/installation/) | The installer behind npm create strutvane@latest: questions, then a migrated, seeded app. | In development, Phase 1 |
| [`@strutvane/framework`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/framework/) | The framework: container, config, routing, controllers, validation, ORM, migrations, logging, authorization, tenancy and the node strut command line. | In development, Phase 1 |
| [`strutvane`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/strutvane/) | The small npx strutvane command: the same as node strut inside a project, a pointer to create one outside. Which repository holds it is still open. | In development, Phase 1 |
| [`@strutvane/ui`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/ui/) | The React admin's behaviour: auto CRUD screens, tables, forms, sidebar, command palette. The look comes from a design package. | In development, Phase 1 |

### Designs

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/design-crisp`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/designs/) | The default design: clean, minimal, quiet colours, dense readable tables. Default in the installer. The look is proven as a mockup (spike 19). | In development, Phase 1 |
| [`@strutvane/design-vivid`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/designs/) | A colourful design with soft-shadow cards, gradient charts and roomier spacing. The look is proven as a mockup (spike 17). | In development, Phase 1 |

### Operations

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/log-viewer`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/log-viewer/) | The logs screen at /_strutvane/logs: live tail, search and download. Logging itself is in the framework. The repository is still named strutvane-logs; it is renamed to strutvane-log-viewer (ADR-0022). | In development, Phase 1 |
| [`@strutvane/queue-dashboard`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/queue-dashboard/) | Jobs, failures, retries and scheduled tasks on one screen. | Planned, Phase 2 |
| [`@strutvane/redis`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/redis/) | Redis and Valkey drivers for cache, queue, locks, sessions, rate limits and broadcasting. | Planned, Phase 2 |
| `@strutvane/health` | Scheduled health checks, history, alerts and an uptime endpoint. | Planned, Phase 3 |
| [`@strutvane/inspector`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/inspector/) | A development recorder for requests, queries, jobs, mail and policy decisions. | Planned, Phase 3 |
| [`@strutvane/observability`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/observability/) | OpenTelemetry export and a self-hosted metrics dashboard. | Planned, Phase 3 |
| [`@strutvane/backup`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/backup/) | Encrypted database and storage backups, with restore drills. | Planned, Phase 4 |

### Data

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/charts`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/charts/) | Chart and KPI widgets suggested from your tables, fed by a policy- and tenant-safe aggregate endpoint. | Planned, Phase 3 |
| [`@strutvane/dashboards`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/dashboards/) | Dashboard pages, per-user layouts, filters and scheduled digests. | Planned, Phase 3 |
| [`@strutvane/files`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/files/) | S3 and Azure disks, presigned and resumable uploads, virus scanning and quotas. | Planned, Phase 3 |
| [`@strutvane/import-export`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/import-export/) | CSV and XLSX import with column mapping and a dry run; policy-aware exports. | Planned, Phase 3 |
| [`@strutvane/search`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/search/) | Meilisearch and Typesense engines, and hybrid vector search. | Planned, Phase 3 |
| `@strutvane/api-explorer` | An interactive OpenAPI explorer with try-it-out. | Planned, Phase 4 |
| `@strutvane/graphql` | A GraphQL API generated from your models, policies and teams. | Planned, Phase 5 |

### Back office

| Package | What it does | Status |
|---|---|---|
| `@strutvane/activity-log` | Per-record change history, an activity feed and an audit explorer. | Planned, Phase 4 |
| `@strutvane/comments` | Threaded comments, mentions and reactions on any record. | Planned, Phase 4 |
| `@strutvane/media-library` | Attachments, image conversions, responsive images and a media manager. | Planned, Phase 4 |
| `@strutvane/pdf` | PDFs such as invoices and reports from React templates. | Planned, Phase 4 |
| `@strutvane/privacy` | GDPR data export and erasure, consent and retention. | Planned, Phase 4 |
| `@strutvane/settings` | Typed, database-backed app, team and user settings with generated pages. | Planned, Phase 4 |
| `@strutvane/tags` | Team-scoped, typed tags on any model. | Planned, Phase 4 |
| `@strutvane/mail-templates` | Editable, per-team transactional mail templates. | Planned, Phase 6 |
| `@strutvane/resource-views` | Kanban board and calendar views over any resource. | Planned, Phase 6 |

### Identity

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/social-login`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/social-login/) | Sign in with Google, Microsoft, GitHub and Apple. Moved up to phase 2 (blueprint §10); the master list still says 5. | Planned, Phase 2 |
| [`@strutvane/oauth-server`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/oauth-server/) | An OAuth 2.1 provider, so other apps can sign in with yours. | Planned, Phase 5 |
| [`@strutvane/sso`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/sso/) | Per-team OIDC and SAML single sign-on, SCIM and domain verification. | Planned, Phase 5 |

### Integrations

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/feature-flags`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/feature-flags/) | Typed feature flags per user, team or plan. | Planned, Phase 5 |
| [`@strutvane/webhooks`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/webhooks/) | Signed outgoing webhooks with retries, and verification of incoming ones. | Planned, Phase 5 |
| [`@strutvane/notification-channels`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/notification-channels/) | SMS, Slack, Teams, web push and WhatsApp next to email, with a preference centre. | Planned, Phase 6 |
| [`@strutvane/realtime`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/realtime/) | A WebSocket server, channels and live tables. | Planned, Phase 6 |
| `@strutvane/geo` | Spatial columns, distance queries, geocoding and map views. | Planned, Phase 8 |

### Money

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/billing`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/billing/) | SaaS subscriptions, seats and entitlements per team. | Planned, Phase 6 |
| `@strutvane/invoicing` | Numbered invoices with tax, credit notes and PDFs. | Planned, Phase 6 |
| `@strutvane/payments` | One-off payments from your own customers through a hosted checkout. | Planned, Phase 8 |

### AI and automation

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/agent-tools`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/agent-tools/) | AGENTS.md, skills, a local docs MCP server and offline docs search for AI coding assistants. Moved up to phase 2 (blueprint §10); the master list still says 3. | Planned, Phase 2 |
| [`@strutvane/mcp-server`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/mcp-server/) | Lets AI agents use your app through MCP, under your policies and teams. | Planned, Phase 5 |
| [`@strutvane/ai`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/ai/) | AI model calls, structured output, embeddings and policy-bound agent tools. | Planned, Phase 7 |
| [`@strutvane/workflows`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/workflows/) | Durable workflows, approvals, timers and state machines. | Planned, Phase 7 |

### Content

| Package | What it does | Status |
|---|---|---|
| `@strutvane/cms` | Pages, blocks, menus, redirects, SEO and a sitemap. | Planned, Phase 7 |
| `@strutvane/form-builder` | Forms designed by admins, and custom fields per team. | Planned, Phase 7 |
| `@strutvane/translations` | Database-backed UI strings and translatable record fields. | Planned, Phase 7 |

### Testing

| Package | What it does | Status |
|---|---|---|
| [`@strutvane/browser-testing`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/browser-testing/) | Playwright fixtures for testing the real UI in a browser. | Planned, Phase 7 |

### Retired and shelved

| Package | What it does | Status |
|---|---|---|
| [`design-glass`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/designs/) | A translucent "glass" design direction, explored as a mockup (spike 18). Shelved on 2026-11-15 in favour of Crisp and Vivid. It is the first candidate for a future design package. | Shelved |
| [`@strutvane/core`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/) | v1's kernel: container, providers, config, env, errors, events and hooks. Replaced by: @strutvane/framework/core. The repository was archived on GitHub on 2026-11-15. The npm name is deprecated with a pointer once framework v2 is published. | Retired |
| [`@strutvane/contracts`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/) | v1's shared types and wire protocols. Replaced by: @strutvane/framework/contracts. The repository was archived on GitHub on 2026-11-15. The npm name is deprecated with a pointer once framework v2 is published. | Retired |
| [`@strutvane/cli`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/) | v1's command line (the sv command). Replaced by: @strutvane/framework/console (run as node strut). The repository was archived on GitHub on 2026-11-15. The npm name is deprecated with a pointer once framework v2 is published. The framework names this subpath console, not cli. | Retired |
| [`@strutvane/devkit`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/) | v1's SDK for installers, generators and plugins. Replaced by: @strutvane/framework/devkit. The repository was archived on GitHub on 2026-11-15. The npm name is deprecated with a pointer once framework v2 is published. | Retired |
| [`@strutvane/logs`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/logging/) | v1's logging package: the pipeline and the viewer in one. Replaced by: Logging in @strutvane/framework (ADR-0022), plus @strutvane/log-viewer for the screen. | Retired |
| [`launcher`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/) | v1's separate launcher and release-channel logic (pnpm sv, @next-only starter). Replaced by: node strut (strut.js in the app) and npm create strutvane@latest. | Retired |
| [`registry-compiler`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/migrations/) | v1's registry compiler, which built the app from model files. Replaced by: Migrations as the source of truth, replayed into types and resources.json by node strut migrate. | Retired |
| [`field-spec-parser`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/migrations/) | v1's command-line field specs (title:string(120)) for generating models. Replaced by: Columns written in migrations with the Schema builder (node strut make:migration). | Retired |
| [`upgrade-merge`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/upgrade/) | v1's upgrade command and its three-way merge of generated files. Replaced by: Owned files are never overwritten: auto() picks up new columns, and the upgrade guide lists every change. | Retired |
| [`better-auth-default`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/authentication/) | Better Auth as v1's default identity engine. Replaced by: @strutvane/auth's own engine, with its tables as ordinary migrations in your app. The superseding ADR (for ADR-0005 and ADR-0013) is still to be written. | Retired |

> **Coming in 0.3 and later**
> Packages in phase 2 come in 0.3, phase 3 before 1.0, and phases 4 to 8 after 1.0. None of them is in 0.2. The installer only offers a package once it is published, so in 0.2 the "Extra features" question offers only what has shipped.

## Common mistakes

### "is not an available package"

```text
These options do not work together:
  - --features "billing" is not an available package (unknown, unpublished, or not for this framework version). Search with: node strut add

Run with --help to see every option.
```

**Why:** the id is misspelt, the package isn't published yet, or it doesn't support your framework version.

**Fix:** search the catalogue for the right id, and check the package's phase above:

```bash
node strut add
```

### My `--feature-option` is refused

```text
These options do not work together:
  - --feature-option billing.provider=braintree is not a choice. Use one of: stripe, paddle

Run with --help to see every option.
```

**Why:** follow-up questions only accept the choices the package declares.

**Fix:** use one of the listed values:

```bash
npm create strutvane@latest my-app -- --features billing --feature-option billing.provider=paddle --yes
```

### "belongs to no picked feature with that question"

```text
These options do not work together:
  - --feature-option billing.provider belongs to no picked feature with that question

Run with --help to see every option.
```

**Why:** you answered a question for a package you didn't pick.

**Fix:** add the package to `--features`, or drop the option.

### My options were ignored

**Why:** with `npm create`, flags before `--` are kept by npm itself and never reach the installer.

**Fix:** put the installer's flags after `--`:

```bash
npm create strutvane@latest my-app -- --features search --yes
```

### I edited a package's files and lost my changes

**Why:** files under `node_modules/` belong to npm and are replaced on every install or upgrade.

**Fix:** change the package's behaviour through the files it copied into your app (`config/<name>.ts`, its migrations, owned screens) or through its documented options.

## Next steps

- [Installation](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/installation/): question 22 and every other installer question.
- [Designs](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/designs/): the design packages.
- [`@strutvane/log-viewer`](https://vishwajit-vm.github.io/strutvane-docs/docs/0.2.x/packages/log-viewer/): the package every new app starts with.
