@aiguru/google-web-operations 0.6.5 → 0.6.7

package/.env.example

@@ -31,8 +31,8 @@ GWO_DOCX_TEMPLATE=
 
 # --- Delivery (worker --deliver) -------------------------------------------
 RESEND_API_KEY=
-GWO_REPORT_FROM=ops@aiguru.co.il
-GWO_REPORT_TO=ai@aiguru.co.il
+GWO_REPORT_FROM=            # e.g. ops@your-domain.co.il (a domain verified in Resend)
+GWO_REPORT_TO=              # e.g. you@your-domain.co.il
 
 # --- GitHub (pull requests for repository-backed sites) --------------------
 # Fine-grained token: Contents write + Pull requests write on the site repos.

package/bin/gwo.js

@@ -27,6 +27,12 @@ if (major < 22 || (major === 22 && minor < 18)) {
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const cmd = process.argv[2];
+
+// Installed inside a project rather than globally? Say so once per run (stderr, never on the MCP channel).
+// Global installs live under <prefix>/lib/node_modules or <prefix>/npm/node_modules; a checkout has no node_modules above it.
+if (/[\\/]node_modules[\\/]/.test(root) && !/[\\/](lib|npm)[\\/]node_modules[\\/]/i.test(root) && cmd !== 'mcp') {
+  console.error('note: gwo is installed locally in a project. For a stable setup: npm i -g @aiguru/google-web-operations\n');
+}
 // A checkout runs the TypeScript sources; the packaged build ships JavaScript.
 const ext = existsSync(path.join(root, 'apps', 'cli', 'src', 'index.js')) ? 'index.js' : 'index.ts';
 // Dynamic imports need file URLs on Windows; a bare drive path is read as a URL scheme.

package/docs/GETTING-STARTED.he.md

@@ -6,7 +6,7 @@
 
 דרישות: Node 22.18 ומעלה.
 
-1. בטרמינל:
+1. בטרמינל, מכל תיקייה, עם `-g` (בלעדיו npm מתקין לתיקייה הנוכחית ו‑`gwo` לא יהיה זמין):
    ```
    npm i -g @aiguru/google-web-operations
    gwo install

package/docs/INSTALL.he.md

@@ -7,15 +7,29 @@
 
 ## 1. התקנה
 
+מכל תיקייה שהיא (לא צריך תיקיית פרויקט), עם `-g`:
+
 ```
 npm i -g @aiguru/google-web-operations
 gwo install
 ```
 
+ה‑`-g` חשוב: בלעדיו npm יוצר `package.json`, `package-lock.json` ו‑`node_modules` בתיקייה הנוכחית, ו‑`gwo` לא נכנס ל‑PATH. הכלי מזהה את זה: `gwo install` מסרב לרשום נתיב מתוך `node_modules` של פרויקט ואומר מה לעשות. אם זה קרה: למחוק את שלושת אלה ולהריץ שוב עם `-g`.
+
 `gwo install` רושם את שרת ה‑MCP, את הסקילים ואת הפקודות בקלוד ובקודקס, ויוצר את `~/.gwo`. רק להוסט אחד: `gwo install claude` או `gwo install codex`. לראות בלי לשנות: `gwo install --print`.
 
 חלופה בלי npm: להוריד את ה‑tgz מעמוד ה‑Releases בריפו ולהריץ `npm i -g ./aiguru-google-web-operations-<version>.tgz` (ה‑`./` חובה).
 
+**איפה להריץ.** בטרמינל של המחשב שבו רצים Claude Code וקודקס (ב‑Windows: PowerShell או CMD). לא מתוך סוכן שרץ בסביבה מבודדת (Cowork, קונטיינר, VM): שם ההתקנה עובדת אבל נמחקת בסוף הסשן ולא נראית להוסטים שלך.
+
+**Linux/macOS, שגיאת EACCES** על `/usr/lib/node_modules`: להתקין ל‑prefix של המשתמש במקום `sudo`:
+```
+npm config set prefix ~/.npm-global
+export PATH=~/.npm-global/bin:$PATH     # וגם ב-~/.bashrc או ~/.zshrc
+```
+
+**המצב הוא לכל משתמש ולכל מחשב.** `~/.gwo` (אתרים, הסכמה לגוגל, `.env`) לא משותף בין מחשבים או בין Windows ל‑VM. במחשב נוסף שאמור לראות את אותם אתרים: להעתיק `sites/*.yaml`, ולעשות את ההסכמה לגוגל מחדש.
+
 ## 2. הפעלה מחדש ובדיקה
 
 הפעלה מחדש של Claude Code ו‑Codex, ואז:
@@ -30,6 +44,9 @@ gwo doctor
 
 - Claude Code: `/gwo-setup`
 - Codex: "הגדר את Google Web Operations"
+- Claude for Windows / Mac (הדסקטופ, Cowork): "הגדר את Google Web Operations"
+
+**Claude Desktop זה הוסט אחר.** הוא לא קורא את הסקילים מהדיסק. `gwo install desktop` (או `gwo install` כשהאפליקציה מותקנת) רושם את ה‑MCP ב‑`claude_desktop_config.json`, ואורז את הסקילים כקובצי zip ב‑`~/.gwo/skills-for-claude-ai/`. אותם מעלים פעם אחת ב‑claude.ai: Settings > Capabilities > Skills > Upload, ומאז הם מסתנכרנים לכל המחשבים של אותו חשבון. בלי ההעלאה, ה‑MCP עובד אבל אין סקילים, והסוכן יעבוד לפי תיאורי הכלים בלבד.
 
 הסוכן מוביל: חיבור לגוגל (לתת לו את הנתיב לקובץ ה‑JSON של לקוח ה‑OAuth, לא את התוכן), הסכמה בדפדפן עם חשבון התפעול, רישום אתר ראשון, ורשימת ההרשאות שהלקוח צריך לתת.
 

package/hosts/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "google-web-operations",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Google Web Operations: agent-run SEO and GEO operations for client websites. One core, one MCP server, two hosts (Claude Code, Codex).",
   "author": {
     "name": "AI Guru"

package/hosts/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "google-web-operations",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Google Web Operations: agent-run SEO and GEO operations for client websites. One core, one MCP server, two hosts (Claude Code, Codex).",
   "author": {
     "name": "AI Guru"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiguru/google-web-operations",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Google Web Operations: agent-run SEO and GEO operations for client websites. One core, one MCP server, two hosts (Claude Code, Codex).",
   "license": "UNLICENSED",
   "private": false,

package/packages/core/src/admin.js

@@ -24,9 +24,9 @@ function siteSetup(s) {
     const missing = [];
     const gsc = s.google.search_console?.property ?? null, ga4 = s.google.ga4?.property_id ?? null, gtm = s.google.tag_manager?.public_id ?? null;
     if (!gsc)
-        missing.push('Search Console property (grant access, then google_discover_apply)');
+        missing.push('Search Console property (the client grants access, then discover the properties)');
     if (!ga4)
-        missing.push('GA4 property id (grant access, then google_discover_apply)');
+        missing.push('GA4 property id (the client grants access, then discover the properties)');
     if (!gtm)
         missing.push('Tag Manager container (none registered; fine if the site has no container)');
     const adapter = s.write?.adapter ?? 'none';
@@ -62,22 +62,22 @@ export function setupStatus() {
     const sites = listSites({ includeDisabled: true }).map(siteSetup);
     const next = [];
     if (!o.clientFile)
-        next.push('Create a "Desktop app" OAuth client in Google Cloud (project "Google Web Operations"), download its JSON, then google_setup_oauth_client with the downloaded file path.');
+        next.push('Connect Google: create a "Desktop app" OAuth client in Google Cloud (one project for all sites), download its JSON, then in the chat "/gwo-setup" and give it the file path (CLI: save it as secrets/oauth-client.json under the state directory).');
     else if (!o.authorised)
-        next.push('google_auth_login: the browser opens for consent with the operations account.');
+        next.push('Authorise the operations Google account: in the chat "/gwo-setup" (CLI: gwo auth login). A browser opens for consent.');
     else {
         if (!writeScopes.ga4_write)
-            next.push('Optional: google_auth_login with scopes ["ga4_write"] before creating key events.');
+            next.push('Optional, before creating key events: add the ga4_write scope (chat: ask for it in /gwo-setup; CLI: gwo auth login --scope ga4_write).');
         if (!writeScopes.gtm_edit || !writeScopes.gtm_publish)
-            next.push('Optional: google_auth_login with scopes ["gtm_edit", "gtm_publish"] before staging Tag Manager changes.');
+            next.push('Optional, before Tag Manager changes: add the gtm_edit and gtm_publish scopes (CLI: gwo auth login --scope gtm_edit --scope gtm_publish).');
     }
     if (!sites.length)
-        next.push('ops_add_site for the first site.');
+        next.push('Register the first site: in the chat "/gwo-add-site https://example.co.il" (CLI: gwo add-site <url> --name "...").');
     if (o.authorised && sites.some((s) => !s.searchConsole || !s.ga4PropertyId))
-        next.push('google_discover_apply once the client has added the operations account to Search Console and GA4.');
+        next.push('Once the client has added the operations account to Search Console and GA4: discover the properties (chat: "discover the Google properties"; CLI: gwo discover --apply).');
     for (const s of sites)
         for (const m of s.missing)
-            if (!/discover_apply|none registered/.test(m))
+            if (!/discover the properties|none registered/.test(m))
                 next.push(`${s.id}: ${m}`);
     if (!env.RESEND_API_KEY)
         next.push('Optional: RESEND_API_KEY, GWO_REPORT_FROM, GWO_REPORT_TO in .env for emailed worker reports.');

package/packages/core/src/doctor.js

@@ -4,12 +4,18 @@
  * by the chat when the operator asks "is everything set up?".
  */
 import { setupStatus } from "./admin.js";
+import { hostname, userInfo } from 'node:os';
 import { HOME_DIR, IS_CHECKOUT, ROOT } from "./paths.js";
 const OK = '  [ok] ', MISSING = '  [--] ', OPT = '  [..] ';
 export function renderDoctor(s = setupStatus()) {
     const out = [];
     const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
-    out.push('Google Web Operations: doctor', '');
+    let who = '';
+    try {
+        who = `${userInfo().username}@${hostname()}`;
+    }
+    catch { /* cosmetic */ }
+    out.push(`Google Web Operations: doctor${who ? ` (${who})` : ''}`, '');
     out.push(`${major > 22 || (major === 22 && minor >= 18) ? OK : MISSING}Node ${process.versions.node} (needs 22.18+)`);
     out.push(`${OK}package ${ROOT}`);
     out.push(`${OK}state ${IS_CHECKOUT ? 'next to the code (repository checkout)' : HOME_DIR}`);

package/tools/install.js

@@ -2,12 +2,12 @@
 /**
  * Install or remove the hosts' side of Google Web Operations on this machine.
  *
- *   gwo install [claude|codex|all] [--print]
- *   gwo uninstall [claude|codex|all]
+ *   gwo install [claude|codex|desktop|all] [--print]
+ *   gwo uninstall [claude|codex|desktop|all]
  *
  * Claude Code: the MCP server goes into ~/.claude.json (user scope), skills
  *              into ~/.claude/skills/gwo-*, slash commands into
- *              ~/.claude/commands/gwo-*.md.
+ *              ~/.claude/commands/gwo-*.md (both show under /gwo-...).
  * Codex:       the MCP server goes into ~/.codex/config.toml, skills into
  *              ~/.codex/skills/gwo-*.
  * Both:        the operator state directory (GWO_HOME, default ~/.gwo) is
@@ -17,15 +17,20 @@
  * Only gwo-* entries are ever written or removed; nothing else in those
  * directories or files is touched. Idempotent: run it again after an upgrade.
  */
+import { execSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, copyFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { HOME_DIR, HOSTS_DIR, IS_CHECKOUT, ROOT } from "../packages/core/src/paths.js";
 const argv = process.argv.slice(2);
 const uninstall = argv.includes('uninstall');
-const targetArg = argv.find((a) => ['claude', 'codex', 'all'].includes(a)) ?? 'all';
+const targetArg = argv.find((a) => ['claude', 'codex', 'desktop', 'all'].includes(a)) ?? 'all';
 const print = argv.includes('--print') || argv.includes('--dry-run');
-const targets = targetArg === 'all' ? ['claude', 'codex'] : [targetArg];
+/** Claude Desktop (Claude for Windows/Mac, Cowork) keeps its MCP servers in its own config file. */
+const DESKTOP_DIR = process.platform === 'win32' ? path.join(process.env['APPDATA'] ?? path.join(homedir(), 'AppData', 'Roaming'), 'Claude')
+    : process.platform === 'darwin' ? path.join(homedir(), 'Library', 'Application Support', 'Claude') : path.join(homedir(), '.config', 'Claude');
+// "all" covers the desktop app only where it is installed, so a plain `gwo install` never invents its config.
+const targets = targetArg === 'all' ? ['claude', 'codex', ...(existsSync(DESKTOP_DIR) ? ['desktop'] : [])] : [targetArg];
 const SERVER = 'google-web-operations';
 const toPosix = (p) => p.replace(/\\/g, '/');
 const node = process.execPath;
@@ -86,6 +91,45 @@ function claude() {
             copyFileSync(path.join(cmdSrc, n), path.join(cmdDst, n));
     }
 }
+// ---------------------------------------------------------------- Claude Desktop (Claude for Windows / Mac, Cowork)
+/**
+ * The desktop app reads MCP servers from claude_desktop_config.json. Skills
+ * cannot be installed from a local file: they are uploaded once in claude.ai
+ * (Settings > Capabilities > Skills) and sync down. So the skills are packed
+ * as one zip per skill under <state>/skills-for-claude-ai/ for that upload.
+ */
+async function desktop() {
+    const cfg = path.join(DESKTOP_DIR, 'claude_desktop_config.json');
+    const skillsSrc = path.join(HOSTS_DIR, 'claude', 'skills');
+    const skills = gwoDirs(skillsSrc);
+    const zipDir = path.join(HOME_DIR, 'skills-for-claude-ai');
+    log(`\nClaude Desktop (Claude for Windows / Mac, Cowork)`);
+    log(`  MCP server "${SERVER}" ${uninstall ? 'removed from' : 'in'} ${cfg}`);
+    log(`  ${skills.length} skills packed as zips -> ${zipDir} (upload once in claude.ai: Settings > Capabilities > Skills)`);
+    if (print)
+        return;
+    mkdirSync(DESKTOP_DIR, { recursive: true });
+    let json = {};
+    if (existsSync(cfg))
+        json = JSON.parse(readFileSync(cfg, 'utf8'));
+    const servers = (json['mcpServers'] ?? {});
+    if (uninstall)
+        delete servers[SERVER];
+    else
+        servers[SERVER] = { command: node, args: [server] };
+    json['mcpServers'] = servers;
+    writeFileSync(cfg, JSON.stringify(json, null, 2));
+    rmSync(zipDir, { recursive: true, force: true });
+    if (!uninstall) {
+        const { default: JSZip } = await import('jszip');
+        mkdirSync(zipDir, { recursive: true });
+        for (const n of skills) {
+            const zip = new JSZip();
+            zip.file(`${n}/SKILL.md`, readFileSync(path.join(skillsSrc, n, 'SKILL.md')));
+            writeFileSync(path.join(zipDir, `${n}.zip`), await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }));
+        }
+    }
+}
 // ---------------------------------------------------------------- Codex
 function codex() {
     const cfg = path.join(CODEX_HOME, 'config.toml');
@@ -119,12 +163,37 @@ function codex() {
 log(`Google Web Operations ${uninstall ? 'uninstall' : 'install'}${print ? ' (print only)' : ''}`);
 log(`package: ${ROOT}`);
 log(`node:    ${node}`);
+// A package under some project's node_modules is a fragile place to point the
+// hosts at: it disappears with the folder or the next npm install there.
+if (!uninstall && !IS_CHECKOUT && /[\\/]node_modules[\\/]/.test(ROOT) && !argv.includes('--allow-local')) {
+    let globalRoot = '';
+    try {
+        globalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch { /* npm not on PATH */ }
+    const isGlobal = globalRoot && path.resolve(ROOT).toLowerCase().startsWith(path.resolve(globalRoot).toLowerCase());
+    if (!isGlobal) {
+        console.error([
+            '',
+            'This copy of the package is installed locally (inside a project\'s node_modules), so the hosts would be',
+            'pointed at a path that vanishes with the folder or the next npm install there. Install it globally instead:',
+            '',
+            '    npm i -g @aiguru/google-web-operations',
+            '    gwo install',
+            '',
+            'To register this local copy anyway (a deliberate, pinned setup): gwo install --allow-local',
+        ].join('\n'));
+        process.exit(2);
+    }
+}
 if (!uninstall)
     ensureHome();
 if (targets.includes('claude'))
     claude();
 if (targets.includes('codex'))
     codex();
+if (targets.includes('desktop'))
+    await desktop();
 if (print)
     log('\nNothing changed. Run without --print to apply.');
 else if (uninstall)
@@ -135,8 +204,9 @@ else
         'Done.',
         '',
         'Next',
-        '  1. Restart Claude Code and Codex so they pick up the server and skills.',
-        '  2. Claude Code: type /gwo-setup.   Codex: say "set up Google Web Operations".',
+        '  1. Restart Claude Code, Codex or the Claude desktop app so they pick up the server and skills.',
+        '  2. Claude Code: type /gwo-setup.   Codex or Claude desktop: say "set up Google Web Operations".',
+        ...(targets.includes('desktop') ? ['     Claude desktop: first upload the skill zips once at claude.ai > Settings > Capabilities > Skills.'] : []),
         '     The assistant connects Google, registers the first site and tells you what the client must grant.',
         '  3. Any time: gwo doctor   (what is configured, what is missing, the next step)',
         '',