npm - selftune - Versions diffs - 0.2.5 → 0.2.8 - Mend

selftune 0.2.5 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/README.md +1 -0
package/apps/local-dashboard/dist/assets/index-Bk9vSHHd.js +15 -0
package/apps/local-dashboard/dist/assets/index-CRtLkBTi.css +1 -0
package/apps/local-dashboard/dist/assets/vendor-react-BQH_6WrG.js +60 -0
package/apps/local-dashboard/dist/assets/{vendor-table-B7VF2Ipl.js → vendor-table-dK1QMLq9.js} +1 -1
package/apps/local-dashboard/dist/assets/{vendor-ui-r2k_Ku_V.js → vendor-ui-CO2mrx6e.js} +60 -65
package/apps/local-dashboard/dist/index.html +5 -5
package/cli/selftune/activation-rules.ts +30 -9
package/cli/selftune/agent-guidance.ts +96 -0
package/cli/selftune/alpha-identity.ts +157 -0
package/cli/selftune/alpha-upload/build-payloads.ts +151 -0
package/cli/selftune/alpha-upload/client.ts +113 -0
package/cli/selftune/alpha-upload/flush.ts +191 -0
package/cli/selftune/alpha-upload/index.ts +194 -0
package/cli/selftune/alpha-upload/queue.ts +252 -0
package/cli/selftune/alpha-upload/stage-canonical.ts +242 -0
package/cli/selftune/alpha-upload-contract.ts +52 -0
package/cli/selftune/auth/device-code.ts +110 -0
package/cli/selftune/auto-update.ts +130 -0
package/cli/selftune/badge/badge.ts +19 -9
package/cli/selftune/canonical-export.ts +16 -3
package/cli/selftune/constants.ts +28 -8
package/cli/selftune/contribute/bundle.ts +32 -5
package/cli/selftune/dashboard-contract.ts +32 -1
package/cli/selftune/dashboard-server.ts +256 -692
package/cli/selftune/dashboard.ts +1 -1
package/cli/selftune/eval/baseline.ts +11 -7
package/cli/selftune/eval/hooks-to-evals.ts +27 -9
package/cli/selftune/eval/synthetic-evals.ts +54 -1
package/cli/selftune/evolution/audit.ts +24 -19
package/cli/selftune/evolution/constitutional.ts +176 -0
package/cli/selftune/evolution/evidence.ts +18 -13
package/cli/selftune/evolution/evolve-body.ts +104 -7
package/cli/selftune/evolution/evolve.ts +195 -22
package/cli/selftune/evolution/propose-body.ts +18 -1
package/cli/selftune/evolution/propose-description.ts +27 -2
package/cli/selftune/evolution/rollback.ts +11 -15
package/cli/selftune/export.ts +84 -0
package/cli/selftune/grading/auto-grade.ts +13 -4
package/cli/selftune/grading/grade-session.ts +16 -6
package/cli/selftune/hooks/evolution-guard.ts +26 -9
package/cli/selftune/hooks/prompt-log.ts +23 -9
package/cli/selftune/hooks/session-stop.ts +78 -15
package/cli/selftune/hooks/skill-eval.ts +189 -10
package/cli/selftune/index.ts +274 -2
package/cli/selftune/ingestors/claude-replay.ts +48 -21
package/cli/selftune/init.ts +249 -47
package/cli/selftune/last.ts +7 -7
package/cli/selftune/localdb/db.ts +90 -10
package/cli/selftune/localdb/direct-write.ts +531 -0
package/cli/selftune/localdb/materialize.ts +296 -42
package/cli/selftune/localdb/queries.ts +325 -32
package/cli/selftune/localdb/schema.ts +109 -0
package/cli/selftune/monitoring/watch.ts +26 -8
package/cli/selftune/normalization.ts +85 -15
package/cli/selftune/observability.ts +248 -2
package/cli/selftune/orchestrate.ts +165 -20
package/cli/selftune/quickstart.ts +34 -10
package/cli/selftune/repair/skill-usage.ts +12 -2
package/cli/selftune/routes/actions.ts +77 -0
package/cli/selftune/routes/badge.ts +66 -0
package/cli/selftune/routes/doctor.ts +12 -0
package/cli/selftune/routes/index.ts +14 -0
package/cli/selftune/routes/orchestrate-runs.ts +13 -0
package/cli/selftune/routes/overview.ts +14 -0
package/cli/selftune/routes/report.ts +293 -0
package/cli/selftune/routes/skill-report.ts +230 -0
package/cli/selftune/status.ts +203 -7
package/cli/selftune/sync.ts +13 -1
package/cli/selftune/types.ts +50 -0
package/cli/selftune/utils/jsonl.ts +58 -1
package/cli/selftune/utils/selftune-meta.ts +38 -0
package/cli/selftune/utils/skill-log.ts +30 -4
package/cli/selftune/utils/transcript.ts +15 -0
package/cli/selftune/workflows/workflows.ts +7 -6
package/package.json +11 -7
package/packages/telemetry-contract/fixtures/complete-push.ts +184 -0
package/packages/telemetry-contract/fixtures/evidence-only-push.ts +58 -0
package/packages/telemetry-contract/fixtures/golden.json +1 -0
package/packages/telemetry-contract/fixtures/index.ts +4 -0
package/packages/telemetry-contract/fixtures/partial-push-no-sessions.ts +40 -0
package/packages/telemetry-contract/fixtures/partial-push-unresolved-parents.ts +79 -0
package/packages/telemetry-contract/package.json +6 -1
package/packages/telemetry-contract/src/index.ts +1 -0
package/packages/telemetry-contract/src/schemas.ts +215 -0
package/packages/telemetry-contract/src/types.ts +3 -1
package/packages/telemetry-contract/src/validators.ts +3 -1
package/packages/telemetry-contract/tests/compatibility.test.ts +144 -0
package/packages/ui/package.json +4 -0
package/packages/ui/src/components/ActivityTimeline.tsx +61 -29
package/packages/ui/src/components/section-cards.tsx +31 -14
package/packages/ui/src/types.ts +1 -0
package/skill/SKILL.md +214 -174
package/skill/Workflows/AlphaUpload.md +45 -0
package/skill/Workflows/Baseline.md +18 -12
package/skill/Workflows/Composability.md +3 -3
package/skill/Workflows/Dashboard.md +44 -91
package/skill/Workflows/Doctor.md +93 -66
package/skill/Workflows/Evals.md +49 -40
package/skill/Workflows/Evolve.md +76 -28
package/skill/Workflows/EvolveBody.md +37 -38
package/skill/Workflows/Initialize.md +172 -26
package/skill/Workflows/Orchestrate.md +11 -2
package/skill/Workflows/Sync.md +23 -0
package/skill/Workflows/Watch.md +2 -5
package/skill/agents/diagnosis-analyst.md +163 -0
package/skill/agents/evolution-reviewer.md +149 -0
package/skill/agents/integration-guide.md +154 -0
package/skill/agents/pattern-analyst.md +149 -0
package/skill/assets/multi-skill-settings.json +1 -1
package/skill/assets/single-skill-settings.json +1 -1
package/skill/references/interactive-config.md +39 -0
package/skill/references/invocation-taxonomy.md +34 -0
package/skill/references/logs.md +9 -1
package/skill/references/setup-patterns.md +3 -3
package/skill/settings_snippet.json +1 -1
package/apps/local-dashboard/dist/assets/index-C75H1Q3n.css +0 -1
package/apps/local-dashboard/dist/assets/index-axE4kz3Q.js +0 -15
package/apps/local-dashboard/dist/assets/vendor-react-U7zYD9Rg.js +0 -60

