selftune 0.2.18 → 0.2.19

package/cli/selftune/contribute/contribute.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * selftune contribute — opt-in export of anonymized skill observability data.
+ * selftune contribute — community export of anonymized skill observability data.
  *
  * Usage:
  *   bun run cli/selftune/contribute/contribute.ts --skill selftune [--preview] [--output file.json]
@@ -31,10 +31,38 @@ export async function cliMain(): Promise<void> {
       submit: { type: "boolean", default: false },
       endpoint: { type: "string", default: "https://selftune-api.fly.dev" },
       github: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
     },
     strict: true,
   });
 
+  if (values.help) {
+    console.log(`selftune contribute — Export an anonymized community bundle
+
+Usage:
+  selftune contribute --skill <name> [--preview] [--sanitize conservative|aggressive]
+  selftune contribute --skill <name> [--output <file>] [--submit]
+
+Purpose:
+  Build a sanitized community contribution bundle from local SQLite data.
+  This is separate from:
+    selftune contributions  Creator-directed sharing preferences
+    selftune alpha upload   Personal cloud upload cycle
+
+Options:
+  --skill <name>                    Skill to export
+  --preview                         Print the sanitized bundle instead of writing it
+  --sanitize conservative|aggressive
+                                    Choose the sanitization level
+  --output <file>                   Write the bundle to an explicit file path
+  --since <timestamp>               Only include records on or after this time
+  --submit                          Submit the bundle after writing it
+  --endpoint <url>                  Override the default service endpoint
+  --github                          Submit via GitHub flow instead of the service
+  -h, --help                        Show this help`);
+    return;
+  }
+
   const skillName = values.skill ?? "selftune";
   const sanitizationLevel = values.sanitize === "aggressive" ? "aggressive" : "conservative";
 
