pgplan 0.0.1 → 0.2.0

package/bin/pgplan

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const os = require("os");
+
+const PLATFORMS = {
+  "linux-x64": { pkg: "@pgplan/linux-x64", bin: "pgplan" },
+  "linux-arm64": { pkg: "@pgplan/linux-arm64", bin: "pgplan" },
+  "darwin-x64": { pkg: "@pgplan/darwin-x64", bin: "pgplan" },
+  "darwin-arm64": { pkg: "@pgplan/darwin-arm64", bin: "pgplan" },
+  "win32-x64": { pkg: "@pgplan/win32-x64", bin: "pgplan.exe" },
+};
+
+function getPlatformKey() {
+  const platform = os.platform();
+  const arch = os.arch();
+  return `${platform}-${arch}`;
+}
+
+function getBinaryPath() {
+  const key = getPlatformKey();
+  const entry = PLATFORMS[key];
+  if (!entry) {
+    const supported = Object.keys(PLATFORMS).join(", ");
+    console.error(
+      `pgplan: unsupported platform ${key}\nSupported: ${supported}`
+    );
+    process.exit(1);
+  }
+
+  try {
+    const pkgPath = require.resolve(`${entry.pkg}/package.json`);
+    return path.join(path.dirname(pkgPath), entry.bin);
+  } catch {
+    console.error(
+      `pgplan: platform package ${entry.pkg} not installed.\n` +
+        `Try reinstalling: npm install pgplan`
+    );
+    process.exit(1);
+  }
+}
+
+const binary = getBinaryPath();
+
+try {
+  const result = execFileSync(binary, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (e) {
+  if (e.status !== null) {
+    process.exit(e.status);
+  }
+  throw e;
+}

package/package.json

@@ -1,6 +1,28 @@
-{
-  "name": "pgplan",
-  "version": "0.0.1",
-  "description": "Compare and analyze PostgreSQL EXPLAIN plans from the CLI",
-  "private": false
-}
+{
+  "name": "pgplan",
+  "version": "0.2.0",
+  "description": "Analyze and compare PostgreSQL query plans",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobArthurs/pgplan.git"
+  },
+  "author": "Jacob Arthurs",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/JacobArthurs/pgplan/issues"
+  },
+  "homepage": "https://github.com/JacobArthurs/pgplan",
+  "bin": {
+    "pgplan": "bin/pgplan"
+  },
+  "files": [
+    "bin/**"
+  ],
+  "optionalDependencies": {
+    "@pgplan/linux-x64": "0.2.0",
+    "@pgplan/linux-arm64": "0.2.0",
+    "@pgplan/darwin-x64": "0.2.0",
+    "@pgplan/darwin-arm64": "0.2.0",
+    "@pgplan/win32-x64": "0.2.0"
+  }
+}

package/DESIGN.md