package/apps/local-dashboard/dist/index.html CHANGED Viewed

@@ -5,11 +5,11 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>selftune — Dashboard</title>
   <link rel="icon" type="image/png" href="/favicon.png" />
-  <script type="module" crossorigin src="/assets/index-axE4kz3Q.js"></script>
-  <link rel="modulepreload" crossorigin href="/assets/vendor-react-U7zYD9Rg.js">
-  <link rel="modulepreload" crossorigin href="/assets/vendor-ui-r2k_Ku_V.js">
-  <link rel="modulepreload" crossorigin href="/assets/vendor-table-B7VF2Ipl.js">
-  <link rel="stylesheet" crossorigin href="/assets/index-C75H1Q3n.css">
+  <script type="module" crossorigin src="/assets/index-Bk9vSHHd.js"></script>
+  <link rel="modulepreload" crossorigin href="/assets/vendor-react-BQH_6WrG.js">
+  <link rel="modulepreload" crossorigin href="/assets/vendor-ui-CO2mrx6e.js">
+  <link rel="modulepreload" crossorigin href="/assets/vendor-table-dK1QMLq9.js">
+  <link rel="stylesheet" crossorigin href="/assets/index-CRtLkBTi.css">
 </head>
 <body>
   <div id="root"></div>

package/cli/selftune/activation-rules.ts CHANGED Viewed

