@higrowth/cli 0.2.0 → 0.3.2

package/dist/index.js

@@ -703,157 +703,179 @@ just say which one \u2014 you don't have to redo the whole interview."*
 // src/skills/marketing-strategy.ts
 var MARKETING_STRATEGY = `---
 name: higrowth-marketing-strategy
-description: Helps the user interpret a Higrowth diagnostic, pick which pillars to prioritize, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, or plan.
+description: Helps the user interpret a Higrowth diagnostic, choose a bounded scoped-plan area, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, ask what can be fixed in an area, or plan.
 allowed-tools: mcp__higrowth__execute_typescript
 ---
 
 # Higrowth \u2014 Marketing strategy chat
 
-You are the user's strategy partner for the next 30 minutes. They have a
-diagnostic open; your job is to help them turn 80 opportunities into a
-focused 5-10-item plan.
+You are the user's strategy partner. They have Higrowth data available;
+your job is to help them turn noisy diagnostics into one bounded,
+measurable scoped plan that can move the needle.
 
 ## When to use this skill
 
 Trigger on: "what should I focus on", "walk me through my report",
-"prioritize this", "what's the move", "plan my sprint".
+"prioritize this", "what's the move", "plan my sprint", "what can we
+fix in [area/topic/page]".
 
 ## Mental model
 
-The diagnostic surfaces opportunities ranked by data score. Strategy
-ranks them by **leverage** \u2014 which work will compound. Your job is to
-push the user from "rank by score" thinking to "rank by pillar
-strategy" thinking.
+Plans are not giant backlogs. A good plan is a scoped intervention:
+one topic area, page cluster, gap type, or conversion slice with enough
+evidence to act and narrow enough boundaries to avoid conflicting work.
+
+Rank by **leverage and executability**, not raw opportunity count.
 
 ## The conversation
 
-### Step 1 \u2014 Pull the synthesis
+### Step 1 \u2014 Pull current context
 
-Don't dump opportunities. Start with the LLM-written narrative.
+Start with the latest diagnostic narrative and any known entity context.
+Don't dump all opportunities.
 
 \`\`\`ts
 const dx = await api.get(\`/api/diagnostics/\${diagnosticId}\`);
 console.log(dx.synthesis);
 \`\`\`
 
-Read it. Then ask the user: *"Did that match your read of how the site
-is doing right now? Anything missing?"*
+Ask: *"Did that match your read of how the site is doing right now?
+Anything missing or recently changed?"*
 
-Listen for context the diagnostic can't know \u2014 recent launches,
-seasonal pages, things that are about to change. Note these. They
-should shape priorities.
+Use the answer to steer scope selection. Recent launches, product
+changes, seasonality, and sales priorities should shape what you plan.
 
-### Step 2 \u2014 Pick ONE pillar
+### Step 2 \u2014 Choose a bounded area
 
-This is the most important step. Most users want to spray-and-pray
-across all pillars. Don't let them.
+If the user named an area, use it as the scope query. If not, help them
+pick one from the diagnostic: a pillar, subtopic, page cluster, gap type,
+or conversion issue.
 
 \`\`\`ts
-const topics = await api.get(\`/api/diagnostics/\${diagnosticId}/topics\`);
-const pillars = topics.topics.flatMap(c => c.pillars);
-// Rank by impressions \xD7 priority
+const q = userIntent || 'highest leverage scoped fixes';
+const candidates = await api.get(
+  \`/api/entities/\${entityId}/plan-scopes/candidates?q=\${encodeURIComponent(q)}&limit=6&maxItems=8\`
+);
 \`\`\`
 
-Show the top 3 pillars by impressions, with their priority tier and a
-one-line gap summary. Ask: *"If we could only fix ONE topic area in the
-next 2 weeks, which one would change your business the most?"*
+Show the top 3 candidates with:
+- label
+- scope type
+- pages and gaps included
+- expected outcome
+- conflict state and warnings
+- why you prefer one
+
+If every candidate is weak, broaden the query once. If candidates are
+still thin, say the source data is missing and suggest the prerequisite
+connection or scan.
 
-If they pick the one with the most opportunities: good.
-If they pick the one with the most strategic value: better.
-If they say "all of them": push back. *"Sprint focus beats sprint
-breadth. We'll get to the others \u2014 pick the one that, if it wins, you
-can point to."*
+### Step 3 \u2014 Inspect conflicts before committing
 
-### Step 3 \u2014 Read the pillar dashboard with them
+Never stage a scope blindly. Use preview when the user is leaning toward
+a candidate or asks why it is safe.
 
 \`\`\`ts
-const pillar = await api.get(\`/api/topics/\${pillarId}\`);
-const dashboard = await api.get(\`/api/topics/\${pillarId}/dashboard\`);
+const selected = candidates.candidates[0];
+const preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\`, {
+  selectedBy: 'agent',
+  scope: {
+    version: 1,
+    selectedAt: new Date().toISOString(),
+    selectedBy: 'agent',
+    sourceCandidateId: selected.id,
+    entityId: selected.entityId,
+    label: selected.label,
+    scopeType: selected.scopeType,
+    topicId: selected.topicId,
+    subtopicIds: selected.subtopicIds,
+    pageIds: selected.pageIds,
+    gapIds: selected.gapIds,
+    analysisTypes: selected.analysisTypes,
+    includedSignals: ['gap_inventory', ...selected.analysisTypes],
+    excludedAdjacentScopes: [],
+    reasonForScope: selected.whyThisScope,
+    expectedOutcome: selected.expectedOutcome,
+  },
+});
 \`\`\`
 
-Walk them through:
-- **AEO readiness** \u2014 what's missing (schema gaps, low stat density,
-  buried answers)
-- **Sub-topic coverage** \u2014 uncovered slots = new_brief candidates
-- **"Who to beat"** \u2014 the named competitor(s) winning in this pillar
-- **Top 5 striking-distance opportunities** \u2014 quick wins on existing pages
-
-For each, give your opinion. Be a strategist, not a librarian.
+If preview returns blocked conflicts, do not create the plan. Explain
+the overlap and pick another scope.
 
-> "Your fresh-page % is 28 \u2014 way below where it should be. Your top
-> competitor refreshes monthly. I'd start with 3 \`freshness_refresh\`
-> work orders on your highest-impression pages."
+If preview returns warnings, ask for explicit user acceptance before
+creating. Warnings are allowed only when the user understands the overlap.
 
-### Step 4 \u2014 Build the shortlist
+### Step 4 \u2014 Create the scoped plan
 
-Together, pick 5-10 opportunities. Sequence matters: ship cheap-and-safe
-first (schema, internal links), then medium (title rewrites, freshness),
-then invasive (section rewrites, new briefs). Add to a plan as you go.
+Create from the selected scope. Do not use legacy topic-plan or
+opportunity-basket endpoints.
 
 \`\`\`ts
-const plan = await api.post('/api/plans', {
-  entityId,
-  name: \`\${pillar.name} \u2014 sprint 1\`,
-  description: 'What hypothesis are we testing this sprint',
+const plan = await api.post(\`/api/entities/\${entityId}/plans/from-scope\`, {
+  name: selected.label,
+  description: selected.expectedOutcome,
+  scope: preview.scope,
+  conflictOverride:
+    preview.conflicts.some(c => c.severity === 'warn')
+      ? { allowWarnings: true, allowBlocks: false }
+      : undefined,
 });
-
-for (const oppKey of selectedKeys) {
-  await api.post(\`/api/plans/\${plan.plan.id}/candidates\`, {
-    opportunityKeys: [oppKey],
-  });
-}
 \`\`\`
 
-### Step 5 \u2014 Generate briefs + propose work orders
+### Step 5 \u2014 Generate scoped items
 
 \`\`\`ts
-await api.post(\`/api/plans/\${plan.plan.id}/generate\`);
+const generation = await api.post(\`/api/plans/\${plan.plan.id}/generate-scoped\`);
+console.log(generation);
 \`\`\`
 
-Then for each plan item, propose its work order. Tell the user the
-plan is ready for review and they should approve in the work-orders
-UI when they're ready.
+Generation must stay inside the selected scope. It should claim only
+the gaps and pages in the scope, carry conflict warnings into the audit,
+and return deferred or not-recommended items instead of stretching the
+scope to look productive.
+
+After generation, send the user to the plan detail. Explain what to
+review and which first 1-3 items are safest to move into execution.
 
 ### Step 6 \u2014 Set expectations
 
 End with reality:
 
 > "Outcome verdicts take 14 days minimum because GSC needs that long
-> to stabilize. Re-run the diagnostic in 2 weeks and reconcile the
-> plan. Plan to ship a second sprint at the same time you read sprint
-> 1's outcomes \u2014 that's the flywheel."
+> to stabilize. Re-run the diagnostic in 2 weeks, reconcile the plan,
+> and choose the next scoped slice from what changed."
 
 ## Strong opinions to bring
 
-The user will look to you to break ties. Hold these:
-
-- **One pillar per sprint.** Always.
-- **Schema and internal links first.** Lowest risk, highest velocity.
+- **One bounded scope per plan.** Always.
+- **Prefer conflict-clear scopes.** Warning scopes require explicit user acceptance.
+- **Use the signal, not the URL.** Match on topic, page summaries, gap evidence,
+  GSC, GA, AEO, conversion, and strategy context.
+- **Small is fine.** A plan with 3 high-confidence page items can beat a giant backlog.
 - **Don't promise CTR lift in week 1.** The data takes 14 days.
-- **Inconclusive \u2260 failed.** Many flip to verified on the next window.
-- **Re-run cadence is 2 weeks.** Not 2 days. Not 2 months.
-- **Plans have a defined end.** Archive after 4-6 weeks, even if
-  unfinished \u2014 open-ended plans become graveyards.
+- **Inconclusive is not failed.** Many outcomes need another window.
+- **Archive old/conflicting plans.** Open-ended plans become graveyards.
 
 ## What success looks like
 
-- One pillar picked
-- One plan created
-- 5-10 candidates added
-- Briefs generated
-- Work orders proposed for at least 3 of them
-- User knows when to come back (14 days for outcomes, ~immediately for
-  approvals)
+- One bounded scope picked
+- Conflicts reviewed
+- One scoped plan created
+- Scoped generation run
+- First execution items are obvious
+- User knows when to come back: 14 days for outcomes, sooner for approvals
 
 ## What NOT to do
 
-- Don't sort opportunities by score and list the top 10. That's not
-  strategy.
-- Don't tell the user "it depends" when they ask what to ship first.
-  Have an opinion.
-- Don't promise outcomes you can't deliver. The engine measures wins
-  honestly; you should too.
-- Don't gloss over the KB. If their KB is empty, stop and run the
+- Don't create a generic topic plan.
+- Don't use \`POST /api/plans\`, \`POST /api/plans/topic\`,
+  \`POST /api/plans/:id/candidates\`, \`POST /api/plans/:id/generate\`,
+  or \`POST /api/plans/:id/generate-topic\`.
+- Don't sort opportunities by score and list the top 10. That's not strategy.
+- Don't let URLs alone classify scope. Use the evidence Higrowth gathered.
+- Don't create a plan that overlaps blocked active work.
+- Don't gloss over the KB. If the KB is empty, stop and run the
   populate-kb playbook first. Strategy without KB context is generic.
 `;
 
