npm - selftune - Versions diffs - 0.2.10 → 0.2.13 - Mend

selftune 0.2.10 → 0.2.13

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 (733) hide show

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

@@ -5,11 +5,12 @@
     <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-BZVLv70T.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/vendor-react-BXP54cYo.js">
-    <link rel="modulepreload" crossorigin href="/assets/vendor-ui-CWU0d1wd.js">
-    <link rel="modulepreload" crossorigin href="/assets/vendor-table-DTF_SXoy.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-Bs3Y4ixf.css">
+    <script type="module" crossorigin src="/assets/index-4_dAY17K.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-Dw2cE7zH.js">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-react-CKkiCskZ.js">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-ui-7xD7fNEU.js">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-table-pHbDxq36.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-BxV5WZHc.css">
   </head>
   <body>
     <div id="root"></div>

package/cli/selftune/evolution/deploy-proposal.ts CHANGED Viewed

@@ -1,98 +1,18 @@
 /**
  * deploy-proposal.ts
  *
- * Deploys a validated evolution proposal by updating SKILL.md, creating a
- * backup, building a commit message with metrics, and optionally creating
- * a git branch and PR via `gh pr create`.
- */
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
-import type { EvolutionProposal, SkillSections } from "../types.js";
-import type { ValidationResult } from "./validate-proposal.js";
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-export interface DeployOptions {
-  proposal: EvolutionProposal;
-  validation: ValidationResult;
-  skillPath: string;
-  createPr: boolean;
-  branchPrefix?: string; // default "selftune/evolve"
-}
-export interface DeployResult {
-  skillMdUpdated: boolean;
-  backupPath: string | null;
-  branchName: string | null;
-  commitMessage: string;
-}
-// ---------------------------------------------------------------------------
-// SKILL.md reading
-// ---------------------------------------------------------------------------
-/** Read the contents of a SKILL.md file. Throws if the file does not exist. */
-export function readSkillMd(skillPath: string): string {
-  if (!existsSync(skillPath)) {
-    throw new Error(`SKILL.md not found at ${skillPath}`);
-  }
-  return readFileSync(skillPath, "utf-8");
-}
-// ---------------------------------------------------------------------------
-// Description replacement
-// ---------------------------------------------------------------------------
-/**
- * Replace the description section of a SKILL.md file.
+ * SKILL.md manipulation utilities for the evolution pipeline: description
+ * replacement, structured section parsing, section replacement, and full
+ * body replacement.
  *
- * The description is defined as the content between the first `#` heading
- * and the first `##` heading. If no `##` heading exists, the entire body
- * after the first heading is replaced.
+ * Evolution is a local personalization — the evolved description reflects how
+ * *this user* works, not a change the skill creator should adopt. A future
+ * upstream feedback channel (anonymized patterns, not raw descriptions) may
+ * let end-users send useful signal back to skill creators, but that's a
+ * separate concern from deploy. See TD-019 in tech-debt-tracker.md.
  */
-export function replaceDescription(currentContent: string, newDescription: string): string {
-  const lines = currentContent.split("\n");
-  // Find the first # heading line
-  let headingIndex = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith("# ") && !lines[i].startsWith("## ")) {
-      headingIndex = i;
-      break;
-    }
-  }
-  // If no heading found, just prepend the description
-  if (headingIndex === -1) {
-    return `${newDescription}\n${currentContent}`;
-  }
-  // Find the first ## heading after the main heading
-  let subHeadingIndex = -1;
-  for (let i = headingIndex + 1; i < lines.length; i++) {
-    if (lines[i].startsWith("## ")) {
-      subHeadingIndex = i;
-      break;
-    }
-  }
-  // Build the new content, preserving any preamble before the first heading
-  const preamble = headingIndex > 0 ? `${lines.slice(0, headingIndex).join("\n")}\n` : "";
-  const headingLine = lines[headingIndex];
-  const descriptionBlock = newDescription.length > 0 ? `\n${newDescription}\n` : "\n";
-  if (subHeadingIndex === -1) {
-    // No sub-heading: preamble + heading + new description + trailing newline
-    return `${preamble}${headingLine}\n${descriptionBlock}\n`;
-  }
-  // Preamble + heading + description + everything from the first ## onward
-  const afterSubHeading = lines.slice(subHeadingIndex).join("\n");
-  return `${preamble}${headingLine}\n${descriptionBlock}\n${afterSubHeading}`;
-}
+import type { SkillSections } from "../types.js";
 // ---------------------------------------------------------------------------
 // Structured SKILL.md parsing
