@ottermind/sqlx 0.1.5

package/LICENSE

@@ -0,0 +1,178 @@
+# License
+
+Chat2DB Rust is licensed under a modified version of the Apache License 2.0,
+with the additional conditions below.
+
+The Chat2DB Community source used by Chat2DB Rust remains subject to the
+license included with that source. Third-party components remain subject to
+their own license terms and notices.
+
+For package metadata, these terms may be identified as
+`LicenseRef-Chat2DB`. That identifier refers only to this root `LICENSE` file
+and does not create a separate license.
+
+## 1. Permitted Use
+
+Subject to this License, you may use, copy, and modify the Software for:
+
+a. personal self-use, or self-hosted use by an educational, academic research,
+   or non-profit organization; and
+
+b. Internal Use by you and Your Organization, including internal use of the
+   desktop application, Web interface, Docker image, HTTP API, CLI, MCP,
+   plugins, and reusable modules.
+
+You may publish and redistribute the Software or your modifications in Source
+form under this License, provided that you keep this License and all applicable
+copyright, attribution, and third-party notices. This permission does not allow
+you to provide an External Product or Service, Managed Delivery, Embedded
+Product Use, white-label delivery, OEM delivery, or Object-form distribution
+to an Independent External Party without written commercial authorization.
+
+## 2. Internal Processing and Results Delivery
+
+Internal Use includes use by your Authorized Personnel to process data owned
+or provided by an Independent External Party and to deliver reports, analyses,
+migration results, or other non-interactive outputs to that party, provided
+that the party does not receive credentials, interfaces, configurations,
+controls, repeatable automated access, or any other ability to operate,
+configure, invoke, integrate, or direct the Software or its Community Core
+Capabilities.
+
+An Independent External Party providing business requirements, data, or
+acceptance criteria does not by itself make the use external. However, shared
+accounts, human intermediaries, proxy interfaces, prompts, agents, workflows,
+plugins, scheduled requests, or similar arrangements do not qualify for this
+exception when they give the party repeatable or practical control over the
+Software or its Community Core Capabilities.
+
+## 3. Commercial Authorization Required
+
+Unless Chat2DB has expressly authorized you in writing, you may not:
+
+a. provide an External Product or Service;
+
+b. perform Managed Delivery for an Independent External Party;
+
+c. except for the Source-form redistribution expressly permitted by Section 1,
+   distribute installers, binaries, archives, container images, deployment
+   charts, patches, configurations, or other materials that enable an
+   Independent External Party to deploy or use the Software in Object form;
+
+d. perform Embedded Product Use;
+
+e. provide white-label or OEM versions of the Software or a derivative work;
+   or
+
+f. remove, obscure, or modify Chat2DB logos, copyright information, licensing
+   notices, or attribution displayed by the official frontend or included in
+   an official distribution.
+
+These conditions apply whether the offering is paid or free, whether access is
+direct or indirect, whether accounts exist, whether there is one tenant or many
+tenants, and whether the Software runs in a shared instance, a dedicated
+instance, a customer-owned cloud account, or any other deployment topology.
+The identity of the payer, account owner, infrastructure owner, distributor,
+or operator does not change the result. The relevant question is whether an
+Independent External Party receives the ability to use Community Core
+Capabilities.
+
+For written commercial authorization, contact Chat2DB through
+https://chat2db.ai.
+
+## 4. Definitions
+
+"Chat2DB" means 爱獭科技（杭州）有限公司, the producer of the Software.
+
+"Software" means the Chat2DB Rust software made available under this License
+in Source or Object form, including its official desktop, Web, HTTP API, CLI,
+MCP, compatibility engine, plugins, and reusable module distributions.
+
+"Source" and "Object" have the meanings given in the Apache License 2.0.
+
+"You" means the individual or legal entity exercising permissions under this
+License.
+
+"Your Organization" means you and any legal entities that control, are
+controlled by, or are under common control with you. "Control" means direct or
+indirect ownership of more than fifty percent of the voting interests, or the
+power to direct the management and policies of an entity by ownership,
+contract, or otherwise.
+
+"Authorized Personnel" means employees and individual contractors acting
+solely on behalf of Your Organization, under obligations that protect the
+Software and prevent its use for any other person or organization. Customers,
+vendors, channel partners, distributors, and independent service providers are
+not Authorized Personnel merely because they have a commercial relationship
+with you.
+
+"Internal Use" means use of the Software solely by Authorized Personnel and
+internal systems for the internal operations of Your Organization, where no
+Independent External Party receives Community Core Capabilities.
+
+"Independent External Party" means any individual or organization outside
+Your Organization that is not Authorized Personnel.
+
+"Community Core Capabilities" means substantive database functionality
+provided by the Software, including database connection and credential
+management, metadata browsing, SQL, DDL, or DML execution, data editing,
+import or export, tasks and history, dashboards and charts, AI features, CLI,
+MCP, frontend interaction, HTTP APIs, plugins, and reusable API, Core, or SPI
+modules.
+
+"External Product or Service" means any product or service through which an
+Independent External Party can directly or indirectly operate, configure,
+invoke, integrate, automate, or otherwise use Community Core Capabilities,
+including through a Web UI, desktop application, HTTP API, CLI, MCP, embedded
+module, prompt, agent, workflow, proxy, or other interface.
+
+"Managed Delivery" means deploying, configuring, customizing, hosting,
+operating, maintaining, upgrading, or continuously administering the Software
+or a derivative work for an Independent External Party in a way that gives
+that party Community Core Capabilities.
+
+"Embedded Product Use" means incorporating the Software, its frontend, HTTP
+API, CLI, MCP, plugins, reusable modules, or a derivative implementation into
+a product made available to an Independent External Party, where that product
+provides substantive Community Core Capabilities.
+
+## 5. Branding and Notices
+
+This License does not grant permission to use Chat2DB trade names, trademarks,
+service marks, or product names except as required to describe the origin of
+the Software and reproduce required notices. All uses of Chat2DB marks remain
+subject to applicable trademark law and any separately published trademark
+policy.
+
+If you modify the Software, you must include prominent notices stating that
+you changed it. You must retain all applicable copyright, patent, trademark,
+licensing, and attribution notices from the Software.
+
+## 6. Contributions
+
+Unless you explicitly state otherwise in writing before submission, any
+contribution intentionally submitted for inclusion in Chat2DB Rust is provided
+under this License. By submitting a contribution, you also agree that Chat2DB
+may use the contribution for commercial purposes and may include it in future
+Chat2DB releases made available under different license terms.
+
+## 7. Third-Party Software
+
+Third-party components included with the Software remain subject to their own
+license terms and notices. This License does not replace, restrict, or modify
+those third-party terms. Where a file or component contains a separate license
+or copyright notice, that separate notice governs that file or component.
+
+## 8. Apache License 2.0 Terms
+
+Except for the additional conditions stated in this License, all other rights
+and restrictions follow the Apache License 2.0, available at
+https://www.apache.org/licenses/LICENSE-2.0. If these additional conditions
+conflict with the Apache License 2.0 for Chat2DB Rust, these additional
+conditions control.
+
+The Apache License 2.0 provisions concerning patent grants, patent litigation,
+notices, disclaimer of warranty, limitation of liability, and acceptance of
+additional liability are incorporated into this License.
+
+Copyright 2026 爱獭科技（杭州）有限公司.

