@altikva/cgh 0.12.0

package/README.md

@@ -0,0 +1,65 @@
+# @altikva/cgh
+
+Run [**cgh**](https://github.com/altikva/cgh) — a local code graph + memory +
+plans + knowledge layer for AI coding agents — with no Python installed. This
+package is a thin launcher: on first use it downloads the standalone `cgh`
+binary for your OS from the matching GitHub Release, verifies its SHA-256,
+caches it, and runs it.
+
+```bash
+# one-off, no install
+npx @altikva/cgh --version
+npx @altikva/cgh serve --root .        # start the MCP server for this repo
+
+# or install the `cgh` command globally
+npm install -g @altikva/cgh
+cgh serve --root .
+```
+
+## Sealed vs egress
+
+The binary ships in two variants, and this launcher picks between them:
+
+- **Sealed (default).** The core graph, the MCP tools, memory / plans /
+  knowledge, and the local-only plugins (PII scrubbing, classification). It
+  contains no code that can reach the network, so it cannot phone home.
+- **Egress.** Adds the plugins that can call an external model (code
+  generation, summarization, bug reports). They stay behind cgh's egress gate
+  and do nothing until configured, and can target a local model too.
+
+```bash
+npx @altikva/cgh --egress serve        # fetch and run the egress build
+CGH_EGRESS=1 npx @altikva/cgh serve    # same, via env
+```
+
+A leading `--egress` is consumed by the launcher; everything after it is passed
+straight to `cgh`.
+
+## What you get vs pip / uvx
+
+This launcher runs the **light SQLite build**. If you want DuckDB's analytical
+speed, or the heavy `docs` / `vision` plugins, install with Python instead:
+
+```bash
+uvx cgh serve                 # bundles DuckDB
+pip install "cgh[full]"       # DuckDB + every first-party plugin
+```
+
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `CGH_EGRESS=1` / `CGH_VARIANT=egress` | Use the egress build. |
+| `CGH_CACHE_DIR` | Where the binary is cached (default: `~/.cache/cgh/bin`). |
+| `CGH_DOWNLOAD_BASE` | Override the release download base (private mirrors, testing). |
+
+## Supported platforms
+
+macOS (Apple Silicon), Linux (x64, arm64), Windows (x64). Intel Macs and any
+other platform have no prebuilt binary, so the launcher tells you to `uvx cgh`
+instead.
+
+## License
+
+MIT AND CC-BY-NC-SA-4.0, the same as cgh itself. See the
+[main repository](https://github.com/altikva/cgh).

package/bin/cgh.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+// __creation__ = 2026-09-17
+// __author__ = "jndjama (Joy Ndjama)"
+// __copyright__ = "Copyright 2026 ALTIKVA."
+// __licence__ = "MIT & CC BY-NC-SA (https://www.altikva.com/licenses/LICENSE-1.0)"
+// -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+// Description: The npx launcher. Resolves the standalone cgh binary for this
+//              OS/arch and variant (sealed by default, egress with a leading
+//              --egress), downloading it from the matching GitHub Release on
+//              first use, verifying its SHA-256 against the published .sha256,
+//              caching it under the user's cache dir, then exec-ing it with the
+//              remaining args and forwarding its exit code. No binary is bundled
+//              in the npm package: it is fetched lazily so a single small
+//              package serves every platform, and the variant is a runtime
+//              choice the wrapper cannot know at install time. The download base
+//              and cache dir are overridable (CGH_DOWNLOAD_BASE, CGH_CACHE_DIR)
+//              for private mirrors and for tests.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const { targetFor, assetName, selectVariant, downloadUrl } = require('../lib/resolve');
+const pkg = require('../package.json');
+
+const DEFAULT_BASE = 'https://github.com/altikva/cgh/releases/download';
+
+function log(msg) {
+  process.stderr.write(`[cgh] ${msg}\n`);
+}
+
+function httpGet(url, redirects) {
+  redirects = redirects || 0;
+  return new Promise((resolve, reject) => {
+    if (redirects > 6) {
+      reject(new Error(`too many redirects fetching ${url}`));
+      return;
+    }
+    const client = url.startsWith('http://') ? http : https;
+    client
+      .get(url, { headers: { 'user-agent': `cgh-npm/${pkg.version}` } }, (res) => {
+        const { statusCode, headers } = res;
+        if (statusCode >= 300 && statusCode < 400 && headers.location) {
+          res.resume();
+          resolve(httpGet(new URL(headers.location, url).toString(), redirects + 1));
+          return;
+        }
+        if (statusCode !== 200) {
+          res.resume();
+          reject(new Error(`GET ${url} -> HTTP ${statusCode}`));
+          return;
+        }
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      })
+      .on('error', reject);
+  });
+}
+
+// sha256sum / shasum -a 256 write "<64 hex>  <filename>"; take the digest.
+function expectedSha(shaText) {
+  const m = /^([0-9a-fA-F]{64})\b/.exec(shaText.trim());
+  if (!m) {
+    throw new Error('could not parse the .sha256 checksum file');
+  }
+  return m[1].toLowerCase();
+}
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function cacheDir(version) {
+  const base =
+    process.env.CGH_CACHE_DIR || path.join(os.homedir() || os.tmpdir(), '.cache', 'cgh', 'bin');
+  return path.join(base, `v${version}`);
+}
+
+async function ensureBinary(variant) {
+  const version = pkg.version;
+  const target = targetFor(process.platform, process.arch);
+  const asset = assetName(target, variant);
+  const dir = cacheDir(version);
+  const dest = path.join(dir, asset);
+  if (fs.existsSync(dest)) {
+    return dest;
+  }
+
+  const base = process.env.CGH_DOWNLOAD_BASE || DEFAULT_BASE;
+  const url = downloadUrl(base, version, asset);
+  log(`downloading ${asset} (v${version})...`);
+  const [bin, shaText] = await Promise.all([httpGet(url), httpGet(`${url}.sha256`)]);
+  const want = expectedSha(shaText.toString('utf8'));
+  const got = sha256(bin);
+  if (got !== want) {
+    throw new Error(`checksum mismatch for ${asset}: expected ${want}, got ${got}`);
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${dest}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, bin);
+  fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, dest);
+  log(`cached at ${dest}`);
+  return dest;
+}
+
+async function main() {
+  const { variant, rest } = selectVariant(process.argv.slice(2), process.env);
+  let bin;
+  try {
+    bin = await ensureBinary(variant);
+  } catch (err) {
+    log(`error: ${err.message}`);
+    process.exit(1);
+  }
+  const result = spawnSync(bin, rest, { stdio: 'inherit' });
+  if (result.error) {
+    log(`failed to run the binary: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { ensureBinary, cacheDir, expectedSha, sha256 };

package/lib/resolve.js

@@ -0,0 +1,71 @@
+// -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+// __creation__ = 2026-09-17
+// __author__ = "jndjama (Joy Ndjama)"
+// __copyright__ = "Copyright 2026 ALTIKVA."
+// __licence__ = "MIT & CC BY-NC-SA (https://www.altikva.com/licenses/LICENSE-1.0)"
+// -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
+// Description: Pure, side-effect-free resolution helpers for the npx wrapper.
+//              targetFor maps a Node platform/arch to the release asset target;
+//              assetName builds the file name for a target and variant (sealed
+//              -> cgh-<target>, egress -> cgh-egress-<target>, plus .exe on
+//              Windows); selectVariant reads a leading --egress flag or the
+//              env and returns the variant plus the untouched pass-through
+//              args; downloadUrl joins the release base, version and asset. No
+//              I/O here so the launcher's logic is unit-testable without a
+//              network or a real binary.
+
+'use strict';
+
+// Node (platform, arch) -> the release asset target. These are the targets the
+// release matrix builds; anything else has no prebuilt binary. macOS x64
+// (Intel) is absent on purpose: GitHub retired the Intel macOS hosted runner
+// and PyInstaller cannot cross-compile one, so Intel-Mac users get the
+// install-with-Python hint below instead of a download that 404s.
+const PLATFORM_MAP = {
+  'darwin arm64': 'macos-arm64',
+  'linux x64': 'linux-x64',
+  'linux arm64': 'linux-arm64',
+  'win32 x64': 'windows-x64',
+};
+
+function targetFor(platform, arch) {
+  const target = PLATFORM_MAP[`${platform} ${arch}`];
+  if (!target) {
+    const supported = Object.keys(PLATFORM_MAP).join(', ');
+    throw new Error(
+      `no prebuilt cgh binary for ${platform}/${arch}. Supported: ${supported}. ` +
+        'Install with Python instead: uvx cgh (or pip install cgh).',
+    );
+  }
+  return target;
+}
+
+function assetName(target, variant) {
+  const prefix = variant === 'egress' ? 'cgh-egress' : 'cgh';
+  const ext = target.startsWith('windows') ? '.exe' : '';
+  return `${prefix}-${target}${ext}`;
+}
+
+// A leading --egress selects the egress build; CGH_VARIANT=egress or
+// CGH_EGRESS=1 do the same. Everything else is passed through to the binary
+// untouched, so tool flags are never swallowed. Only a LEADING --egress is
+// consumed, so a stray later occurrence reaches the binary and errors loudly
+// rather than being silently reinterpreted.
+function selectVariant(argv, env) {
+  env = env || {};
+  const wantEgress =
+    env.CGH_VARIANT === 'egress' || env.CGH_EGRESS === '1' || env.CGH_EGRESS === 'true';
+  let variant = wantEgress ? 'egress' : 'sealed';
+  const rest = argv.slice();
+  if (rest[0] === '--egress') {
+    variant = 'egress';
+    rest.shift();
+  }
+  return { variant, rest };
+}
+
+function downloadUrl(base, version, asset) {
+  return `${base.replace(/\/+$/, '')}/v${version}/${asset}`;
+}
+
+module.exports = { PLATFORM_MAP, targetFor, assetName, selectVariant, downloadUrl };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@altikva/cgh",
+  "version": "0.12.0",
+  "description": "Local code graph + memory + plans + knowledge for AI coding agents. Downloads and runs the standalone cgh binary; no Python required.",
+  "bin": {
+    "cgh": "bin/cgh.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "code-graph",
+    "cgh",
+    "codegraph",
+    "mcp",
+    "ai",
+    "navigation"
+  ],
+  "homepage": "https://github.com/altikva/cgh#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/altikva/cgh.git",
+    "directory": "packaging/npm"
+  },
+  "bugs": {
+    "url": "https://github.com/altikva/cgh/issues"
+  },
+  "author": "Joy Ndjama <joy.ndjama@altikva.com>",
+  "license": "MIT AND CC-BY-NC-SA-4.0"
+}