@@ -1157,8 +1179,181 @@ function compareSkill(path, skill) {
   }
 }
 
+// src/commands/upgrade.ts
+var PKG_NAME = "@higrowth/cli";
+async function upgradeCommand() {
+  process.stdout.write(
+    `
+Upgrade ${PKG_NAME} to the latest version with whichever package
+manager you used to install it:
+
+  npm install -g ${PKG_NAME}@latest
+  pnpm add -g ${PKG_NAME}@latest
+  bun add -g ${PKG_NAME}@latest
+  yarn global add ${PKG_NAME}@latest
+
+Or, if you installed via the curl-piped flow:
+
+  curl -fsSL https://app.higrowth.ai/install.sh | sh
+
+After upgrade, run \`higrowth -v\` to confirm.
+`
+  );
+}
+
+// src/lib/update-check.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join3 } from "path";
+import { homedir as homedir3 } from "os";
+var PKG_NAME2 = "@higrowth/cli";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REQUEST_TIMEOUT_MS = 2e3;
+function cachePath() {
+  return join3(homedir3(), ".config", "higrowth", "update-check.json");
+}
+function readCache() {
+  const path = cachePath();
+  if (!existsSync3(path)) return null;
+  try {
+    const raw = readFileSync3(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.latestVersion !== "string") return null;
+    if (typeof parsed.fetchedAt !== "number") return null;
+    return { latestVersion: parsed.latestVersion, fetchedAt: parsed.fetchedAt };
+  } catch {
+    return null;
+  }
+}
+function writeCache(latestVersion) {
+  const path = cachePath();
+  try {
+    mkdirSync3(dirname3(path), { recursive: true });
+    writeFileSync3(
+      path,
+      JSON.stringify({ latestVersion, fetchedAt: Date.now() }, null, 2),
+      "utf-8"
+    );
+  } catch {
+  }
+}
+async function fetchLatestFromNpm() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PKG_NAME2}/latest`, {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body.version ?? null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function compareVersions(a, b) {
+  const parse = (v) => v.split("-")[0].split(".").map((s) => Number.parseInt(s, 10)).map((n2) => Number.isFinite(n2) ? n2 : 0);
+  const aa = parse(a);
+  const bb = parse(b);
+  const n = Math.max(aa.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    const ai = aa[i] ?? 0;
+    const bi = bb[i] ?? 0;
+    if (ai !== bi) return ai - bi;
+  }
+  return 0;
+}
+function shouldSkip() {
+  if (process.env.HIGROWTH_NO_UPDATE_CHECK === "1") return true;
+  if (process.env.CI) return true;
+  if (!process.stdout.isTTY) return true;
+  return false;
+}
+function beginUpdateCheck(currentVersion) {
+  if (shouldSkip()) {
+    return async () => {
+    };
+  }
+  const cached = readCache();
+  const fresh = cached && Date.now() - cached.fetchedAt < CHECK_INTERVAL_MS;
+  const fetchPromise = fresh ? Promise.resolve(cached.latestVersion) : fetchLatestFromNpm().then((v) => {
+    if (v) writeCache(v);
+    return v;
+  });
+  return async () => {
+    let latest;
+    try {
+      latest = await fetchPromise;
+    } catch {
+      return;
+    }
+    if (!latest) return;
+    if (compareVersions(latest, currentVersion) <= 0) return;
+    process.stderr.write(
+      `
+\u2191 ${PKG_NAME2} ${latest} is available (you have ${currentVersion}).
+  Upgrade:  npm i -g ${PKG_NAME2}@latest
+  (or bun add -g / pnpm add -g / yarn global add depending on how you installed.)
+  Silence:  set HIGROWTH_NO_UPDATE_CHECK=1
+`
+    );
+  };
+}
+
+// package.json
+var package_default = {
+  name: "@higrowth/cli",
+  version: "0.3.2",
+  description: "Higrowth CLI \u2014 log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
+  type: "module",
+  license: "Apache-2.0",
+  bin: {
+    higrowth: "dist/index.js"
+  },
+  files: [
+    "dist/",
+    "README.md"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    check: "tsc --noEmit"
+  },
+  engines: {
+    node: ">=20"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  devDependencies: {
+    "@types/iarna__toml": "^2.0.5",
+    "@types/node": "^22.10.5",
+    tsup: "^8.5.0",
+    typescript: "^5.6.3"
+  },
+  keywords: [
+    "higrowth",
+    "seo",
+    "aeo",
+    "mcp",
+    "claude-code",
+    "agent"
+  ],
+  homepage: "https://github.com/higrowth-ai/hg-engine",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/higrowth-ai/hg-engine.git",
+    directory: "cli"
+  },
+  dependencies: {
+    "@iarna/toml": "^2.2.5"
+  }
+};
+
 // src/index.ts
-var VERSION = "0.1.1";
+var VERSION = package_default.version;
 var DEFAULT_HOST = "https://app.higrowth.ai";
 var USAGE = `higrowth \u2014 Connect your agent to a Higrowth workspace
 