package/NOTICE

@@ -0,0 +1,14 @@
+SQLX
+Copyright 2026 爱獭科技（杭州）有限公司 / OtterMind.
+
+Database connection, result conversion, and JDBC loading code is adapted from
+OtterMind/Chat2DB-Rust, commit e17ee8be373407e193e7e12da0dcd3b5b4b5550b.
+These adaptations replace product-specific storage and session integrations
+with standalone worker processes and complete streamed SQL results.
+The retained LICENSE governs the derived code. Third-party dependencies keep
+their own licenses. SQLX is a public source repository; its license contains
+additional conditions beyond the standard Apache License 2.0.
+
+Result toolbar sizing is adapted from Chat2DB Community (commit 777b06099):
+chat2db-community-client/src/blocks/SearchResult/components/ResultSetToolbar.
+The original license and copyright conditions remain applicable.

package/README.md

@@ -0,0 +1,125 @@
+# @ottermind/sqlx
+
+Install or update the [SQLX](https://github.com/OtterMind/sqlx) database CLI and
+its agent Skill with one command.
+
+```bash
+npx -y @ottermind/sqlx@latest
+```
+
+The command installs or updates the native CLI, initializes the local SQLX data
+directory when it does not exist yet, and installs the Skill. Node.js is only
+needed to run the installer: the CLI itself has no Node.js runtime dependency.
+
+This package contains no binaries. It downloads the CLI and the Skill from the
+GitHub Release that matches the version of this package.
+
+## Requirements
+
+- Node.js 22 or newer (`npx` is part of npm).
+- Write access to the CLI directory and to the Skill directory.
+- Access to the npm Registry and to GitHub Releases.
+
+Windows ARM64 is not a release target.
+
+## Usage
+
+```bash
+# Skill in ./sqlx, CLI in the official user-level location
+npx -y @ottermind/sqlx@latest
+
+# Skill in the Codex user-level Skill directory
+npx -y @ottermind/sqlx@latest --target codex
+
+# Skill in the Claude Code user-level Skill directory
+npx -y @ottermind/sqlx@latest --target claude
+
+# Skill in an explicit directory
+npx -y @ottermind/sqlx@latest --target ./tools/sqlx
+
+npx -y @ottermind/sqlx@latest --help
+```
+
+| `--target`          | Skill directory                    |
+| ------------------- | ---------------------------------- |
+| not given           | `./sqlx` in the current directory  |
+| `codex`             | `~/.agents/skills/sqlx`            |
+| `claude`            | `~/.claude/skills/sqlx`            |
+| any other value     | that path, used as the directory   |
+
+Relative paths are resolved against the directory the command runs from, not
+against a temporary download directory.
+
+## Where things are installed
+
+| Item       | Location                                                    |
+| ---------- | ----------------------------------------------------------- |
+| CLI        | `~/.local/bin/sqlx` (macOS, Linux)                          |
+| CLI        | `%LOCALAPPDATA%\Programs\SQLX\sqlx.exe` (Windows)           |
+| Skill      | the `--target` directory                                    |
+| Local data | `~/.sqlx`, created by `sqlx init` when missing              |
+
+The CLI is reused when it is already at the target version, updated when it is
+older and supports self-updates, and left untouched when it is newer: this
+installer never downgrades a working CLI and never replaces an executable it
+does not recognize as `OtterMind/sqlx`.
+
+The Skill is installed by the verified CLI itself, so it shares the same
+`skill-installs.json` record, integrity data and local-modification protection
+as `sqlx skill install`. The installer never copies Skill files on its own, so
+there is only one update rule.
+
+If the CLI installs successfully but the Skill step fails, the command exits
+non-zero, keeps the working CLI and reports the Skill failure separately.
+
+## Environment
+
+| Variable            | Meaning                                                    |
+| ------------------- | ---------------------------------------------------------- |
+| `SQLX_INSTALL_DIR`  | CLI directory instead of the official location             |
+| `SQLX_RELEASE_BASE` | Release download base instead of `github.com`              |
+| `SQLX_DATA_DIR`     | SQLX data directory instead of `~/.sqlx`                   |
+| `SQLX_VERSION`      | Release to install instead of this package version         |
+
+## Verification
+
+Before anything is written, the installer checks that the release metadata, the
+`SHA256SUMS` file and the downloaded archive agree:
+
+1. `SHA256SUMS` is downloaded and `manifest.json` is verified against it.
+2. The CLI archive is verified against the SHA-256 in the manifest.
+3. The archive is extracted with a ZIP reader that rejects absolute paths, `..`
+   traversal, backslashes and symbolic links.
+4. The extracted binary is executed once as `--version` and must report
+   `OtterMind/sqlx` at the expected version.
+5. The binary is staged inside the CLI directory and renamed into place, so a
+   failure cannot leave a half-written executable.
+
+## This package does not
+
+- run `preinstall`, `install` or `postinstall` scripts;
+- write to the `package.json`, lockfile or `node_modules` of the calling
+  project;
+- download database workers, drivers or a JRE — the CLI fetches those when a
+  connection actually needs them;
+- modify `PATH` or shell profiles; it reports the directory to add when the CLI
+  is not reachable.
+
+## Troubleshooting
+
+- **`SQLX installation failed (cli)`** — the CLI directory is not writable, or
+  it already contains a `sqlx` that is not an OtterMind build. Set
+  `SQLX_INSTALL_DIR` to a directory you own.
+- **`SQLX installation failed (skill)`** — the Skill destination already exists
+  and is not managed by SQLX, or it has local changes. The CLI stays installed;
+  fix the destination and run the command again.
+- **`SQLX installation failed (download)`** — the GitHub Release for this
+  package version is not reachable. Check the version exists before retrying.
+
+No Node.js? Use the Shell or PowerShell installer described in the
+[SQLX README](https://github.com/OtterMind/sqlx#readme).
+
+## License
+
+See `LICENSE` and `NOTICE`. For package metadata these terms are identified as
+`LicenseRef-Chat2DB`.

package/bin/sqlx-install.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/main.mjs";
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ottermind/sqlx",
+  "version": "0.1.5",
+  "description": "Install or update the SQLX database CLI and its agent Skill.",
+  "license": "LicenseRef-Chat2DB",
+  "homepage": "https://github.com/OtterMind/sqlx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OtterMind/sqlx.git",
+    "directory": "packages/npm-installer"
+  },
+  "bugs": {
+    "url": "https://github.com/OtterMind/sqlx/issues"
+  },
+  "type": "module",
+  "bin": {
+    "sqlx-install": "bin/sqlx-install.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/unit.test.mjs test/e2e.test.mjs"
+  }
+}

