@gox-lang/cli 0.0.0-stage → 0.1.3

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to GOX
+
+Thank you for your interest in contributing to GOX.
+
+GOX recognizes that contributing to an open source project does not necessarily mean writing code. Bug reports, proposals for new features, and other contributions that materially help improve the project may be recognized as contributions.
+
+At this stage of the project, GOX primarily accepts contributions through **bug reports** and **proposals**. Direct implementation and modification of the source code are handled by the project maintainers.
+
+This model may evolve in the future as the project, its community, and its resources grow.
+
+## Bug Reports
+
+If you find incorrect behavior in GOX, you can report it through **GitHub Issues**.
+
+A good bug report should include, when possible:
+
+- A clear description of the problem.
+- The expected behavior.
+- The observed behavior.
+- The steps required to reproduce it.
+- The GOX version being used.
+- Relevant information about the environment.
+- A minimal example or reproduction code, when useful.
+- Logs, error messages, or other information that may help investigate the problem.
+
+A report that materially contributes to identifying, reproducing, or resolving an issue may be recognized as a contribution to the project.
+
+The implementation of the fix will be handled by the GOX maintainers.
+
+Issues that may have security implications **must not be published as public GitHub Issues**. See [`SECURITY.md`](SECURITY.md) for the reporting process using GitHub Private Vulnerability Reporting.
+
+## Proposals
+
+Proposals for new features, APIs, syntax, or significant changes to GOX behavior are welcome.
+
+A proposal should clearly explain:
+
+- The problem or need it is intended to address.
+- The proposed behavior.
+- Why it would be useful to GOX or its users.
+- Examples that help explain the proposal, when necessary.
+
+Proposals will be evaluated with consideration for the architecture, consistency, philosophy, and goals of GOX.
+
+An accepted proposal does not necessarily mean that its original design will be implemented exactly as presented. The maintainers may adapt, modify, or redesign the solution to ensure that it integrates correctly with the rest of GOX.
+
+When a proposal materially contributes to a feature that is ultimately incorporated into the project, its author may be recognized for their contribution.
+
+The final implementation will be handled by the GOX maintainers.
+
+## Code Contributions
+
+At this stage, GOX **does not accept Pull Requests containing direct code contributions**.
+
+Development and modifications to the source code are handled by the maintainers. This helps maintain a consistent architecture, API, syntax, and technical direction while the project is in its early stages.
+
+This does not prevent contributors from including code as part of a bug report or proposal. Contributors may provide code examples, minimal reproducible cases, proofs of concept, or possible API and syntax designs when they help explain or demonstrate a contribution.
+
+These examples are considered supporting material for evaluating and developing the contribution. The implementation ultimately incorporated into GOX will be designed and written by the maintainers.
+
+The policy regarding direct code contributions and Pull Requests may change in the future as the project evolves.
+
+## Recognition
+
+GOX may recognize as contributors people who have made significant contributions to the project even if they did not directly write the code that is ultimately incorporated.
+
+This may include, among other things:
+
+- Bug reports that materially contribute to identifying or resolving an issue.
+- Proposals that materially contribute to the design or introduction of a new feature.
+- Other technical or documentation contributions that have a significant impact on the project.
+
+Recognition of a contribution **does not imply authorship or ownership of code written by the GOX maintainers**.
+
+## Security
+
+Potential security vulnerabilities must not be reported through public GitHub Issues.
+
+See [`SECURITY.md`](SECURITY.md) for the vulnerability reporting process using **GitHub Private Vulnerability Reporting**.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Marquez
+
+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,3 +1,99 @@
-# Temporary Holding Version
+# GOX CLI for npm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One JavaScript package installs the official GOX executable from **GitHub Releases**.
+No native binaries are committed to this repository or included in the npm package.
+No Python, Go compiler, curl, tar or unzip command is needed by this installer.
+
+## Installation
+
+Node.js 20 or newer is required.
+
+```sh
+npm install -g @gox-lang/cli --ignore-scripts=false --foreground-scripts
+gox version
+```
+
+Installation scripts must be enabled. On npm versions that require explicit script
+approval, also allow this package (for global installs, supported npm versions offer
+`--allow-scripts=@gox-lang/cli`). Do not disable organization security policies globally.
+See [npm configuration](https://docs.npmjs.com/cli/using-npm/config/) for your version.
+
+npm places `gox` in its global command directory, which must be on PATH. The installer
+does not modify shell profiles or create a second installation outside this package.
+
+Linux/glibc, macOS and Windows releases support x64 and arm64. Native Windows can run
+the CLI/LSP; use WSL for application development because Go plugins require it.
+Alpine/musl is not supported by the official Linux binaries.
+
+## How it works
+
+`postinstall` detects the platform, downloads the exact release matching this package's
+version from `gox-lang/server`, verifies the archive against that release's SHA-256
+checksums, extracts only the executable, and checks `gox version` before installing.
+The downloaded executable and receipt live in `.vendor/`, excluded from Git and npm.
+The launcher checks the receipt and binary digest, then forwards arguments and stdio.
+It never downloads during ordinary command execution.
+
+Internet access to GitHub and its release-asset CDN is required during installation.
+A failed download or verification fails installation; it never falls back to another
+binary source. HTTPS and release checksums are used, not an independent signing system.
+
+## Scripts disabled or incomplete installation
+
+The command prints instructions and exits without downloading. To complete a global
+installation explicitly:
+
+```sh
+npm rebuild -g @gox-lang/cli --ignore-scripts=false --foreground-scripts
+```
+
+For a local project dependency, omit `-g`. If your npm version requires package-specific
+approval, approve this package before rebuilding.
+
+## Updates
+
+```sh
+npm install -g @gox-lang/cli@latest --ignore-scripts=false --foreground-scripts
+```
+
+Use npm to manage this installation. `gox update` prints npm update instructions; LSP
+auto-update is disabled in the child environment so it cannot replace npm's executable.
+GOX v0.1.3 native update notices may still recommend `gox update`; the launcher redirects
+that command. Future server releases can improve the wording. Invoking the nested
+binary directly bypasses these launcher rules.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run test:install
+npm pack --dry-run
+```
+
+The smoke test installs a tarball in a temporary global prefix, checks the missing-script
+message, explicitly rebuilds from GitHub, runs GOX, and checks corruption detection.
+No developer installation or shell configuration is changed.
+
+- `bin/gox.cjs`: command launcher.
+- `lib/install.cjs`: installation, verification and archive handling in JavaScript.
+- `tests/`: JavaScript unit and isolated installation tests.
+- `package-lock.json`: locked development dependency tree.
+
+The package version pins the corresponding GOX release, not a moving latest download.
+Before each publication, run the cross-platform CI checks and inspect the tarball.
+Publication requires maintainer access to the npm organization and is not automated here.
+
+## Contributing
+
+Bug reports and proposals are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md)
+for the current GOX contribution policy.
+
+## Security
+
+Report potential vulnerabilities privately through GitHub Private Vulnerability Reporting.
+See [SECURITY.md](SECURITY.md) for the reporting process.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,53 @@
+# Security Policy
+
+The security of GOX is a priority. If you discover a potential security vulnerability in GOX, report it through **GitHub Private Vulnerability Reporting**, available in the **Security** section of this repository, so it can be investigated before being made public.
+
+## Reporting a Vulnerability
+
+Potential security vulnerabilities should be reported using **GitHub Private Vulnerability Reporting** in the **Security** section of the repository.
+
+Please **do not publish vulnerabilities or potential vulnerabilities as public GitHub Issues**.
+
+When possible, include:
+
+- A clear description of the issue.
+- The steps required to reproduce it.
+- The affected GOX versions.
+- The security impact you believe it may have.
+- Any examples, proof of concept, or additional information that may help reproduce and investigate the issue.
+
+You do not need to determine the severity of the vulnerability beforehand. GOX will evaluate the report and determine its impact and severity during the investigation.
+
+If you are unsure whether an issue has security implications, **report it through GitHub Private Vulnerability Reporting in the Security section of the repository**.
+
+## What Should Be Reported Through GitHub Private Vulnerability Reporting
+
+Use GitHub Private Vulnerability Reporting for issues that may have security implications, including but not limited to:
+
+- Unauthorized access or actions.
+- Authentication or authorization issues.
+- Exposure of sensitive information.
+- Session-related manipulation or vulnerabilities.
+- Unintended code execution.
+- Vulnerabilities related to paths or filesystem access.
+- Security issues related to WebSockets or other communications.
+- Vulnerabilities that could cause a denial of service through abnormal or exploitable GOX behavior.
+- Any other behavior that could compromise the security of a GOX application, server, or user.
+
+## What Should Not Be Reported as a Vulnerability
+
+Issues that do not have security implications should be reported through **GitHub Issues**.
+
+This includes compilation errors, incorrect API behavior, CLI issues, hot reload issues, tooling problems, framework compatibility issues, performance issues, documentation problems, and other functional bugs that do not represent a security risk.
+
+## Supported Versions
+
+Security vulnerabilities will be evaluated for versions of GOX that are currently supported.
+
+Versions that have reached the end of their support period may not receive security fixes.
+
+## Disclosure
+
+Please do not publicly disclose the details of a vulnerability while it is being investigated and, when applicable, fixed.
+
+Once the issue has been resolved, GOX may publish information about the vulnerability, the affected versions, and the corresponding fix.

package/bin/gox.cjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn } = require('node:child_process');
+const { installed } = require('../lib/install.cjs');
+
+async function main(args) {
+  if (args[0] === 'update') {
+    console.error('This GOX installation is managed by npm.\nGlobal installation: npm install -g @gox-lang/cli@latest\nProject dependency: npm install @gox-lang/cli@latest');
+    process.exitCode = 1;
+    return;
+  }
+  let executable;
+  try {
+    executable = await installed();
+  } catch (error) {
+    console.error('GOX is not installed or its installation is incomplete. Installation scripts must be enabled.\nRun: npm rebuild -g @gox-lang/cli --ignore-scripts=false --foreground-scripts\nFor a project dependency, omit -g. If npm requires script approval, approve @gox-lang/cli before rebuilding.');
+    process.exitCode = 1;
+    return;
+  }
+  const child = spawn(executable, args, {
+    stdio: 'inherit',
+    env: { ...process.env, GOX_LSP_AUTO_UPDATE: '0' },
+  });
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  const handlers = new Map();
+  for (const signal of signals) {
+    const handler = () => { if (!child.killed) child.kill(signal); };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  const cleanup = () => {
+    for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+  };
+  child.once('error', (error) => {
+    cleanup();
+    console.error(`Could not start GOX: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.once('exit', (code, signal) => {
+    cleanup();
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+}
+
+module.exports = { main };
+if (require.main === module) main(process.argv.slice(2));

package/lib/install.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const tar = require('tar');
+const AdmZip = require('adm-zip');
+const { version } = require('../package.json');
+const root = path.resolve(__dirname, '..');
+const LIMIT = 256 * 1024 * 1024;
+
+function target(platform = process.platform, arch = process.arch) {
+  const systems = { linux: 'linux', darwin: 'darwin', win32: 'windows' };
+  const arches = { x64: 'amd64', arm64: 'arm64' };
+  if (!systems[platform] || !arches[arch]) throw new Error(`Unsupported platform: ${platform}/${arch}.`);
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error('Invalid pinned GOX version.');
+  return {
+    id: `${version}-${platform}-${arch}`,
+    binary: platform === 'win32' ? 'gox.exe' : 'gox',
+    archive: `gox_${version}_${systems[platform]}_${arches[arch]}.${platform === 'win32' ? 'zip' : 'tar.gz'}`,
+  };
+}
+
+async function download(url, limit = LIMIT) {
+  // GitHub serves release assets through its HTTPS release CDN.
+  for (let redirects = 0; redirects <= 5; redirects++) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || !['github.com', 'release-assets.githubusercontent.com', 'objects.githubusercontent.com'].includes(parsed.hostname)) {
+      throw new Error('Refusing an untrusted release URL.');
+    }
+    const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(120000) });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      await response.body?.cancel();
+      url = new URL(response.headers.get('location'), url).href;
+      continue;
+    }
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`GitHub download failed: HTTP ${response.status}`); }
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of response.body) {
+      length += chunk.length;
+      if (length > limit) throw new Error('Release download exceeds the size limit.');
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+  throw new Error('Too many release redirects.');
+}
+
+function digest(data) { return createHash('sha256').update(data).digest('hex'); }
+function verify(data, checksums, filename) {
+  const matches = checksums.toString().split(/\r?\n/).map(line => line.trim().split(/\s+/)).filter(fields => fields.length === 2 && fields[1] === filename);
+  if (matches.length !== 1 || !/^[a-f\d]{64}$/i.test(matches[0][0])) throw new Error('Missing, duplicate or invalid release checksum.');
+  if (digest(data) !== matches[0][0].toLowerCase()) throw new Error('Release checksum mismatch. Nothing was installed.');
+}
+
+async function extract(data, filename) {
+  if (filename === 'gox.exe') {
+    const matches = new AdmZip(data).getEntries().filter(entry => entry.entryName === filename);
+    if (matches.length !== 1 || matches[0].isDirectory || matches[0].header.size > LIMIT) throw new Error('Invalid executable in ZIP archive.');
+    return matches[0].getData();
+  }
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let count = 0;
+    let size = 0;
+    let invalid = false;
+    const parser = tar.t({ strict: true, onReadEntry(entry) {
+      if (entry.path !== filename) { entry.resume(); return; }
+      count++;
+      if (entry.type !== 'File' || entry.size > LIMIT) { invalid = true; entry.resume(); return; }
+      entry.on('data', chunk => {
+        size += chunk.length;
+        if (size > LIMIT) invalid = true;
+        else chunks.push(chunk);
+      });
+    } });
+    parser.on('error', reject);
+    parser.on('end', () => {
+      if (invalid || count !== 1 || !size) reject(new Error('Invalid executable in TAR archive.'));
+      else resolve(Buffer.concat(chunks));
+    });
+    parser.end(data);
+  });
+}
+
+async function installed(packageRoot = root) {
+  const platform = target();
+  const directory = path.join(packageRoot, '.vendor', platform.id);
+  const binary = path.join(directory, platform.binary);
+  const metadata = JSON.parse(await fs.readFile(path.join(directory, 'receipt.json'), 'utf8'));
+  if (metadata.id !== platform.id || digest(await fs.readFile(binary)) !== metadata.sha256) throw new Error('Installed GOX binary is incomplete or has changed.');
+  return binary;
+}
+
+async function install(packageRoot = root, get = download) {
+  const platform = target();
+  if (process.platform === 'linux' && !process.report.getReport().header.glibcVersionRuntime) {
+    throw new Error('Official GOX Linux binaries require glibc. Alpine/musl is not supported.');
+  }
+  const base = `https://github.com/gox-lang/server/releases/download/v${version}`;
+  console.error(`Downloading GOX v${version} from GitHub Releases...`);
+  const checksums = await get(`${base}/checksums.sha256`, 1024 * 1024);
+  const archive = await get(`${base}/${platform.archive}`);
+  verify(archive, checksums, platform.archive);
+  const executable = await extract(archive, platform.binary);
+  const directory = path.join(packageRoot, '.vendor', platform.id);
+  await fs.mkdir(directory, { recursive: true });
+  const staging = await fs.mkdtemp(path.join(packageRoot, '.gox-install-'));
+  try {
+    const candidate = path.join(staging, platform.binary);
+    await fs.writeFile(candidate, executable, { mode: 0o755 });
+    const output = execFileSync(candidate, ['version'], { encoding: 'utf8', timeout: 15000 });
+    if (!output.includes(`v${version}`)) throw new Error('Downloaded executable reported an unexpected version.');
+    await fs.writeFile(path.join(staging, 'receipt.json'), JSON.stringify({ id: platform.id, sha256: digest(executable) }));
+    await fs.rename(candidate, path.join(directory, platform.binary));
+    await fs.rename(path.join(staging, 'receipt.json'), path.join(directory, 'receipt.json'));
+  } finally { await fs.rm(staging, { recursive: true, force: true }); }
+  console.error(`GOX v${version} installed successfully. Run: gox version`);
+}
+
+module.exports = { target, verify, extract, install, installed };
+if (require.main === module) install().catch(error => { console.error(`GOX installation failed: ${error.message}`); process.exitCode = 1; });

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@gox-lang/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "Install and run the official GOX binary from GitHub Releases.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "gox": "bin/gox.cjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "postinstall": "node lib/install.cjs",
+    "test": "node --test tests/*.test.cjs",
+    "test:install": "node tests/smoke-install.cjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "adm-zip": "0.6.1",
+    "tar": "7.5.22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gox-lang/npm.git"
+  },
+  "homepage": "https://gox-lang.dev",
+  "bugs": {
+    "url": "https://github.com/gox-lang/npm/issues"
+  }
+}