luckiest-co 1.0.7 → 1.0.9

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "luckiest",
   "description": "Plan, go, finish. Guided planning, progress dashboards, and your luckiest.co tribe inside Claude Code.",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "author": { "name": "Luckiest" }
 }

package/README.md

@@ -31,6 +31,10 @@ npx claude plugin add luckiest-co
 | `/luckiest wishes` | See what your tribe is working toward |
 | `/luckiest charms` | View and use your skill boosters |
 
+## Telemetry
+
+When a Luckiest skill runs, the plugin reports anonymized, metadata-only usage so run counts, version adoption, and owner-facing improvement suggestions stay accurate. Exactly these fields are sent: skill slug, plugin version, whether the skill matched and (when observed) succeeded, an error category, duration, a SHA-256 hash of your key, a SHA-256 hash of the session id, and the reporting surface (`hook`, `mcp`, or `cli`). Prompt text, tool output, and file contents are never sent. Reporting is best-effort and never blocks or fails a skill run. Full policy: https://luckiest.co/privacy
+
 ## Requirements
 
 - Claude Code (CLI)

package/bin/install.js

@@ -38,6 +38,11 @@ const args = process.argv.slice(2);
 const hasGlobal = args.includes('--global') || args.includes('-g');
 const hasLocal = args.includes('--local') || args.includes('-l');
 const syncOnly = args.includes('--sync-only');