@@ -81,7 +109,7 @@ export async function cliMain(): Promise<void> {
   writeFileSync(outputPath, json, "utf-8");
 
   // 6. Summary
-  console.log(`Contribution bundle written to: ${outputPath}`);
+  console.log(`Community contribution bundle written to: ${outputPath}`);
   console.log(`  Queries:       ${bundle.positive_queries.length}`);
   console.log(`  Eval entries:  ${bundle.eval_entries.length}`);
   console.log(`  Sessions:      ${bundle.session_metrics.total_sessions}`);

package/cli/selftune/contribution-config.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import {
+  findInstalledSkillPath,
+  findRepositoryClaudeSkillDirs,
+  findRepositorySkillDirs,
+} from "./utils/skill-discovery.js";
+
+export interface CreatorContributionConfig {
+  version: 1;
+  creator_id: string;
+  skill_name: string;
+  config_path: string;
+  skill_path: string;
+  contribution: {
+    enabled: boolean;
+    signals: string[];
+    message?: string;
+    privacy_url?: string;
+  };
+}
+
+export interface CreatorContributionConfigInput {
+  creator_id: string;
+  skill_name: string;
+  skill_path: string;
+  signals: string[];
+  message?: string;
+  privacy_url?: string;
+}
+
+interface ParsedContributionConfig {
+  version?: unknown;
+  creator_id?: unknown;
+  skill_name?: unknown;
+  contribution?: {
+    enabled?: unknown;
+    signals?: unknown;
+    message?: unknown;
+    privacy_url?: unknown;
+  };
+}
+
+function getOverrideRoots(): string[] {
+  const raw = process.env.SELFTUNE_SKILL_DIRS;
+  if (!raw) return [];
+  return raw
+    .split(process.platform === "win32" ? ";" : ":")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function getContributionConfigSearchRoots(
+  cwd: string = process.cwd(),
+  homeDir: string = process.env.HOME ?? "",
+  codexHome: string = process.env.CODEX_HOME ?? join(homeDir, ".codex"),
+): string[] {
+  const overrideRoots = getOverrideRoots();
+  if (overrideRoots.length > 0) return overrideRoots;
+
+  const roots = [
+    ...findRepositorySkillDirs(cwd),
+    ...findRepositoryClaudeSkillDirs(cwd),
+    join(homeDir, ".agents", "skills"),
+    join(homeDir, ".claude", "skills"),
+    join(codexHome, "skills"),
+  ];
+
+  return [...new Set(roots)];
+}
+
+function normalizeContributionConfig(
+  raw: ParsedContributionConfig,
+  configPath: string,
+  skillPath: string,
+): CreatorContributionConfig | null {
+  const creatorId = typeof raw.creator_id === "string" ? raw.creator_id.trim() : "";
+  const skillName = typeof raw.skill_name === "string" ? raw.skill_name.trim() : "";
+  if (
+    raw.version !== 1 ||
+    !creatorId ||
+    !skillName ||
+    !raw.contribution ||
+    typeof raw.contribution !== "object" ||
+    raw.contribution.enabled !== true ||
+    !Array.isArray(raw.contribution.signals)
+  ) {
+    return null;
+  }
+
+  const signals = raw.contribution.signals
+    .filter((signal): signal is string => typeof signal === "string")
+    .map((signal) => signal.trim())
+    .filter(Boolean);
+  if (signals.length === 0) return null;
+
+  return {
+    version: 1,
+    creator_id: creatorId,
+    skill_name: skillName,
+    config_path: configPath,
+    skill_path: skillPath,
+    contribution: {
+      enabled: true,
+      signals: [...new Set(signals)],
+      message: typeof raw.contribution.message === "string" ? raw.contribution.message : undefined,
+      privacy_url:
+        typeof raw.contribution.privacy_url === "string" ? raw.contribution.privacy_url : undefined,
+    },
+  };
+}
+
+function readContributionConfig(skillDir: string): CreatorContributionConfig | null {
+  const skillPath = join(skillDir, "SKILL.md");
+  const configPath = join(skillDir, "selftune.contribute.json");
+  if (!existsSync(skillPath) || !existsSync(configPath)) return null;
+
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as ParsedContributionConfig;
+    return normalizeContributionConfig(parsed, configPath, skillPath);
+  } catch {
+    return null;
+  }
+}
+
+export function findCreatorContributionConfig(
+  skillName: string,
+  roots: string[] = getContributionConfigSearchRoots(),
+): CreatorContributionConfig | null {
+  return (
+    discoverCreatorContributionConfigs(roots).find((config) => config.skill_name === skillName) ??
+    null
+  );
+}
+
+export function resolveContributionSkillPath(
+  skillName: string,
+  explicitSkillPath?: string,
+  roots: string[] = getContributionConfigSearchRoots(),
+): string | null {
+  if (explicitSkillPath?.trim()) {
+    const trimmed = explicitSkillPath.trim();
+    if (trimmed.endsWith("SKILL.md")) return trimmed;
+    return join(trimmed, "SKILL.md");
+  }
+  return findInstalledSkillPath(skillName, roots) ?? null;
+}
+
+export function writeCreatorContributionConfig(
+  input: CreatorContributionConfigInput,
+): CreatorContributionConfig {
+  const normalized = normalizeContributionConfig(
+    {
+      version: 1,
+      creator_id: input.creator_id,
+      skill_name: input.skill_name,
+      contribution: {
+        enabled: true,
+        signals: input.signals,
+        message: input.message,
+        privacy_url: input.privacy_url,
+      },
+    },
+    join(dirname(input.skill_path), "selftune.contribute.json"),
+    input.skill_path,
+  );
+
+  if (!normalized) {
+    throw new Error("Invalid creator contribution config input");
+  }
+
+  writeFileSync(
+    normalized.config_path,
+    JSON.stringify(
+      {
+        version: normalized.version,
+        creator_id: normalized.creator_id,
+        skill_name: normalized.skill_name,
+        contribution: normalized.contribution,
+      },
+      null,
+      2,
+    ),
+    "utf-8",
+  );
+
+  return normalized;
+}
+
+export function removeCreatorContributionConfig(skillPath: string): boolean {
+  const configPath = join(dirname(skillPath), "selftune.contribute.json");
+  if (!existsSync(configPath)) return false;
+  rmSync(configPath, { force: true });
+  return true;
+}
+
+function scanSkillRoot(root: string): CreatorContributionConfig[] {
+  if (!existsSync(root)) return [];
+
+  const discovered: CreatorContributionConfig[] = [];
+  for (const entry of readdirSync(root)) {
+    const entryPath = join(root, entry);
+    try {
+      if (!statSync(entryPath).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    const direct = readContributionConfig(entryPath);
+    if (direct) {
+      discovered.push(direct);
+      continue;
+    }
+
+    try {
+      for (const nestedEntry of readdirSync(entryPath)) {
+        const nestedPath = join(entryPath, nestedEntry);
+        try {
+          if (!statSync(nestedPath).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+        const nested = readContributionConfig(nestedPath);
+        if (nested) discovered.push(nested);
+      }
+    } catch {
+      // Ignore unreadable nested skill registries.
+    }
+  }
+
+  return discovered;
+}
+
+export function discoverCreatorContributionConfigs(
+  roots: string[] = getContributionConfigSearchRoots(),
+): CreatorContributionConfig[] {
+  const bySkill = new Map<string, CreatorContributionConfig>();
+
+  for (const root of roots) {
+    for (const config of scanSkillRoot(root)) {
+      if (!bySkill.has(config.skill_name)) {
+        bySkill.set(config.skill_name, config);
+      }
+    }
+  }
+
+  return [...bySkill.values()].sort((a, b) => a.skill_name.localeCompare(b.skill_name));
+}

package/cli/selftune/contribution-relay.ts

@@ -0,0 +1,177 @@
+import type { Database } from "bun:sqlite";
+
+import { readAlphaIdentity } from "./alpha-identity.js";
+import { CONTRIBUTION_RELAY_ENDPOINT, SELFTUNE_CONFIG_PATH } from "./constants.js";
+import type { CreatorContributionRelayPayload } from "./contribution-signals.js";
+import {
+  markCreatorContributionFailed,
+  markCreatorContributionSending,
+  markCreatorContributionSent,
+  requeueFailedCreatorContributionSignals,
+  requeueSendingCreatorContributionSignals,
+} from "./contribution-staging.js";
+import {
+  getCreatorContributionRelayStats,
+  getPendingCreatorContributionRows,
+  type CreatorContributionRelayStats,
+} from "./localdb/queries.js";
+import { getSelftuneVersion } from "./utils/selftune-meta.js";
+
+export interface ContributionRelayUploadResult {
+  success: boolean;
+  errors: string[];
+  _status: number;
+}
+
+export interface FlushCreatorContributionSignalsOptions {
+  endpoint?: string;
+  apiKey?: string;
+  limit?: number;
+  dryRun?: boolean;
+  retryFailed?: boolean;
+}
+
+export interface FlushCreatorContributionSignalsResult {
+  endpoint: string;
+  attempted: number;
+  sent: number;
+  failed: number;
+  requeued: number;
+  retried_failed: number;
+  stats: CreatorContributionRelayStats;
+  dry_run: boolean;
+}
+
+function isAcceptedContributionResponse(
+  value: unknown,
+): value is { status: "accepted" | "duplicate" } {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return record.status === "accepted" || record.status === "duplicate";
+}
+
+export function resolveContributionRelayEndpoint(explicit?: string): string {
+  return explicit?.trim() || CONTRIBUTION_RELAY_ENDPOINT;
+}
+
+export function resolveContributionRelayApiKey(explicit?: string): string | null {
+  if (explicit?.trim()) return explicit.trim();
+  return readAlphaIdentity(SELFTUNE_CONFIG_PATH)?.api_key?.trim() || null;
+}
+
+export async function uploadContributionSignal(
+  payload: CreatorContributionRelayPayload,
+  endpoint: string,
+  apiKey: string,
+): Promise<ContributionRelayUploadResult> {
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": `selftune/${getSelftuneVersion()}`,
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (response.ok || response.status === 409) {
+      const body = await response.text();
+      if (!body.trim()) return { success: true, errors: [], _status: response.status };
+      try {
+        const parsed: unknown = JSON.parse(body);
+        if (isAcceptedContributionResponse(parsed)) {
+          return { success: true, errors: [], _status: response.status };
+        }
+      } catch {
+        // Empty or non-JSON success bodies are still acceptable here.
+      }
+      return { success: true, errors: [], _status: response.status };
+    }
+
+    const errorText = await response.text().catch(() => "unknown error");
+    return {
+      success: false,
+      errors: [`HTTP ${response.status}: ${errorText.slice(0, 200)}`],
+      _status: response.status,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      errors: [message],
+      _status: 0,
+    };
+  }
+}
+
+export async function flushCreatorContributionSignals(
+  db: Database,
+  options: FlushCreatorContributionSignalsOptions = {},
+): Promise<FlushCreatorContributionSignalsResult> {
+  const endpoint = resolveContributionRelayEndpoint(options.endpoint);
+  const limit = Math.max(1, options.limit ?? 50);
+
+  if (options.dryRun) {
+    const pendingRows = getPendingCreatorContributionRows(db, limit);
+    return {
+      endpoint,
+      attempted: pendingRows.length,
+      sent: 0,
+      failed: 0,
+      requeued: 0,
+      retried_failed: 0,
+      stats: getCreatorContributionRelayStats(db),
+      dry_run: true,
+    };
+  }
+
+  const requeued = requeueSendingCreatorContributionSignals(db);
+  const retriedFailed = options.retryFailed ? requeueFailedCreatorContributionSignals(db) : 0;
+  const pendingRows = getPendingCreatorContributionRows(db, limit);
+
+  const apiKey = resolveContributionRelayApiKey(options.apiKey);
+  if (!apiKey) {
+    throw new Error(
+      "Creator contribution relay upload requires a cloud API key. Run `selftune init --alpha` or pass --api-key.",
+    );
+  }
+
+  let sent = 0;
+  let failed = 0;
+
+  for (const row of pendingRows) {
+    if (!markCreatorContributionSending(db, row.id)) continue;
+
+    let payload: CreatorContributionRelayPayload;
+    try {
+      payload = JSON.parse(row.payload_json) as CreatorContributionRelayPayload;
+    } catch {
+      markCreatorContributionFailed(db, row.id, "Invalid staged creator contribution payload JSON");
+      failed += 1;
+      continue;
+    }
+
+    const result = await uploadContributionSignal(payload, endpoint, apiKey);
+    if (result.success) {
+      markCreatorContributionSent(db, row.id);
+      sent += 1;
+      continue;
+    }
+
+    markCreatorContributionFailed(db, row.id, result.errors.join("; "));
+    failed += 1;
+  }
+
+  return {
+    endpoint,
+    attempted: pendingRows.length,
+    sent,
+    failed,
+    requeued,
+    retried_failed: retriedFailed,
+    stats: getCreatorContributionRelayStats(db),
+    dry_run: false,
+  };
+}

package/cli/selftune/contribution-signals.ts

@@ -0,0 +1,219 @@
+import type { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { hostname } from "node:os";
+
+import { readAlphaIdentity } from "./alpha-identity.js";
+import { SELFTUNE_CONFIG_PATH } from "./constants.js";
+import type { CreatorContributionConfig } from "./contribution-config.js";
+import { queryGradingResults, queryTrustedSkillObservationRows } from "./localdb/queries.js";
+
+export type ContributionSignal = "trigger" | "grade" | "miss_category";
+
+export interface CreatorContributionRelayPayload {
+  version: 1;
+  signal_type: "skill_session";
+  relay_destination: string;
+  skill_hash: string;
+  user_cohort: string;
+  signals: {
+    triggered?: boolean;
+    invocation_type?: "explicit" | "implicit" | "contextual" | "missed";
+    execution_grade?: "A" | "B" | "C" | "F";
+    query_bucket?: string;
+    miss_detected?: boolean;
+  };
+  timestamp_bucket: string;
+  client_version: string;
+}
+
+export interface CreatorContributionSignalRecord {
+  skill_name: string;
+  creator_id: string;
+  source_key: string;
+  payload: CreatorContributionRelayPayload;
+}
+
+export interface ContributionSignalBuildOptions {
+  now?: Date;
+  clientVersion?: string;
+  cohortSeed?: string;
+}
+
+function gradeBucket(value: number): "A" | "B" | "C" | "F" {
+  if (value >= 0.9) return "A";
+  if (value >= 0.75) return "B";
+  if (value >= 0.5) return "C";
+  return "F";
+}
+
+function bucketWeek(date: Date): string {
+  const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const day = utc.getUTCDay() || 7;
+  utc.setUTCDate(utc.getUTCDate() + 4 - day);
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((utc.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+  return `${utc.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function resolveContributionCohortSeed(explicitSeed?: string): string {
+  if (explicitSeed?.trim()) return explicitSeed.trim();
+  const alphaIdentity = readAlphaIdentity(SELFTUNE_CONFIG_PATH);
+  return alphaIdentity?.cloud_user_id || alphaIdentity?.user_id || hostname() || "selftune-local";
+}
+
+export function buildContributionUserCohort(now: Date = new Date(), explicitSeed?: string): string {
+  const monthBucket = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
+  const basis = `${resolveContributionCohortSeed(explicitSeed)}:${monthBucket}`;
+  return `uc_sha256_${createHash("sha256").update(basis).digest("hex").slice(0, 12)}`;
+}
+
+export function classifyContributionQueryBucket(query: string | null | undefined): string {
+  const text = (query ?? "").toLowerCase();
+  if (!text) return "other";
+
+  const patterns: Array<[string, RegExp]> = [
+    ["comparison", /\b(compare|comparison|versus|vs\b|trade[- ]?off|which is better)\b/],
+    ["troubleshooting", /\b(debug|debugging|fix|broken|not working|issue|error|troubleshoot)\b/],
+    ["migration", /\b(migrate|migration|upgrade|move from|switch to|convert)\b/],
+    ["configuration", /\b(config|configure|configuration|setup|set up)\b/],
+    ["analysis", /\b(analyze|analysis|evaluate|assess|review)\b/],
+    ["search", /\b(search|find|lookup)\b/],
+    ["generation", /\b(generate|create|write|draft)\b/],
+    ["testing", /\b(test|testing|spec|assert|regression)\b/],
+    ["refactoring", /\b(refactor|cleanup|clean up|restructure)\b/],
+    ["documentation", /\b(doc|docs|documentation|readme)\b/],
+  ];
+
+  for (const [bucket, pattern] of patterns) {
+    if (pattern.test(text)) return bucket;
+  }
+  return "other";
+}
+
+function invocationType(
+  invocationMode: string | null,
+  triggered: number,
+): "explicit" | "implicit" | "contextual" | "missed" {
+  if (triggered === 0) return "missed";
+  if (invocationMode === "explicit") return "explicit";
+  if (invocationMode === "implicit" || invocationMode === "inferred") return "implicit";
+  return "contextual";
+}
+
+function normalizeContributionSkillIdentifier(skillName: string): string {
+  return skillName.trim().toLowerCase();
+}
+
+function buildContributionSkillHash(skillName: string): string {
+  return `sk_sha256_${createHash("sha256").update(normalizeContributionSkillIdentifier(skillName)).digest("hex").slice(0, 12)}`;
+}
+
+export function buildCreatorDirectedContributionSignals(
+  db: Database,
+  configs: CreatorContributionConfig[],
+  options: ContributionSignalBuildOptions = {},
+): CreatorContributionSignalRecord[] {
+  const bySkill = new Map(configs.map((config) => [config.skill_name, config]));
+  const gradingBySession = new Map<string, "A" | "B" | "C" | "F">();
+  for (const row of queryGradingResults(db)) {
+    const source = typeof row.mean_score === "number" ? row.mean_score : row.pass_rate;
+    if (typeof source === "number" && !gradingBySession.has(row.session_id)) {
+      gradingBySession.set(row.session_id, gradeBucket(source));
+    }
+  }
+
+  const cohort = buildContributionUserCohort(options.now ?? new Date(), options.cohortSeed);
+  const clientVersion = options.clientVersion ?? "local-preview";
+
+  return queryTrustedSkillObservationRows(db)
+    .filter((row) => bySkill.has(row.skill_name))
+    .map((row) => {
+      const config = bySkill.get(row.skill_name)!;
+      const signals: CreatorContributionRelayPayload["signals"] = {};
+      if (config.contribution.signals.includes("trigger")) {
+        signals.triggered = row.triggered === 1;
+        signals.invocation_type = invocationType(row.invocation_mode, row.triggered);
+        signals.miss_detected = row.triggered === 0;
+      }
+      if (config.contribution.signals.includes("grade")) {
+        const grade = gradingBySession.get(row.session_id);
+        if (grade) signals.execution_grade = grade;
+      }
+      if (config.contribution.signals.includes("miss_category")) {
+        signals.query_bucket = classifyContributionQueryBucket(row.query_text);
+      }
+
+      return {
+        skill_name: row.skill_name,
+        creator_id: config.creator_id,
+        source_key: createHash("sha256")
+          .update(
+            [
+              row.skill_name,
+              row.session_id,
+              row.occurred_at ?? "",
+              row.query_text,
+              String(row.triggered),
+              row.invocation_mode ?? "",
+            ].join("::"),
+          )
+          .digest("hex")
+          .slice(0, 16),
+        payload: {
+          version: 1 as const,
+          signal_type: "skill_session" as const,
+          relay_destination: config.creator_id,
+          skill_hash: buildContributionSkillHash(config.skill_name),
+          user_cohort: cohort,
+          signals,
+          timestamp_bucket: bucketWeek(
+            row.occurred_at ? new Date(row.occurred_at) : (options.now ?? new Date()),
+          ),
+          client_version: clientVersion,
+        },
+      };
+    });
+}
+
+export function buildContributionPreview(
+  db: Database,
+  config: CreatorContributionConfig,
+  options: ContributionSignalBuildOptions = {},
+): {
+  observedCount: number;
+  triggerRate: number | null;
+  missRate: number | null;
+  gradedSessions: number;
+  samplePayload: CreatorContributionRelayPayload;
+} {
+  const payloads = buildCreatorDirectedContributionSignals(db, [config], options);
+  const observedCount = payloads.length;
+  const triggeredCount = payloads.filter(
+    (record) => record.payload.signals.triggered === true,
+  ).length;
+  const missedCount = payloads.filter(
+    (record) => record.payload.signals.miss_detected === true,
+  ).length;
+  const gradedSessions = queryGradingResults(db).filter(
+    (row) => row.skill_name === config.skill_name,
+  ).length;
+
+  return {
+    observedCount,
+    triggerRate: observedCount > 0 ? Math.round((triggeredCount / observedCount) * 100) : null,
+    missRate: observedCount > 0 ? Math.round((missedCount / observedCount) * 100) : null,
+    gradedSessions,
+    samplePayload: payloads[0]?.payload ?? {
+      version: 1,
+      signal_type: "skill_session",
+      relay_destination: config.creator_id,
+      skill_hash: buildContributionSkillHash(config.skill_name),
+      user_cohort: buildContributionUserCohort(options.now ?? new Date(), options.cohortSeed),
+      signals: {
+        query_bucket: "other",
+      },
+      timestamp_bucket: bucketWeek(options.now ?? new Date()),
+      client_version: options.clientVersion ?? "local-preview",
+    },
+  };
+}