@@ -1189,7 +1384,14 @@ COMMANDS
   skills update [--target TARGET]
       Re-install the bundled skill versions.
 
-  version
+  upgrade
+      Show the right command to upgrade @higrowth/cli to the latest
+      published version, matched to your package manager (npm / pnpm /
+      bun / yarn / curl-pipe). The CLI auto-checks for new versions on
+      every invocation (cached 24h); set HIGROWTH_NO_UPDATE_CHECK=1 to
+      silence the nudge.
+
+  version | --version | -v
       Print version + exit.
 
 FLAGS
@@ -1247,6 +1449,23 @@ function resolveTarget(raw) {
 }
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  if (args.flags.version === true || args.flags.v === true) {
+    process.stdout.write(`higrowth ${VERSION}
+`);
+    return;
+  }
+  if (args.command === "" && (args.flags.help === true || args.flags.h === true)) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  const showUpdateNotice = beginUpdateCheck(VERSION);
+  try {
+    await runCommand(args);
+  } finally {
+    await showUpdateNotice();
+  }
+}
+async function runCommand(args) {
   const host = typeof args.flags.host === "string" ? args.flags.host : DEFAULT_HOST;
   const target = resolveTarget(args.flags.target);
   const device = args.flags.device === true;
@@ -1254,13 +1473,9 @@ async function main() {
   switch (args.command) {
     case "":
     case "help":
-    case "--help":
-    case "-h":
       process.stdout.write(USAGE);
       return;
     case "version":
-    case "--version":
-    case "-v":
       process.stdout.write(`higrowth ${VERSION}
 `);
       return;
@@ -1280,6 +1495,9 @@ async function main() {
     case "logout":
       await logoutCommand();
       return;
+    case "upgrade":
+      await upgradeCommand();
+      return;
     case "skills":
       if (args.subcommand === "install" || args.subcommand === void 0) {
         await skillsInstallCommand({ target });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higrowth/cli",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Higrowth CLI — log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
   "type": "module",
   "license": "Apache-2.0",
@@ -28,7 +28,14 @@
     "tsup": "^8.5.0",
     "typescript": "^5.6.3"
   },
-  "keywords": ["higrowth", "seo", "aeo", "mcp", "claude-code", "agent"],
+  "keywords": [
+    "higrowth",
+    "seo",
+    "aeo",
+    "mcp",
+    "claude-code",
+    "agent"
+  ],
   "homepage": "https://github.com/higrowth-ai/hg-engine",
   "repository": {
     "type": "git",