package/src/args.mjs

@@ -0,0 +1,66 @@
+import { UsageError } from "./errors.mjs";
+
+export const HELP = `Install or update the SQLX CLI and its agent Skill.
+
+Usage:
+  npx -y @ottermind/sqlx@latest [--target <codex|claude|path>]
+
+Options:
+  --target <codex|claude|path>  Skill destination. Without it the Skill is
+                                installed to ./sqlx in the directory the command
+                                runs from. "codex" and "claude" select the
+                                user-level Skill directory of that agent; any
+                                other value is used as the Skill directory.
+  -h, --help                    Show this help and exit.
+
+The CLI is installed to its official user-level location:
+  macOS, Linux  ~/.local/bin/sqlx
+  Windows       %LOCALAPPDATA%\\Programs\\SQLX\\sqlx.exe
+
+This package never runs an install script, never downloads inside a project and
+never edits the package.json, lockfile or node_modules of the calling project.
+
+Environment:
+  SQLX_INSTALL_DIR   CLI directory instead of the official location.
+  SQLX_RELEASE_BASE  Release download base instead of github.com.
+  SQLX_DATA_DIR      SQLX data directory instead of ~/.sqlx.
+  SQLX_VERSION       Release to install instead of this package version.
+
+Examples:
+  npx -y @ottermind/sqlx@latest
+  npx -y @ottermind/sqlx@latest --target codex
+  npx -y @ottermind/sqlx@latest --target ./tools/sqlx
+`;
+
+export function parseArgs(argv) {
+  const options = { target: undefined, help: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--help" || argument === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (argument === "--target" || argument.startsWith("--target=")) {
+      if (options.target !== undefined) {
+        throw new UsageError("--target was given more than once");
+      }
+      if (argument === "--target") {
+        index += 1;
+        if (index >= argv.length) {
+          throw new UsageError("--target needs codex, claude or a directory");
+        }
+        options.target = argv[index];
+      } else {
+        options.target = argument.slice("--target=".length);
+      }
+      if (options.target === "") {
+        throw new UsageError("--target needs codex, claude or a directory");
+      }
+      continue;
+    }
+    throw new UsageError(
+      argument.startsWith("-") ? `unknown option: ${argument}` : `unexpected argument: ${argument}`,
+    );
+  }
+  return options;
+}

