gkt-node 3.3.0

package/lib/commands.js

@@ -0,0 +1,133 @@
+/**
+ * Supplementary commands: version, doctor, list, groups.
+ */
+
+const { execSync } = require('child_process');
+const { VERSION } = require('./constants');
+
+/**
+ * Show current version.
+ */
+function versionCommand() {
+  console.log(`v${VERSION}`);
+}
+
+/**
+ * Check environment health.
+ */
+function doctorCommand() {
+  console.log('\n🩺 GravityKit Doctor - Checking Environment...\n');
+
+  const checks = [
+    { cmd: 'python --version', name: 'Python' },
+    { cmd: 'node --version', name: 'Node.js' },
+    { cmd: 'git --version', name: 'Git' },
+    { cmd: 'npm --version', name: 'npm' },
+  ];
+
+  let allGood = true;
+
+  for (const { cmd, name } of checks) {
+    try {
+      const output = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      const version = output.split('\n')[0];
+      console.log(`✅ ${name.padEnd(10)}: Found (${version})`);
+    } catch {
+      console.log(`❌ ${name.padEnd(10)}: NOT FOUND`);
+      allGood = false;
+    }
+  }
+
+  // Check .agent folder
+  const fs = require('fs');
+  const path = require('path');
+  if (fs.existsSync(path.join(process.cwd(), '.agent'))) {
+    console.log(`✅ .agent    : Found in current directory`);
+  } else {
+    console.log(`⚠️  .agent    : Not found (Run 'gkt init' to install)`);
+  }
+
+  console.log('');
+  if (allGood) {
+    console.log('🎉 Your environment is healthy and ready to go!');
+  } else {
+    console.log('🩹 Some tools are missing. Please install them to use full capabilities.');
+  }
+}
+
+/**
+ * List available agents from installed .agent/workflows/.
+ */
+function listCommand() {
+  const fs = require('fs');
+  const path = require('path');
+  const workflowsDir = path.join(process.cwd(), '.agent', 'workflows');
+
+  if (!fs.existsSync(workflowsDir)) {
+    console.log('❌ .agent/workflows directory not found. Run \'gkt init\' first.');
+    return;
+  }
+
+  console.log('\n🤖 Available GravityKit Agents:\n');
+  console.log(`${'Agent'.padEnd(25)} ${'Role Description'.padEnd(50)}`);
+  console.log('-'.repeat(75));
+
+  const files = fs.readdirSync(workflowsDir).filter((f) => f.endsWith('.md')).sort();
+  for (const file of files) {
+    const name = file.replace('.md', '');
+    let description = 'No description available.';
+    try {
+      const content = fs.readFileSync(path.join(workflowsDir, file), 'utf8');
+      const match = content.match(/description:\s*(.+)/);
+      if (match) description = match[1].trim();
+    } catch { /* ignore */ }
+    console.log(`@[/${name.padEnd(22)}] ${description}`);
+  }
+  console.log('');
+}
+
+/**
+ * List available skill groups.
+ * Since groups are in the source repo, we download the groups file.
+ */
+async function groupsCommand() {
+  const https = require('https');
+  const { GITHUB_RAW, VERSION } = require('./constants');
+
+  const url = `${GITHUB_RAW}/v${VERSION}/GravityKit/data/skill_groups.json`;
+
+  try {
+    const data = await new Promise((resolve, reject) => {
+      https.get(url, { headers: { 'User-Agent': 'gkt-npx' } }, (res) => {
+        if (res.statusCode !== 200) {
+          return reject(new Error(`HTTP ${res.statusCode}`));
+        }
+        let body = '';
+        res.on('data', (chunk) => (body += chunk));
+        res.on('end', () => resolve(body));
+      }).on('error', reject);
+    });
+
+    const skillGroups = JSON.parse(data);
+
+    console.log('\n📦 Available Skill Groups:\n');
+    console.log(`${'Group'.padEnd(18)} ${'Skills'.padStart(6)} ${'Workflows'.padStart(9)}   ${'Description'.padEnd(50)}`);
+    console.log('-'.repeat(90));
+
+    for (const [name, config] of Object.entries(skillGroups)) {
+      const skillsCount = (config.skills || []).length;
+      const wfCount = (config.workflows || []).length;
+      const desc = config.description || 'No description';
+      console.log(
+        `${name.padEnd(18)} ${String(skillsCount).padStart(6)} ${String(wfCount).padStart(9)}   ${desc}`
+      );
+    }
+    console.log(`\n💡 Usage: gkt init <group-name>  (e.g. gkt init general-dev)`);
+    console.log('');
+  } catch (err) {
+    console.log(`❌ Failed to fetch skill groups: ${err.message}`);
+    console.log('   Make sure you have internet access.');
+  }
+}
+
+module.exports = { versionCommand, doctorCommand, listCommand, groupsCommand };

