Bolt Feature Installer

Install reusable feature folders into Expo + Supabase projects.

This package is a small CLI and feature catalogue. A feature is a folder under integrations/; installing a feature copies its payload files into a target project, writes target-side Codex instructions, and records the installed metadata in the target project's root integration.json.

The installer does not adapt application UI, install npm packages, deploy Supabase functions, or create secrets. It prepares the files and metadata that a developer or Codex can safely adapt in the target project.

Commands

Run locally from this repository:

npm install
npm run cli -- <command>

When installed as a package, use the binary directly:

bolt-feature-installer <command>

Common commands:

# List available feature folders.
npm run cli -- feature list

# Show the AI/operator usage prompt for a feature.
npm run cli -- how-to pulsar

# Install a feature into a target project.
npm run cli -- install pulsar --target ../my-expo-product

# Reinstall and allow overwriting copied files/instructions.
npm run cli -- install pulsar --target ../my-expo-product --force

# Validate that a target still contains the installed feature.
npm run cli -- validate pulsar --target ../my-expo-product

# Also run the target project's npm typecheck script during validation.
npm run cli -- validate pulsar --target ../my-expo-product --run-typecheck

# Print the target project's root integration.json registry.
npm run cli -- status --target ../my-expo-product

# Create a new source feature scaffold.
npm run cli -- feature new my-feature

# Check that a source feature has the required scaffold files.
npm run cli -- feature check-integration my-feature

What Install Creates

For a target project, install <name>:

1. loads the feature's required source contract files;
2. discovers every installable file under integrations/<name>/;
3. excludes source-only root contract files from copied payloads;
4. copies the remaining files to the same relative paths in the target project;
5. writes integrations/<name>.md in the target project;
6. creates or updates root integration.json;
7. reports missing dependency declarations and required environment variables.

Example for example-feature:

integrations/example-feature/services/exampleFeatureClient.ts
  -> services/exampleFeatureClient.ts

integrations/example-feature/supabase/functions/example-feature/index.ts
  -> supabase/functions/example-feature/index.ts

integrations/example-feature/tests/integrations/example-feature/exampleFeatureClient.test.ts
  -> tests/integrations/example-feature/exampleFeatureClient.test.ts

integrations/example-feature/instructions.md
  -> integrations/example-feature.md

integrations/example-feature/feature.json
  -> integration.json entry

integrations/example-feature/how-to.md
  -> printed by how-to, not copied

The target-side integration.json stores the installed feature name, version, target, description, installed file paths, dependency/env requirements, app-facing exports, and adaptation rules.

Feature Authoring Contract

The source catalogue is the list of direct child folders under integrations/. There is no root source catalogue file.

Every feature must contain:

integrations/<name>/
  instructions.md
  feature.json
  how-to.md

Everything else in the feature folder is payload and should mirror the target project path exactly.

integrations/<name>/supabase/functions/<name>/index.ts
  -> supabase/functions/<name>/index.ts

integrations/<name>/services/client.ts
  -> services/client.ts

integrations/<name>/tests/integrations/<name>/client.test.ts
  -> tests/integrations/<name>/client.test.ts

Ignored catalogue entries are .DS_Store, .git, and __MACOSX.

The root source-file contract lives in src/lib/source-feature-contract.ts. Catalog loading, scaffold creation, scaffold checks, and payload copy exclusion all consume that contract. Add future root source-only files there instead of duplicating filename checks across the installer.

feature.json

feature.json is the machine-readable source of truth for installed metadata.

{
  "version": "1.0.0",
  "target": "expo-supabase",
  "description": "Short description written into the target registry.",
  "requires": {
    "dependencies": ["@supabase/supabase-js"],
    "env": ["EXPO_PUBLIC_SUPABASE_URL", "EXPO_PUBLIC_SUPABASE_ANON_KEY"]
  },
  "exports": ["sendExampleFeatureMessage"],
  "rules": [
    "Application code must use sendExampleFeatureMessage().",
    "Do not expose provider API keys to Expo client code."
  ]
}

Field meanings:

• version: feature contract version recorded in target integration.json.
• target: feature family or platform marker, for example expo-supabase or pulsar.
• description: target-facing summary shown in generated docs and registry.
• requires.dependencies: packages expected in the target project package.json.
• requires.env: environment variables the target must configure or document.
• exports: app-facing functions/constants validation should find in copied TypeScript files.
• rules: adaptation constraints copied into target docs and registry.

instructions.md

instructions.md is human/Codex follow-up guidance. It is rendered into the target project as integrations/<name>.md together with generated sections for:

• installed files;
• required dependencies and whether they are missing;
• required environment variables;
• app-facing exports;
• adaptation rules from feature.json.

Use it for product-specific notes that cannot be expressed as metadata, such as expected routes, required Supabase deploy steps, or how the target application should call the installed wrapper.

how-to.md

how-to.md is the AI/operator prompt printed by how-to <name>. It is meant for the project where the feature will be applied: install commands, validation commands, adaptation constraints, and the expected final report. It is not copied into target projects.

Scaffolding

feature new <name> uses REQUIRED_INTEGRATION_PATHS in src/lib/scaffold.ts, derived from src/lib/source-feature-contract.ts.

The default scaffold creates:

integrations/<name>/
  instructions.md   # rendered from templates/integration-instructions.md
  feature.json      # rendered from templates/integration-feature.json
  how-to.md         # rendered from templates/integration-how-to.md

The scaffold config supports both files and directories:

{
  path: "feature.json",
  type: "file",
  templatePath: "templates/integration-feature.json"
}

{
  path: "services",
  type: "directory"
}

Templates currently support {{name}} replacement.

Validation

validate <name> --target <path> checks:

• every expected payload file exists in the target;
• integrations/<name>.md exists;
• root integration.json exists and contains the feature entry;
• registry metadata matches the source feature.json;
• registry file paths, dependencies, env vars, exports, and rules are complete;
• required dependency declarations exist in the target package.json;
• declared exports appear in copied TypeScript files.

With --run-typecheck, validation also runs npm run typecheck in the target project when that script exists.

Warnings do not fail the command. Errors set a non-zero exit code.

Current Features

• example-feature: mock Expo + Supabase feature used to test the install and validation flow.
• pulsar: Supabase Edge Function proxy for the Pulsar API.

Inspect available features with:

npm run cli -- feature list

Development

npm test
npm run typecheck
npm run build

The package requires Node.js 20 or newer.

The package is configured to publish to the npm registry:

{
  "publishConfig": {
    "registry": "https://registry.npmjs.org"
  }
}