Ghost Viewer 👻

Ghost Viewer is a specialized tool designed to visualize your SST (Serverless Stack) state and "hunt" for orphaned resources in your AWS account. It provides a modern web interface to explore your local state file and compare it against live AWS resources to identify items that may have been left behind after deployments or manual removals.

Built for both SST v2 (Pulumi-based) and SST v3 (Ion).

🚀 Quick Start

Run it directly in your SST project root:

npx @_mustachio/ghost-viewer

This will:

1. Auto-detect your SST state file (supporting Ion's .sst/state.json and v2's Pulumi stacks).
2. Start a local server on port 3001.
3. Open your browser to the Ghost Viewer dashboard.

🛠 Manual Configuration

If Ghost Viewer cannot auto-detect your state file, or if you want to view a specific state file from another directory:

• Click the Settings (gear icon) in the top right of the dashboard.
• Enter the absolute or relative path to your state.json or .json Pulumi stack file.
• S3 Support: You can also provide an S3 URI (e.g., s3://my-bucket/path/to/state.json).
• Region Selection: When an S3 path is detected, a dropdown will appear to select the bucket's region (defaults to us-west-2).
• Click the checkmark to save and reload.

🔐 Prerequisites & Permissions

Ghost Viewer uses your local AWS configuration to scan for resources.

• AWS Credentials: Ensure your terminal session has active AWS credentials (e.g., run aws sso login or export your keys).
• Permissions:
  • The user/role must have tag:GetResources permissions to perform the Ghost Hunt.
  • If using an S3-hosted state file, s3:GetObject permission is required for that bucket/key.

✨ Key Features

🔍 State Explorer

Visualize your state.json or Pulumi stack file in a searchable, categorized tree or flat list view.

• Deep Linking: One-click navigation to the AWS Console for almost any resource (Lambda, S3, DynamoDB, API Gateway, EC2, VPC, etc.).
• Smart Filtering: Filter by source (AWS vs SST) or specific resource types.
• Metadata Inspection: View the full outputs and metadata for every resource managed by your stack.

🏹 Ghost Hunter

Scan your live AWS account for resources tagged with your SST app and stage to identify "orphans"—resources that exist in AWS but are no longer tracked in your local state.

• Grouped Views: See orphans categorized by resource type.
• Persistent Scans: Scan results stay active as you navigate the app.
• Wide Coverage: Detects orphans across a wide range of AWS services.

🛠 CLI First

Designed to be zero-config. It automatically resolves your app name, stage, and region by parsing .sst/stage, sst.config.ts, or your Pulumi environment.

🛠 Tech Stack

• Frontend: React (Vite), Tailwind CSS, Lucide React, Fuse.js.
• Backend: Node.js (Express), AWS SDK v3.
• Bundling: tsup for the CLI, vite for the UI.

💻 Local Development

If you want to contribute or run Ghost Viewer from source:

1. Clone the repo:

   git clone https://github.com/the-human-mustachio/ghost-viewer.git
   cd ghost-viewer

2. Install dependencies:

   npm install

3. Run in development mode:

   npm run dev

   This starts the Vite frontend (port 5173) and the Express backend (port 3001) concurrently with hot-reloading.

4. Build the project:

   npm run build

📦 Automated Releases

This project uses Semantic Release to automate versioning and publishing. To trigger a release, your commit messages must follow the Conventional Commits specification:

• feat: ...: Triggers a minor release (e.g., 1.0.0 -> 1.1.0).
• fix: ...: Triggers a patch release (e.g., 1.0.0 -> 1.0.1).
• perf: ...: Triggers a patch release.
• docs: ...: No release.
• chore: ...: No release.
• BREAKING CHANGE: ...: Triggers a major release (e.g., 1.0.0 -> 2.0.0).

To run a release manually (requires NPM_TOKEN and GITHUB_TOKEN):

npm run semantic-release

📄 License

MIT © Matt Puccio