@@ -234,153 +154,3 @@ export function replaceBody(currentContent: string, proposedBody: string): strin
   return `${parts.join("\n").trimEnd()}\n`;
 }
-// ---------------------------------------------------------------------------
-// Commit message builder
-// ---------------------------------------------------------------------------
-/** Build a commit message that includes the skill name and pass rate change. */
-export function buildCommitMessage(
-  proposal: EvolutionProposal,
-  validation: ValidationResult,
-): string {
-  const changePercent = Math.round(validation.net_change * 100);
-  const sign = changePercent >= 0 ? "+" : "";
-  const passRateStr = `${sign}${changePercent}% pass rate`;
-  return `evolve(${proposal.skill_name}): ${passRateStr}`;
-}
-// ---------------------------------------------------------------------------
-// Git/GH operations (PR creation)
-// ---------------------------------------------------------------------------
-/** Sanitize a string for use in a git branch name. */
-function sanitizeForGitRef(name: string): string {
-  return name
-    .replace(/[^a-zA-Z0-9._-]/g, "-")
-    .replace(/\.{2,}/g, ".")
-    .replace(/^[.-]|[.-]$/g, "")
-    .replace(/-{2,}/g, "-");
-}
-/** Generate a branch name from the prefix and skill name. */
-function makeBranchName(prefix: string, skillName: string): string {
-  const timestamp = Date.now();
-  const safeName = sanitizeForGitRef(skillName) || "untitled";
-  return `${prefix}/${safeName}-${timestamp}`;
-}
-/**
- * Run a git/gh command via Bun.spawn. Returns stdout on success.
- * Throws on non-zero exit code or if the command exceeds timeoutMs.
- */
-async function runCommand(args: string[], cwd?: string, timeoutMs = 30_000): Promise<string> {
-  const proc = Bun.spawn(args, {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  let timedOut = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    proc.kill();
-  }, timeoutMs);
-  try {
-    // Read stdout and stderr concurrently to avoid deadlock when both pipes fill.
-    const [stdout, stderr] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    const exitCode = await proc.exited;
-    if (timedOut) {
-      throw new Error(`Command timed out after ${timeoutMs}ms: ${args.join(" ")}`);
-    }
-    if (exitCode !== 0) {
-      throw new Error(`Command failed (exit ${exitCode}): ${args.join(" ")}\n${stderr}`);
-    }
-    return stdout.trim();
-  } finally {
-    clearTimeout(timer);
-  }
-}
-// ---------------------------------------------------------------------------
-// Main deploy function
-// ---------------------------------------------------------------------------
-/** Deploy a validated evolution proposal to SKILL.md and optionally create a PR. */
-export async function deployProposal(options: DeployOptions): Promise<DeployResult> {
-  const { proposal, validation, skillPath, createPr, branchPrefix = "selftune/evolve" } = options;
-  // Step 1: Read current SKILL.md
-  const currentContent = readSkillMd(skillPath);
-  // Step 2: Create backup (unique per deploy to avoid overwriting previous backups)
-  const backupTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const backupPath = `${skillPath}.${backupTimestamp}.bak`;
-  copyFileSync(skillPath, backupPath);
-  // Step 3: Replace description and write
-  const updatedContent = replaceDescription(currentContent, proposal.proposed_description);
-  writeFileSync(skillPath, updatedContent, "utf-8");
-  // Step 4: Build commit message
-  const commitMessage = buildCommitMessage(proposal, validation);
-  // Step 5: Optionally create branch and PR
-  let branchName: string | null = null;
-  if (createPr) {
-    branchName = makeBranchName(branchPrefix, proposal.skill_name);
-    try {
-      // Create and checkout branch
-      await runCommand(["git", "checkout", "-b", branchName]);
-      // Stage the SKILL.md
-      await runCommand(["git", "add", skillPath]);
-      // Commit
-      await runCommand(["git", "commit", "-m", commitMessage]);
-      // Push
-      await runCommand(["git", "push", "-u", "origin", branchName]);
-      // Create PR
-      await runCommand([
-        "gh",
-        "pr",
-        "create",
-        "--title",
-        commitMessage,
-        "--body",
-        `Proposal: ${proposal.proposal_id}\nRationale: ${proposal.rationale}\nNet change: ${validation.net_change > 0 ? "+" : ""}${Math.round(validation.net_change * 100)}%`,
-      ]);
-    } catch (err) {
-      // Git/GH operations are best-effort in test environments.
-      // The branch name is still returned for tracking.
-      console.error(`[WARN] Git/GH operation failed: ${err instanceof Error ? err.message : err}`);
-    }
-  }
-  return {
-    skillMdUpdated: true,
-    backupPath,
-    branchName,
-    commitMessage,
-  };
-}
-// ---------------------------------------------------------------------------
-// CLI entry guard
-// ---------------------------------------------------------------------------
-if (import.meta.main) {
-  console.log("deploy-proposal: use deployProposal() programmatically or via evolve CLI");
-}

