# Package Authoring

Capell treats package authoring as a platform surface, not a side effect of Laravel auto-discovery. A package should declare what it owns in `capell.json`, route runtime work through provider buckets, and keep public output safe for anonymous users and cached HTML.

## Scaffold First

Use the existing `capell:make-extension` command to create new packages:

```bash
php artisan capell:make-extension
php artisan capell:make-extension vendor/example --profile=minimal --path=packages --name="Example"
php artisan capell:make-extension vendor/example-tools --profile=full --path=packages --premium
```

Interactive mode asks for the package name, scaffold profile, target directory, and display name when they are missing. Non-interactive scripts must pass `package`, `--profile`, and `--path`.

## Profiles

`minimal` creates the smallest useful package:

- Composer metadata and PSR-4 autoloading.
- Manifest v3 with all provider buckets present and only the runtime bucket populated.
- A runtime provider extending `AbstractPackageServiceProvider`.
- Translations, README, and a manifest/public-cache safety test.

`full` creates live, harmless examples:

- Metadata, install, runtime, admin, and frontend providers.
- A package-owned console command.
- Settings registration with translated labels.
- A safe frontend render hook backed by an Action and Data object.
- Frontend asset registration.
- Tests for manifest validity, provider bucket shape, and unsafe public-output regressions.

## Safety Rules

Public package output must not expose admin or editor details. Render hooks and Blade views should receive hydrated public state from Actions or view models, not query models directly. Cached HTML must remain safe to serve to anonymous visitors, signed-in users, admins, crawlers, and static exports.

Use the generated tests as the baseline, then add package-specific tests for settings, commands, admin surfaces, routes, migrations, and frontend rendering before release.

## Lifecycle Actions

Install, setup, and after-install work that can run from the web UI or Marketplace must be implemented as Actions, not nested Artisan commands. Add lifecycle classes that implement `Capell\Core\Contracts\PackageLifecycleAction` and declare them in `capell.json`:

```json
{
    "actions": {
        "install": "Vendor\\Example\\Actions\\InstallExamplePackageAction",
        "setup": "Vendor\\Example\\Actions\\SetupExamplePackageAction",
        "afterInstall": "Vendor\\Example\\Actions\\AfterInstallExamplePackageAction"
    }
}
```

Console commands may remain as thin CLI adapters for developers, but they should delegate to the same Action. Web-triggered lifecycle work will prefer these Actions and will not fall back to legacy commands.

## Install In An App

Require published packages normally:

```bash
composer require vendor/example
php artisan optimize:clear
php artisan capell:package-cache:clear
```

For local development, point the app at a sibling package repository:

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "../capell-packages-4/packages/*",
            "options": {
                "symlink": true
            }
        }
    ]
}
```

Then require the package by Composer name:

```bash
composer require vendor/example:@dev
```

Use the wildcard path repository when one app should load several local packages. For one package only, this is enough:

```bash
composer config repositories.vendor-example path ../capell-packages-4/packages/example
composer require vendor/example:@dev
```

## Share On Marketplace

Before sharing a package, tag a release, run package tests, and audit the manifest:

```bash
php artisan capell:extension-audit ../capell-packages-4/packages/example
```

Marketplace-ready packages should have aligned `composer.json` and `capell.json` names, clear `marketplace` metadata, screenshots where useful, support notes in the README, and a normal Composer install path through Packagist, private Composer, VCS, or another configured repository.

## Read Next

- [Packages](../packages/README.md)
- [How to create a Capell extension](../packages/how-to-create-a-capell-extension.md)
- [Package anatomy](../packages/package-anatomy.md)
- [Package checklist](../packages/package-checklist.md)
- [Extension point chooser](../packages/extension-point-chooser.md)
- [Build an extension end to end](../packages/build-extension-end-to-end.md)