forge-fsql 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christian Hatch
+
+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,60 @@
+# Forge FSQL CLI
+
+Interactive command-line interface for querying Atlassian Forge SQL databases via web triggers.
+
+## Features
+
+- 🎨 Beautiful table formatting with colors
+- 📝 Multi-line SQL support
+- ⌨️ Command history (↑/↓ arrows)
+- ⚡ Special commands (.tables, .describe, .schema)
+- ⏱️ Query timing
+- 💾 Persistent history across sessions
+
+## Installation
+
+### In Your Forge Project
+
+```bash
+pnpm add -D forge-fsql
+```
+
+Add to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "sql": "fsql"
+  }
+}
+```
+
+### Global Installation
+
+```bash
+pnpm add -g forge-fsql
+```
+
+## Configuration
+
+Create a `.env` file in your project root:
+
+```bash
+FORGE_SQL_URL=https://your-trigger-url.forge.atlassian.com/sql
+```
+
+Or pass via command line:
+
+```bash
+fsql --url https://your-trigger-url.com
+```
+
+## Usage
+
+```bash
+# If installed in project
+pnpm sql
+
+# If installed globally
+fsql
+```

package/bin/fsql

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/bin/setup

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+
+// Support both ESM and CJS imports for js-yaml
+const require = createRequire(import.meta.url);
+const yaml = require("js-yaml");
+
+const projectRoot = process.cwd();
+
+console.log("Setting up Forge SQL CLI in this project...");
+
+// Detect consumer project type
+let isEsm = false;
+let isTypeScript = fs.existsSync(path.join(projectRoot, "tsconfig.json"));
+
+try {
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    if (pkg.type === "module") {
+      isEsm = true;
+    }
+  }
+} catch (e) {
+  // Ignore errors reading package.json
+}
+
+// 1. Create src/fsql file
+const srcDir = path.join(projectRoot, "src");
+if (!fs.existsSync(srcDir)) {
+  fs.mkdirSync(srcDir, { recursive: true });
+}
+
+const extension = isTypeScript ? "ts" : isEsm ? "js" : "js";
+// If it's CJS, we still use .js but different content
+const fsqlPath = path.join(srcDir, `fsql.${extension}`);
+
+let fsqlContent = "";
+if (isEsm || isTypeScript) {
+  fsqlContent = `import { executeSql } from 'forge-fsql';
+
+export { executeSql };
+`;
+} else {
+  fsqlContent = `const { executeSql } = require('forge-fsql');
+
+module.exports = { executeSql };
+`;
+}
+
+fs.writeFileSync(fsqlPath, fsqlContent);
+console.log(`✓ Created src/fsql.${extension}`);
+
+// 2. Update manifest.yaml or manifest.yml
+let manifestPath = path.join(projectRoot, "manifest.yml");
+if (!fs.existsSync(manifestPath)) {
+  manifestPath = path.join(projectRoot, "manifest.yaml");
+}
+
+if (!fs.existsSync(manifestPath)) {
+  console.error(
+    "Error: Could not find manifest.yml or manifest.yaml in the current directory.",
+  );
+  process.exit(1);
+}
+
+let manifest;
+try {
+  const fileContents = fs.readFileSync(manifestPath, "utf8");
+  manifest = yaml.load(fileContents);
+} catch (e) {
+  console.error("Error reading manifest:", e);
+  process.exit(1);
+}
+
+if (!manifest.modules) {
+  manifest.modules = {};
+}
+
+// Ensure function is an array
+const functionKey = "executeSql";
+if (!manifest.modules.function) {
+  manifest.modules.function = [];
+} else if (!Array.isArray(manifest.modules.function)) {
+  // Handle case where it might be a map (unlikely in Forge but just in case)
+  manifest.modules.function = Object.entries(manifest.modules.function).map(
+    ([key, val]) => ({ key, ...val }),
+  );
+}
+
+const functionExists = manifest.modules.function.find(
+  (f) => f.key === functionKey,
+);
+const handlerName = "fsql.executeSql";
+
+if (!functionExists) {
+  manifest.modules.function.push({
+    key: functionKey,
+    handler: handlerName,
+  });
+  console.log(
+    `✓ Added function:${functionKey} with handler ${handlerName} to manifest`,
+  );
+} else {
+  functionExists.handler = handlerName;
+  console.log(
+    `✓ Updated function:${functionKey} handler to ${handlerName} in manifest`,
+  );
+}
+
+// Ensure webtrigger is an array
+const webtriggerKey = "execute-sql";
+if (!manifest.modules.webtrigger) {
+  manifest.modules.webtrigger = [];
+} else if (!Array.isArray(manifest.modules.webtrigger)) {
+  manifest.modules.webtrigger = Object.entries(manifest.modules.webtrigger).map(
+    ([key, val]) => ({ key, ...val }),
+  );
+}
+
+const webtriggerExists = manifest.modules.webtrigger.find(
+  (w) => w.key === webtriggerKey,
+);
+if (!webtriggerExists) {
+  manifest.modules.webtrigger.push({
+    key: webtriggerKey,
+    function: functionKey,
+  });
+  console.log(`✓ Added webtrigger:${webtriggerKey} to manifest`);
+} else {
+  webtriggerExists.function = functionKey;
+  console.log(
+    `✓ Ensured webtrigger:${webtriggerKey} points to function ${functionKey}`,
+  );
+}
+
+try {
+  // Use a large enough lineWidth to prevent wrapping which can break Forge parsing sometimes
+  const newYaml = yaml.dump(manifest, {
+    indent: 2,
+    lineWidth: -1,
+    noRefs: true,
+  });
+  fs.writeFileSync(manifestPath, newYaml);
+  console.log("✓ Updated manifest file successfully");
+} catch (e) {
+  console.error("Error writing manifest:", e);
+  process.exit(1);
+}
+
+console.log("\nSetup completed successfully!");
+console.log(
+  "You can now use the forge-fsql CLI to interact with your Forge SQL database.",
+);

package/dist/cjs/cli.js

@@ -0,0 +1,49 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const dotenv = __importStar(require("dotenv"));
+const index_js_1 = require("./index.js");
+dotenv.config();
+// Parse command line arguments
+const args = process.argv.slice(2);
+const config = {};
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--url" && args[i + 1]) {
+        config.url = args[i + 1];
+        i++;
+    }
+}
+const cli = new index_js_1.ForgeSqlCli(config);
+cli.start();

package/dist/cjs/client.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeClient = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+class ForgeClient {
+    constructor(config) {
+        this.config = {
+            timeout: 30000,
+            ...config,
+        };
+    }
+    async execute(sql) {
+        const startTime = Date.now();
+        // Ensure SQL ends with a semicolon
+        const finalSql = sql.trim().endsWith(";") ? sql : `${sql};`;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            const response = await (0, node_fetch_1.default)(this.config.url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ query: finalSql }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                return {
+                    error: `HTTP ${response.status}: ${errorText}`,
+                };
+            }
+            const data = await response.json();
+            const elapsed = Date.now() - startTime;
+            return {
+                ...data,
+                metadata: {
+                    ...data.metadata,
+                    queryTime: elapsed,
+                },
+            };
+        }
+        catch (error) {
+            if (error.name === "AbortError") {
+                return { error: "Query timeout exceeded" };
+            }
+            return { error: error.message || "Unknown error" };
+        }
+    }
+    async testConnection() {
+        try {
+            const result = await this.execute("SELECT 1 as test");
+            return !result.error;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.ForgeClient = ForgeClient;

package/dist/cjs/commands.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specialCommands = void 0;
+exports.parseCommand = parseCommand;
+const formatter_js_1 = require("./formatter.js");
+const chalk_1 = __importDefault(require("chalk"));
+exports.specialCommands = [
+    {
+        name: ".tables",
+        description: "List all tables",
+        execute: async (client) => {
+            const result = await client.execute("SELECT table_name FROM information_schema.tables WHERE table_schema = DATABASE()");
+            return formatter_js_1.ResultFormatter.formatResult(result);
+        },
+    },
+    {
+        name: ".describe",
+        description: "Describe a table (.describe table_name)",
+        execute: async (client, args) => {
+            if (!args) {
+                return chalk_1.default.yellow("Usage: .describe <table_name>");
+            }
+            const result = await client.execute(`DESCRIBE ${args}`);
+            return formatter_js_1.ResultFormatter.formatResult(result);
+        },
+    },
+    {
+        name: ".schema",
+        description: "Show database schema",
+        execute: async (client) => {
+            const result = await client.execute("SELECT table_name, column_name, data_type FROM information_schema.columns WHERE table_schema = DATABASE() ORDER BY table_name, ordinal_position");
+            return formatter_js_1.ResultFormatter.formatResult(result);
+        },
+    },
+    {
+        name: ".help",
+        description: "Show available commands",
+        execute: async () => {
+            const helpText = [
+                chalk_1.default.bold("Special Commands:"),
+                ...exports.specialCommands.map((cmd) => `  ${chalk_1.default.cyan(cmd.name.padEnd(15))} ${cmd.description}`),
+                "",
+                chalk_1.default.bold("Other:"),
+                `  ${chalk_1.default.cyan("exit, quit".padEnd(15))} Exit the CLI`,
+                `  ${chalk_1.default.cyan("Ctrl+C".padEnd(15))} Cancel current query`,
+                `  ${chalk_1.default.cyan("Ctrl+D".padEnd(15))} Exit the CLI`,
+                `  ${chalk_1.default.cyan("↑/↓".padEnd(15))} Navigate command history`,
+            ];
+            return helpText.join("\n");
+        },
+    },
+];
+function parseCommand(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith(".")) {
+        const parts = trimmed.split(/\s+/);
+        const cmdName = parts[0];
+        const args = parts.slice(1).join(" ");
+        const command = exports.specialCommands.find((c) => c.name === cmdName);
+        return { command, args, isSpecial: true };
+    }
+    return { isSpecial: false };
+}

package/dist/cjs/execute-sql.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeSql = void 0;
+const sql_1 = require("@forge/sql");
+const executeSql = async (req) => {
+    console.log("\n=== Executing Custom SQL Query ===");
+    const payload = req.body;
+    let sqlRequest = null;
+    let query;
+    try {
+        sqlRequest = JSON.parse(payload);
+        query = sqlRequest?.query;
+        if (!query) {
+            return getHttpResponse(400, {
+                success: false,
+                error: "No SQL query provided",
+            });
+        }
+        console.log("Executing query:", query);
+        // Import sql directly for custom queries
+        const result = await sql_1.sql.executeRaw(query);
+        console.log("Query result:", result);
+        return getHttpResponse(200, {
+            success: true,
+            rows: result.rows || [],
+            rowCount: result.rows?.length || 0,
+            query,
+        });
+    }
+    catch (error) {
+        console.error(error);
+        console.error("Error while executing sql", { error });
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return getHttpResponse(500, {
+            success: false,
+            error: errorMessage,
+            ...(query && { query }),
+        });
+    }
+};
+exports.executeSql = executeSql;
+function getHttpResponse(statusCode, body) {
+    const statusTexts = {
+        200: "OK",
+        400: "Bad Request",
+        404: "Not Found",
+        500: "Internal Server Error",
+    };
+    const statusText = statusTexts[statusCode] || "Bad Request";
+    return {
+        headers: { "Content-Type": ["application/json"] },
+        statusCode,
+        statusText,
+        body: JSON.stringify(body),
+    };
+}

package/dist/cjs/formatter.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResultFormatter = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const cli_table3_1 = __importDefault(require("cli-table3"));
+class ResultFormatter {
+    static formatTable(rows) {
+        if (!rows || rows.length === 0) {
+            return chalk_1.default.yellow("(0 rows)");
+        }
+        const headers = Object.keys(rows[0]);
+        const table = new cli_table3_1.default({
+            head: headers.map((h) => chalk_1.default.cyan(h)),
+            style: {
+                head: [],
+                border: ["grey"],
+            },
+        });
+        rows.forEach((row) => {
+            table.push(headers.map((h) => this.formatValue(row[h])));
+        });
+        return (table.toString() +
+            "\n" +
+            chalk_1.default.gray(`(${rows.length} row${rows.length !== 1 ? "s" : ""})`));
+    }
+    static formatValue(value) {
+        if (value === null || value === undefined) {
+            return chalk_1.default.gray("NULL");
+        }
+        if (typeof value === "boolean") {
+            return value ? chalk_1.default.green("true") : chalk_1.default.red("false");
+        }
+        if (typeof value === "number") {
+            return chalk_1.default.yellow(value.toString());
+        }
+        return value.toString();
+    }
+    static formatError(error) {
+        return chalk_1.default.red("✗ Error: ") + error;
+    }
+    static formatSuccess(message) {
+        return chalk_1.default.green("✓ ") + message;
+    }
+    static formatResult(result) {
+        if (result.error) {
+            return this.formatError(result.error);
+        }
+        if (result.rows && result.rows.length > 0) {
+            return this.formatTable(result.rows);
+        }
+        if (result.affectedRows !== undefined) {
+            return this.formatSuccess(`${result.affectedRows} row(s) affected`);
+        }
+        return chalk_1.default.gray("Query executed successfully");
+    }
+    static formatQueryTime(ms) {
+        const seconds = (ms / 1000).toFixed(3);
+        return chalk_1.default.gray(`⏱  ${seconds}s`);
+    }
+}
+exports.ResultFormatter = ResultFormatter;

package/dist/cjs/history.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.History = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+class History {
+    constructor(maxSize = 1000) {
+        this.history = [];
+        this.historyFile = path.join(os.homedir(), ".forge_sql_history");
+        this.maxSize = maxSize;
+        this.load();
+    }
+    load() {
+        try {
+            if (fs.existsSync(this.historyFile)) {
+                const content = fs.readFileSync(this.historyFile, "utf-8");
+                this.history = content.split("\n").filter(Boolean);
+            }
+        }
+        catch (error) {
+            console.error("Failed to load history:", error);
+        }
+    }
+    save() {
+        try {
+            // Keep only last maxSize entries
+            const toSave = this.history.slice(-this.maxSize);
+            fs.writeFileSync(this.historyFile, toSave.join("\n"));
+        }
+        catch (error) {
+            console.error("Failed to save history:", error);
+        }
+    }
+    add(command) {
+        const trimmed = command.trim();
+        if (trimmed && trimmed !== this.history[this.history.length - 1]) {
+            this.history.push(trimmed);
+        }
+    }
+    getAll() {
+        return [...this.history];
+    }
+}
+exports.History = History;

package/dist/cjs/index.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeSqlCli = exports.executeSql = exports.ForgeClient = void 0;
+const readline = __importStar(require("readline"));
+const chalk_1 = __importDefault(require("chalk"));
+const client_js_1 = require("./client.js");
+const formatter_js_1 = require("./formatter.js");
+const history_js_1 = require("./history.js");
+const commands_js_1 = require("./commands.js");
+var client_js_2 = require("./client.js");
+Object.defineProperty(exports, "ForgeClient", { enumerable: true, get: function () { return client_js_2.ForgeClient; } });
+var execute_sql_js_1 = require("./execute-sql.js");
+Object.defineProperty(exports, "executeSql", { enumerable: true, get: function () { return execute_sql_js_1.executeSql; } });
+const getPrimaryPrompt = () => chalk_1.default.green("fsql> ");
+const getMultilinePrompt = () => chalk_1.default.green("      ...> ");
+class ForgeSqlCli {
+    constructor(config) {
+        this.multilineBuffer = "";
+        this.isMultiline = false;
+        const url = config.url || process.env.FORGE_SQL_URL;
+        if (!url) {
+            console.error(chalk_1.default.red("Error: FORGE_SQL_URL not configured"));
+            console.error(chalk_1.default.yellow("Set it via environment variable or .env file"));
+            process.exit(1);
+        }
+        this.client = new client_js_1.ForgeClient({
+            url,
+        });
+        this.history = new history_js_1.History();
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            prompt: getPrimaryPrompt(),
+            history: this.history.getAll().reverse(),
+            historySize: 1000,
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.rl.on("line", (line) => this.handleLine(line));
+        this.rl.on("close", () => this.handleClose());
+        // Handle Ctrl+C
+        this.rl.on("SIGINT", () => {
+            if (this.isMultiline) {
+                console.log("\n" + chalk_1.default.yellow("Multi-line input cancelled"));
+                this.multilineBuffer = "";
+                this.isMultiline = false;
+                this.rl.setPrompt(getPrimaryPrompt());
+            }
+            else {
+                console.log("\n" + chalk_1.default.gray("(Use .exit, exit, or Ctrl+D to quit)"));
+            }
+            this.rl.prompt();
+        });
+    }
+    async handleLine(line) {
+        const input = line.trim();
+        // Handle exit commands
+        if (input === "exit" || input === "quit" || input === ".exit") {
+            this.rl.close();
+            return;
+        }
+        // Handle empty input
+        if (!input) {
+            this.rl.prompt();
+            return;
+        }
+        // Check for multi-line SQL (doesn't end with semicolon)
+        if (!this.isMultiline && !input.endsWith(";") && !input.startsWith(".")) {
+            this.isMultiline = true;
+            this.multilineBuffer = input;
+            this.rl.setPrompt(getMultilinePrompt());
+            this.rl.prompt();
+            return;
+        }
+        // Continue multi-line
+        if (this.isMultiline) {
+            this.multilineBuffer += "\n" + input;
+            if (input.endsWith(";")) {
+                const fullSql = this.multilineBuffer;
+                this.multilineBuffer = "";
+                this.isMultiline = false;
+                this.rl.setPrompt(getPrimaryPrompt());
+                await this.executeCommand(fullSql);
+            }
+            else {
+                this.rl.prompt();
+                return;
+            }
+        }
+        else {
+            await this.executeCommand(input);
+        }
+        this.rl.prompt();
+    }
+    async executeCommand(input) {
+        this.history.add(input);
+        // Check for special commands
+        const { command, args, isSpecial } = (0, commands_js_1.parseCommand)(input);
+        if (isSpecial) {
+            if (command) {
+                const result = await command.execute(this.client, args);
+                console.log(result);
+            }
+            else {
+                console.log(chalk_1.default.red("Unknown command. Type .help for available commands"));
+            }
+            return;
+        }
+        // Execute SQL
+        const result = await this.client.execute(input);
+        console.log(formatter_js_1.ResultFormatter.formatResult(result));
+        if (result.metadata?.queryTime) {
+            console.log(formatter_js_1.ResultFormatter.formatQueryTime(result.metadata.queryTime));
+        }
+    }
+    handleClose() {
+        this.history.save();
+        console.log(chalk_1.default.gray("\nGoodbye!"));
+        process.exit(0);
+    }
+    async start() {
+        console.log(chalk_1.default.bold.blue("Forge FSQL CLI"));
+        console.log(chalk_1.default.gray("Type .help for commands, exit to quit"));
+        console.log(chalk_1.default.gray("=".repeat(50)));
+        // Test connection
+        process.stdout.write("Testing connection... ");
+        const connected = await this.client.testConnection();
+        if (connected) {
+            console.log(chalk_1.default.green("✓ Connected"));
+        }
+        else {
+            console.log(chalk_1.default.red("✗ Connection failed"));
+            console.log(chalk_1.default.yellow("Check your FORGE_SQL_URL configuration"));
+        }
+        console.log("");
+        this.rl.prompt();
+    }
+}
+exports.ForgeSqlCli = ForgeSqlCli;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/dist/cli.js

@@ -0,0 +1,14 @@
+import * as dotenv from "dotenv";
+import { ForgeSqlCli } from "./index.js";
+dotenv.config();
+// Parse command line arguments
+const args = process.argv.slice(2);
+const config = {};
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--url" && args[i + 1]) {
+        config.url = args[i + 1];
+        i++;
+    }
+}
+const cli = new ForgeSqlCli(config);
+cli.start();

package/dist/client.js

@@ -0,0 +1,58 @@
+import fetch from "node-fetch";
+export class ForgeClient {
+    constructor(config) {
+        this.config = {
+            timeout: 30000,
+            ...config,
+        };
+    }
+    async execute(sql) {
+        const startTime = Date.now();
+        // Ensure SQL ends with a semicolon
+        const finalSql = sql.trim().endsWith(";") ? sql : `${sql};`;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            const response = await fetch(this.config.url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ query: finalSql }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                return {
+                    error: `HTTP ${response.status}: ${errorText}`,
+                };
+            }
+            const data = await response.json();
+            const elapsed = Date.now() - startTime;
+            return {
+                ...data,
+                metadata: {
+                    ...data.metadata,
+                    queryTime: elapsed,
+                },
+            };
+        }
+        catch (error) {
+            if (error.name === "AbortError") {
+                return { error: "Query timeout exceeded" };
+            }
+            return { error: error.message || "Unknown error" };
+        }
+    }
+    async testConnection() {
+        try {
+            const result = await this.execute("SELECT 1 as test");
+            return !result.error;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/commands.js

@@ -0,0 +1,59 @@
+import { ResultFormatter } from "./formatter.js";
+import chalk from "chalk";
+export const specialCommands = [
+    {
+        name: ".tables",
+        description: "List all tables",
+        execute: async (client) => {
+            const result = await client.execute("SELECT table_name FROM information_schema.tables WHERE table_schema = DATABASE()");
+            return ResultFormatter.formatResult(result);
+        },
+    },
+    {
+        name: ".describe",
+        description: "Describe a table (.describe table_name)",
+        execute: async (client, args) => {
+            if (!args) {
+                return chalk.yellow("Usage: .describe <table_name>");
+            }
+            const result = await client.execute(`DESCRIBE ${args}`);
+            return ResultFormatter.formatResult(result);
+        },
+    },
+    {
+        name: ".schema",
+        description: "Show database schema",
+        execute: async (client) => {
+            const result = await client.execute("SELECT table_name, column_name, data_type FROM information_schema.columns WHERE table_schema = DATABASE() ORDER BY table_name, ordinal_position");
+            return ResultFormatter.formatResult(result);
+        },
+    },
+    {
+        name: ".help",
+        description: "Show available commands",
+        execute: async () => {
+            const helpText = [
+                chalk.bold("Special Commands:"),
+                ...specialCommands.map((cmd) => `  ${chalk.cyan(cmd.name.padEnd(15))} ${cmd.description}`),
+                "",
+                chalk.bold("Other:"),
+                `  ${chalk.cyan("exit, quit".padEnd(15))} Exit the CLI`,
+                `  ${chalk.cyan("Ctrl+C".padEnd(15))} Cancel current query`,
+                `  ${chalk.cyan("Ctrl+D".padEnd(15))} Exit the CLI`,
+                `  ${chalk.cyan("↑/↓".padEnd(15))} Navigate command history`,
+            ];
+            return helpText.join("\n");
+        },
+    },
+];
+export function parseCommand(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith(".")) {
+        const parts = trimmed.split(/\s+/);
+        const cmdName = parts[0];
+        const args = parts.slice(1).join(" ");
+        const command = specialCommands.find((c) => c.name === cmdName);
+        return { command, args, isSpecial: true };
+    }
+    return { isSpecial: false };
+}

package/dist/execute-sql.js

@@ -0,0 +1,53 @@
+import { sql } from "@forge/sql";
+const executeSql = async (req) => {
+    console.log("\n=== Executing Custom SQL Query ===");
+    const payload = req.body;
+    let sqlRequest = null;
+    let query;
+    try {
+        sqlRequest = JSON.parse(payload);
+        query = sqlRequest?.query;
+        if (!query) {
+            return getHttpResponse(400, {
+                success: false,
+                error: "No SQL query provided",
+            });
+        }
+        console.log("Executing query:", query);
+        // Import sql directly for custom queries
+        const result = await sql.executeRaw(query);
+        console.log("Query result:", result);
+        return getHttpResponse(200, {
+            success: true,
+            rows: result.rows || [],
+            rowCount: result.rows?.length || 0,
+            query,
+        });
+    }
+    catch (error) {
+        console.error(error);
+        console.error("Error while executing sql", { error });
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return getHttpResponse(500, {
+            success: false,
+            error: errorMessage,
+            ...(query && { query }),
+        });
+    }
+};
+function getHttpResponse(statusCode, body) {
+    const statusTexts = {
+        200: "OK",
+        400: "Bad Request",
+        404: "Not Found",
+        500: "Internal Server Error",
+    };
+    const statusText = statusTexts[statusCode] || "Bad Request";
+    return {
+        headers: { "Content-Type": ["application/json"] },
+        statusCode,
+        statusText,
+        body: JSON.stringify(body),
+    };
+}
+export { executeSql };

package/dist/formatter.js

@@ -0,0 +1,57 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+export class ResultFormatter {
+    static formatTable(rows) {
+        if (!rows || rows.length === 0) {
+            return chalk.yellow("(0 rows)");
+        }
+        const headers = Object.keys(rows[0]);
+        const table = new Table({
+            head: headers.map((h) => chalk.cyan(h)),
+            style: {
+                head: [],
+                border: ["grey"],
+            },
+        });
+        rows.forEach((row) => {
+            table.push(headers.map((h) => this.formatValue(row[h])));
+        });
+        return (table.toString() +
+            "\n" +
+            chalk.gray(`(${rows.length} row${rows.length !== 1 ? "s" : ""})`));
+    }
+    static formatValue(value) {
+        if (value === null || value === undefined) {
+            return chalk.gray("NULL");
+        }
+        if (typeof value === "boolean") {
+            return value ? chalk.green("true") : chalk.red("false");
+        }
+        if (typeof value === "number") {
+            return chalk.yellow(value.toString());
+        }
+        return value.toString();
+    }
+    static formatError(error) {
+        return chalk.red("✗ Error: ") + error;
+    }
+    static formatSuccess(message) {
+        return chalk.green("✓ ") + message;
+    }
+    static formatResult(result) {
+        if (result.error) {
+            return this.formatError(result.error);
+        }
+        if (result.rows && result.rows.length > 0) {
+            return this.formatTable(result.rows);
+        }
+        if (result.affectedRows !== undefined) {
+            return this.formatSuccess(`${result.affectedRows} row(s) affected`);
+        }
+        return chalk.gray("Query executed successfully");
+    }
+    static formatQueryTime(ms) {
+        const seconds = (ms / 1000).toFixed(3);
+        return chalk.gray(`⏱  ${seconds}s`);
+    }
+}

package/dist/history.js

@@ -0,0 +1,41 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+export class History {
+    constructor(maxSize = 1000) {
+        this.history = [];
+        this.historyFile = path.join(os.homedir(), ".forge_sql_history");
+        this.maxSize = maxSize;
+        this.load();
+    }
+    load() {
+        try {
+            if (fs.existsSync(this.historyFile)) {
+                const content = fs.readFileSync(this.historyFile, "utf-8");
+                this.history = content.split("\n").filter(Boolean);
+            }
+        }
+        catch (error) {
+            console.error("Failed to load history:", error);
+        }
+    }
+    save() {
+        try {
+            // Keep only last maxSize entries
+            const toSave = this.history.slice(-this.maxSize);
+            fs.writeFileSync(this.historyFile, toSave.join("\n"));
+        }
+        catch (error) {
+            console.error("Failed to save history:", error);
+        }
+    }
+    add(command) {
+        const trimmed = command.trim();
+        if (trimmed && trimmed !== this.history[this.history.length - 1]) {
+            this.history.push(trimmed);
+        }
+    }
+    getAll() {
+        return [...this.history];
+    }
+}

package/dist/index.js

@@ -0,0 +1,134 @@
+import * as readline from "readline";
+import chalk from "chalk";
+import { ForgeClient } from "./client.js";
+import { ResultFormatter } from "./formatter.js";
+import { History } from "./history.js";
+import { parseCommand } from "./commands.js";
+export { ForgeClient } from "./client.js";
+export { executeSql } from "./execute-sql.js";
+const getPrimaryPrompt = () => chalk.green("fsql> ");
+const getMultilinePrompt = () => chalk.green("      ...> ");
+export class ForgeSqlCli {
+    constructor(config) {
+        this.multilineBuffer = "";
+        this.isMultiline = false;
+        const url = config.url || process.env.FORGE_SQL_URL;
+        if (!url) {
+            console.error(chalk.red("Error: FORGE_SQL_URL not configured"));
+            console.error(chalk.yellow("Set it via environment variable or .env file"));
+            process.exit(1);
+        }
+        this.client = new ForgeClient({
+            url,
+        });
+        this.history = new History();
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            prompt: getPrimaryPrompt(),
+            history: this.history.getAll().reverse(),
+            historySize: 1000,
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.rl.on("line", (line) => this.handleLine(line));
+        this.rl.on("close", () => this.handleClose());
+        // Handle Ctrl+C
+        this.rl.on("SIGINT", () => {
+            if (this.isMultiline) {
+                console.log("\n" + chalk.yellow("Multi-line input cancelled"));
+                this.multilineBuffer = "";
+                this.isMultiline = false;
+                this.rl.setPrompt(getPrimaryPrompt());
+            }
+            else {
+                console.log("\n" + chalk.gray("(Use .exit, exit, or Ctrl+D to quit)"));
+            }
+            this.rl.prompt();
+        });
+    }
+    async handleLine(line) {
+        const input = line.trim();
+        // Handle exit commands
+        if (input === "exit" || input === "quit" || input === ".exit") {
+            this.rl.close();
+            return;
+        }
+        // Handle empty input
+        if (!input) {
+            this.rl.prompt();
+            return;
+        }
+        // Check for multi-line SQL (doesn't end with semicolon)
+        if (!this.isMultiline && !input.endsWith(";") && !input.startsWith(".")) {
+            this.isMultiline = true;
+            this.multilineBuffer = input;
+            this.rl.setPrompt(getMultilinePrompt());
+            this.rl.prompt();
+            return;
+        }
+        // Continue multi-line
+        if (this.isMultiline) {
+            this.multilineBuffer += "\n" + input;
+            if (input.endsWith(";")) {
+                const fullSql = this.multilineBuffer;
+                this.multilineBuffer = "";
+                this.isMultiline = false;
+                this.rl.setPrompt(getPrimaryPrompt());
+                await this.executeCommand(fullSql);
+            }
+            else {
+                this.rl.prompt();
+                return;
+            }
+        }
+        else {
+            await this.executeCommand(input);
+        }
+        this.rl.prompt();
+    }
+    async executeCommand(input) {
+        this.history.add(input);
+        // Check for special commands
+        const { command, args, isSpecial } = parseCommand(input);
+        if (isSpecial) {
+            if (command) {
+                const result = await command.execute(this.client, args);
+                console.log(result);
+            }
+            else {
+                console.log(chalk.red("Unknown command. Type .help for available commands"));
+            }
+            return;
+        }
+        // Execute SQL
+        const result = await this.client.execute(input);
+        console.log(ResultFormatter.formatResult(result));
+        if (result.metadata?.queryTime) {
+            console.log(ResultFormatter.formatQueryTime(result.metadata.queryTime));
+        }
+    }
+    handleClose() {
+        this.history.save();
+        console.log(chalk.gray("\nGoodbye!"));
+        process.exit(0);
+    }
+    async start() {
+        console.log(chalk.bold.blue("Forge FSQL CLI"));
+        console.log(chalk.gray("Type .help for commands, exit to quit"));
+        console.log(chalk.gray("=".repeat(50)));
+        // Test connection
+        process.stdout.write("Testing connection... ");
+        const connected = await this.client.testConnection();
+        if (connected) {
+            console.log(chalk.green("✓ Connected"));
+        }
+        else {
+            console.log(chalk.red("✗ Connection failed"));
+            console.log(chalk.yellow("Check your FORGE_SQL_URL configuration"));
+        }
+        console.log("");
+        this.rl.prompt();
+    }
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "forge-fsql",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Interactive SQL CLI for Atlassian Forge SQL via web triggers",
+  "main": "dist/cjs/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fsql": "bin/fsql",
+    "fsql-setup": "bin/setup"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "fsql": "node ./bin/fsql",
+    "lint": "pnpm lint:eslint && pnpm lint:prettier",
+    "lint:eslint": "eslint '**/*.{ts,tsx,js,jsx}' --ignore-pattern '**/eslint.config.js'",
+    "lint:prettier": "prettier '**/*.{ts,tsx,js,jsx,json,md,yaml,yml}' --check || echo '⚠️  Warning: Prettier formatting issues found. Run \"pnpm fixstyle\" to fix them.'",
+    "fixall": "pnpm fixstyle && pnpm fixsrc",
+    "fixsrc": "eslint '**/*.{ts,tsx,js,jsx}' --ignore-pattern '**/eslint.config.js' --fix",
+    "fixstyle": "prettier '**/*.{ts,tsx,js,jsx,json,md,yaml,yml}' --write",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "**/*.{ts,tsx,js,jsx,json,md,yaml,yml}": [
+      "pnpm fixstyle",
+      "pnpm run lint:eslint"
+    ]
+  },
+  "keywords": [
+    "forge",
+    "sql",
+    "cli",
+    "atlassian"
+  ],
+  "author": "Chris Hatch",
+  "license": "MIT",
+  "dependencies": {
+    "@forge/sql": "^3.0.14",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "dotenv": "^16.0.3",
+    "js-yaml": "^4.1.1",
+    "node-fetch": "^2.7.0",
+    "readline": "^1.3.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.19.1",
+    "@types/node-fetch": "^2.6.11",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "eslint": "9.39.1",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^15.15.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0"
+  }
+}