package/lib/constants.js

@@ -0,0 +1,76 @@
+/**
+ * Shared constants for the GravityKit npx CLI.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Read version from package.json
+const PKG = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+
+const VERSION = PKG.version;
+const REPO_OWNER = 'OrgGem';
+const REPO_NAME = 'VibeGravityKit';
+const GITHUB_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}`;
+const GITHUB_RAW = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}`;
+const TARBALL_URL = `https://github.com/${REPO_OWNER}/${REPO_NAME}/archive/refs/tags`;
+
+const IDE_NAMES = new Set([
+  'antigravity', 'cursor', 'windsurf', 'cline',
+  'kilocode', 'copilot', 'kiro', 'all'
+]);
+
+/**
+ * IDE target → directory mapping.
+ * source / target paths are relative to repo root / cwd respectively.
+ */
+const IDE_CONFIG = {
+  antigravity: {
+    sourceRel: 'GravityKit/.agent',
+    targetRel: '.agent',
+    label: '.agent/ (workflows + skills)',
+  },
+  cursor: {
+    sourceRel: 'GravityKit/ide-adapters/cursor',
+    targetRel: '.cursor/rules',
+    label: '.cursor/rules/ (Cursor IDE)',
+  },
+  windsurf: {
+    sourceRel: 'GravityKit/ide-adapters/windsurf',
+    targetRel: '.windsurf/rules',
+    label: '.windsurf/rules/ (Windsurf IDE)',
+  },
+  cline: {
+    sourceRel: 'GravityKit/ide-adapters/cline',
+    targetRel: '.clinerules',
+    label: '.clinerules/ (Cline IDE)',
+  },
+  kilocode: {
+    sourceRel: 'GravityKit/ide-adapters/kilocode',
+    targetRel: '.kilocode/rules',
+    label: '.kilocode/rules/ (Kilo Code)',
+  },
+  copilot: {
+    sourceRel: 'GravityKit/ide-adapters/copilot',
+    targetRel: '.github/instructions',
+    label: '.github/instructions/ (GitHub Copilot)',
+  },
+  kiro: {
+    sourceRel: 'GravityKit/.agent',
+    targetRel: '.kiro',
+    label: '.kiro/ (Kiro IDE - skills, hooks, steering, specs)',
+  },
+};
+
+module.exports = {
+  VERSION,
+  REPO_OWNER,
+  REPO_NAME,
+  GITHUB_API,
+  GITHUB_RAW,
+  TARBALL_URL,
+  IDE_NAMES,
+  IDE_CONFIG,
+};

package/lib/download.js

