@adgine/geo-cli 1.2.8

package/src/config.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * Config manager for adgine-geo CLI.
+ *
+ * The GEO API key and optional base URL live in ~/.adgine/config.json
+ * (0600). They are NOT written into the package (node_modules is often
+ * read-only for global installs) and NOT written to shell rc files.
+ *
+ * Resolution precedence (highest first):
+ *   1. process.env.GEO_API_KEY / GEO_API_BASE_URL
+ *   2. ~/.adgine/config.json
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CONFIG_DIR = path.join(os.homedir(), '.adgine');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_BASE_URL = 'https://platform.adgine.ai';
+
+function configPath() {
+  return CONFIG_PATH;
+}
+
+function readConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  const json = JSON.stringify(config, null, 2) + '\n';
+  // Write then chmod so the key file is never briefly world-readable.
+  fs.writeFileSync(CONFIG_PATH, json, { mode: 0o600 });
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    /* best effort on platforms without chmod */
+  }
+}
+
+function setKey(key) {
+  const trimmed = (key || '').trim();
+  if (!trimmed) {
+    throw new Error('API key is empty.');
+  }
+  const config = readConfig();
+  config.apiKey = trimmed;
+  writeConfig(config);
+  return trimmed;
+}
+
+function setBaseUrl(url) {
+  const config = readConfig();
+  const trimmed = (url || '').trim().replace(/\/+$/, '');
+  if (trimmed) {
+    config.baseUrl = trimmed;
+  } else {
+    delete config.baseUrl;
+  }
+  writeConfig(config);
+  return trimmed;
+}
+
+/**
+ * Resolve the effective key. Returns undefined if none configured.
+ */
+function getKey() {
+  if (process.env.GEO_API_KEY && process.env.GEO_API_KEY.trim()) {
+    return process.env.GEO_API_KEY.trim();
+  }
+  const config = readConfig();
+  return config.apiKey || undefined;
+}
+
+/**
+ * Resolve the effective base URL. Env > config > default.
+ */
+function getBaseUrl() {
+  if (process.env.GEO_API_BASE_URL && process.env.GEO_API_BASE_URL.trim()) {
+    return process.env.GEO_API_BASE_URL.trim().replace(/\/+$/, '');
+  }
+  const config = readConfig();
+  return (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+}
+
+/**
+ * Where the effective key came from, for `config get` / doctor messaging.
+ */
+function keySource() {
+  if (process.env.GEO_API_KEY && process.env.GEO_API_KEY.trim()) {
+    return 'env (GEO_API_KEY)';
+  }
+  if (readConfig().apiKey) {
+    return CONFIG_PATH;
+  }
+  return null;
+}
+
+function maskKey(key) {
+  if (!key) return '(not set)';
+  if (key.length <= 12) return key.slice(0, 3) + '…';
+  return key.slice(0, 10) + '…' + key.slice(-4);
+}
+
+module.exports = {
+  CONFIG_PATH,
+  DEFAULT_BASE_URL,
+  configPath,
+  readConfig,
+  writeConfig,
+  setKey,
+  setBaseUrl,
+  getKey,
+  getBaseUrl,
+  keySource,
+  maskKey,
+};

package/src/doctor.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * Environment health check for adgine-geo.
+ *
+ * Verifies: Python 3 present, API key configured + valid, and (optionally
+ * installs) the extra pip dependencies the site-audit skill needs.
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const config = require('./config');
+const runner = require('./runner');
+
+const OK = '✔';
+const BAD = '✖';
+const WARN = '!';
+
+const AUDIT_REQS = path.join(
+  runner.SKILLS_DIR,
+  'adgine-geo-site-audit',
+  'requirements.txt'
+);
+const AUDIT_MODULES = ['curl_cffi', 'bs4', 'lxml', 'markdown', 'reportlab'];
+
+function checkPython() {
+  const py = runner.findPython();
+  if (!py) return { ok: false, line: `${BAD} Python 3: not found on PATH` };
+  const res = spawnSync(py, ['--version'], { encoding: 'utf8' });
+  const ver = ((res.stdout || '') + (res.stderr || '')).trim();
+  return { ok: true, py, line: `${OK} Python 3: ${ver} (${py})` };
+}
+
+async function checkKey() {
+  const key = config.getKey();
+  if (!key) {
+    return {
+      ok: false,
+      line:
+        `${BAD} GEO_API_KEY: not set\n` +
+        `     Fix: adgine-geo config set-key geo_sk_live_xxx\n` +
+        `     Get a key at https://platform.adgine.ai`,
+    };
+  }
+  const source = config.keySource();
+  const base = config.getBaseUrl();
+  // Verify against the same endpoint setup.py uses.
+  try {
+    const res = await fetch(`${base}/api/projects?limit=1`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${key}`,
+        Accept: 'application/json',
+        'User-Agent': 'adgine-geo-cli-doctor/1.0',
+      },
+      signal: AbortSignal.timeout(10000),
+    });
+    if (res.status === 401) {
+      return {
+        ok: false,
+        line:
+          `${BAD} GEO_API_KEY: ${config.maskKey(key)} — 401 Unauthorized (invalid or revoked)\n` +
+          `     Generate a new key at https://platform.adgine.ai`,
+      };
+    }
+    if (res.ok) {
+      return {
+        ok: true,
+        line: `${OK} GEO_API_KEY: ${config.maskKey(key)} — valid (from ${source})`,
+      };
+    }
+    return {
+      ok: true,
+      line: `${WARN} GEO_API_KEY: ${config.maskKey(key)} — HTTP ${res.status} (non-auth; treating as ok)`,
+    };
+  } catch (err) {
+    return {
+      ok: true,
+      line: `${WARN} GEO_API_KEY: ${config.maskKey(key)} — verification skipped (${err.message})`,
+    };
+  }
+}
+
+function checkAuditDeps() {
+  const py = runner.findPython();
+  if (!py) return { ok: false, line: `${WARN} site-audit deps: skipped (no Python)` };
+  const res = spawnSync(py, ['-c', `import ${AUDIT_MODULES.join(', ')}`], {
+    encoding: 'utf8',
+  });
+  if (res.status === 0) {
+    return { ok: true, line: `${OK} site-audit deps: installed` };
+  }
+  return {
+    ok: true, // optional — not a hard failure
+    line:
+      `${WARN} site-audit deps: missing (${AUDIT_MODULES.join(', ')})\n` +
+      `     Only needed for the site-audit skill. Install with:\n` +
+      `     adgine-geo doctor --install-audit-deps`,
+  };
+}
+
+function installAuditDeps() {
+  const py = runner.findPython();
+  if (!py) {
+    process.stderr.write('ERROR: Python 3 not found; cannot install deps.\n');
+    return 69;
+  }
+  process.stdout.write(`Installing site-audit dependencies from ${AUDIT_REQS} ...\n`);
+  const res = spawnSync(py, ['-m', 'pip', 'install', '-r', AUDIT_REQS], {
+    stdio: 'inherit',
+  });
+  return res.status == null ? 1 : res.status;
+}
+
+async function run({ installAudit = false } = {}) {
+  if (installAudit) {
+    return installAuditDeps();
+  }
+  process.stdout.write('adgine-geo doctor\n\n');
+  const py = checkPython();
+  process.stdout.write(py.line + '\n');
+  const key = await checkKey();
+  process.stdout.write(key.line + '\n');
+  const audit = checkAuditDeps();
+  process.stdout.write(audit.line + '\n');
+  process.stdout.write('\n');
+
+  const hardFail = !py.ok || !key.ok;
+  if (hardFail) {
+    process.stdout.write('Some checks failed — see fixes above.\n');
+    return 1;
+  }
+  process.stdout.write('All required checks passed.\n');
+  return 0;
+}
+
+module.exports = { run, installAuditDeps };