+// Usage-hook registration writes to the user's settings.json, so it's opt-in by
+// a prompt rather than silent. These flags answer that prompt ahead of time for
+// scripted installs, where there's no terminal to ask at.
+const hasHook = args.includes('--hook');
+const hasNoHook = args.includes('--no-hook');
 
 // Parse --config-dir argument
 function parseConfigDirArg() {
@@ -70,6 +75,8 @@ if (hasHelp) {
     ${cyan}-l, --local${reset}               Install locally (to ./.claude in current directory)
     ${cyan}-c, --config-dir <path>${reset}   Specify custom Claude config directory
     ${cyan}--sync-only${reset}               Skip install, only sync owned skills from luckiest.co
+    ${cyan}--hook${reset}                    Enable skill usage tracking without prompting
+    ${cyan}--no-hook${reset}                 Skip it (and remove it if a past install added it)
     ${cyan}-h, --help${reset}                Show this help message
 
   ${yellow}Examples:${reset}
@@ -205,6 +212,8 @@ async function syncSkills() {
     console.log(`  ${green}✓${reset} Removed duplicate commands/luckiest (plugin marketplace already provides them)`);
   }
 
+  nudgeUsageHook(globalDir);
+
   const key = readSavedKey();
   if (!key) {
     console.log(`  ${dim}No luckiest.co connection key saved yet. Run ${cyan}npx luckiest-co${dim} and paste one to sync your owned skills.${reset}`);
@@ -388,7 +397,7 @@ function install(isGlobal) {
   }
 
   // Copy references/, templates/, .claude-plugin/ into the target root
-  const topLevelDirs = ['references', 'templates', 'skills', '.claude-plugin'];
+  const topLevelDirs = ['references', 'templates', 'skills', '.claude-plugin', 'hooks'];
   for (const dir of topLevelDirs) {
     const dirSrc = path.join(src, dir);
     const dirDest = path.join(claudeDir, dir);
@@ -401,6 +410,152 @@ function install(isGlobal) {
   console.log(`
   ${green}Done!${reset} Launch Claude Code and run ${cyan}/luckiest:plan${reset}.
 `);
+
+  return { claudeDir, globalClaudeDir: defaultGlobalDir };
+}
+
+/**
+ * Ask before touching settings.json. Returns true when we may register.
+ *
+ * Order: explicit flags win, then a prompt when there's a terminal to ask at.
+ * With no TTY (CI, piped installs) we decline rather than default to yes —
+ * silently editing a config file nobody was asked about is not a default worth
+ * having. --hook opts in for those cases.
+ */
+async function shouldRegisterHook() {
+  if (hasNoHook) return false;
+  if (hasHook) return true;
+  if (!process.stdin.isTTY) {
+    console.log(`  ${dim}Skipped usage-hook setup (no terminal to ask at). Re-run with ${cyan}--hook${dim} to enable.${reset}`);
+    return false;
+  }
+
+  console.log(`
+  ${yellow}Track your skill usage?${reset}
+  ${dim}Adds a hook to settings.json that reports which Luckiest skill ran, and
+  its version — never your prompts, tool output, or file contents. Powers your
+  usage stats at luckiest.co. You can remove it any time.${reset}
+`);
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let answered = false;
+    rl.question(`  Enable? ${dim}[Y/n]${reset}: `, (answer) => {
+      answered = true;
+      rl.close();
+      resolve(!/^n/i.test(answer.trim()));
+    });
+    // Input closed before an answer arrived (piped stdin that ran dry, ^D).
+    // Decline: an unanswered consent prompt is not consent.
+    rl.on('close', () => {
+      if (!answered) resolve(false);
+    });
+  });
+}
+
+// Identifies our hook entry across installs even when the absolute path changed.
+const isOurHookEntry = (entry) =>
+  (entry?.hooks || []).some((h) => String(h?.command || '').includes('report-skill-usage.mjs'));
+
+function usageHookRegistered(claudeDir) {
+  try {
+    const settings = JSON.parse(fs.readFileSync(path.join(claudeDir, 'settings.json'), 'utf8'));
+    return (settings.hooks?.PostToolUse || []).some(isOurHookEntry);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Tell, don't act. --sync-only runs unattended at session start, so there's no
+ * terminal to ask at and registering there would mean silently editing
+ * settings.json on a call the user never typed. Instead, say the tracking is off
+ * once and let them opt in deliberately. Silent when it's already handled, so
+ * this adds nothing to the common session-start path.
+ */
+function nudgeUsageHook(globalClaudeDir) {
+  if (hasMarketplacePlugin(globalClaudeDir)) return; // plugin registers its own
+  if (usageHookRegistered(globalClaudeDir)) return;
+  console.log(`  ${dim}Skill usage tracking is off. Run ${cyan}npx luckiest-co@latest --hook${dim} to turn it on.${reset}`);
+}
+
+/**
+ * Register the PostToolUse(Skill) telemetry hook in the user's settings.json.
+ *
+ * The marketplace plugin ships hooks/hooks.json and Claude Code registers it
+ * automatically; an npx install has no such mechanism, so until now the npx
+ * path shipped no hook at all and reported nothing. This closes that gap.
+ *
+ * settings.json belongs to the user, so this is a merge, never an overwrite:
+ * unknown keys are preserved, an existing PostToolUse array is appended to, and
+ * a previous Luckiest entry is replaced rather than duplicated (the install path
+ * can change between runs). Best-effort — an unreadable or malformed settings
+ * file warns and leaves the install otherwise complete.
+ */
+function registerUsageHook(claudeDir, globalClaudeDir, consented) {
+  const hookPath = path.join(claudeDir, 'hooks', 'report-skill-usage.mjs');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      console.log(`  ${yellow}!${reset} Couldn't parse settings.json — skipped hook registration.`);
+      console.log(`  ${dim}Skill usage won't be tracked from Claude Code until it's valid JSON.${reset}`);
+      return;
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+  const existing = Array.isArray(settings.hooks.PostToolUse) ? settings.hooks.PostToolUse : [];
+  const others = existing.filter((e) => !isOurHookEntry(e));
+  const hadOurs = others.length !== existing.length;
+
+  // Declining is also an instruction to remove a hook a past install added.
+  // Cleanup never needs consent — only adding does.
+  if (!consented) {
+    if (!hadOurs) return;
+    settings.hooks.PostToolUse = others;
+    if (writeSettings(settingsPath, settings)) {
+      console.log(`  ${green}✓${reset} Removed the usage hook from settings.json`);
+    }
+    return;
+  }
+
+  // The marketplace plugin already registers this hook via hooks.json. Adding a
+  // second registration would fire it twice and double every usage count, so
+  // when the plugin is present we only clean up a stale copy of our own.
+  if (hasMarketplacePlugin(globalClaudeDir)) {
+    if (!hadOurs) {
+      console.log(`  ${dim}Skipped usage hook (plugin marketplace already provides it)${reset}`);
+      return;
+    }
+    settings.hooks.PostToolUse = others;
+    writeSettings(settingsPath, settings);
+    console.log(`  ${green}✓${reset} Removed duplicate usage hook (plugin marketplace already provides it)`);
+    return;
+  }
+
+  settings.hooks.PostToolUse = [
+    ...others,
+    {
+      matcher: 'Skill',
+      hooks: [{ type: 'command', command: `node "${hookPath}"` }],
+    },
+  ];
+  if (writeSettings(settingsPath, settings)) {
+    console.log(`  ${green}✓${reset} Registered skill usage hook in settings.json`);
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  try {
+    fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    return true;
+  } catch (err) {
+    console.log(`  ${yellow}!${reset} Couldn't write settings.json (${err.message}) — skipped hook registration.`);
+    return false;
+  }
 }
 
 /**
@@ -454,7 +609,14 @@ async function main() {
     isGlobal = await promptLocation();
   }
 
-  install(isGlobal);
+  const { claudeDir, globalClaudeDir } = install(isGlobal);
+
+  // Global installs only: a project-level hook would land in a shared repo and
+  // fire for every collaborator, so ./.claude installs get the files but no
+  // registration.
+  if (isGlobal) {
+    registerUsageHook(claudeDir, globalClaudeDir, await shouldRegisterHook());
+  }
 
   const alreadyHasKey = !!readSavedKey();
   if (!alreadyHasKey) {

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "description": "Luckiest plugin hooks — deterministic skill-usage telemetry on every Luckiest skill run.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/report-skill-usage.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/report-skill-usage.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// PostToolUse(Skill) hook: records one skill-usage telemetry row per Luckiest
+// skill run, deterministically — no dependence on the model remembering to call
+// report_usage, and no MCP tool required. Metadata only (slug + matched/success);
+// never sends prompt text or tool output. Best-effort: any failure is swallowed
+// so a tracking hiccup can never break the user's skill run.
+// ponytail: fire-and-forget POST; if telemetry ever needs delivery guarantees,
+// queue to disk and flush on SessionStart instead.
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, hostname } from "node:os";
+import { createHash } from "node:crypto";
+
+const API = (process.env.LUCKIEST_API_URL || "https://api.luckiest.co").replace(/\/$/, "");
+// Env var wins; otherwise fall back to the key the installer saves to
+// ~/.luckiest/key, so usage is attributed without any settings.json env block.
+const KEY = process.env.LUCKIEST_SKILL_KEY || (() => {
+  try {
+    return readFileSync(join(homedir(), ".luckiest", "key"), "utf8").trim();
+  } catch {
+    return "";
+  }
+})();
+
+// Marketplace installs never run bin/install.js, so they have no key and used to
+// report with a null reporter_hash — invisible to count(DISTINCT reporter_hash),
+// which undercounted unique installs to zero for that whole population. When no
+// key exists, send a stable per-install id instead: a salted sha256 of hostname
+// + home dir. Not an account and not reversible to one; it only says "same
+// install as last time". A real key always wins, so keyed members still link to
+// their member id server-side.
+// ponytail: hostname+homedir is the cheapest stable pair available to a hook;
+// if installs ever need to survive a machine rename, write a random id to
+// ~/.luckiest/install-id instead.
+const INSTALL_ID = KEY
+  ? ""
+  : createHash("sha256").update(`luckiest-install:${hostname()}:${homedir()}`).digest("hex");
+
+// The plugin's own version, read once from its manifest. Every Luckiest skill
+// ships inside this one plugin and bumps with it, so reporting this per run lets
+// the server see which plugin version each member is actually on. Best-effort:
+// if the manifest can't be read, we just omit the field.
+// CLAUDE_PLUGIN_ROOT is set only for marketplace plugin installs. An npx
+// install registers this hook by absolute path with no such env var, so fall
+// back to the manifest sitting next to the installed hook (…/hooks/../
+// .claude-plugin/plugin.json). Without this every npx row reported a null
+// version and silently skewed version-adoption numbers.
+const PLUGIN_VERSION = (() => {
+  const roots = [
+    process.env.CLAUDE_PLUGIN_ROOT,
+    join(dirname(fileURLToPath(import.meta.url)), ".."),
+  ].filter(Boolean);
+  for (const root of roots) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(root, ".claude-plugin", "plugin.json"), "utf8"));
+      if (manifest?.version) return manifest.version;
+    } catch {
+      /* try the next root */
+    }
+  }
+  return null;
+})();
+
+const ok = () => { process.stdout.write('{"continue":true,"suppressOutput":true}'); process.exit(0); };
+
+let raw = "";
+process.stdin.on("data", (c) => (raw += c));
+process.stdin.on("end", async () => {
+  try {
+    const evt = JSON.parse(raw || "{}");
+    // Skill tool input: { skill: "luckiest:luckiest-aso" | "luckiest:charms" | ... }
+    const skill = String(evt?.tool_input?.skill || "");
+    // Identify our plugin's skills two ways, so tracking survives whether the host
+    // passes the namespaced form or a bare name. Foreign skills (superpowers,
+    // vercel, gsd, …) match neither and are ignored so we don't post their runs.
+    //   "luckiest:<slug>" — namespaced plugin skill (charms, plan, luckiest-aso, …)
+    //   "luckiest-<slug>" — bare marketing/coder skill name
+    let slug;
+    if (skill.startsWith("luckiest:")) slug = skill.slice("luckiest:".length);
+    else if (skill.startsWith("luckiest-")) slug = skill;
+    else return ok();
+    // server resolves slug -> listing id
+
+    const headers = { "content-type": "application/json" };
+    if (KEY) headers.authorization = `Bearer ${KEY}`; // sets reporter_hash; optional
+
+    // 3s cap: telemetry must never stall the session.
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 3000);
+    await fetch(`${API}/api/skills/telemetry`, {
+      method: "POST",
+      headers,
+      // No success flag: the hook fires at PostToolUse time and never observes
+      // the outcome. Real outcomes arrive via report_usage (outcome_known=true).
+      body: JSON.stringify({
+        listing_id: slug,
+        matched: true,
+        skill_version: PLUGIN_VERSION,
+        surface: "hook",
+        // Only sent when there's no key; the server prefers the key's hash.
+        install_hash: INSTALL_ID || undefined,
+        session_hash: evt?.session_id
+          ? createHash("sha256").update(String(evt.session_id)).digest("hex")
+          : undefined,
+      }),
+      signal: ctrl.signal,
+    }).catch(() => {});
+    clearTimeout(timer);
+  } catch {
+    /* best-effort — never fail the tool */
+  }
+  ok();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luckiest-co",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Luckiest for Claude Code: plan, go, finish. Your luckiest.co skills and tribe, inside Claude.",
   "bin": {
     "luckiest-co": "./bin/install.js"
@@ -11,6 +11,7 @@
     "references",
     "templates",
     "skills",
+    "hooks",
     ".claude-plugin"
   ],
   "license": "SEE LICENSE IN LICENSE",