@@ -1,169 +0,0 @@
-# pgplan design
-
-## Project Goals
-
-- Compare PostgreSQL EXPLAIN plans with semantic understanding
-- Provide CLI-native analysis without browser dependency  
-- Support multiple input formats (SQL, JSON, TEXT)
-- Offer actionable optimization recommendations
-
-## Commands
-
-```text
-pgplan compare [file1] [file2] [OPTIONS]   Compare two query plans
-pgplan analyze [file] [OPTIONS]            Analyze a single query plan
-pgplan init                                Create ~/.config/pgplan/config.yml with example template
-pgplan --help                              Show help
-pgplan --version                           Show version
-```
-
-## pgplan compare [file1] [file2] [OPTIONS]
-
-### Compare Files
-
-- `file1` and `file2` are optional
-- Can be SQL files, JSON files (EXPLAIN output), or TEXT files (EXPLAIN output)
-- Either file (but not both) can be `-` to read from stdin
-- Files don't need to be the same type
-- If no files provided, enters interactive mode
-
-### Compare Options
-
-| Flag                | Description                             |
-| ------------------- | --------------------------------------- |
-| `--db <connection>` | PostgreSQL connection string            |
-| `--profile <name>`  | Use named profile from config           |
-| `--format <type>`   | Output format: `text` (default), `json` |
-
-### Compare Connection Resolution (only needed for SQL input)
-
-1. If `--db` flag provided, use it
-2. Else if `--profile` flag provided, load from config.yml
-3. Else if config.yml exists with `default_profile`, use default
-4. Else, error with helpful message
-
-### Compare Behavior
-
-Process each input independently:
-
-- SQL: requires DB connection, wraps query in `EXPLAIN (ANALYZE, FORMAT JSON)` and captures output
-- JSON: parse directly
-- EXPLAIN TEXT: parse directly
-
-Then compare the two resulting plans.
-
-### Compare Examples
-
-```bash
-# Interactive mode (no files)
-pgplan compare
-
-# From files (any combination)
-pgplan compare old.sql new.sql --db postgres://localhost/mydb
-pgplan compare prod-plan.json new-query.sql --profile dev
-
-# Read one plan from stdin
-psql -c "EXPLAIN (ANALYZE, FORMAT JSON) SELECT ..." | pgplan compare - new.sql --db postgres://localhost/mydb
-pgplan compare old-plan.json - < new-plan.json
-
-# Using default profile
-pgplan compare old.sql new.sql
-```
-
-## pgplan analyze [file] [OPTIONS]
-
-### Analyze File
-
-- `file` is optional
-- Can be a SQL file, JSON file (EXPLAIN output), or TEXT file (EXPLAIN output)
-- Use `-` for stdin
-- If no file provided, enters interactive mode
-
-### Analyze Options
-
-| Flag                | Description                             |
-| ------------------- | --------------------------------------- |
-| `--db <connection>` | PostgreSQL connection string            |
-| `--profile <name>`  | Use named profile from config           |
-| `--format <type>`   | Output format: `text` (default), `json` |
-
-### Analyze Connection Resolution (only needed for SQL input)
-
-Same as `pgplan compare`.
-
-### Analyze Behavior
-
-Process input:
-
-- SQL: requires DB connection, wraps query in `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and captures output
-- JSON: parse directly
-- EXPLAIN TEXT: parse directly
-
-Then analyze the plan and provide insights:
-
-- Execution summary (time, cost, rows)
-- Detected issues (seq scans, high filter ratios, missing indexes)
-- Node-by-node breakdown
-- Recommendations for optimization
-
-### Analyze Interactive Mode
-
-If no file provided:
-
-```text
-pgplan analyze
-
-→ Paste or type query or query plan (Ctrl+D or Ctrl+Z when done):
-[user pastes content]
-^D
-
-→ Auto-detect input type
-→ If SQL, resolve DB connection
-→ Analyze plan
-```
-
-### Analyze Examples
-
-```bash
-# Interactive mode
-pgplan analyze
-
-# Analyze SQL file
-pgplan analyze slow-query.sql --db postgres://localhost/mydb
-
-# Analyze saved EXPLAIN output
-pgplan analyze prod-slow-plan.json
-
-# Analyze from stdin
-pgplan analyze -
-
-# Pipe from psql
-psql -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT ..." | pgplan analyze -
-
-# Using profile
-pgplan analyze query.sql --profile prod
-
-# JSON output for scripting
-pgplan analyze query.sql --db postgres://localhost/mydb --format json
-```
-
-## Config File (optional)
-
-Location: `~/.config/pgplan/config.yml`
-
-```yaml
-profiles:
-  dev:
-    host: localhost
-    database: myapp_dev
-    user: postgres
-    password: dev_pass
-
-  prod:
-    host: prod.example.com
-    database: myapp_prod
-    user: readonly
-    password: prod_pass
-
-default_profile: dev
-```

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Jacob Arthurs
-
-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

@@ -1,47 +0,0 @@
-# pgplan
-
-> ⚠️ **Early Development** - Not ready for production use
-
-Compare and analyze PostgreSQL EXPLAIN plans from the CLI.
-
-## Why?
-
-Understand query performance regressions and get optimization insights without leaving your terminal.
-
-## Planned Features
-
-- [ ] EXPLAIN plan parsing (JSON, TEXT formats)
-- [ ] Intelligent plan comparison with semantic diff
-- [ ] Single plan analysis with recommendations
-- [ ] Interactive mode (paste plans directly)
-- [ ] Connection profiles for multiple databases
-- [ ] Web interface
-
-## Installation
-
-Not yet published. Clone and run locally:
-
-```bash
-git clone https://github.com/JacobArthurs/pgplan
-cd pgplan
-```
-
-## Usage (Planned)
-
-```bash
-# Compare two query plans
-pgplan compare old.sql new.sql --db postgres://localhost/mydb
-
-# Analyze a single query
-pgplan analyze slow-query.sql --profile prod
-
-# Interactive mode
-pgplan compare
-# Paste Plan A, then Plan B
-```
-
-## Development
-
-Contributions welcome! This is an early-stage project.
-
-MIT License

package/cmd/analyze.go

@@ -1,39 +0,0 @@
-/*
-Copyright © 2026 JACOB ARTHURS
-*/
-package cmd
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-)
-
-// analyzeCmd represents the analyze command
-var analyzeCmd = &cobra.Command{
-	Use:   "analyze",
-	Short: "A brief description of your command",
-	Long: `A longer description that spans multiple lines and likely contains examples
-and usage of using your command. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Println("analyze called")
-	},
-}
-
-func init() {
-	rootCmd.AddCommand(analyzeCmd)
-
-	// Here you will define your flags and configuration settings.
-
-	// Cobra supports Persistent Flags which will work for this command
-	// and all subcommands, e.g.:
-	// analyzeCmd.PersistentFlags().String("foo", "", "A help for foo")
-
-	// Cobra supports local flags which will only run when this command
-	// is called directly, e.g.:
-	// analyzeCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
-}