@@ -9,6 +9,9 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { EVOLUTION_AUDIT_LOG, QUERY_LOG } from "./constants.js";
+import { getDb } from "./localdb/db.js";
+import { queryEvolutionAudit, queryQueryLog, querySkillUsageRecords } from "./localdb/queries.js";
 import type { ActivationContext, ActivationRule } from "./types.js";
 import { readJsonl } from "./utils/jsonl.js";
@@ -21,18 +24,32 @@ const postSessionDiagnostic: ActivationRule = {
   description: "Suggest `selftune last` when session has >2 unmatched queries",
   evaluate(ctx: ActivationContext): string | null {
     // Count queries for this session
-    const queries = readJsonl<{ session_id: string; query: string }>(ctx.query_log_path);
+    let queries: Array<{ session_id: string; query: string }>;
+    if (ctx.query_log_path === QUERY_LOG) {
+      const db = getDb();
+      queries = queryQueryLog(db) as Array<{ session_id: string; query: string }>;
+    } else {
+      queries = readJsonl<{ session_id: string; query: string }>(ctx.query_log_path);
+    }
     const sessionQueries = queries.filter((q) => q.session_id === ctx.session_id);
     if (sessionQueries.length === 0) return null;
     // Count skill usages for this session (skill log is in the same dir as query log)
     const skillLogPath = join(dirname(ctx.query_log_path), "skill_usage_log.jsonl");
-    const skillUsages = existsSync(skillLogPath)
-      ? readJsonl<{ session_id: string }>(skillLogPath).filter(
-          (s) => s.session_id === ctx.session_id,
-        )
-      : [];
+    let skillUsages: Array<{ session_id: string }>;
+    if (ctx.query_log_path === QUERY_LOG) {
+      const db = getDb();
+      skillUsages = (querySkillUsageRecords(db) as Array<{ session_id: string }>).filter(
+        (s) => s.session_id === ctx.session_id,
+      );
+    } else {
+      skillUsages = existsSync(skillLogPath)
+        ? readJsonl<{ session_id: string }>(skillLogPath).filter(
+            (s) => s.session_id === ctx.session_id,
+          )
+        : [];
+    }
     const unmatchedCount = sessionQueries.length - skillUsages.length;
@@ -94,9 +111,13 @@ const staleEvolution: ActivationRule = {
     const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
     // Check last evolution timestamp
-    const auditEntries = readJsonl<{ timestamp: string; action: string }>(
-      ctx.evolution_audit_log_path,
-    );
+    let auditEntries: Array<{ timestamp: string; action: string }>;
+    if (ctx.evolution_audit_log_path === EVOLUTION_AUDIT_LOG) {
+      const db = getDb();
+      auditEntries = queryEvolutionAudit(db) as Array<{ timestamp: string; action: string }>;
+    } else {
+      auditEntries = readJsonl<{ timestamp: string; action: string }>(ctx.evolution_audit_log_path);
+    }
     if (auditEntries.length === 0) {
       // No evolution has ever run — check for false negatives

package/cli/selftune/agent-guidance.ts ADDED Viewed

@@ -0,0 +1,96 @@
+import { getAlphaLinkState } from "./alpha-identity.js";
+import type { AgentCommandGuidance, AlphaIdentity, AlphaLinkState } from "./types.js";
+function emailArg(email?: string): string {
+  return email?.trim() ? email : "<email>";
+}
+function buildAlphaInitCommand(options?: {
+  email?: string;
+  includeKey?: boolean;
+  force?: boolean;
+}): string {
+  const parts = ["selftune", "init", "--alpha", "--alpha-email", emailArg(options?.email)];
+  if (options?.includeKey) {
+    parts.push("--alpha-key", "<st_live_key>");
+  }
+  if (options?.force) {
+    parts.push("--force");
+  }
+  return parts.join(" ");
+}
+function buildGuidance(
+  code: string,
+  message: string,
+  nextCommand: string,
+  blocking: boolean,
+  suggestedCommands: string[],
+): AgentCommandGuidance {
+  return {
+    code,
+    message,
+    next_command: nextCommand,
+    suggested_commands: suggestedCommands,
+    blocking,
+  };
+}
+export function getAlphaGuidanceForState(
+  state: AlphaLinkState,
+  options?: { email?: string },
+): AgentCommandGuidance {
+  switch (state) {
+    case "not_linked":
+      return buildGuidance(
+        "alpha_cloud_link_required",
+        "Alpha upload is not linked. Sign in to app.selftune.dev, enroll in alpha, mint an st_live_* credential, then store it locally.",
+        buildAlphaInitCommand({ email: options?.email, includeKey: true }),
+        true,
+        ["selftune status", "selftune doctor"],
+      );
+    case "linked_not_enrolled":
+      return buildGuidance(
+        "alpha_enrollment_incomplete",
+        "Cloud account is linked but alpha enrollment is incomplete. Finish enrollment in app.selftune.dev, then refresh the local credential.",
+        buildAlphaInitCommand({ email: options?.email, includeKey: true, force: true }),
+        true,
+        ["selftune status", "selftune doctor"],
+      );
+    case "enrolled_no_credential":
+      return buildGuidance(
+        "alpha_credential_required",
+        "Alpha enrollment exists, but the local upload credential is missing or invalid.",
+        buildAlphaInitCommand({ email: options?.email, includeKey: true, force: true }),
+        true,
+        ["selftune status", "selftune doctor"],
+      );
+    case "ready":
+      return buildGuidance(
+        "alpha_upload_ready",
+        "Alpha upload is configured and ready.",
+        "selftune alpha upload",
+        false,
+        ["selftune status", "selftune doctor"],
+      );
+  }
+}
+export function getAlphaGuidance(identity: AlphaIdentity | null): AgentCommandGuidance {
+  if (!identity) {
+    return getAlphaGuidanceForState("not_linked");
+  }
+  return getAlphaGuidanceForState(getAlphaLinkState(identity), { email: identity.email });
+}
+export function formatGuidanceLines(
+  guidance: AgentCommandGuidance,
+  options?: { indent?: string },
+): string[] {
+  const indent = options?.indent ?? "  ";
+  const lines = [`${indent}Next command:       ${guidance.next_command}`];
+  if (guidance.suggested_commands.length > 0) {
+    lines.push(`${indent}Suggested commands: ${guidance.suggested_commands.join(", ")}`);
+  }
+  return lines;
+}

package/cli/selftune/alpha-identity.ts ADDED Viewed

@@ -0,0 +1,157 @@
+/**
+ * Alpha program identity management — cached cloud identity model.
+ *
+ * Local config is a cache of cloud-linked identity, not the source of truth.
+ * The cloud_user_id field is the primary "linked" indicator. Legacy local-only
+ * identities (user_id without cloud_user_id) are detected by migrateLocalIdentity().
+ *
+ * Handles stable user identity generation, config persistence,
+ * and consent notice for the selftune alpha program.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { AlphaIdentity, AlphaLinkState, SelftuneConfig } from "./types.js";
+// ---------------------------------------------------------------------------
+// User ID generation
+// ---------------------------------------------------------------------------
+/** Generate a stable UUID for alpha user identity. */
+export function generateUserId(): string {
+  return randomUUID();
+}
+// ---------------------------------------------------------------------------
+// Config read/write helpers
+// ---------------------------------------------------------------------------
+/**
+ * Read the alpha identity block from the selftune config file.
+ * Returns null if config does not exist or has no alpha block.
+ */
+export function readAlphaIdentity(configPath: string): AlphaIdentity | null {
+  if (!existsSync(configPath)) return null;
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw) as SelftuneConfig;
+    return config.alpha ?? null;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Write the alpha identity block into the selftune config file.
+ * Reads existing config, merges the alpha block, and writes back.
+ * Creates parent directories if needed.
+ */
+export function writeAlphaIdentity(configPath: string, identity: AlphaIdentity): void {
+  let config: Record<string, unknown> = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Unable to update alpha identity: ${configPath} is not valid JSON (${message})`,
+      );
+    }
+  }
+  config.alpha = identity;
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Link state helper — cloud-first model
+// ---------------------------------------------------------------------------
+/** Check if an API key has the expected st_live_ or st_test_ prefix. */
+export function isValidApiKeyFormat(key: string): boolean {
+  return key.startsWith("st_live_") || key.startsWith("st_test_");
+}
+/**
+ * Derive the cloud link readiness state from an AlphaIdentity.
+ *
+ * State machine:
+ *   null                              -> "not_linked"
+ *   not enrolled, no cloud_user_id    -> "not_linked"
+ *   not enrolled, has cloud_user_id   -> "linked_not_enrolled"
+ *   enrolled, no valid api_key        -> "enrolled_no_credential"
+ *   enrolled, valid api_key           -> "ready"
+ *
+ * cloud_user_id enriches the identity (confirms cloud link) but is not a gate.
+ * The direct-key path (--alpha-key) sets api_key without cloud_user_id, and
+ * that is a valid "ready" state. cloud_user_id can be backfilled later.
+ */
+export function getAlphaLinkState(identity: AlphaIdentity | null): AlphaLinkState {
+  if (!identity) return "not_linked";
+  if (!identity.enrolled) return identity.cloud_user_id ? "linked_not_enrolled" : "not_linked";
+  if (!identity.api_key || !isValidApiKeyFormat(identity.api_key)) return "enrolled_no_credential";
+  // Enrolled + valid key = ready (cloud_user_id is bonus, not gate)
+  return "ready";
+}
+// ---------------------------------------------------------------------------
+// Migration helper
+// ---------------------------------------------------------------------------
+/**
+ * Detect legacy local-only alpha blocks and mark them as needing cloud link.
+ * A legacy identity has email + user_id but no cloud_user_id.
+ */
+export function migrateLocalIdentity(identity: AlphaIdentity): {
+  needsCloudLink: boolean;
+  identity: AlphaIdentity;
+} {
+  if (identity.cloud_user_id) {
+    return { needsCloudLink: false, identity };
+  }
+  // Legacy: has local user_id but no cloud link
+  return { needsCloudLink: true, identity };
+}
+// ---------------------------------------------------------------------------
+// Consent notice
+// ---------------------------------------------------------------------------
+export const ALPHA_CONSENT_NOTICE = `
+========================================
+  selftune Alpha Program
+========================================
+You are enrolling in the selftune alpha program.
+WHAT IS COLLECTED:
+  - Skill invocations and trigger metadata
+  - Session metadata (timestamps, tool counts, error counts)
+  - Evolution outcomes (proposals, pass rates, deployments)
+  - Raw user prompt/query text submitted during captured sessions
+WHAT IS NOT COLLECTED:
+  - File contents or source code
+  - Full transcript bodies beyond the captured prompt/query text
+  - Structured repository names or file paths as separate fields
+IMPORTANT:
+  Raw prompt/query text is uploaded unchanged for the friendly alpha cohort.
+  If your prompt includes repository names, file paths, or secrets, that text
+  may be included in the alpha data you choose to share.
+Your alpha identity (email, display name, and any upload API key)
+is stored locally in ~/.selftune/config.json and used for alpha coordination
+and authenticated uploads.
+TO UNENROLL:
+  selftune init --no-alpha
+========================================
+`;

package/cli/selftune/alpha-upload/build-payloads.ts ADDED Viewed

@@ -0,0 +1,151 @@
+/**
+ * V2 canonical push payload builder (staging-based).
+ *
+ * Reads from the canonical_upload_staging table using a single monotonic
+ * cursor (local_seq). Each staged row contains the full canonical record
+ * JSON, so no fields are dropped or hardcoded during payload construction.
+ *
+ * Evolution evidence rows (record_kind = "evolution_evidence") are separated
+ * and placed in the canonical.evolution_evidence array.
+ */
+import type { Database } from "bun:sqlite";
+import type { CanonicalRecord } from "@selftune/telemetry-contract";
+import { buildPushPayloadV2 } from "../canonical-export.js";
+import type { EvolutionEvidenceEntry } from "../types.js";
+// -- Types --------------------------------------------------------------------
+export interface BuildV2Result {
+  payload: Record<string, unknown>;
+  lastSeq: number;
+}
+// -- Constants ----------------------------------------------------------------
+const DEFAULT_LIMIT = 500;
+// -- Helpers ------------------------------------------------------------------
+/** Parse a JSON string, returning null on failure. */
+function safeParseJson<T>(json: string | null): T | null {
+  if (!json) return null;
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return null;
+  }
+}
+// -- Main builder -------------------------------------------------------------
+/**
+ * Build a V2 canonical push payload from the staging table.
+ *
+ * Reads records from canonical_upload_staging WHERE local_seq > afterSeq,
+ * groups them by record_kind, and assembles a V2 push payload.
+ *
+ * Returns null when no new records exist after afterSeq.
+ */
+export function buildV2PushPayload(
+  db: Database,
+  afterSeq?: number,
+  limit: number = DEFAULT_LIMIT,
+): BuildV2Result | null {
+  const whereClause = afterSeq !== undefined ? "WHERE local_seq > ?" : "";
+  const params = afterSeq !== undefined ? [afterSeq, limit] : [limit];
+  const sql = `
+    SELECT local_seq, record_kind, record_json
+    FROM canonical_upload_staging
+    ${whereClause}
+    ORDER BY local_seq ASC
+    LIMIT ?
+  `;
+  const rows = db.query(sql).all(...params) as Array<{
+    local_seq: number;
+    record_kind: string;
+    record_json: string;
+  }>;
+  if (rows.length === 0) return null;
+  const canonicalRecords: CanonicalRecord[] = [];
+  const evidenceEntries: EvolutionEvidenceEntry[] = [];
+  const orchestrateRuns: Record<string, unknown>[] = [];
+  let lastParsedSeq: number | null = null;
+  let hitMalformedRow = false;
+  for (const row of rows) {
+    const parsed = safeParseJson<Record<string, unknown>>(row.record_json);
+    if (!parsed) {
+      hitMalformedRow = true;
+      break;
+    }
+    if (row.record_kind === "evolution_evidence") {
+      const timestamp =
+        typeof parsed.timestamp === "string" && parsed.timestamp.trim().length > 0
+          ? parsed.timestamp
+          : null;
+      const proposalId =
+        typeof parsed.proposal_id === "string" && parsed.proposal_id.trim().length > 0
+          ? parsed.proposal_id
+          : null;
+      if (!timestamp || !proposalId) {
+        hitMalformedRow = true;
+        break;
+      }
+      // Evolution evidence has its own shape
+      evidenceEntries.push({
+        timestamp,
+        proposal_id: proposalId,
+        skill_name: parsed.skill_name as string,
+        skill_path: (parsed.skill_path as string) ?? "",
+        target: (parsed.target as EvolutionEvidenceEntry["target"]) ?? "description",
+        stage: (parsed.stage as EvolutionEvidenceEntry["stage"]) ?? "created",
+        rationale: parsed.rationale as string | undefined,
+        confidence: parsed.confidence as number | undefined,
+        details: parsed.details as string | undefined,
+        original_text: parsed.original_text as string | undefined,
+        proposed_text: parsed.proposed_text as string | undefined,
+        eval_set: parsed.eval_set_json as EvolutionEvidenceEntry["eval_set"],
+        validation: parsed.validation_json as EvolutionEvidenceEntry["validation"],
+        evidence_id: parsed.evidence_id as string | undefined,
+      });
+    } else if (row.record_kind === "orchestrate_run") {
+      // Orchestrate run records -- pass through as-is
+      orchestrateRuns.push(parsed);
+    } else {
+      // Canonical telemetry records -- pass through as-is
+      canonicalRecords.push(parsed as unknown as CanonicalRecord);
+    }
+    lastParsedSeq = row.local_seq;
+  }
+  // If nothing parsed successfully, return null
+  if (
+    canonicalRecords.length === 0 &&
+    evidenceEntries.length === 0 &&
+    orchestrateRuns.length === 0
+  ) {
+    return null;
+  }
+  const payload = buildPushPayloadV2(canonicalRecords, evidenceEntries, orchestrateRuns);
+  if (lastParsedSeq === null) {
+    return null;
+  }
+  const lastSeq = lastParsedSeq;
+  if (hitMalformedRow && (process.env.DEBUG || process.env.NODE_ENV === "development")) {
+    console.error(
+      "[alpha-upload/build-payloads] encountered malformed staged row; cursor held at last valid seq",
+    );
+  }
+  return { payload, lastSeq };
+}

package/cli/selftune/alpha-upload/client.ts ADDED Viewed

@@ -0,0 +1,113 @@
+/**
+ * Alpha upload HTTP client.
+ *
+ * POSTs V2 canonical push payloads to the cloud API's POST /api/v1/push.
+ * Uses native fetch (Bun built-in). Never throws -- returns a
+ * PushUploadResult indicating success or failure.
+ */
+import type { PushUploadResult } from "../alpha-upload-contract.js";
+import { getSelftuneVersion } from "../utils/selftune-meta.js";
+function isPushUploadResult(value: unknown): value is PushUploadResult {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.success === "boolean" &&
+    Array.isArray(record.errors) &&
+    record.errors.every((entry) => typeof entry === "string") &&
+    (record.push_id === undefined || typeof record.push_id === "string") &&
+    (record._status === undefined || typeof record._status === "number")
+  );
+}
+function isAcceptedPushResponse(value: unknown): value is { status: "accepted"; push_id: string } {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return record.status === "accepted" && typeof record.push_id === "string";
+}
+/**
+ * Upload a single V2 push payload to the given endpoint.
+ *
+ * Returns a typed result. Never throws -- network errors and HTTP
+ * failures are captured in the result.
+ */
+export async function uploadPushPayload(
+  payload: Record<string, unknown>,
+  endpoint: string,
+  apiKey?: string,
+): Promise<PushUploadResult> {
+  try {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "User-Agent": `selftune/${getSelftuneVersion()}`,
+    };
+    if (apiKey) {
+      headers.Authorization = `Bearer ${apiKey}`;
+    }
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (response.ok) {
+      // Read body as text first — Bun consumes the stream on .json(),
+      // so a failed .json() followed by .text() would throw.
+      const body = await response.text();
+      if (body.length === 0) {
+        return {
+          success: true,
+          push_id: (payload as { push_id?: string }).push_id,
+          errors: [],
+          _status: response.status,
+        };
+      }
+      try {
+        const parsed: unknown = JSON.parse(body);
+        if (isPushUploadResult(parsed)) {
+          return { ...parsed, _status: parsed._status ?? response.status };
+        }
+        if (isAcceptedPushResponse(parsed)) {
+          return {
+            success: true,
+            push_id: parsed.push_id,
+            errors: [],
+            _status: response.status,
+          };
+        }
+        return {
+          success: false,
+          errors: ["Invalid JSON response shape for PushUploadResult"],
+          _status: response.status,
+        };
+      } catch {
+        return {
+          success: false,
+          errors: [`Unexpected non-JSON response body: ${body.slice(0, 200)}`],
+          _status: response.status,
+        };
+      }
+    }
+    // Non-2xx response -- read error text for diagnostics
+    const errorText = await response.text().catch(() => "unknown error");
+    return {
+      success: false,
+      errors: [`HTTP ${response.status}: ${errorText.slice(0, 200)}`],
+      _status: response.status,
+    };
+  } catch (err) {
+    // Network-level failure (DNS, timeout, connection refused, etc.)
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      errors: [message],
+      _status: 0,
+    };
+  }
+}