package/src/install.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Install the bundled skill folders into an AI agent's skills directory, so
+ * agents (Claude Code, Cursor, etc.) can load them as native skills and run the
+ * Python scripts themselves — the same layout they'd get from a git clone.
+ *
+ * We copy the skill folders plus the supporting files (scripts/, VERSION,
+ * SKILL.md, .env.example) preserving the layout _client.py expects (repo root =
+ * the install target). The GEO_API_KEY is written to a .env at the target root
+ * so the agent-run scripts pick it up, matching the existing clone workflow.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const config = require('./config');
+const { SKILLS_DIR } = require('./runner');
+
+/** Common agent skill directories, offered as install targets. */
+function defaultTargets() {
+  const home = os.homedir();
+  return [
+    { label: 'Claude Code (user)', dir: path.join(home, '.claude', 'skills', 'adgine-geo') },
+    { label: 'Current project (.claude)', dir: path.join(process.cwd(), '.claude', 'skills', 'adgine-geo') },
+  ];
+}
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (path.basename(src) === '__pycache__') return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else if (stat.isFile()) {
+    if (src.endsWith('.pyc')) return;
+    fs.copyFileSync(src, dest);
+  }
+}
+
+/**
+ * Copy the whole skills payload into `targetDir`. Returns the target path.
+ */
+function installTo(targetDir) {
+  const target = path.resolve(targetDir);
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of fs.readdirSync(SKILLS_DIR)) {
+    copyRecursive(path.join(SKILLS_DIR, entry), path.join(target, entry));
+  }
+  writeEnv(target);
+  return target;
+}
+
+/**
+ * Write GEO_API_KEY into <target>/.env if a key is configured. Preserves any
+ * existing lines. No-op (with a note) when no key is available.
+ */
+function writeEnv(target) {
+  const key = config.getKey();
+  const envPath = path.join(target, '.env');
+  if (!key) return { written: false, envPath };
+
+  let lines = [];
+  if (fs.existsSync(envPath)) {
+    lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+  }
+  let found = false;
+  lines = lines.map((l) => {
+    if (l.startsWith('GEO_API_KEY=')) {
+      found = true;
+      return `GEO_API_KEY=${key}`;
+    }
+    return l;
+  });
+  if (!found) {
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    lines.push(`GEO_API_KEY=${key}`);
+  }
+  fs.writeFileSync(envPath, lines.join('\n').replace(/\n*$/, '\n'), { mode: 0o600 });
+  try {
+    fs.chmodSync(envPath, 0o600);
+  } catch {
+    /* best effort */
+  }
+  return { written: true, envPath };
+}
+
+module.exports = { defaultTargets, installTo, writeEnv };