package/cmd/compare.go

@@ -1,39 +0,0 @@
-/*
-Copyright © 2026 JACOB ARTHURS
-*/
-package cmd
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-)
-
-// compareCmd represents the compare command
-var compareCmd = &cobra.Command{
-	Use:   "compare",
-	Short: "A brief description of your command",
-	Long: `A longer description that spans multiple lines and likely contains examples
-and usage of using your command. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Println("compare called")
-	},
-}
-
-func init() {
-	rootCmd.AddCommand(compareCmd)
-
-	// Here you will define your flags and configuration settings.
-
-	// Cobra supports Persistent Flags which will work for this command
-	// and all subcommands, e.g.:
-	// compareCmd.PersistentFlags().String("foo", "", "A help for foo")
-
-	// Cobra supports local flags which will only run when this command
-	// is called directly, e.g.:
-	// compareCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
-}

package/cmd/init.go

@@ -1,39 +0,0 @@
-/*
-Copyright © 2026 JACOB ARTHURS
-*/
-package cmd
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-)
-
-// initCmd represents the init command
-var initCmd = &cobra.Command{
-	Use:   "init",
-	Short: "A brief description of your command",
-	Long: `A longer description that spans multiple lines and likely contains examples
-and usage of using your command. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Println("init called")
-	},
-}
-
-func init() {
-	rootCmd.AddCommand(initCmd)
-
-	// Here you will define your flags and configuration settings.
-
-	// Cobra supports Persistent Flags which will work for this command
-	// and all subcommands, e.g.:
-	// initCmd.PersistentFlags().String("foo", "", "A help for foo")
-
-	// Cobra supports local flags which will only run when this command
-	// is called directly, e.g.:
-	// initCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
-}

package/cmd/root.go

@@ -1,46 +0,0 @@
-/*
-Copyright © 2026 JACOB ARTHURS
-*/
-package cmd
-
-import (
-	"os"
-
-	"github.com/spf13/cobra"
-)
-
-// rootCmd represents the base command when called without any subcommands
-var rootCmd = &cobra.Command{
-	Use:   "pgplan",
-	Short: "A brief description of your application",
-	Long: `A longer description that spans multiple lines and likely contains
-examples and usage of using your application. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
-	// Uncomment the following line if your bare application
-	// has an action associated with it:
-	// Run: func(cmd *cobra.Command, args []string) { },
-}
-
-// Execute adds all child commands to the root command and sets flags appropriately.
-// This is called by main.main(). It only needs to happen once to the rootCmd.
-func Execute() {
-	err := rootCmd.Execute()
-	if err != nil {
-		os.Exit(1)
-	}
-}
-
-func init() {
-	// Here you will define your flags and configuration settings.
-	// Cobra supports persistent flags, which, if defined here,
-	// will be global for your application.
-
-	// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.pgplan.yaml)")
-
-	// Cobra also supports local flags, which will only run
-	// when this action is called directly.
-	rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
-}

package/go.mod

@@ -1,9 +0,0 @@
-module pgplan
-
-go 1.25.6
-
-require (
-	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/spf13/cobra v1.10.2
-	github.com/spf13/pflag v1.0.10 // indirect
-)

package/go.sum

@@ -1,11 +0,0 @@
-github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
-github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
-github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
-github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
-github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
-github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
-github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
-go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

package/main.go

@@ -1,10 +0,0 @@
-/*
-Copyright © 2026 JACOB ARTHURS
-*/
-package main
-
-import "pgplan/cmd"
-
-func main() {
-	cmd.Execute()
-}