feat(install): track CLI installs with deduplicated counting

Add install_count tracking when CLI `skillx use` runs. New `installs`
table with partial unique indexes for per-user/device dedup. API endpoint
accepts optional API key or device fingerprint. Fire-and-forget POST
from CLI doesn't block UX. Atomic install_count increment + score
recomputation on new installs only.

Author: mrgoonie

apps/web/app/lib/db/schema.ts

@@ -1,3 +1,4 @@
+import { sql } from "drizzle-orm";
 import { sqliteTable, text, integer, real, uniqueIndex, index } from "drizzle-orm/sqlite-core";
 
 // Skills - core marketplace entity
@@ -112,6 +113,29 @@ export const usageStats = sqliteTable(
   ]
 );
 
+// Installs - deduplicated install tracking per user/device
+export const installs = sqliteTable(
+  "installs",
+  {
+    id: text("id").primaryKey(),
+    skill_id: text("skill_id")
+      .notNull()
+      .references(() => skills.id, { onDelete: "cascade" }),
+    user_id: text("user_id"),
+    device_id: text("device_id"),
+    created_at: integer("created_at", { mode: "timestamp_ms" }).notNull(),
+  },
+  (table) => [
+    index("idx_installs_skill").on(table.skill_id),
+    uniqueIndex("idx_installs_user")
+      .on(table.skill_id, table.user_id)
+      .where(sql`user_id IS NOT NULL`),
+    uniqueIndex("idx_installs_device")
+      .on(table.skill_id, table.device_id)
+      .where(sql`device_id IS NOT NULL`),
+  ]
+);
+
 // Better Auth tables — required by drizzle adapter
 export const user = sqliteTable("user", {
   id: text("id").primaryKey(),

apps/web/app/routes.ts

@@ -16,6 +16,7 @@ export default [
   route("api/skills/:slug/rate", "routes/api.skill-rate.ts"),
   route("api/skills/:slug/review", "routes/api.skill-review.ts"),
   route("api/skills/:slug/favorite", "routes/api.skill-favorite.ts"),
+  route("api/skills/:slug/install", "routes/api.skill-install.ts"),
   route("api/report", "routes/api.usage-report.ts"),
   route("api/user/api-keys", "routes/api.user-api-keys.ts"),
   route("*", "routes/$.tsx"),

apps/web/app/routes/api.skill-install.ts

@@ -0,0 +1,100 @@
+import type { ActionFunctionArgs } from "react-router";
+import { getDb } from "~/lib/db";
+import { skills, installs, apiKeys } from "~/lib/db/schema";
+import { eq, and, isNull, sql } from "drizzle-orm";
+import { verifyApiKey } from "~/lib/auth/api-key-utils";
+import { recomputeSkillScores } from "~/lib/leaderboard/recompute-skill-scores";
+
+export async function action({ request, params, context }: ActionFunctionArgs) {
+  try {
+    const slug = params.slug;
+    if (!slug) {
+      return Response.json({ error: "Skill slug required" }, { status: 400 });
+    }
+
+    const env = context.cloudflare.env as Env;
+    const db = getDb(env.DB);
+
+    // Resolve identity: API key (user_id) or device fingerprint
+    let userId: string | null = null;
+    const deviceId = request.headers.get("X-Device-Id");
+    const authHeader = request.headers.get("Authorization");
+
+    if (authHeader?.startsWith("Bearer ")) {
+      const apiKeyPlaintext = authHeader.substring(7);
+      const prefix = apiKeyPlaintext.substring(0, 8);
+      const [foundKey] = await db
+        .select()
+        .from(apiKeys)
+        .where(and(eq(apiKeys.key_prefix, prefix), isNull(apiKeys.revoked_at)))
+        .limit(1);
+
+      if (foundKey) {
+        const isValid = await verifyApiKey(apiKeyPlaintext, foundKey.key_hash);
+        if (isValid) {
+          userId = foundKey.user_id;
+          await db
+            .update(apiKeys)
+            .set({ last_used_at: new Date() })
+            .where(eq(apiKeys.id, foundKey.id));
+        }
+      }
+    }
+
+    // Need at least one identifier
+    if (!userId && !deviceId) {
+      return Response.json(
+        { error: "Authorization header or X-Device-Id required" },
+        { status: 400 },
+      );
+    }
+
+    // Find skill
+    const [skill] = await db
+      .select({ id: skills.id })
+      .from(skills)
+      .where(eq(skills.slug, slug))
+      .limit(1);
+
+    if (!skill) {
+      return Response.json({ error: "Skill not found" }, { status: 404 });
+    }
+
+    // Insert install (ON CONFLICT DO NOTHING) and check if row was inserted
+    const installId = `inst-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    let inserted = false;
+
+    try {
+      await db.insert(installs).values({
+        id: installId,
+        skill_id: skill.id,
+        user_id: userId,
+        device_id: userId ? null : deviceId, // Nullify device_id when user_id present to prevent double-counting
+        created_at: new Date(),
+      });
+      inserted = true;
+    } catch (e: unknown) {
+      // UNIQUE constraint violation = already installed (dedup)
+      const msg = e instanceof Error ? e.message : "";
+      if (!msg.includes("UNIQUE constraint")) throw e;
+    }
+
+    if (inserted) {
+      // Atomic increment
+      await db
+        .update(skills)
+        .set({ install_count: sql`install_count + 1`, updated_at: new Date() })
+        .where(eq(skills.id, skill.id));
+
+      await recomputeSkillScores(db, skill.id);
+    }
+
+    return Response.json({ installed: inserted });
+  } catch (error) {
+    console.error("Error tracking install:", error);
+    return Response.json(
+      { error: "Failed to track install" },
+      { status: 500 },
+    );
+  }
+}

apps/web/drizzle/migrations/0005_crazy_kate_bishop.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `installs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`skill_id` text NOT NULL,
+	`user_id` text,
+	`device_id` text,
+	`created_at` integer NOT NULL,
+	FOREIGN KEY (`skill_id`) REFERENCES `skills`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `idx_installs_skill` ON `installs` (`skill_id`);--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_installs_user` ON `installs` (`skill_id`,`user_id`) WHERE user_id IS NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_installs_device` ON `installs` (`skill_id`,`device_id`) WHERE device_id IS NOT NULL;