@@ -0,0 +1,165 @@
+/**
+ * Download and extract GravityKit assets from GitHub.
+ */
+
+const https = require('https');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { createGunzip } = require('zlib');
+const { REPO_OWNER, REPO_NAME, VERSION } = require('./constants');
+
+/**
+ * Follow redirects and download a URL to a file.
+ * @param {string} url
+ * @param {string} dest
+ * @param {number} maxRedirects
+ * @returns {Promise<void>}
+ */
+function downloadFile(url, dest, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) return reject(new Error('Too many redirects'));
+
+    const client = url.startsWith('https') ? https : http;
+    client.get(url, { headers: { 'User-Agent': 'gkt-npx' } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow redirect
+        return downloadFile(res.headers.location, dest, maxRedirects - 1)
+          .then(resolve)
+          .catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        return reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+      }
+
+      const stream = fs.createWriteStream(dest);
+      res.pipe(stream);
+      stream.on('finish', () => {
+        stream.close();
+        resolve();
+      });
+      stream.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Extract a .tar.gz file using Node.js built-in zlib + tar parsing.
+ * We use a minimal tar extraction to avoid external dependencies.
+ *
+ * @param {string} tarGzPath Path to .tar.gz file
+ * @param {string} destDir   Destination directory
+ * @param {string} stripPrefix  Strip this prefix from paths in the tarball
+ * @returns {Promise<void>}
+ */
+function extractTarGz(tarGzPath, destDir, stripPrefix = '') {
+  return new Promise((resolve, reject) => {
+    const input = fs.createReadStream(tarGzPath);
+    const gunzip = createGunzip();
+    const chunks = [];
+
+    input.pipe(gunzip);
+
+    gunzip.on('data', (chunk) => chunks.push(chunk));
+    gunzip.on('end', () => {
+      try {
+        const buffer = Buffer.concat(chunks);
+        extractTar(buffer, destDir, stripPrefix);
+        resolve();
+      } catch (err) {
+        reject(err);
+      }
+    });
+    gunzip.on('error', reject);
+    input.on('error', reject);
+  });
+}
+
+/**
+ * Minimal tar extractor — handles standard USTAR format.
+ */
+function extractTar(buffer, destDir, stripPrefix) {
+  let offset = 0;
+
+  while (offset < buffer.length - 512) {
+    // Read header (512 bytes)
+    const header = buffer.slice(offset, offset + 512);
+
+    // Check for zero block (end of archive)
+    if (header.every((b) => b === 0)) break;
+
+    // Parse file name
+    let name = header.slice(0, 100).toString('utf8').replace(/\0/g, '');
+
+    // USTAR prefix field
+    const prefix = header.slice(345, 500).toString('utf8').replace(/\0/g, '');
+    if (prefix) name = prefix + '/' + name;
+
+    // Parse size (octal)
+    const sizeStr = header.slice(124, 136).toString('utf8').replace(/\0/g, '').trim();
+    const size = parseInt(sizeStr, 8) || 0;
+
+    // Parse type ('0' or '' = file, '5' = directory)
+    const type = String.fromCharCode(header[156]);
+
+    offset += 512; // Move past header
+
+    // Strip prefix from tar path (e.g. "VibeGravityKit-3.3.0/")
+    let relPath = name;
+    if (stripPrefix && relPath.startsWith(stripPrefix)) {
+      relPath = relPath.slice(stripPrefix.length);
+    }
+
+    // Skip empty paths
+    if (!relPath || relPath === '/') {
+      offset += Math.ceil(size / 512) * 512;
+      continue;
+    }
+
+    const fullPath = path.join(destDir, relPath);
+
+    if (type === '5' || name.endsWith('/')) {
+      // Directory
+      fs.mkdirSync(fullPath, { recursive: true });
+    } else if (type === '0' || type === '' || type === '\0') {
+      // Regular file
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      const fileData = buffer.slice(offset, offset + size);
+      fs.writeFileSync(fullPath, fileData);
+    }
+
+    // Advance past file data (padded to 512-byte blocks)
+    offset += Math.ceil(size / 512) * 512;
+  }
+}
+
+/**
+ * Download and extract the GravityKit source from a specific version tag.
+ *
+ * @param {string} version  Tag version (e.g. "3.3.0")
+ * @param {string} tmpDir   Temp directory for download
+ * @returns {Promise<string>} Path to the extracted source root
+ */
+async function downloadRelease(version, tmpDir) {
+  const tag = `v${version}`;
+  const url = `https://github.com/${REPO_OWNER}/${REPO_NAME}/archive/refs/tags/${tag}.tar.gz`;
+  const tarPath = path.join(tmpDir, `${REPO_NAME}-${tag}.tar.gz`);
+  const extractDir = path.join(tmpDir, 'extracted');
+
+  fs.mkdirSync(extractDir, { recursive: true });
+
+  console.log(`⬇️  Downloading GravityKit ${tag} from GitHub...`);
+  await downloadFile(url, tarPath);
+
+  console.log(`📦 Extracting...`);
+  const stripPrefix = `${REPO_NAME}-${version}/`;
+  await extractTarGz(tarPath, extractDir, stripPrefix);
+
+  // Clean up tarball
+  fs.unlinkSync(tarPath);
+
+  return extractDir;
+}
+
+module.exports = { downloadFile, extractTarGz, downloadRelease };

package/lib/init.js

@@ -0,0 +1,294 @@
+/**
+ * GravityKit init command — download and install skills/workflows.
+ *
+ * Strategy:
+ *  1. Try bundled assets (packages/npx/assets/) — offline-capable
+ *  2. Fall back to remote download from GitHub if bundled assets are missing
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { IDE_NAMES, IDE_CONFIG, VERSION } = require('./constants');
+const { downloadRelease } = require('./download');
+
+// Path to bundled assets (relative to this file)
+const BUNDLED_ASSETS = path.join(__dirname, '..', 'assets');
+
+/**
+ * Recursively copy a directory.
+ */
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Remove a directory recursively.
+ */
+function rmDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * Load skill groups — from bundled assets or extracted source.
+ */
+function loadSkillGroups(sourceRoot) {
+  // Try bundled first
+  const bundledGroups = path.join(BUNDLED_ASSETS, 'skill_groups.json');
+  if (fs.existsSync(bundledGroups)) {
+    return JSON.parse(fs.readFileSync(bundledGroups, 'utf8'));
+  }
+  // Fall back to extracted source
+  const groupsFile = path.join(sourceRoot, 'GravityKit', 'data', 'skill_groups.json');
+  if (!fs.existsSync(groupsFile)) return {};
+  return JSON.parse(fs.readFileSync(groupsFile, 'utf8'));
+}
+
+/**
+ * Check if bundled assets exist and contain the needed source dirs.
+ */
+function hasBundledAssets() {
+  return fs.existsSync(path.join(BUNDLED_ASSETS, '.agent', 'skills'))
+    && fs.existsSync(path.join(BUNDLED_ASSETS, '.agent', 'workflows'));
+}
+
+/**
+ * Build a "sourceRoot" object from bundled assets that looks like
+ * the extracted GitHub tarball structure.
+ */
+function getBundledSourceRoot() {
+  // Return a virtual path object — we'll remap IDE_CONFIG paths to bundled assets
+  return BUNDLED_ASSETS;
+}
+
+/**
+ * Copy only skills and workflows defined in a group config.
+ */
+function copyGroupSelective(sourceAgentDir, targetAgentDir, groupConfig) {
+  rmDir(targetAgentDir);
+  fs.mkdirSync(targetAgentDir, { recursive: true });
+
+  // Always copy brain/
+  const brainSrc = path.join(sourceAgentDir, 'brain');
+  if (fs.existsSync(brainSrc)) {
+    copyDir(brainSrc, path.join(targetAgentDir, 'brain'));
+  }
+
+  // Copy selected skills
+  const skillsTarget = path.join(targetAgentDir, 'skills');
+  fs.mkdirSync(skillsTarget, { recursive: true });
+  const skillsSrc = path.join(sourceAgentDir, 'skills');
+  let copiedSkills = 0;
+  for (const skillName of (groupConfig.skills || [])) {
+    const src = path.join(skillsSrc, skillName);
+    if (fs.existsSync(src)) {
+      copyDir(src, path.join(skillsTarget, skillName));
+      copiedSkills++;
+    }
+  }
+
+  // Copy selected workflows
+  const wfTarget = path.join(targetAgentDir, 'workflows');
+  fs.mkdirSync(wfTarget, { recursive: true });
+  for (const wfName of (groupConfig.workflows || [])) {
+    const src = path.join(sourceAgentDir, 'workflows', `${wfName}.md`);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(wfTarget, `${wfName}.md`));
+    }
+  }
+
+  return copiedSkills;
+}
+
+/**
+ * Install for Kiro IDE — maps .agent/ → .kiro/ structure.
+ */
+function installKiro(sourceRoot, cwd, groupConfig, useBundled) {
+  const kiroDir = path.join(cwd, '.kiro');
+  const agentDir = useBundled
+    ? path.join(sourceRoot, '.agent')
+    : path.join(sourceRoot, 'GravityKit', '.agent');
+  const templatesDir = useBundled
+    ? path.join(sourceRoot, 'ide-adapters', 'kiro')
+    : path.join(sourceRoot, 'GravityKit', 'ide-adapters', 'kiro');
+
+  rmDir(kiroDir);
+  fs.mkdirSync(kiroDir, { recursive: true });
+
+  // 1. Copy skills
+  const skillsSrc = path.join(agentDir, 'skills');
+  const skillsTarget = path.join(kiroDir, 'skills');
+  fs.mkdirSync(skillsTarget, { recursive: true });
+  let copiedSkills = 0;
+
+  if (fs.existsSync(skillsSrc)) {
+    if (groupConfig) {
+      for (const skillName of (groupConfig.skills || [])) {
+        const src = path.join(skillsSrc, skillName);
+        if (fs.existsSync(src)) {
+          copyDir(src, path.join(skillsTarget, skillName));
+          copiedSkills++;
+        }
+      }
+    } else {
+      for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+        if (entry.isDirectory() && fs.existsSync(path.join(skillsSrc, entry.name, 'SKILL.md'))) {
+          copyDir(path.join(skillsSrc, entry.name), path.join(skillsTarget, entry.name));
+          copiedSkills++;
+        }
+      }
+    }
+  }
+
+  // 2. Copy steering
+  const steeringSrc = path.join(templatesDir, 'steering');
+  if (fs.existsSync(steeringSrc)) {
+    copyDir(steeringSrc, path.join(kiroDir, 'steering'));
+  }
+
+  // 3. Copy hooks
+  const hooksSrc = path.join(templatesDir, 'hooks');
+  if (fs.existsSync(hooksSrc)) {
+    copyDir(hooksSrc, path.join(kiroDir, 'hooks'));
+  }
+
+  // 4. Create specs/
+  fs.mkdirSync(path.join(kiroDir, 'specs'), { recursive: true });
+
+  return copiedSkills;
+}
+
+/**
+ * Resolve IDE source/target paths for bundled vs remote mode.
+ */
+function resolveSourceDir(sourceRoot, ide, useBundled) {
+  const config = IDE_CONFIG[ide];
+  if (!config) return null;
+
+  if (useBundled) {
+    // Bundled paths: assets/.agent or assets/ide-adapters/xxx
+    if (ide === 'antigravity') {
+      return path.join(sourceRoot, '.agent');
+    }
+    return path.join(sourceRoot, 'ide-adapters', ide);
+  }
+  // Remote paths use the original sourceRel (relative to extracted tarball)
+  return path.join(sourceRoot, config.sourceRel);
+}
+
+/**
+ * Main init command handler.
+ *
+ * @param {string} target  IDE name or group name
+ * @param {string|null} group  Optional group filter
+ */
+async function initCommand(target = 'all', group = null) {
+  const cwd = process.cwd();
+  const useBundled = hasBundledAssets();
+  let sourceRoot;
+  let tmpDir = null;
+
+  if (useBundled) {
+    console.log(`📦 Using bundled assets (v${VERSION})...`);
+    sourceRoot = BUNDLED_ASSETS;
+  } else {
+    console.log(`🌐 No bundled assets — downloading from GitHub...`);
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gkt-'));
+    sourceRoot = await downloadRelease(VERSION, tmpDir);
+  }
+
+  try {
+    const skillGroups = loadSkillGroups(sourceRoot);
+
+    // Auto-detect: IDE name or group name?
+    let ideTarget, groupName;
+    if (IDE_NAMES.has(target)) {
+      ideTarget = target;
+      groupName = group;
+    } else if (skillGroups[target]) {
+      ideTarget = 'antigravity';
+      groupName = target;
+    } else {
+      console.log(`❌ Unknown target: '${target}'`);
+      console.log(`   IDE names: all, antigravity, cursor, windsurf, cline, kilocode, copilot, kiro`);
+      console.log(`   Group names: ${Object.keys(skillGroups).join(', ')}`);
+      return;
+    }
+
+    // Validate group
+    if (groupName && !skillGroups[groupName]) {
+      console.log(`❌ Unknown skill group: '${groupName}'`);
+      console.log(`   Available groups: ${Object.keys(skillGroups).join(', ')}`);
+      return;
+    }
+
+    // Determine which IDEs to install
+    const targets = ideTarget === 'all'
+      ? Object.keys(IDE_CONFIG)
+      : [ideTarget];
+
+    if (groupName) {
+      const grp = skillGroups[groupName];
+      console.log(`🚀 Installing group '${groupName}' (${grp.description})...`);
+      console.log(`   Skills: ${(grp.skills || []).length} | Workflows: ${(grp.workflows || []).length}`);
+    } else {
+      console.log(`🚀 Installing GravityKit (all skills)...`);
+    }
+
+    let installed = 0;
+    for (const ide of targets) {
+      const config = IDE_CONFIG[ide];
+      if (!config) continue;
+
+      const sourceDir = resolveSourceDir(sourceRoot, ide, useBundled);
+      const targetDir = path.join(cwd, config.targetRel);
+
+      if (!sourceDir || !fs.existsSync(sourceDir)) {
+        console.log(`  ⚠️  Skipped ${ide}: source not found`);
+        continue;
+      }
+
+      try {
+        if (ide === 'kiro') {
+          const grp = groupName ? skillGroups[groupName] : null;
+          const copied = installKiro(sourceRoot, cwd, grp, useBundled);
+          console.log(`  ✅ ${config.label} (${copied} skills)`);
+        } else if (groupName && ide === 'antigravity') {
+          const copied = copyGroupSelective(sourceDir, targetDir, skillGroups[groupName]);
+          console.log(`  ✅ ${config.label} (${copied} skills)`);
+        } else {
+          rmDir(targetDir);
+          fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+          copyDir(sourceDir, targetDir);
+          console.log(`  ✅ ${config.label}`);
+        }
+        installed++;
+      } catch (err) {
+        console.log(`  ❌ ${ide}: ${err.message}`);
+      }
+    }
+
+    console.log(`\n✨ Done! Installed for ${installed} IDE(s).`);
+    if (groupName) {
+      console.log(`👉 Group '${groupName}' is ready. Use the workflows in .agent/workflows/.`);
+    } else {
+      console.log('👉 Use @[/planner], @[/architect], etc. in your AI chat.');
+    }
+  } finally {
+    // Clean up temp directory if we downloaded
+    if (tmpDir) rmDir(tmpDir);
+  }
+}
+
+module.exports = { initCommand };
+