package/src/cli.mjs

@@ -0,0 +1,232 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { InstallError } from "./errors.mjs";
+import { extractZip } from "./zip.mjs";
+
+const COMMAND_TIMEOUT_MS = 60_000;
+const INSTALL_TIMEOUT_MS = 600_000;
+const MANAGED_PARTS = [
+  "/target/debug/",
+  "/target/release/",
+  "/cellar/",
+  "/windowsapps/",
+  "/scoop/apps/",
+  "/chocolatey/",
+];
+const MANAGED_PREFIXES = ["/nix/store/", "/snap/", "/usr/bin/", "/bin/"];
+
+export function binaryName() {
+  return process.platform === "win32" ? "sqlx.exe" : "sqlx";
+}
+
+export function cliDirectory() {
+  const override = process.env.SQLX_INSTALL_DIR?.trim();
+  if (override) {
+    return path.resolve(override);
+  }
+  if (process.platform === "win32") {
+    const local = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    return path.join(local, "Programs", "SQLX");
+  }
+  return path.join(os.homedir(), ".local", "bin");
+}
+
+export function dataDirectory() {
+  const override = process.env.SQLX_DATA_DIR?.trim();
+  return override ? path.resolve(override) : path.join(os.homedir(), ".sqlx");
+}
+
+function cliFailure(stdout, stderr, status) {
+  for (const stream of [stdout, stderr]) {
+    try {
+      const message = JSON.parse(stream)?.error?.message;
+      if (typeof message === "string" && message !== "") {
+        return message;
+      }
+    } catch {
+      // Not a JSON result; fall back to the raw output.
+    }
+  }
+  return `${stdout ?? ""}${stderr ?? ""}`.trim() || `exit code ${status}`;
+}
+
+function run(binary, args, timeout, stage) {
+  const result = spawnSync(binary, args, {
+    encoding: "utf8",
+    timeout,
+    windowsHide: true,
+    env: { ...process.env, SQLX_NO_UPDATE_CHECK: "1" },
+  });
+  if (result.error) {
+    throw new InstallError(stage, `${path.basename(binary)} ${args.join(" ")} failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new InstallError(
+      stage,
+      `${path.basename(binary)} ${args.join(" ")} failed: ${cliFailure(result.stdout, result.stderr, result.status)}`,
+    );
+  }
+  return result.stdout ?? "";
+}
+
+export function readVersion(binary) {
+  const result = spawnSync(binary, ["--version"], {
+    encoding: "utf8",
+    timeout: COMMAND_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+  const match = /^sqlx (\S+) \(OtterMind\/sqlx\)$/m.exec(result.stdout ?? "");
+  return match ? match[1] : null;
+}
+
+export function inspect(binary) {
+  let stats;
+  try {
+    stats = fs.lstatSync(binary);
+  } catch {
+    return { path: binary, exists: false };
+  }
+  if (stats.isSymbolicLink()) {
+    throw new InstallError(
+      "cli",
+      `${binary} is a symbolic link; install SQLX with the tool that owns it, or set SQLX_INSTALL_DIR`,
+    );
+  }
+  if (!stats.isFile()) {
+    throw new InstallError("cli", `${binary} is not a regular file`);
+  }
+  const version = readVersion(binary);
+  if (!version) {
+    throw new InstallError(
+      "cli",
+      `${binary} already exists and is not an OtterMind SQLX executable; refusing to replace it`,
+    );
+  }
+  return { path: binary, exists: true, version };
+}
+
+function assertReplaceable(binary) {
+  const normalized = binary.replaceAll("\\", "/").toLowerCase();
+  if (
+    MANAGED_PARTS.some((part) => normalized.includes(part)) ||
+    MANAGED_PREFIXES.some((prefix) => normalized.startsWith(prefix))
+  ) {
+    throw new InstallError(
+      "cli",
+      `${binary} is owned by a package manager or a source build; update SQLX with that tool`,
+    );
+  }
+  if ((fs.statSync(binary).mode & 0o222) === 0) {
+    throw new InstallError("cli", `${binary} is read-only; update SQLX with the tool that installed it`);
+  }
+}
+
+export function supportsSelfUpdate(binary) {
+  const result = spawnSync(binary, ["update", "status"], {
+    encoding: "utf8",
+    timeout: COMMAND_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    return false;
+  }
+  try {
+    return typeof JSON.parse(result.stdout)?.current_version === "string";
+  } catch {
+    return false;
+  }
+}
+
+function replace(candidate, target) {
+  if (process.platform !== "win32" || !fs.existsSync(target)) {
+    fs.renameSync(candidate, target);
+    return;
+  }
+  // Windows cannot rename over a running executable, so keep an independent copy
+  // until the replacement is in place.
+  const backup = `${target}.sqlx-previous`;
+  fs.rmSync(backup, { force: true });
+  fs.renameSync(target, backup);
+  try {
+    fs.renameSync(candidate, target);
+  } catch (error) {
+    fs.renameSync(backup, target);
+    throw error;
+  }
+  fs.rmSync(backup, { force: true });
+}
+
+export function selfUpdate(binary, version) {
+  run(binary, ["update", "install", "--version", version], INSTALL_TIMEOUT_MS, "cli");
+  const installed = readVersion(binary);
+  if (installed !== version) {
+    throw new InstallError(
+      "cli",
+      `sqlx update install finished but ${binary} reports ${installed ?? "no version"}`,
+    );
+  }
+}
+
+export function installCli({ binary, bytes, entrypoint, version }) {
+  const directory = path.dirname(binary);
+  try {
+    fs.mkdirSync(directory, { recursive: true });
+  } catch (error) {
+    throw new InstallError("cli", `cannot create ${directory}: ${error.message}`);
+  }
+  if (fs.existsSync(binary)) {
+    inspect(binary);
+    assertReplaceable(binary);
+  }
+  let stage;
+  try {
+    stage = fs.mkdtempSync(path.join(directory, ".sqlx-npm-"));
+  } catch (error) {
+    throw new InstallError("cli", `cannot write to ${directory}: ${error.message}`);
+  }
+  try {
+    extractZip(bytes, stage);
+    const candidate = path.join(stage, entrypoint);
+    if (!fs.existsSync(candidate)) {
+      throw new InstallError("archive", `archive does not contain ${entrypoint}`);
+    }
+    fs.chmodSync(candidate, 0o755);
+    const candidateVersion = readVersion(candidate);
+    if (candidateVersion !== version) {
+      throw new InstallError(
+        "verify",
+        `downloaded CLI reports ${candidateVersion ?? "no version"}, expected ${version}`,
+      );
+    }
+    replace(candidate, binary);
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+  const installed = readVersion(binary);
+  if (installed !== version) {
+    throw new InstallError("cli", `installed ${binary} reports ${installed ?? "no version"}`);
+  }
+}
+
+export function initializeData(binary, directory) {
+  if (fs.existsSync(directory)) {
+    return false;
+  }
+  run(binary, ["init"], INSTALL_TIMEOUT_MS, "init");
+  return true;
+}
+
+export function installSkill(binary, target) {
+  const stdout = run(binary, ["skill", "install", "--path", target], INSTALL_TIMEOUT_MS, "skill");
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}

package/src/errors.mjs

@@ -0,0 +1,8 @@
+export class UsageError extends Error {}
+
+export class InstallError extends Error {
+  constructor(stage, message, options) {
+    super(message, options);
+    this.stage = stage;
+  }
+}

package/src/main.mjs

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { HELP, parseArgs } from "./args.mjs";
+import * as cli from "./cli.mjs";
+import { InstallError, UsageError } from "./errors.mjs";
+import { compareVersions, downloadAsset, loadRelease, platformName, targetVersion } from "./release.mjs";
+
+export function resolveSkillTarget(value, cwd) {
+  if (value === undefined) {
+    return path.resolve(cwd, "sqlx");
+  }
+  if (value === "codex") {
+    return path.join(os.homedir(), ".agents", "skills", "sqlx");
+  }
+  if (value === "claude") {
+    return path.join(os.homedir(), ".claude", "skills", "sqlx");
+  }
+  return path.resolve(cwd, value);
+}
+
+function pathHint(directory) {
+  if (process.platform === "win32") {
+    return [
+      `${directory} is not in PATH.`,
+      `  This session:  $env:Path = "${directory};$env:Path"`,
+      "  Permanent:     add that directory to your user PATH",
+    ];
+  }
+  return [
+    `${directory} is not in PATH.`,
+    `  This shell:  export PATH="${directory}:$PATH"`,
+    "  Permanent:   add that line to your shell profile",
+  ];
+}
+
+function report(progress, log) {
+  log.log(`SQLX ${progress.cli.version}`);
+  log.log(`  CLI    ${progress.cli.path} (${progress.cli.action})`);
+  log.log(`  Skill  ${progress.skill.path}${progress.skill.version ? ` (${progress.skill.version})` : ""}`);
+  log.log(`  Data   ${progress.data.path} (${progress.data.created ? "created" : "already initialized"})`);
+  const directory = path.dirname(progress.cli.path);
+  const entries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  if (!entries.some((entry) => path.resolve(entry) === directory)) {
+    log.log("");
+    for (const line of pathHint(directory)) {
+      log.log(line);
+    }
+  }
+  log.log("");
+  log.log("Next: sqlx --version && sqlx skill status");
+}
+
+async function install(options, cwd, log) {
+  const version = targetVersion();
+  const platform = platformName();
+  const binary = path.join(cli.cliDirectory(), cli.binaryName());
+  const skillTarget = resolveSkillTarget(options.target, cwd);
+  const progress = { cli: null, skill: null, data: null };
+
+  // Refuse an unusable Skill destination before changing anything else.
+  let stats = null;
+  try {
+    stats = fs.lstatSync(skillTarget);
+  } catch {
+    stats = null;
+  }
+  if (stats?.isSymbolicLink()) {
+    throw new InstallError("skill", `${skillTarget} is a symbolic link; choose another --target`);
+  }
+
+  const existing = cli.inspect(binary);
+  let action;
+  if (!existing.exists) {
+    action = "install";
+  } else if (existing.version === version) {
+    action = "reuse";
+  } else if (compareVersions(existing.version, version) > 0) {
+    action = "keep";
+  } else {
+    action = cli.supportsSelfUpdate(binary) ? "update" : "replace";
+  }
+
+  if (action === "install" || action === "replace") {
+    const release = await loadRelease(version, platform);
+    const bytes = await downloadAsset(release.asset);
+    cli.installCli({ binary, bytes, entrypoint: release.asset.entrypoint, version });
+    progress.cli = { path: binary, version, action: action === "install" ? "installed" : "replaced" };
+  } else if (action === "update") {
+    cli.selfUpdate(binary, version);
+    progress.cli = { path: binary, version, action: "updated" };
+  } else if (action === "reuse") {
+    progress.cli = { path: binary, version, action: "reused" };
+  } else {
+    progress.cli = { path: binary, version: existing.version, action: "kept newer version" };
+  }
+
+  const dataDirectory = cli.dataDirectory();
+  progress.data = { path: dataDirectory, created: cli.initializeData(binary, dataDirectory) };
+
+  try {
+    const result = cli.installSkill(binary, skillTarget);
+    progress.skill = { path: skillTarget, version: result?.version ?? null };
+  } catch (error) {
+    throw new InstallError(
+      "skill",
+      `${error.message}\nThe CLI at ${binary} (${progress.cli.version}) is installed and usable; fix the Skill destination and run the command again to finish the Skill step.`,
+      { cause: error },
+    );
+  }
+
+  report(progress, log);
+  return 0;
+}
+
+export async function run(argv, log = console) {
+  const cwd = process.cwd();
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    if (!(error instanceof UsageError)) {
+      throw error;
+    }
+    log.error(`sqlx-install: ${error.message}`);
+    log.error("Run with --help for usage.");
+    return 2;
+  }
+  if (options.help) {
+    log.log(HELP);
+    return 0;
+  }
+  try {
+    return await install(options, cwd, log);
+  } catch (error) {
+    const stage = error instanceof InstallError ? error.stage : "install";
+    log.error(`SQLX installation failed (${stage}): ${error.message}`);
+    return 1;
+  }
+}

package/src/release.mjs

@@ -0,0 +1,177 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+
+import { InstallError } from "./errors.mjs";
+
+const DEFAULT_RELEASE_BASE = "https://github.com/OtterMind/sqlx/releases";
+const METADATA_TIMEOUT_MS = 30_000;
+const ARCHIVE_TIMEOUT_MS = 600_000;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+let metadata;
+
+function packageMetadata() {
+  metadata ??= JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  return metadata;
+}
+
+export function targetVersion() {
+  return process.env.SQLX_VERSION?.trim() || packageMetadata().version;
+}
+
+export function platformName() {
+  const os = { darwin: "macos", linux: "linux", win32: "windows" }[process.platform];
+  if (!os) {
+    throw new InstallError("platform", `unsupported operating system: ${process.platform}`);
+  }
+  const arch = { arm64: "arm64", x64: "x64" }[process.arch];
+  if (!arch) {
+    throw new InstallError("platform", `unsupported CPU architecture: ${process.arch}`);
+  }
+  if (os === "windows" && arch !== "x64") {
+    throw new InstallError("platform", "Windows ARM64 is not a release target");
+  }
+  return `${os}-${arch}`;
+}
+
+export function releaseBase() {
+  return (process.env.SQLX_RELEASE_BASE?.trim() || DEFAULT_RELEASE_BASE).replace(/\/+$/, "");
+}
+
+export function compareVersions(left, right) {
+  const parts = (value) => {
+    const numbers = value.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : Number.NaN));
+    if (numbers.some(Number.isNaN)) {
+      throw new InstallError("version", `cannot compare versions ${left} and ${right}`);
+    }
+    return numbers;
+  };
+  const a = parts(left);
+  const b = parts(right);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) {
+      return Math.sign(difference);
+    }
+  }
+  return 0;
+}
+
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function allowedUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    return false;
+  }
+  if (url.protocol === "https:") {
+    return true;
+  }
+  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+}
+
+function releaseUrl(base, version, file) {
+  return `${base}/download/v${version}/${file}`;
+}
+
+async function fetchBytes(url, timeout, what) {
+  let response;
+  try {
+    response = await fetch(url, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(timeout),
+      headers: { "user-agent": `${packageMetadata().name}/${packageMetadata().version}` },
+    });
+  } catch (error) {
+    throw new InstallError("download", `could not download ${what} from ${url}: ${error.message}`);
+  }
+  if (!response.ok) {
+    throw new InstallError("download", `could not download ${what} from ${url}: HTTP ${response.status}`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function parseSums(text) {
+  const sums = new Map();
+  for (const line of text.split("\n")) {
+    const match = /^([0-9a-fA-F]{64})\s+\*?(.+?)\s*$/.exec(line);
+    if (match) {
+      sums.set(match[2], match[1].toLowerCase());
+    }
+  }
+  return sums;
+}
+
+function validEntrypoint(value) {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value !== "." &&
+    value !== ".." &&
+    !value.includes("/") &&
+    !value.includes("\\")
+  );
+}
+
+export async function loadRelease(version, platform) {
+  const base = releaseBase();
+  const sums = parseSums(
+    (await fetchBytes(releaseUrl(base, version, "SHA256SUMS"), METADATA_TIMEOUT_MS, "SHA256SUMS")).toString("utf8"),
+  );
+  const manifestBytes = await fetchBytes(
+    releaseUrl(base, version, "manifest.json"),
+    METADATA_TIMEOUT_MS,
+    "manifest.json",
+  );
+  if (sums.get("manifest.json") !== sha256(manifestBytes)) {
+    throw new InstallError("verify", "SHA256SUMS does not match the downloaded manifest.json");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestBytes.toString("utf8"));
+  } catch (error) {
+    throw new InstallError("verify", `release manifest is not valid JSON: ${error.message}`);
+  }
+  if (manifest?.schema_version !== 1) {
+    throw new InstallError("verify", "unsupported release manifest schema");
+  }
+  const asset = manifest.components?.[`cli:${platform}`];
+  if (!asset) {
+    throw new InstallError("verify", `release ${version} has no CLI build for ${platform}`);
+  }
+  if (asset.version !== version) {
+    throw new InstallError("verify", `release manifest CLI version ${asset.version} does not match ${version}`);
+  }
+  if (asset.archive !== "zip") {
+    throw new InstallError("verify", `unsupported CLI archive format: ${asset.archive}`);
+  }
+  if (!validEntrypoint(asset.entrypoint)) {
+    throw new InstallError("verify", `unsafe CLI entrypoint: ${asset.entrypoint}`);
+  }
+  if (!/^[0-9a-fA-F]{64}$/.test(asset.sha256 ?? "")) {
+    throw new InstallError("verify", "release manifest has an invalid CLI SHA-256");
+  }
+  if (!allowedUrl(asset.url)) {
+    throw new InstallError("verify", `unsafe CLI download URL: ${asset.url}`);
+  }
+  const name = new URL(asset.url).pathname.split("/").pop();
+  if (!name || sums.get(name) !== asset.sha256.toLowerCase()) {
+    throw new InstallError("verify", `SHA256SUMS and manifest disagree about ${name || "the CLI archive"}`);
+  }
+  return { version, platform, asset: { ...asset, name } };
+}
+
+export async function downloadAsset(asset) {
+  const bytes = await fetchBytes(asset.url, ARCHIVE_TIMEOUT_MS, asset.name);
+  if (sha256(bytes) !== asset.sha256.toLowerCase()) {
+    throw new InstallError("verify", `checksum verification failed for ${asset.name}`);
+  }
+  return bytes;
+}

package/src/zip.mjs

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+
+import { InstallError } from "./errors.mjs";
+
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+const CENTRAL_FILE_HEADER = 0x02014b50;
+const LOCAL_FILE_HEADER = 0x04034b50;
+const ZIP64_MARKER = 0xffffffff;
+const MAXIMUM_COMMENT = 0xffff;
+const UNIX_FILE_TYPE = 0xf000;
+const UNIX_SYMBOLIC_LINK = 0xa000;
+const UNIX_DIRECTORY = 0x4000;
+
+function centralDirectoryEnd(buffer) {
+  const earliest = Math.max(0, buffer.length - MAXIMUM_COMMENT - 22);
+  for (let offset = buffer.length - 22; offset >= earliest; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === END_OF_CENTRAL_DIRECTORY) {
+      return offset;
+    }
+  }
+  throw new InstallError("archive", "downloaded archive is not a ZIP file");
+}
+
+function safeName(raw) {
+  if (raw.includes("\\") || raw.includes(":")) {
+    return null;
+  }
+  const trimmed = raw.replace(/\/+$/, "");
+  if (trimmed === "") {
+    return null;
+  }
+  const parts = trimmed.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) {
+    return null;
+  }
+  return trimmed;
+}
+
+export function extractZip(buffer, destination) {
+  const end = centralDirectoryEnd(buffer);
+  const entries = buffer.readUInt16LE(end + 10);
+  const centralSize = buffer.readUInt32LE(end + 12);
+  const centralOffset = buffer.readUInt32LE(end + 16);
+  if (centralOffset === ZIP64_MARKER || centralSize === ZIP64_MARKER || entries === 0xffff) {
+    throw new InstallError("archive", "ZIP64 archives are not supported");
+  }
+  if (centralOffset + centralSize > buffer.length) {
+    throw new InstallError("archive", "ZIP central directory is out of bounds");
+  }
+  const written = [];
+  let offset = centralOffset;
+  for (let index = 0; index < entries; index += 1) {
+    if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== CENTRAL_FILE_HEADER) {
+      throw new InstallError("archive", "ZIP central directory is damaged");
+    }
+    const flags = buffer.readUInt16LE(offset + 8);
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const uncompressedSize = buffer.readUInt32LE(offset + 24);
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    const externalAttributes = buffer.readUInt32LE(offset + 38);
+    const localOffset = buffer.readUInt32LE(offset + 42);
+    if (offset + 46 + nameLength > buffer.length) {
+      throw new InstallError("archive", "ZIP central directory is damaged");
+    }
+    const rawName = buffer.toString("utf8", offset + 46, offset + 46 + nameLength);
+    offset += 46 + nameLength + extraLength + commentLength;
+
+    if (flags & 0x1) {
+      throw new InstallError("archive", "encrypted ZIP entries are not supported");
+    }
+    if (
+      compressedSize === ZIP64_MARKER ||
+      uncompressedSize === ZIP64_MARKER ||
+      localOffset === ZIP64_MARKER
+    ) {
+      throw new InstallError("archive", "ZIP64 entries are not supported");
+    }
+    if (((externalAttributes >>> 16) & UNIX_FILE_TYPE) === UNIX_SYMBOLIC_LINK) {
+      throw new InstallError("archive", `ZIP symbolic links are not supported: ${rawName}`);
+    }
+    const name = safeName(rawName);
+    if (name === null) {
+      throw new InstallError("archive", `unsafe archive path: ${rawName}`);
+    }
+    if (method !== 0 && method !== 8) {
+      throw new InstallError("archive", `unsupported ZIP compression method ${method} for ${name}`);
+    }
+    if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== LOCAL_FILE_HEADER) {
+      throw new InstallError("archive", `ZIP local header is damaged for ${name}`);
+    }
+    const start =
+      localOffset + 30 + buffer.readUInt16LE(localOffset + 26) + buffer.readUInt16LE(localOffset + 28);
+    if (start + compressedSize > buffer.length) {
+      throw new InstallError("archive", `ZIP entry data is out of bounds for ${name}`);
+    }
+    const target = path.join(destination, name);
+    if (((externalAttributes >>> 16) & UNIX_FILE_TYPE) === UNIX_DIRECTORY || rawName.endsWith("/")) {
+      fs.mkdirSync(target, { recursive: true });
+      continue;
+    }
+    const raw = buffer.subarray(start, start + compressedSize);
+    let content;
+    try {
+      content = method === 0 ? raw : zlib.inflateRawSync(raw);
+    } catch (error) {
+      throw new InstallError("archive", `could not decompress ${name}: ${error.message}`);
+    }
+    if (content.length !== uncompressedSize) {
+      throw new InstallError("archive", `ZIP entry ${name} has an unexpected size`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const mode = (externalAttributes >>> 16) & 0o777;
+    fs.writeFileSync(target, content, { mode: mode || 0o644, flag: "wx" });
+    written.push(name);
+  }
+  return written;
+}