antigravity-seo-kit 2.7.4 → 2.9.8

package/README.md

@@ -14,7 +14,7 @@ npx antigravity-seo-kit install-plugin --key=SK-XXXX-XXXX-XXXX
 # OR: npx antigravity-seo-kit install --global --key=SK-XXXX-XXXX-XXXX
 ```
 
-When you start work in a new workspace, run the following command to sync the agent rules and folders locally:
+When you start work in a new workspace, run the following command to sync the `.agents/` structure locally:
 ```bash
 npx antigravity-seo-kit setup-workspace
 ```
@@ -45,12 +45,15 @@ npx antigravity-seo-kit install --key=SK-XXXX-XXXX-XXXX
 # Install globally as a plugin (recommended)
 npx antigravity-seo-kit install-plugin --key=SK-XXXX-XXXX-XXXX
 
-# Replicate .agent config directory from global plugin to local workspace
+# Replicate .agents/ workspace structure from global plugin
 npx antigravity-seo-kit setup-workspace
 
 # Install locally into current workspace
 npx antigravity-seo-kit install --key=SK-XXXX-XXXX-XXXX
 
+# Migrate from v2.x (.agent/) to v3.0 (.agents/)
+npx antigravity-seo-kit migrate
+
 # Update to latest version
 npx antigravity-seo-kit update
 

package/bin/cli.js

@@ -75,6 +75,12 @@ async function main() {
         break;
       }
 
+      case 'migrate': {
+        showBanner();
+        installer.migrate(cwd);
+        break;
+      }
+
       case 'update': {
         showBanner();
         await installer.update(cwd);

package/lib/downloader.js

@@ -149,6 +149,7 @@ function extractTarGz(gzBuffer, targetDir) {
       const isConfigJson = fullName.endsWith('.json') &&
         (fullName.startsWith('config/') ||
          fullName.startsWith('.agent/config/') ||
+         fullName.startsWith('.agents/config/') ||
          fullName.includes('/config/'));
 
       fs.mkdirSync(path.dirname(targetPath), { recursive: true });

package/lib/installer.js

@@ -69,7 +69,46 @@ async function install(licenseKey, cwd) {
     process.exit(1);
   }
 
-  // Step 3: Save license info + manifest
+  // Step 3: Restructure into .agents/ flat format if server sent legacy .agent/
+  const legacyAgentDir = path.join(cwd, '.agent');
+  const newAgentsDir = path.join(cwd, '.agents');
+
+  if (fs.existsSync(legacyAgentDir) && !fs.existsSync(newAgentsDir)) {
+    const spinMigrate = spinner('Restructuring to .agents/ format...').start();
+    try {
+      fs.mkdirSync(newAgentsDir, { recursive: true });
+
+      // ALL dirs go directly into .agents/ (flat workspace structure)
+      const allDirs = ['skills', 'rules', 'agents', 'workflows', 'scripts', 'config', 'dashboard', 'docs', '.shared'];
+      let migrateCount = 0;
+      for (const dir of allDirs) {
+        const src = path.join(legacyAgentDir, dir);
+        const dest = path.join(newAgentsDir, dir);
+        if (fs.existsSync(src)) {
+          migrateCount += copyRecursive(src, dest, { overwrite: true });
+        }
+      }
+
+      // Root-level files (.md, .json) → .agents/
+      for (const f of fs.readdirSync(legacyAgentDir)) {
+        const src = path.join(legacyAgentDir, f);
+        if (fs.statSync(src).isFile()) {
+          fs.copyFileSync(src, path.join(newAgentsDir, f));
+          migrateCount++;
+        }
+      }
+
+      // Remove legacy .agent/
+      removeRecursive(legacyAgentDir);
+
+      spinMigrate.succeed(`Restructured to .agents/ format (${migrateCount} files)`);
+    } catch (err) {
+      spinMigrate.fail('Restructuring failed, keeping .agent/ as-is');
+      warn(`You can manually run: npx antigravity-seo-kit migrate`);
+    }
+  }
+
+  // Step 4: Save license info + manifest
   writeLicenseFile(cwd, {
     key: licenseKey,
     deviceId,
@@ -122,6 +161,10 @@ async function update(cwd) {
     process.exit(1);
   }
 
+  // Detect structure: v3.0 (.agents/) or v2.x (.agent/)
+  const isV3 = fs.existsSync(path.join(cwd, '.agents'));
+  const isV2 = fs.existsSync(path.join(cwd, '.agent'));
+
   // Download latest assets from server
   console.log('');
   const spinDl = spinner('Downloading latest SEO Kit assets...').start();
@@ -136,6 +179,13 @@ async function update(cwd) {
     process.exit(1);
   }
 
+  // If user was on v2 (.agent/) and download brings v3 (.agents/), inform about migrate
+  if (isV2 && !isV3 && fs.existsSync(path.join(cwd, '.agents'))) {
+    console.log('');
+    info('v3.0 structure detected in update. Run migrate to complete:');
+    console.log(`  ${colorize('cyan', 'npx antigravity-seo-kit migrate')}`);
+  }
+
   // Update license file
   config.version = PACKAGE_VERSION;
   config.updatedAt = new Date().toISOString();
@@ -160,7 +210,7 @@ async function uninstall(cwd) {
   let totalRemoved = 0;
 
   if (config.installedFiles && config.installedFiles.length > 0) {
-    // New approach: use manifest from license file
+    // Manifest-based removal
     for (const filePath of config.installedFiles) {
       const target = path.join(cwd, filePath);
       if (fs.existsSync(target)) {
@@ -168,10 +218,11 @@ async function uninstall(cwd) {
         totalRemoved++;
       }
     }
-    // Clean up empty directories
+    // Clean up empty directories for both v2 and v3 structures
     cleanEmptyDirsUp(path.join(cwd, '.agent'));
+    cleanEmptyDirsUp(path.join(cwd, '.agents'));
   } else {
-    // Legacy fallback: use hardcoded arrays
+    // Legacy fallback: use prefix scan
     totalRemoved += legacyUninstall(cwd);
   }
 
@@ -253,24 +304,36 @@ async function status(cwd) {
 
   // Count installed files
   if (config.installedFiles && config.installedFiles.length > 0) {
-    // New: count from manifest
+    // Manifest-based count
     let existingFiles = 0;
     for (const f of config.installedFiles) {
       if (fs.existsSync(path.join(cwd, f))) existingFiles++;
     }
     console.log(`  ${colorize('cyan', 'Files:')}        ${existingFiles}/${config.installedFiles.length} present`);
   } else {
-    // Legacy: scan for seo-* prefixed entries
-    const agentDir = path.join(cwd, '.agent');
+    // Legacy: scan for seo-* prefixed entries in both .agent/ and .agents/
     let totalLegacy = 0;
-    for (const subDir of LEGACY_DIRS) {
-      const dirPath = path.join(agentDir, subDir);
-      if (!fs.existsSync(dirPath)) continue;
-      for (const entry of fs.readdirSync(dirPath)) {
-        if (entry.startsWith(LEGACY_SEO_PREFIX) || entry === 'seo') totalLegacy++;
+    for (const baseDir of ['.agent', '.agents']) {
+      const agentDir = path.join(cwd, baseDir);
+      if (!fs.existsSync(agentDir)) continue;
+      for (const subDir of LEGACY_DIRS) {
+        const dirPath = path.join(agentDir, subDir);
+        if (!fs.existsSync(dirPath)) continue;
+        for (const entry of fs.readdirSync(dirPath)) {
+          if (entry.startsWith(LEGACY_SEO_PREFIX) || entry === 'seo') totalLegacy++;
+        }
       }
     }
-    console.log(`  ${colorize('cyan', 'Components:')}  ${totalLegacy} installed (legacy)`);
+    console.log(`  ${colorize('cyan', 'Components:')}  ${totalLegacy} installed`);
+  }
+
+  // Detect structure version
+  const hasV3 = fs.existsSync(path.join(cwd, '.agents'));
+  const hasV2 = fs.existsSync(path.join(cwd, '.agent'));
+  const structureVersion = hasV3 ? 'v3.0 (.agents/)' : hasV2 ? 'v2.x (.agent/)' : 'unknown';
+  console.log(`  ${colorize('cyan', 'Structure:')}   ${structureVersion}`);
+  if (hasV2 && !hasV3) {
+    warn('Using legacy v2.x structure. Run: npx antigravity-seo-kit migrate');
   }
   console.log('');
 
@@ -436,51 +499,72 @@ async function installPlugin(licenseKey) {
     process.exit(1);
   }
 
-  // Step 3: Move files/folders inside the `.agent/` subdirectory up to the plugin root
-  const agentDir = path.join(globalPluginDir, '.agent');
-  if (fs.existsSync(agentDir)) {
-    const entries = fs.readdirSync(agentDir);
+  // Step 3: Restructure into .agents/ plugin format
+  // v3.0: Downloaded assets arrive in .agents/ structure already
+  // Handle legacy .agent/ if server still serves old format
+  const legacyAgentDir = path.join(globalPluginDir, '.agent');
+  const newAgentsDir = path.join(globalPluginDir, '.agents');
+
+  if (fs.existsSync(legacyAgentDir) && !fs.existsSync(newAgentsDir)) {
+    // Legacy format: flatten .agent/ into plugin root
+    const entries = fs.readdirSync(legacyAgentDir);
     for (const entry of entries) {
-      const srcPath = path.join(agentDir, entry);
+      const srcPath = path.join(legacyAgentDir, entry);
       const destPath = path.join(globalPluginDir, entry);
       if (fs.existsSync(destPath)) {
         removeRecursive(destPath);
       }
       fs.renameSync(srcPath, destPath);
     }
-    removeRecursive(agentDir);
+    removeRecursive(legacyAgentDir);
+  } else if (fs.existsSync(newAgentsDir)) {
+    // v3.0 format: move plugin contents (skills, rules) to plugin root
+    const pluginSrcDir = path.join(newAgentsDir, 'plugins', 'antigravity-seo-kit');
+    if (fs.existsSync(pluginSrcDir)) {
+      for (const entry of fs.readdirSync(pluginSrcDir)) {
+        const srcPath = path.join(pluginSrcDir, entry);
+        const destPath = path.join(globalPluginDir, entry);
+        if (fs.existsSync(destPath)) {
+          removeRecursive(destPath);
+        }
+        fs.renameSync(srcPath, destPath);
+      }
+    }
+    // Keep workspace-level dirs (agents, workflows) for setupWorkspace
+    const workspaceDirs = ['agents', 'workflows', 'scripts', 'config', 'dashboard', 'docs', '.shared'];
+    for (const dir of workspaceDirs) {
+      const srcDir = path.join(newAgentsDir, dir);
+      const destDir = path.join(globalPluginDir, `_workspace_${dir}`);
+      if (fs.existsSync(srcDir)) {
+        if (fs.existsSync(destDir)) removeRecursive(destDir);
+        fs.renameSync(srcDir, destDir);
+      }
+    }
+    // Copy seo-architecture.md
+    const archFile = path.join(newAgentsDir, 'seo-architecture.md');
+    if (fs.existsSync(archFile)) {
+      fs.copyFileSync(archFile, path.join(globalPluginDir, '_workspace_seo-architecture.md'));
+    }
+    removeRecursive(newAgentsDir);
   }
 
-  // Step 4: Generate plugin.json and installed_version.json
-  const pluginJson = {
-    name: "antigravity-seo-kit",
-    version: PACKAGE_VERSION,
-    description: "Professional Agentic SEO Platform for Google Antigravity 2 AI Agent — 44 specialized skills covering technical audit, E-E-A-T, schema, GEO, local SEO & more",
-    author: {
-      name: "Antigravity SEO Kit",
-      email: "admin@solann.io",
-    },
-    repository: "https://solann.io/antigravity-seo-kit",
-    license: "SEE LICENSE IN LICENSE",
-    keywords: [
-      "seo",
-      "agentic-seo",
-      "ai-agent",
-      "antigravity",
-      "seo-geo",
-      "seo-audit",
-      "seo-toolkit",
-      "agent-skills",
-      "seo-analysis",
-      "technical-seo",
-      "eeat"
-    ]
-  };
-  fs.writeFileSync(path.join(globalPluginDir, 'plugin.json'), JSON.stringify(pluginJson, null, 2), 'utf-8');
+  // Step 4: Ensure plugin.json and installed_version.json
+  const pluginJsonPath = path.join(globalPluginDir, 'plugin.json');
+  if (!fs.existsSync(pluginJsonPath)) {
+    const pluginJson = {
+      name: "antigravity-seo-kit",
+      version: PACKAGE_VERSION,
+      description: "Professional Agentic SEO Platform — 44+ specialized skills",
+      author: { name: "Solann", email: "admin@solann.io" },
+      repository: "https://solann.io/antigravity-seo-kit",
+      license: "SEE LICENSE IN LICENSE",
+      keywords: ["seo", "agentic-seo", "ai-agent", "antigravity"]
+    };
+    fs.writeFileSync(pluginJsonPath, JSON.stringify(pluginJson, null, 2), 'utf-8');
+  }
   fs.writeFileSync(path.join(globalPluginDir, 'installed_version.json'), JSON.stringify({ version: PACKAGE_VERSION }), 'utf-8');
 
   // Step 5: Save global license info + manifest
-  const LICENSE_FILE = '.seo-kit-license';
   writeLicenseFile(globalPluginDir, {
     key: licenseKey,
     deviceId,
@@ -488,19 +572,19 @@ async function installPlugin(licenseKey) {
     version: PACKAGE_VERSION,
     installedAt: new Date().toISOString(),
     plan: verifyResult?.license?.planName || verifyResult?.license?.plan || 'unknown',
-    installedFiles: downloadResult.files.map(f => f.replace(/^\.agent\//, '')),
+    installedFiles: downloadResult.files.map(f => f.replace(/^\.agents?\//, '')),
   });
 
   // Done!
   console.log('');
   console.log(colorize('green', '═══════════════════════════════════════════════════════'));
-  success(`SEO Kit v${PACKAGE_VERSION} installed successfully as a global Antigravity plugin!`);
+  success(`SEO Kit v${PACKAGE_VERSION} installed as global Antigravity plugin!`);
   console.log(colorize('green', '═══════════════════════════════════════════════════════'));
   console.log('');
 
   info('Next steps:');
   console.log(`  ${colorize('yellow', '1.')} Restart or open any workspace in ${colorize('bold', 'Google Antigravity')}`);
-  console.log(`  ${colorize('yellow', '2.')} The SEO Kit plugin will automatically load globally.`);
+  console.log(`  ${colorize('yellow', '2.')} Plugin loads globally. Run ${colorize('cyan', 'npx antigravity-seo-kit setup-workspace')} in a project.`);
   console.log('');
 
   if (verifyResult?.devicesUsed != null) {
@@ -511,10 +595,10 @@ async function installPlugin(licenseKey) {
 
 function setupWorkspace(cwd) {
   const globalDir = getGlobalPluginDir();
-  const localAgentDir = path.join(cwd, '.agent');
+  const localAgentsDir = path.join(cwd, '.agents');
 
-  if (fs.existsSync(localAgentDir)) {
-    info('Existing .agent directory found. Re-synchronizing and updating files...');
+  if (fs.existsSync(localAgentsDir)) {
+    info('Existing .agents directory found. Re-synchronizing...');
   }
 
   if (!fs.existsSync(globalDir)) {
@@ -523,40 +607,82 @@ function setupWorkspace(cwd) {
     process.exit(1);
   }
 
-  const spin = spinner('Replicating .agent directory to local workspace...').start();
+  const spin = spinner('Setting up .agents/ workspace structure...').start();
   try {
-    fs.mkdirSync(localAgentDir, { recursive: true });
+    fs.mkdirSync(localAgentsDir, { recursive: true });
 
-    // Only copy necessary directories. agents and rules are loaded globally via the plugin.
-    // skills are copied but filtered to exclude .md files to save space and avoid duplicate prompts/instructions.
-    const directoriesToCopy = ['.shared', 'config', 'dashboard', 'docs', 'scripts', 'workflows'];
-    const filesToCopy = ['seo-architecture.md'];
+    // Copy workspace-level dirs from global plugin to local .agents/
+    // Skills & rules are NOT copied — Antigravity loads them from global plugin
+    const workspaceDirs = ['agents', 'workflows', 'scripts', 'config', 'dashboard', 'docs', '.shared'];
+    const rootFiles = ['seo-architecture.md'];
 
     let count = 0;
-    for (const dir of directoriesToCopy) {
-      const src = path.join(globalDir, dir);
-      const dest = path.join(localAgentDir, dir);
+    for (const dir of workspaceDirs) {
+      // Try _workspace_ prefixed dirs first (v3.0 install format)
+      let src = path.join(globalDir, `_workspace_${dir}`);
+      if (!fs.existsSync(src)) {
+        src = path.join(globalDir, dir);
+      }
+      const dest = path.join(localAgentsDir, dir);
       if (fs.existsSync(src)) {
         count += copyRecursive(src, dest, { overwrite: true });
       }
     }
-    for (const file of filesToCopy) {
-      const src = path.join(globalDir, file);
-      const dest = path.join(localAgentDir, file);
+
+    // Copy root-level files
+    for (const f of rootFiles) {
+      let src = path.join(globalDir, `_workspace_${f}`);
+      if (!fs.existsSync(src)) {
+        src = path.join(globalDir, f);
+      }
+      const dest = path.join(localAgentsDir, f);
       if (fs.existsSync(src)) {
         fs.copyFileSync(src, dest);
         count++;
       }
     }
 
-    const LICENSE_FILE = '.seo-kit-license';
-    const globalLicense = path.join(globalDir, LICENSE_FILE);
-    const localLicense = path.join(cwd, LICENSE_FILE);
+    // Copy hooks.json to .agents/ root if exists in global plugin
+    const hooksFiles = ['hooks.json', '_workspace_hooks.json'];
+    for (const hf of hooksFiles) {
+      const hooksSrc = path.join(globalDir, hf);
+      if (fs.existsSync(hooksSrc)) {
+        const hooksDest = path.join(localAgentsDir, 'hooks.json');
+        if (!fs.existsSync(hooksDest)) {
+          fs.copyFileSync(hooksSrc, hooksDest);
+          count++;
+        }
+        break;
+      }
+    }
+
+    // Copy mcp_config.json to .agents/ root if exists in global plugin
+    const mcpFiles = ['mcp_config.json', '_workspace_mcp_config.json'];
+    for (const mf of mcpFiles) {
+      const mcpSrc = path.join(globalDir, mf);
+      if (fs.existsSync(mcpSrc)) {
+        const mcpDest = path.join(localAgentsDir, 'mcp_config.json');
+        if (!fs.existsSync(mcpDest)) {
+          fs.copyFileSync(mcpSrc, mcpDest);
+          count++;
+        }
+        break;
+      }
+    }
+
+    // Copy license file to workspace
+    const LICENSE_FILE_NAME = '.seo-kit-license';
+    const globalLicense = path.join(globalDir, LICENSE_FILE_NAME);
+    const localLicense = path.join(cwd, LICENSE_FILE_NAME);
     if (fs.existsSync(globalLicense) && !fs.existsSync(localLicense)) {
       fs.copyFileSync(globalLicense, localLicense);
     }
 
-    spin.succeed(`Workspace setup complete! Copied ${count} files to .agent/`);
+    spin.succeed(`Workspace setup complete! Copied ${count} files to .agents/`);
+    console.log('');
+    info('Skills and rules are loaded from global plugin automatically.');
+    info('Workspace-level files (workflows, agents, scripts) are now local.');
+    console.log('');
   } catch (err) {
     spin.fail('Workspace setup failed');
     error(err.message);
@@ -564,6 +690,62 @@ function setupWorkspace(cwd) {
   }
 }
 
+// ─── Migrate Command (v2.x → v3.0) ─────────────────────────────────────────
+
+function migrate(cwd) {
+  const oldAgentDir = path.join(cwd, '.agent');
+  const newAgentsDir = path.join(cwd, '.agents');
+
+  if (!fs.existsSync(oldAgentDir)) {
+    if (fs.existsSync(newAgentsDir)) {
+      info('Already using v3.0 .agents/ structure. No migration needed.');
+      return;
+    }
+    error('No .agent/ directory found. Nothing to migrate.');
+    process.exit(1);
+  }
+
+  if (fs.existsSync(newAgentsDir)) {
+    warn('.agents/ already exists. Migration will merge/overwrite.');
+  }
+
+  const spin = spinner('Migrating .agent/ → .agents/ (v2.x → v3.0)...').start();
+  try {
+    fs.mkdirSync(newAgentsDir, { recursive: true });
+    let count = 0;
+
+    // Copy ALL directories directly into .agents/ (flat workspace structure)
+    const allDirs = ['skills', 'rules', 'agents', 'workflows', 'scripts', 'config', 'dashboard', 'docs', '.shared'];
+    for (const dir of allDirs) {
+      const src = path.join(oldAgentDir, dir);
+      const dest = path.join(newAgentsDir, dir);
+      if (fs.existsSync(src)) {
+        count += copyRecursive(src, dest, { overwrite: true, mergeJson: true });
+      }
+    }
+
+    // Copy root-level files (.md, .json, etc.)
+    for (const f of fs.readdirSync(oldAgentDir)) {
+      const src = path.join(oldAgentDir, f);
+      if (fs.statSync(src).isFile()) {
+        fs.copyFileSync(src, path.join(newAgentsDir, f));
+        count++;
+      }
+    }
+
+    spin.succeed(`Migration complete! ${count} files moved to .agents/`);
+    console.log('');
+    info('The old .agent/ directory has been preserved as backup.');
+    info('After verifying everything works, you can remove it:');
+    console.log(`  ${colorize('gray', 'rm -rf .agent/')}`);
+    console.log('');
+  } catch (err) {
+    spin.fail('Migration failed');
+    error(err.message);
+    process.exit(1);
+  }
+}
+
 // ─── Exports ────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -575,4 +757,5 @@ module.exports = {
   deviceRemove,
   installPlugin,
   setupWorkspace,
+  migrate,
 };

package/lib/utils.js

@@ -307,7 +307,8 @@ function showHelp() {
   console.log(`${colorize('bold', 'Commands:')}`);
   console.log(`  ${colorize('green', 'install')}         --key=SK-XXXX-XXXX-XXXX   Install SEO Kit into current workspace`);
   console.log(`  ${colorize('green', 'install-plugin')}  --key=SK-XXXX-XXXX-XXXX   Install SEO Kit globally as an Antigravity plugin`);
-  console.log(`  ${colorize('green', 'setup-workspace')}                            Replicate .agent config directory to current workspace`);
+  console.log(`  ${colorize('green', 'setup-workspace')}                            Replicate .agents config directory to current workspace`);
+  console.log(`  ${colorize('green', 'migrate')}                                   Migrate .agent/ to .agents/ (v2.x → v3.0)`);
   console.log(`  ${colorize('green', 'update')}                                    Update to latest version`);
   console.log(`  ${colorize('green', 'uninstall')}                                 Remove SEO Kit from workspace`);
   console.log(`  ${colorize('green', 'status')}                                    Show license & installation info`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antigravity-seo-kit",
-  "version": "2.7.4",
+  "version": "2.9.8",
   "description": "Professional Agentic SEO Platform for Google Antigravity 2 AI Agent — 44 specialized skills covering technical audit, E-E-A-T, schema, GEO, local SEO & more",
   "main": "lib/installer.js",
   "bin": {