@polterware/polterbase 0.1.2

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,283 @@
+# @polterware/polterbase
+
+[![npm version](https://img.shields.io/npm/v/%40polterware%2Fpolterbase.svg)](https://www.npmjs.com/package/@polterware/polterbase)
+[![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.
+
+Polterbase is a productivity layer on top of the official `supabase` CLI. Instead of memorizing command trees, you choose categories, build commands interactively, attach global flags, and pin common workflows for one-click reuse.
+
+## Features
+
+- **Interactive Command Builder**: Guided flow for command + subcommand + extra args
+- **Supabase Command Discovery**: Organized by practical categories
+- **Global Flags Picker**: Add common global flags in one step
+- **Pinned Commands**: Save successful command combinations for faster repetition
+- **Custom Command Mode**: Run raw Supabase arguments like `-v` or `status -o json`
+- **Shell Execution**: Executes your local `supabase` binary directly
+- **TypeScript-based CLI**: Strongly typed internal implementation
+
+---
+
+## Installation
+
+### Run without installing globally
+
+```bash
+npx @polterware/polterbase
+```
+
+### Install globally
+
+```bash
+npm install -g @polterware/polterbase
+```
+
+Then run:
+
+```bash
+polterbase
+```
+
+`polterbase` is a global CLI tool. Do not add it to `dependencies` or `devDependencies` of app projects.
+
+---
+
+## Requirements
+
+- **Node.js**: `>= 18`
+- **Supabase CLI**: installed and available in `PATH`
+
+Check your environment:
+
+```bash
+node -v
+supabase --version
+```
+
+Install Supabase CLI (official docs):
+
+- [Supabase CLI Guide](https://supabase.com/docs/guides/cli)
+
+---
+
+## Quick Reference
+
+### Execution Model
+
+Polterbase always executes commands as:
+
+```bash
+supabase <command> <extra-args> <global-flags>
+```
+
+### Typical Flow
+
+1. Choose a category
+2. Choose a base command
+3. Add optional extra args
+4. Pick optional global flags
+5. Confirm and execute
+6. Optionally pin command after success
+
+---
+
+## 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
+
+After a successful execution, Polterbase can pin the command for quick reuse.
+
+Pinned items appear at the top of the main menu and can be removed via:
+
+- `Manage Pinned Commands`
+
+Pins are persisted locally using OS-level app config storage.
+
+---
+
+## Usage Examples
+
+### 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 or not in your `PATH`.
+
+Fix:
+
+1. Install Supabase CLI
+2. Restart terminal
+3. Run `supabase --version`
+
+### Command exits with non-zero code
+
+Polterbase forwards execution to Supabase CLI. Use `--debug` and re-run to inspect detailed logs.
+
+### Pinned commands are missing
+
+Pins are only suggested after successful runs. Confirm the pin prompt after a successful command.
+
+### Interactive prompt did not open correctly
+
+Ensure you are running in a terminal that supports interactive TTY prompts.
+
+---
+
+## Security Notes
+
+- Polterbase 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/polterbase](https://github.com/polterware/polterbase)
+
+---
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+[Polterware](https://www.polterware.com)

package/dist/index.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { spawn } from "child_process";
+import Conf from "conf";
+var config = new Conf({ projectName: "polterbase" });
+var supabaseCommands = {
+  "Quick Start": [
+    { value: "bootstrap", label: "bootstrap - Bootstrap a Supabase project from a starter template" }
+  ],
+  "Local Development": [
+    { value: "db", label: "db - Manage Postgres databases" },
+    { value: "gen", label: "gen - Run code generation tools" },
+    { value: "init", label: "init - Initialize a local project" },
+    { value: "inspect", label: "inspect - Tools to inspect your Supabase project" },
+    { value: "link", label: "link - Link to a Supabase project" },
+    { value: "login", label: "login - Authenticate using an access token" },
+    { value: "logout", label: "logout - Log out and delete access tokens locally" },
+    { value: "migration", label: "migration - Manage database migration scripts" },
+    { value: "seed", label: "seed - Seed a Supabase project from supabase/config.toml" },
+    { value: "services", label: "services - Show versions of all Supabase services" },
+    { value: "start", label: "start - Start containers for Supabase local development" },
+    { value: "status", label: "status - Show status of local Supabase containers" },
+    { value: "stop", label: "stop - Stop all local Supabase containers" },
+    { value: "test", label: "test - Run tests on local Supabase containers" },
+    { value: "unlink", label: "unlink - Unlink a Supabase project" }
+  ],
+  "Management APIs": [
+    { value: "backups", label: "backups - Manage Supabase physical backups" },
+    { value: "branches", label: "branches - Manage Supabase preview branches" },
+    { value: "config", label: "config - Manage Supabase project configurations" },
+    { value: "domains", label: "domains - Manage custom domain names for Supabase projects" },
+    { value: "encryption", label: "encryption - Manage encryption keys of Supabase projects" },
+    { value: "functions", label: "functions - Manage Supabase Edge functions" },
+    { value: "network-bans", label: "network-bans - Manage network bans" },
+    { value: "network-restrictions", label: "network-restrictions - Manage network restrictions" },
+    { value: "orgs", label: "orgs - Manage Supabase organizations" },
+    { value: "postgres-config", label: "postgres-config - Manage Postgres database config" },
+    { value: "projects", label: "projects - Manage Supabase projects" },
+    { value: "secrets", label: "secrets - Manage Supabase secrets" },
+    { value: "snippets", label: "snippets - Manage Supabase SQL snippets" },
+    { value: "ssl-enforcement", label: "ssl-enforcement - Manage SSL enforcement configuration" },
+    { value: "sso", label: "sso - Manage Single Sign-On (SSO) authentication for projects" },
+    { value: "storage", label: "storage - Manage Supabase Storage objects" },
+    { value: "vanity-subdomains", label: "vanity-subdomains - Manage vanity subdomains for Supabase projects" }
+  ],
+  "Additional Commands": [
+    { value: "completion", label: "completion - Generate the autocompletion script" },
+    { value: "help", label: "help - Help about any command" }
+  ]
+};
+var globalFlags = [
+  { value: "--create-ticket", label: "--create-ticket (Create support ticket on error)" },
+  { value: "--debug", label: "--debug (Output debug logs)" },
+  { value: "--experimental", label: "--experimental (Enable experimental features)" },
+  { value: "--yes", label: "--yes (Answer yes to all prompts)" }
+];
+function getPinnedCommands() {
+  return config.get("pinnedCommands") || [];
+}
+function addPinnedCommand(cmd) {
+  const current = getPinnedCommands();
+  if (!current.includes(cmd)) {
+    config.set("pinnedCommands", [...current, cmd]);
+  }
+}
+function removePinnedCommand(cmd) {
+  const current = getPinnedCommands();
+  config.set("pinnedCommands", current.filter((c) => c !== cmd));
+}
+async function main() {
+  console.clear();
+  p.intro(`${pc.bgGreen(pc.black(" POLTERBASE "))} The ultimate modern CLI for Supabase`);
+  let shouldExit = false;
+  while (!shouldExit) {
+    const pinned = getPinnedCommands();
+    const mainOptions = [
+      { value: "Quick Start", label: "Quick Start (Bootstrap templates)" },
+      { value: "Local Development", label: "Local Development (db, init, start, etc.)" },
+      { value: "Management APIs", label: "Management APIs (projects, secrets, domains, etc.)" },
+      { value: "Additional Commands", label: "Additional Commands (help, completion)" },
+      { value: "Custom", label: "Custom Command / Check Version" }
+    ];
+    if (pinned.length > 0) {
+      mainOptions.unshift(
+        { value: "MANAGE_PINS", label: pc.magenta("\u2699\uFE0F Manage Pinned Commands") },
+        ...pinned.map((cmd) => ({ value: `PIN:${cmd}`, label: `${pc.cyan("\u{1F4CC}")} ${cmd}` })),
+        // @ts-ignore
+        { value: "SEPARATOR", label: pc.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"), disabled: true }
+      );
+    }
+    mainOptions.push({ value: "EXIT", label: pc.red("Exit Polterbase") });
+    const category = await p.select({
+      message: "What kind of Supabase command do you want to run?",
+      // @ts-ignore
+      options: mainOptions.filter((opt) => opt.value !== "SEPARATOR"),
+      maxItems: 12
+    });
+    if (p.isCancel(category) || category === "EXIT") {
+      p.cancel("See you later!");
+      process.exit(0);
+    }
+    if (category === "MANAGE_PINS") {
+      const toRemove = await p.multiselect({
+        message: "Select commands to remove from pins (Space to select):",
+        options: pinned.map((cmd) => ({ value: cmd, label: cmd })),
+        required: false
+      });
+      if (!p.isCancel(toRemove) && Array.isArray(toRemove)) {
+        toRemove.forEach((cmd) => removePinnedCommand(cmd));
+        p.log.success("Pins updated!");
+      }
+      continue;
+    }
+    let finalArgs = [];
+    let isPinnedExecution = false;
+    if (typeof category === "string" && category.startsWith("PIN:")) {
+      const cmdStr = category.replace("PIN:", "");
+      finalArgs = cmdStr.split(" ");
+      isPinnedExecution = true;
+    } else {
+      let commandValue = "";
+      if (category === "Custom") {
+        const custom = await p.text({
+          message: 'Enter your custom supabase command/flags (e.g., "-v" or "status -o json"):',
+          placeholder: "-v"
+        });
+        if (p.isCancel(custom)) continue;
+        commandValue = custom;
+      } else {
+        const options = [
+          { value: "BACK", label: pc.yellow("\u2190 Go Back") },
+          // @ts-ignore
+          ...supabaseCommands[category]
+        ];
+        const command = await p.select({
+          message: `Select a command from ${category}:`,
+          options,
+          maxItems: 11
+        });
+        if (p.isCancel(command) || command === "BACK") continue;
+        const extraArgs = await p.text({
+          message: `Any additional sub-commands or arguments for "supabase ${command}"?`,
+          placeholder: 'e.g., "push", "pull", "list" (Press Enter to skip)',
+          initialValue: ""
+        });
+        if (p.isCancel(extraArgs)) continue;
+        commandValue = `${command} ${extraArgs}`.trim();
+      }
+      const selectedFlags = await p.multiselect({
+        message: "Select any global flags you want to include (Space to select, Enter to confirm):",
+        options: globalFlags,
+        required: false
+      });
+      if (p.isCancel(selectedFlags)) continue;
+      finalArgs = commandValue.split(" ").filter(Boolean);
+      if (Array.isArray(selectedFlags) && selectedFlags.length > 0) {
+        finalArgs = finalArgs.concat(selectedFlags);
+      }
+    }
+    const finalCmdString = `supabase ${finalArgs.join(" ")}`;
+    const confirm2 = await p.confirm({
+      message: `Ready to execute: ${pc.cyan(finalCmdString)}. Continue?`,
+      initialValue: true
+    });
+    if (p.isCancel(confirm2)) continue;
+    if (!confirm2) {
+      const action = await p.select({
+        message: "Command cancelled. What next?",
+        options: [
+          { value: "RETRY", label: "Try another command" },
+          { value: "EXIT", label: "Exit" }
+        ]
+      });
+      if (action === "RETRY") continue;
+      break;
+    }
+    p.outro(`Executing: ${pc.cyan(finalCmdString)}`);
+    const child = spawn("supabase", finalArgs, {
+      stdio: "inherit",
+      shell: true
+    });
+    await new Promise((resolve) => {
+      child.on("error", (err) => {
+        console.error(pc.red(`Failed to start command: ${err.message}`));
+        resolve();
+      });
+      child.on("exit", (code) => {
+        if (code !== 0) {
+          console.log(pc.red(`
+Command exited with code ${code}`));
+        } else {
+          console.log(pc.green("\nCommand finished successfully!"));
+          if (!isPinnedExecution && !getPinnedCommands().includes(finalArgs.join(" "))) {
+            setTimeout(async () => {
+              const shouldPin = await p.confirm({
+                message: pc.magenta("Pin this command for easy access next time?"),
+                initialValue: false
+              });
+              if (shouldPin && !p.isCancel(shouldPin)) {
+                addPinnedCommand(finalArgs.join(" "));
+                p.log.success("Pinned! You can find it at the top of the main menu.");
+              }
+            }, 100);
+          }
+        }
+        resolve();
+      });
+    });
+    const next = await p.confirm({
+      message: "Do you want to run another command?",
+      initialValue: true
+    });
+    if (!next || p.isCancel(next)) {
+      shouldExit = true;
+    } else {
+      console.clear();
+      p.intro(`${pc.bgGreen(pc.black(" POLTERBASE "))} Continue managing your Supabase project`);
+    }
+  }
+  p.outro("Thank you for using Polterbase!");
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@polterware/polterbase",
+  "version": "0.1.2",
+  "description": "A global CLI for managing Supabase CLI workflows.",
+  "type": "module",
+  "bin": {
+    "polterbase": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polterware/polterbase.git"
+  },
+  "bugs": {
+    "url": "https://github.com/polterware/polterbase/issues"
+  },
+  "homepage": "https://github.com/polterware/polterbase#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "preferGlobal": true,
+  "scripts": {
+    "dev": "tsup src/index.ts --watch --format esm --dts",
+    "build": "tsup src/index.ts --format esm --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "polterware",
+    "polterbase",
+    "cli",
+    "typescript"
+  ],
+  "author": "Polterware",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "conf": "^15.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.3.6",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.7"
+  }
+}