package/cli/selftune/evolution/evolve.ts CHANGED Viewed

@@ -36,7 +36,7 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
-import { parseFrontmatter, replaceFrontmatterDescription } from "../utils/frontmatter.js";
+import { parseFrontmatter, replaceDescription } from "../utils/frontmatter.js";
 import { createEvolveTUI } from "../utils/tui.js";
 import { appendAuditEntry } from "./audit.js";
 import { checkConstitution } from "./constitutional.js";
@@ -958,11 +958,8 @@ export async function evolve(
       copyFileSync(skillPath, backupPath);
       tui.done(`Backup created at ${backupPath}`);
-      // Replace the frontmatter description
-      const updatedContent = replaceFrontmatterDescription(
-        rawContent,
-        lastProposal.proposed_description,
-      );
+      // Replace the description (handles both frontmatter and plain markdown)
+      const updatedContent = replaceDescription(rawContent, lastProposal.proposed_description);
       writeFileSync(skillPath, updatedContent, "utf-8");
       tui.done(`Deployed updated description to ${skillPath}`);

package/cli/selftune/evolution/rollback.ts CHANGED Viewed

@@ -13,8 +13,8 @@ import { parseArgs } from "node:util";
 import { updateContextAfterRollback } from "../memory/writer.js";
 import type { EvolutionAuditEntry } from "../types.js";
+import { replaceDescription } from "../utils/frontmatter.js";
 import { appendAuditEntry, getLastDeployedProposal, readAuditTrail } from "./audit.js";
-import { replaceDescription } from "./deploy-proposal.js";
 // ---------------------------------------------------------------------------
 // Types

package/cli/selftune/routes/report.ts CHANGED Viewed

@@ -180,7 +180,7 @@ function buildReportHTML(
       <tr><th>Metric</th><th>Value</th></tr>
       <tr><td>Total Skills</td><td>${statusResult.skills.length}</td></tr>
       <tr><td>Unmatched Queries</td><td>${statusResult.unmatchedQueries}</td></tr>
-      <tr><td>Pending Proposals</td><td>${statusResult.pendingProposals}</td></tr>
+      <tr><td>Undeployed Proposals</td><td>${statusResult.pendingProposals}</td></tr>
       <tr><td>Last Session</td><td>${escapeHtml(statusResult.lastSession ?? "\u2014")}</td></tr>
     </table>
   </div>

package/cli/selftune/routes/skill-report.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 /**
  * Route handler: GET /api/v2/skills/:name
  *
- * Returns SQLite-backed per-skill report with evolution audit, pending proposals,
+ * Returns SQLite-backed per-skill report with evolution audit, undeployed proposals,
  * invocation details, duration stats, selftune resource usage, prompt samples,
  * and session metadata.
  */

package/cli/selftune/status.ts CHANGED Viewed

@@ -324,7 +324,7 @@ export function formatStatus(result: StatusResult): string {
   // Summary stats
   lines.push(`Unmatched queries:  ${result.unmatchedQueries}`);
-  lines.push(`Pending proposals:  ${result.pendingProposals}`);
+  lines.push(`Undeployed proposals:  ${result.pendingProposals}`);
   // Last session
   if (result.lastSession) {

package/cli/selftune/utils/frontmatter.ts CHANGED Viewed

@@ -3,6 +3,8 @@
  *
  * Line-based YAML frontmatter parser for SKILL.md files.
  * Extracts name, description, and version without a YAML library.
+ * Also provides `replaceDescription` — the single public API for replacing
+ * a skill's description in SKILL.md (handles both frontmatter and plain markdown).
  */
 // ---------------------------------------------------------------------------
@@ -137,16 +139,57 @@ export function parseFrontmatter(content: string): SkillFrontmatter {
 // ---------------------------------------------------------------------------
 /**
- * Replace the `description:` field in YAML frontmatter, preserving all other
- * content. If the new description contains special YAML characters, it is
- * written as a folded scalar (`description: >`).
+ * Replace the description between the first `#` heading and the first `##`
+ * heading. If no `##` heading exists, the entire body after the heading is
+ * replaced. Used as fallback when no YAML frontmatter is present.
+ */
+function replaceMarkdownDescription(currentContent: string, newDescription: string): string {
+  const lines = currentContent.split("\n");
+  let headingIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("# ") && !lines[i].startsWith("## ")) {
+      headingIndex = i;
+      break;
+    }
+  }
+  if (headingIndex === -1) {
+    return `${newDescription}\n${currentContent}`;
+  }
+  let subHeadingIndex = -1;
+  for (let i = headingIndex + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      subHeadingIndex = i;
+      break;
+    }
+  }
+  const preamble = headingIndex > 0 ? `${lines.slice(0, headingIndex).join("\n")}\n` : "";
+  const headingLine = lines[headingIndex];
+  const descriptionBlock = newDescription.length > 0 ? `\n${newDescription}\n` : "\n";
+  if (subHeadingIndex === -1) {
+    return `${preamble}${headingLine}\n${descriptionBlock}\n`;
+  }
+  const afterSubHeading = lines.slice(subHeadingIndex).join("\n");
+  return `${preamble}${headingLine}\n${descriptionBlock}\n${afterSubHeading}`;
+}
+/**
+ * Replace a skill's description in SKILL.md.
  *
- * Returns the original content unchanged if no frontmatter is found.
+ * If the file has YAML frontmatter, replaces the `description:` field
+ * (using folded scalar for long/special-char descriptions).
+ * Otherwise, falls back to markdown heading-based replacement.
  */
-export function replaceFrontmatterDescription(content: string, newDescription: string): string {
+export function replaceDescription(content: string, newDescription: string): string {
   const lines = content.split("\n");
-  if (lines[0]?.trim() !== "---") return content;
+  // No frontmatter — fall back to markdown heading-based replacement
+  if (lines[0]?.trim() !== "---") return replaceMarkdownDescription(content, newDescription);
   let endIdx = -1;
   for (let i = 1; i < lines.length; i++) {
@@ -155,7 +198,7 @@ export function replaceFrontmatterDescription(content: string, newDescription: s
       break;
     }
   }
-  if (endIdx < 0) return content;
+  if (endIdx < 0) return replaceMarkdownDescription(content, newDescription);
   // Find and replace the description within frontmatter lines
   const yamlLines = lines.slice(1, endIdx);

package/node_modules/@selftune/telemetry-contract/README.md ADDED Viewed

@@ -0,0 +1,11 @@
+# @selftune/telemetry-contract
+Canonical telemetry contract shared between local CLI normalization and cloud ingestion.
+This package is intentionally small:
+- canonical enums
+- canonical record types
+- lightweight runtime guards
+It does not include adapter logic, projections, or product-specific analytics.

package/node_modules/@selftune/telemetry-contract/fixtures/complete-push.ts ADDED Viewed

@@ -0,0 +1,184 @@
+import type { PushPayloadV2 } from "../src/schemas.js";
+/**
+ * A valid PushPayloadV2 with at least one of every record type.
+ * All fields populated.
+ */
+export const completePush: PushPayloadV2 = {
+  schema_version: "2.0",
+  client_version: "0.9.0",
+  push_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  normalizer_version: "0.2.1",
+  canonical: {
+    sessions: [
+      {
+        record_kind: "session",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T10:00:00Z",
+        platform: "claude_code",
+        capture_mode: "hook",
+        raw_source_ref: { path: "/tmp/raw/session-100.jsonl" },
+        source_session_kind: "interactive",
+        session_id: "fix-session-100",
+        external_session_id: "ext-100",
+        agent_id: "agent-abc",
+        agent_type: "claude",
+        agent_cli: "claude-code",
+        session_key: "sk-100",
+        channel: "terminal",
+        workspace_path: "/home/user/project",
+        repo_root: "/home/user/project",
+        repo_remote: "git@github.com:user/project.git",
+        branch: "main",
+        commit_sha: "abc123def456",
+        permission_mode: "default",
+        approval_policy: "auto",
+        sandbox_policy: "lenient",
+        provider: "anthropic",
+        model: "claude-sonnet-4-20250514",
+        started_at: "2026-03-19T09:50:00Z",
+        ended_at: "2026-03-19T10:05:00Z",
+        completion_status: "completed",
+        end_reason: "user_exit",
+      },
+    ],
+    prompts: [
+      {
+        record_kind: "prompt",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T10:00:00Z",
+        platform: "claude_code",
+        capture_mode: "hook",
+        raw_source_ref: { path: "/tmp/raw/session-100.jsonl", line: 3 },
+        source_session_kind: "interactive",
+        session_id: "fix-session-100",
+        prompt_id: "fix-prompt-001",
+        occurred_at: "2026-03-19T09:51:00Z",
+        prompt_text: "Fix the authentication middleware",
+        prompt_hash: "sha256-abc123",
+        prompt_kind: "user",
+        is_actionable: true,
+        prompt_index: 0,
+      },
+    ],
+    skill_invocations: [
+      {
+        record_kind: "skill_invocation",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T10:00:00Z",
+        platform: "claude_code",
+        capture_mode: "hook",
+        raw_source_ref: { path: "/tmp/raw/session-100.jsonl", line: 7 },
+        source_session_kind: "interactive",
+        session_id: "fix-session-100",
+        skill_invocation_id: "fix-inv-001",
+        occurred_at: "2026-03-19T09:52:00Z",
+        matched_prompt_id: "fix-prompt-001",
+        skill_name: "auth-debug",
+        skill_path: "/home/user/.claude/skills/auth-debug/SKILL.md",
+        skill_version_hash: "v1-hash-xyz",
+        invocation_mode: "explicit",
+        triggered: true,
+        confidence: 0.95,
+        tool_name: "Read",
+        tool_call_id: "tc-001",
+        agent_type: "claude",
+      },
+    ],
+    execution_facts: [
+      {
+        record_kind: "execution_fact",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T10:00:00Z",
+        platform: "claude_code",
+        capture_mode: "hook",
+        raw_source_ref: { path: "/tmp/raw/session-100.jsonl", line: 15 },
+        source_session_kind: "interactive",
+        session_id: "fix-session-100",
+        execution_fact_id: "fix-ef-001",
+        occurred_at: "2026-03-19T10:04:00Z",
+        prompt_id: "fix-prompt-001",
+        tool_calls_json: { Read: 5, Edit: 3, Bash: 2 },
+        total_tool_calls: 10,
+        bash_commands_redacted: ["git status", "bun test"],
+        assistant_turns: 4,
+        errors_encountered: 0,
+        input_tokens: 12000,
+        output_tokens: 3500,
+        duration_ms: 45000,
+        completion_status: "completed",
+        end_reason: "natural",
+      },
+    ],
+    normalization_runs: [
+      {
+        record_kind: "normalization_run",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T10:00:00Z",
+        platform: "claude_code",
+        capture_mode: "hook",
+        raw_source_ref: {},
+        run_id: "fix-run-001",
+        run_at: "2026-03-19T10:00:00Z",
+        raw_records_seen: 42,
+        canonical_records_written: 38,
+        repair_applied: false,
+      },
+    ],
+    evolution_evidence: [
+      {
+        evidence_id: "ev_complete_authdebug_001",
+        skill_name: "auth-debug",
+        proposal_id: "prop-001",
+        target: "description",
+        stage: "proposed",
+        rationale: "Improved trigger for auth-related queries",
+        confidence: 0.82,
+        original_text: "Debug authentication issues",
+        proposed_text:
+          "Debug and fix authentication middleware, token validation, and session management issues",
+        raw_source_ref: { path: "/tmp/evolution/prop-001.json" },
+      },
+    ],
+    orchestrate_runs: [
+      {
+        run_id: "orch-001",
+        timestamp: "2026-03-19T10:10:00Z",
+        elapsed_ms: 12000,
+        dry_run: false,
+        approval_mode: "auto",
+        total_skills: 5,
+        evaluated: 4,
+        evolved: 1,
+        deployed: 1,
+        watched: 2,
+        skipped: 1,
+        skill_actions: [
+          {
+            skill: "auth-debug",
+            action: "evolve",
+            reason: "Pass rate below threshold",
+            deployed: true,
+            elapsed_ms: 8000,
+            llm_calls: 3,
+          },
+          {
+            skill: "commit",
+            action: "watch",
+            reason: "Recently deployed, monitoring",
+          },
+          {
+            skill: "test-runner",
+            action: "skip",
+            reason: "Insufficient data",
+          },
+        ],
+      },
+    ],
+  },
+};