@polterware/polter 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Polterware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# @polterware/polter
+
+![Polter running](docs/assets/polter-hero.png)
+
+[![npm version](https://img.shields.io/npm/v/%40polterware%2Fpolter.svg)](https://www.npmjs.com/package/@polterware/polter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+
+An optimized interactive CLI for managing Supabase CLI workflows with more speed, consistency, and discoverability.
+
+Polter is a productivity layer on top of the official `supabase` CLI. Instead of memorizing command trees, you browse one unified board, add extra args interactively, attach global flags, and pin common workflows for one-click reuse.
+
+## Features
+
+- **Interactive Command Builder**: Guided flow for command + subcommand + extra args
+- **Suggested Subcommand Picker**: Select common args (for example `db pull`) from boxed sections before typing custom args
+- **Unified Command Board**: Pinned runs, pinned commands, grouped categories, and actions in boxed sections on one screen
+- **Global Flags Picker**: Add common global flags in one step
+- **Pinned Commands and Runs**: Toggle base command pins with `→` and pin exact runs after success
+- **Custom Command Mode**: Run raw Supabase arguments like `-v` or `status -o json`
+- **Built-in Self-Update**: Update Polter for the current repository or globally through npm
+- **Shell Execution**: Resolves `supabase` from the current repository first, then falls back to `PATH`
+- **TypeScript-based CLI**: Strongly typed internal implementation
+- **App Workflows**: Explicit `polter app ...` flows for repository-aware setup, linking, migrations, runtime configuration, and app installation
+
+---
+
+## Installation
+
+### Run one-off without installing
+
+```bash
+npx @polterware/polter@latest
+```
+
+### Install in a repository
+
+```bash
+npm install -D @polterware/polter
+```
+
+Then run it from that repository with:
+
+```bash
+npx polter
+```
+
+### Install globally
+
+```bash
+npm install -g @polterware/polter
+```
+
+Then run:
+
+```bash
+polter
+```
+
+Use a repository install when you want the CLI version pinned to one project.
+Use a global install when you want the same CLI version across every repository.
+
+### Update
+
+If you installed it globally, update it with:
+
+```bash
+npm install -g @polterware/polter@latest
+```
+
+If you installed it in a repository, update it there with:
+
+```bash
+npm install -D @polterware/polter@latest
+```
+
+You can also run the same update flow from inside Polter:
+
+1. Go to the `Actions` section
+2. Choose `Update Polter`
+3. Choose `Current repository` or `Global install`
+4. Confirm the npm update command
+
+---
+
+## Requirements
+
+- **Node.js**: `>= 18`
+- **Supabase CLI**: installed globally in `PATH` or locally in the current repository
+
+Check your environment:
+
+```bash
+node -v
+supabase --version
+```
+
+Install Supabase CLI (official docs):
+
+- [Supabase CLI Guide](https://supabase.com/docs/guides/cli)
+
+---
+
+## Quick Reference
+
+### App Workflows
+
+Polter keeps generic Supabase execution separate from app-specific automation.
+Use the `app` namespace when you want project-aware workflows:
+
+```bash
+polter app setup ops --path .
+```
+
+```bash
+polter app link ops --path .
+```
+
+```bash
+polter app migrate ops push --path .
+```
+
+```bash
+polter app configure ops --path .
+```
+
+```bash
+polter app install ops
+```
+
+```bash
+polter app update ops
+```
+
+`setup ops` installs dependencies, collects Supabase connection data, links the project, pushes migrations, and writes the runtime bootstrap payload used by the desktop app.
+
+`configure ops` refreshes the runtime connection payload without reinstalling the app.
+
+`install ops` is currently macOS-only. By default it resolves the latest GitHub release from `polterware/ops`, accepts `--version <version>` to pin a release, and still supports `--artifact-url` or `POLTER_OPS_MACOS_ARTIFACT_URL` as manual overrides.
+
+`update ops` is also macOS-only. It replaces the installed `ops.app` with a newer release while preserving the persisted runtime configuration, local settings, and Supabase session state stored outside the app bundle.
+
+Use `POLTER_OPS_GITHUB_REPO=owner/repo` when you need to resolve releases from a fork or a different repository.
+
+### Execution Model
+
+Polter executes workflow commands as:
+
+```bash
+supabase <command> <extra-args> <global-flags>
+```
+
+The self-update action is the only built-in exception and can run one of:
+
+```bash
+npm install -g @polterware/polter@latest
+```
+
+```bash
+npm install -D @polterware/polter@latest
+```
+
+### Typical Flow
+
+1. Choose a command from the unified board
+2. Optionally pin/unpin with `→`
+3. Choose suggested args or type custom extra args
+4. Pick optional global flags
+5. Confirm and execute
+
+---
+
+## Command Categories
+
+### Quick Start
+
+- `bootstrap` - Bootstrap a Supabase project from a starter template
+
+### Local Development
+
+- `db` - Manage Postgres databases
+- `gen` - Run code generation tools
+- `init` - Initialize a local project
+- `inspect` - Inspect Supabase project resources
+- `link` - Link local project to remote Supabase project
+- `login` - Authenticate with Supabase access token
+- `logout` - Remove local auth token
+- `migration` - Manage migration scripts
+- `seed` - Seed project from `supabase/config.toml`
+- `services` - Show local service versions
+- `start` - Start local Supabase containers
+- `status` - Show local container status
+- `stop` - Stop local Supabase containers
+- `test` - Run tests against local stack
+- `unlink` - Unlink local project
+
+### Management APIs
+
+- `backups`
+- `branches`
+- `config`
+- `domains`
+- `encryption`
+- `functions`
+- `network-bans`
+- `network-restrictions`
+- `orgs`
+- `postgres-config`
+- `projects`
+- `secrets`
+- `snippets`
+- `ssl-enforcement`
+- `sso`
+- `storage`
+- `vanity-subdomains`
+
+### Additional Commands
+
+- `completion` - Generate shell completion script
+- `help` - Show Supabase command help
+
+### Custom Command / Check Version
+
+Use this mode for free-form args like:
+
+- `-v`
+- `status -o json`
+- `db pull`
+- `projects list`
+
+---
+
+## Global Flags
+
+Available global flags in the interactive selector:
+
+- `--create-ticket` - Create support ticket on error
+- `--debug` - Enable debug logs
+- `--experimental` - Enable experimental features
+- `--yes` - Auto-confirm prompts
+
+---
+
+## Pinned Commands
+
+Polter supports two pinned sections at the top of the main menu:
+
+- `Pinned Runs` for exact commands like `db pull --debug`
+- `Pinned Commands` for base commands like `db` or `start`
+
+The main menu and the suggested-args screen group related options into boxed sections so pinned items, command groups, and actions stay visually separated.
+
+Use `→` on a selected base command to pin or unpin it.
+Use `→` on the suggested subcommand screen to pin exact runs like `db pull` before executing.
+After a successful execution, Polter can also pin that exact command into `Pinned Runs`.
+
+Pins are persisted locally using OS-level app config storage.
+
+---
+
+## Usage Examples
+
+### Bootstrap Ops from source
+
+```bash
+polter app setup ops --path /absolute/path/to/ops
+```
+
+### Reconfigure an installed Ops app
+
+```bash
+polter app configure ops
+```
+
+### Install the latest released Ops app
+
+```bash
+polter app install ops
+```
+
+Install a specific release:
+
+```bash
+polter app install ops --version 1.0.0
+```
+
+Update an existing installation without re-running runtime configuration:
+
+```bash
+polter app update ops
+```
+
+### Check Supabase CLI version
+
+Interactive path:
+
+1. `Custom Command / Check Version`
+2. Input: `-v`
+
+Executed command:
+
+```bash
+supabase -v
+```
+
+### Start local stack with debug
+
+Interactive path:
+
+1. `Local Development`
+2. Command: `start`
+3. Extra args: none
+4. Flags: `--debug`
+
+Executed command:
+
+```bash
+supabase start --debug
+```
+
+### List projects
+
+Interactive path:
+
+1. `Management APIs`
+2. Command: `projects`
+3. Extra args: `list`
+
+Executed command:
+
+```bash
+supabase projects list
+```
+
+### Run DB pull and auto-confirm prompts
+
+Interactive path:
+
+1. `Local Development`
+2. Command: `db`
+3. Extra args: `pull`
+4. Flags: `--yes`
+
+Executed command:
+
+```bash
+supabase db pull --yes
+```
+
+---
+
+## Troubleshooting
+
+### `supabase: command not found`
+
+Supabase CLI is not installed in the current repository and is not available in your `PATH`.
+
+Fix:
+
+1. Install Supabase CLI globally or in the current repository
+2. Restart terminal
+3. Run `supabase --version`
+
+### Command exits with non-zero code
+
+Polter forwards execution to Supabase CLI. Use `--debug` and re-run to inspect detailed logs.
+
+### Pinned commands are missing
+
+Pins are managed directly in the board. Select a base command and press `→` to pin it, or pin an exact run after a successful execution.
+
+### Interactive prompt did not open correctly
+
+Ensure you are running in a terminal that supports interactive TTY prompts.
+
+---
+
+## Security Notes
+
+- Polter executes local shell commands through your installed Supabase CLI.
+- Keep Supabase tokens out of shared shells and CI logs.
+- Prefer short-lived tokens and least-privileged project access.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit changes with clear messages
+4. Open a pull request
+
+Repository:
+
+- [polterware/polter](https://github.com/polterware/polter)
+
+---
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+[Polterware](https://www.polterware.com)