package/src/manifest.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Build the command tree by scanning the bundled skills payload.
+ *
+ * A "skill" is a folder `adgine-geo-<name>`. Its "actions" are the Python
+ * scripts under `scripts/` whose filename does not start with `_` (which are
+ * shared helpers like `_client.py` / `_geo_notice.py`).
+ *
+ * A short description per skill is parsed from the SKILL.md YAML frontmatter.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SKILLS_DIR } = require('./runner');
+
+/** Extract the frontmatter `description:` (inline or `>`/`|` folded block). */
+function parseDescription(skillMdPath) {
+  let text;
+  try {
+    text = fs.readFileSync(skillMdPath, 'utf8');
+  } catch {
+    return '';
+  }
+  const lines = text.split(/\r?\n/);
+  if (lines[0].trim() !== '---') return '';
+  let i = 1;
+  for (; i < lines.length; i++) {
+    if (lines[i].trim() === '---') return '';
+    const m = lines[i].match(/^description:\s*(.*)$/);
+    if (!m) continue;
+    let value = m[1].trim();
+    if (value === '>' || value === '|' || value === '>-' || value === '|-') {
+      // Folded block: collect subsequent indented lines.
+      const parts = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === '---') break;
+        if (/^\S/.test(lines[j])) break; // next top-level key
+        parts.push(lines[j].trim());
+      }
+      value = parts.join(' ').trim();
+    }
+    return firstSentence(value);
+  }
+  return '';
+}
+
+function firstSentence(s) {
+  if (!s) return '';
+  // Cut at first sentence boundary (English period or Chinese 。), else truncate.
+  const m = s.match(/^(.*?[.。])(\s|$)/);
+  let out = m ? m[1] : s;
+  if (out.length > 140) out = out.slice(0, 137) + '…';
+  return out.trim();
+}
+
+function listActions(scriptsDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(scriptsDir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((f) => f.endsWith('.py') && !f.startsWith('_'))
+    .map((f) => f.slice(0, -3))
+    .sort();
+}
+
+/**
+ * Return the full manifest: array of { skill, folder, description, actions }.
+ */
+function buildManifest() {
+  let dirs;
+  try {
+    dirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const d of dirs) {
+    if (!d.isDirectory() || !d.name.startsWith('adgine-geo-')) continue;
+    const folder = d.name;
+    const skill = folder.replace(/^adgine-geo-/, '');
+    const description = parseDescription(path.join(SKILLS_DIR, folder, 'SKILL.md'));
+    const actions = listActions(path.join(SKILLS_DIR, folder, 'scripts'));
+    skills.push({ skill, folder, description, actions });
+  }
+  skills.sort((a, b) => a.skill.localeCompare(b.skill));
+  return skills;
+}
+
+/** Look up one skill by its short name (without the adgine-geo- prefix). */
+function findSkill(name) {
+  const normalized = name.replace(/^adgine-geo-/, '');
+  return buildManifest().find((s) => s.skill === normalized) || null;
+}
+
+module.exports = { buildManifest, findSkill, parseDescription };

package/src/runner.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * Locate a Python interpreter and the bundled skills payload, then spawn a
+ * skill script with the GEO_API_KEY injected into the child environment.
+ *
+ * Key design point: the Python client (_client.py) reads GEO_API_KEY from the
+ * environment first, so we never need to write a .env file — we just pass the
+ * key through in the child's env. We also set GEO_SKIP_VERSION_CHECK so stdout
+ * stays clean and no per-command network round-trip to GitHub happens.
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const config = require('./config');
+
+const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
+
+// Skills whose scripts run without a GEO_API_KEY (site technical audit is fully
+// local; docs just links the manual). Everything else needs a key.
+const KEYLESS_SKILLS = new Set(['site-audit', 'docs']);
+
+const HELP_FLAGS = new Set(['-h', '--help']);
+
+let _cachedPython;
+
+/**
+ * Find a working Python 3 interpreter. Returns the command string or null.
+ */
+function findPython() {
+  if (_cachedPython !== undefined) return _cachedPython;
+  const candidates =
+    process.platform === 'win32'
+      ? ['python', 'python3', 'py']
+      : ['python3', 'python'];
+  for (const cmd of candidates) {
+    try {
+      const res = spawnSync(cmd, ['--version'], { encoding: 'utf8' });
+      if (res.status === 0) {
+        const out = (res.stdout || '') + (res.stderr || '');
+        const m = out.match(/Python (\d+)\.(\d+)/);
+        if (m && Number(m[1]) >= 3) {
+          _cachedPython = cmd;
+          return cmd;
+        }
+      }
+    } catch {
+      /* try next */
+    }
+  }
+  _cachedPython = null;
+  return null;
+}
+
+function skillsDir() {
+  return SKILLS_DIR;
+}
+
+/**
+ * Absolute path to a skill's script, or null if it does not exist.
+ * skill: e.g. "projects" (without the adgine-geo- prefix) or the full folder name.
+ */
+function resolveScript(skill, action) {
+  const folder = skill.startsWith('adgine-geo-') ? skill : `adgine-geo-${skill}`;
+  const scriptPath = path.join(
+    SKILLS_DIR,
+    folder,
+    'scripts',
+    `${action}.py`
+  );
+  return fs.existsSync(scriptPath) ? scriptPath : null;
+}
+
+/**
+ * Build the child environment: pass through the current env, inject the
+ * resolved key + base URL, and suppress the Python version check.
+ */
+function buildEnv(extra = {}) {
+  const env = { ...process.env, GEO_SKIP_VERSION_CHECK: '1', ...extra };
+  const key = config.getKey();
+  if (key) env.GEO_API_KEY = key;
+  const base = config.getBaseUrl();
+  if (base && base !== config.DEFAULT_BASE_URL) {
+    env.GEO_API_BASE_URL = base;
+  }
+  return env;
+}
+
+/**
+ * Run a bundled Python script, inheriting stdio. Returns the exit code.
+ * On missing python, prints guidance and returns 69 (EX_UNAVAILABLE).
+ */
+function runScript(scriptPath, args = [], opts = {}) {
+  const python = findPython();
+  if (!python) {
+    process.stderr.write(
+      'ERROR: Python 3 not found on PATH.\n' +
+        '  adgine-geo wraps Python skills and needs Python 3.9+.\n' +
+        '  Install it from https://www.python.org/downloads/ and re-run.\n' +
+        "  Then verify with: adgine-geo doctor\n"
+    );
+    return 69;
+  }
+  const res = spawnSync(python, [scriptPath, ...args], {
+    stdio: 'inherit',
+    env: buildEnv(opts.env),
+    cwd: opts.cwd,
+  });
+  if (res.error) {
+    process.stderr.write(`ERROR: failed to run python — ${res.error.message}\n`);
+    return 1;
+  }
+  if (res.signal) {
+    // e.g. SIGINT (Ctrl-C)
+    return 130;
+  }
+  return res.status == null ? 1 : res.status;
+}
+
+/**
+ * Run a skill action: adgine-geo <skill> <action> [args].
+ * Returns exit code; 127 if the skill/action pair does not exist.
+ */
+function runSkillAction(skill, action, args = []) {
+  const normalized = skill.replace(/^adgine-geo-/, '');
+  const scriptPath = resolveScript(normalized, action);
+  if (!scriptPath) {
+    process.stderr.write(
+      `ERROR: unknown command '${normalized} ${action}'.\n` +
+        "  Run 'adgine-geo list' to see available skills and actions.\n"
+    );
+    return 127;
+  }
+  // Give npm users the right fix when no key is configured, instead of the
+  // Python client's message that points inside the package dir. Skip for
+  // keyless skills and for --help (argparse handles that before any key check).
+  const isHelp = args.some((a) => HELP_FLAGS.has(a));
+  if (!isHelp && !KEYLESS_SKILLS.has(normalized) && !config.getKey()) {
+    process.stderr.write(
+      'ERROR: GEO_API_KEY is not set.\n' +
+        '  Set it once with:\n' +
+        '    adgine-geo config set-key geo_sk_live_xxx\n' +
+        '  Get your key at https://platform.adgine.ai\n'
+    );
+    return 78; // EX_CONFIG
+  }
+  return runScript(scriptPath, args);
+}
+
+module.exports = {
+  SKILLS_DIR,
+  findPython,
+  skillsDir,
+  resolveScript,
+  buildEnv,
+  runScript,
+  runSkillAction,
+};