selftune 0.1.4 → 0.2.1

package/cli/selftune/workflows/workflows.ts

@@ -0,0 +1,188 @@
+/**
+ * workflows.ts
+ *
+ * CLI entry point and formatter for multi-skill workflow discovery and management.
+ *
+ * Exports:
+ *  - formatWorkflows()  (pure formatter, deterministic)
+ *  - cliMain()          (reads logs, discovers workflows, prints output or saves)
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { TELEMETRY_LOG } from "../constants.js";
+import type {
+  CodifiedWorkflow,
+  SessionTelemetryRecord,
+  WorkflowDiscoveryReport,
+} from "../types.js";
+import { readJsonl } from "../utils/jsonl.js";
+import { readEffectiveSkillUsageRecords } from "../utils/skill-log.js";
+import { discoverWorkflows } from "./discover.js";
+import { appendWorkflow } from "./skill-md-writer.js";
+
+// ---------------------------------------------------------------------------
+// formatWorkflows — pure formatter
+// ---------------------------------------------------------------------------
+
+export function formatWorkflows(report: WorkflowDiscoveryReport): string {
+  if (report.workflows.length === 0) {
+    return "No workflows discovered.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`Discovered Workflows (from ${report.total_sessions_analyzed} sessions):`);
+  lines.push("");
+
+  for (let i = 0; i < report.workflows.length; i++) {
+    const wf = report.workflows[i];
+    const chain = wf.skills.join(" \u2192 ");
+    const synergy = wf.synergy_score.toFixed(2);
+    const consistency = Math.round(wf.sequence_consistency * 100);
+    const completion = Math.round(wf.completion_rate * 100);
+
+    lines.push(`  ${i + 1}. ${chain}`);
+    lines.push(
+      `     Occurrences: ${wf.occurrence_count} | Synergy: ${synergy} | Consistency: ${consistency}% | Completion: ${completion}%`,
+    );
+    if (wf.representative_query) {
+      lines.push(`     Common trigger: "${wf.representative_query}"`);
+    }
+    if (i < report.workflows.length - 1) {
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// cliMain — reads logs, discovers workflows, prints or saves
+// ---------------------------------------------------------------------------
+
+export async function cliMain(): Promise<void> {
+  const { values, positionals } = parseArgs({
+    options: {
+      "min-occurrences": { type: "string" },
+      window: { type: "string" },
+      skill: { type: "string" },
+      "skill-path": { type: "string" },
+      json: { type: "boolean" },
+    },
+    strict: true,
+    allowPositionals: true,
+  });
+
+  const subcommand = positionals[0];
+  const minOccurrences = values["min-occurrences"]
+    ? Number.parseInt(values["min-occurrences"], 10)
+    : undefined;
+  if (minOccurrences !== undefined && (Number.isNaN(minOccurrences) || minOccurrences < 0)) {
+    console.error("[ERROR] --min-occurrences must be a non-negative integer.");
+    process.exit(1);
+  }
+  const window = values.window ? Number.parseInt(values.window, 10) : undefined;
+  if (window !== undefined && (Number.isNaN(window) || window < 0)) {
+    console.error("[ERROR] --window must be a non-negative integer.");
+    process.exit(1);
+  }
+
+  // Read telemetry and skill usage logs
+  const telemetry = readJsonl<SessionTelemetryRecord>(TELEMETRY_LOG);
+  const usage = readEffectiveSkillUsageRecords();
+
+  // Discover workflows
+  const report = discoverWorkflows(telemetry, usage, {
+    minOccurrences,
+    window,
+    skill: values.skill,
+  });
+
+  if (subcommand === "save") {
+    // Save subcommand: find workflow, append to SKILL.md
+    const nameArg = positionals[1];
+    if (!nameArg) {
+      console.error("[ERROR] Usage: selftune workflows save <name-or-index>");
+      process.exit(1);
+    }
+
+    // Match by numeric index (1-based) or workflow_id
+    let workflow = report.workflows.find((w) => w.workflow_id === nameArg);
+    if (!workflow) {
+      const idx = Number.parseInt(nameArg, 10);
+      if (!Number.isNaN(idx) && idx >= 1 && idx <= report.workflows.length) {
+        workflow = report.workflows[idx - 1];
+      }
+    }
+
+    if (!workflow) {
+      console.error(`[ERROR] No workflow found matching "${nameArg}".`);
+      console.error("Run 'selftune workflows' to see discovered workflows and their indices.");
+      process.exit(1);
+    }
+
+    // Determine SKILL.md path
+    let skillPath = values["skill-path"];
+    if (!skillPath) {
+      // Filter usage records to only sessions that contributed to this workflow
+      const sessionSet = new Set(workflow.session_ids);
+      const firstSkill = workflow.skills[0];
+      const matchingRecords = usage.filter(
+        (u) => u.skill_name === firstSkill && sessionSet.has(u.session_id),
+      );
+
+      // Collect unique skill_paths from matching records
+      const uniquePaths = [...new Set(matchingRecords.map((r) => r.skill_path))];
+
+      if (uniquePaths.length === 1) {
+        skillPath = uniquePaths[0];
+      } else if (uniquePaths.length > 1) {
+        // Ambiguous: multiple SKILL.md paths found across contributing sessions
+        console.error(`[ERROR] Multiple SKILL.md paths found for "${firstSkill}":`);
+        for (const p of uniquePaths) {
+          console.error(`  - ${p}`);
+        }
+        console.error("Use --skill-path to specify which one to update.");
+        process.exit(1);
+      }
+    }
+
+    if (!skillPath || !existsSync(skillPath)) {
+      console.error(`[ERROR] Could not determine SKILL.md path. Use --skill-path to specify.`);
+      process.exit(1);
+    }
+
+    // Build CodifiedWorkflow
+    const codified: CodifiedWorkflow = {
+      name: workflow.skills.join("-"),
+      skills: workflow.skills,
+      description: workflow.representative_query || undefined,
+      source: "discovered",
+      discovered_from: {
+        workflow_id: workflow.workflow_id,
+        occurrence_count: workflow.occurrence_count,
+        synergy_score: workflow.synergy_score,
+      },
+    };
+
+    // Read, append, write
+    const content = readFileSync(skillPath, "utf-8");
+    const updated = appendWorkflow(content, codified);
+
+    if (updated === content) {
+      console.log(`Workflow "${codified.name}" already exists in ${skillPath}`);
+    } else {
+      writeFileSync(skillPath, updated, "utf-8");
+      console.log(`Saved workflow "${codified.name}" to ${skillPath}`);
+    }
+
+    return;
+  }
+
+  // Default: discover and display
+  if (values.json || !process.stdout.isTTY) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatWorkflows(report));
+  }
+}

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "selftune",
-  "version": "0.1.4",
-  "description": "Skill observability and continuous improvement CLI for agent platforms",
+  "version": "0.2.1",
+  "description": "Self-improving skills CLI for AI agents",
   "type": "module",
   "license": "MIT",
   "author": "Daniel Petro",
-  "homepage": "https://github.com/WellDunDun/selftune#readme",
+  "homepage": "https://github.com/selftune-dev/selftune#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/WellDunDun/selftune.git"
+    "url": "git+https://github.com/selftune-dev/selftune.git"
   },
   "bugs": {
-    "url": "https://github.com/WellDunDun/selftune/issues"
+    "url": "https://github.com/selftune-dev/selftune/issues"
   },
   "funding": {
     "type": "github",
@@ -20,7 +20,7 @@
   "keywords": [
     "selftune",
     "skill",
-    "observability",
+    "self-improving",
     "claude-code",
     "codex",
     "opencode",
@@ -37,22 +37,39 @@
     "selftune": "bin/selftune.cjs"
   },
   "files": [
+    "assets/",
     "bin/",
     "cli/selftune/",
-    "dashboard/",
+    "apps/local-dashboard/dist/",
+    "packages/telemetry-contract/",
+    "templates/",
+    ".claude/agents/",
     "skill/",
     "README.md",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "lint": "bunx biome check .",
-    "lint:fix": "bunx biome check --write .",
+    "dev": "sh -c 'if lsof -iTCP:7888 -sTCP:LISTEN >/dev/null 2>&1; then if curl -fsS http://127.0.0.1:7888/api/health | grep -q selftune-dashboard; then echo \"Using existing dashboard server on 7888\"; cd apps/local-dashboard && bun install && bunx vite --strictPort; else echo \"Port 7888 is occupied by a non-selftune service\"; exit 1; fi; else cd apps/local-dashboard && bun install && bun run dev; fi'",
+    "dev:dashboard": "bun run cli/selftune/index.ts dashboard --port 7888 --no-open",
+    "lint": "bunx @biomejs/biome check .",
+    "lint:fix": "bunx @biomejs/biome check --write .",
     "lint:arch": "bun run lint-architecture.ts",
     "test": "bun test",
-    "check": "bun run lint && bun run lint:arch && bun test"
+    "test:fast": "bun test $(find tests -name '*.test.ts' ! -name 'evolve.test.ts' ! -name 'integration.test.ts' ! -name 'dashboard-server.test.ts' ! -path '*/blog-proof/*')",
+    "test:slow": "bun test tests/evolution/evolve.test.ts tests/evolution/integration.test.ts tests/monitoring/integration.test.ts tests/dashboard/dashboard-server.test.ts",
+    "build:dashboard": "cd apps/local-dashboard && bun install && bunx vite build",
+    "prepublishOnly": "bun run build:dashboard",
+    "check": "bun run lint && bun run lint:arch && bun test",
+    "start": "bun run cli/selftune/index.ts --help"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "dependencies": {
+    "@selftune/telemetry-contract": "workspace:*"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
+    "@biomejs/biome": "2.4.6",
     "@types/bun": "^1.1.0"
   }
 }

package/packages/telemetry-contract/README.md

@@ -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/packages/telemetry-contract/fixtures/golden.json

@@ -0,0 +1,87 @@
+[
+  {
+    "_description": "Minimal valid session record",
+    "record_kind": "session",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl" },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "started_at": "2026-01-15T11:50:00Z",
+    "ended_at": "2026-01-15T12:05:00Z",
+    "completion_status": "completed"
+  },
+  {
+    "_description": "Minimal valid prompt record",
+    "record_kind": "prompt",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl", "line": 3 },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "prompt_id": "golden-prompt-001",
+    "occurred_at": "2026-01-15T11:51:00Z",
+    "prompt_text": "Fix the login bug",
+    "prompt_kind": "user",
+    "is_actionable": true
+  },
+  {
+    "_description": "Minimal valid skill_invocation record",
+    "record_kind": "skill_invocation",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl", "line": 7 },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "skill_invocation_id": "golden-invocation-001",
+    "occurred_at": "2026-01-15T11:52:00Z",
+    "matched_prompt_id": "golden-prompt-001",
+    "skill_name": "commit",
+    "invocation_mode": "explicit",
+    "triggered": true,
+    "confidence": 1.0
+  },
+  {
+    "_description": "Minimal valid execution_fact record",
+    "record_kind": "execution_fact",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl", "line": 15 },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "occurred_at": "2026-01-15T12:04:00Z",
+    "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,
+    "completion_status": "completed"
+  },
+  {
+    "_description": "Minimal valid normalization_run record",
+    "record_kind": "normalization_run",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": {},
+    "run_id": "golden-run-001",
+    "run_at": "2026-01-15T12:00:00Z",
+    "raw_records_seen": 42,
+    "canonical_records_written": 38,
+    "repair_applied": false
+  }
+]

package/packages/telemetry-contract/fixtures/golden.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CANONICAL_SCHEMA_VERSION } from "../src/types.js";
+import { isCanonicalRecord } from "../src/validators.js";
+
+const fixtures = JSON.parse(
+  readFileSync(join(import.meta.dirname, "golden.json"), "utf-8"),
+) as Record<string, unknown>[];
+
+describe("golden fixtures", () => {
+  test("all fixtures pass isCanonicalRecord", () => {
+    for (const fixture of fixtures) {
+      const desc = fixture._description ?? fixture.record_kind;
+      const result = isCanonicalRecord(fixture);
+      if (!result) throw new Error(`Failed: ${desc}`);
+      expect(result).toBe(true);
+    }
+  });
+
+  test("all fixtures use current schema version", () => {
+    for (const fixture of fixtures) {
+      expect(fixture.schema_version).toBe(CANONICAL_SCHEMA_VERSION);
+    }
+  });
+
+  test("covers every record_kind", () => {
+    const kinds = new Set(fixtures.map((f) => f.record_kind));
+    expect(kinds).toContain("session");
+    expect(kinds).toContain("prompt");
+    expect(kinds).toContain("skill_invocation");
+    expect(kinds).toContain("execution_fact");
+    expect(kinds).toContain("normalization_run");
+  });
+
+  test("mutated fixtures fail validation", () => {
+    for (const fixture of fixtures) {
+      const bad = { ...fixture, schema_version: "0.0" };
+      expect(isCanonicalRecord(bad)).toBe(false);
+    }
+  });
+});

package/packages/telemetry-contract/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.js";

package/packages/telemetry-contract/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@selftune/telemetry-contract",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Canonical telemetry schema, types, and validators for selftune",
+  "type": "module",
+  "license": "MIT",
+  "author": "Daniel Petro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selftune-dev/selftune.git",
+    "directory": "packages/telemetry-contract"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./types": "./src/types.ts",
+    "./validators": "./src/validators.ts"
+  }
+}

package/packages/telemetry-contract/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./validators.js";

package/packages/telemetry-contract/src/types.ts

@@ -0,0 +1,163 @@
+export const CANONICAL_SCHEMA_VERSION = "2.0" as const;
+export type CanonicalSchemaVersion = typeof CANONICAL_SCHEMA_VERSION;
+
+export const CANONICAL_PLATFORMS = ["claude_code", "codex", "opencode", "openclaw"] as const;
+export type CanonicalPlatform = (typeof CANONICAL_PLATFORMS)[number];
+
+export const CANONICAL_CAPTURE_MODES = [
+  "hook",
+  "replay",
+  "wrapper",
+  "batch_ingest",
+  "repair",
+] as const;
+export type CanonicalCaptureMode = (typeof CANONICAL_CAPTURE_MODES)[number];
+
+export const CANONICAL_SOURCE_SESSION_KINDS = [
+  "interactive",
+  "replayed",
+  "synthetic",
+  "repaired",
+] as const;
+export type CanonicalSourceSessionKind = (typeof CANONICAL_SOURCE_SESSION_KINDS)[number];
+
+export const CANONICAL_PROMPT_KINDS = [
+  "user",
+  "continuation",
+  "task_notification",
+  "teammate_message",
+  "system_instruction",
+  "tool_output",
+  "meta",
+  "unknown",
+] as const;
+export type CanonicalPromptKind = (typeof CANONICAL_PROMPT_KINDS)[number];
+
+export const CANONICAL_INVOCATION_MODES = ["explicit", "implicit", "inferred", "repaired"] as const;
+export type CanonicalInvocationMode = (typeof CANONICAL_INVOCATION_MODES)[number];
+
+export const CANONICAL_COMPLETION_STATUSES = [
+  "completed",
+  "failed",
+  "interrupted",
+  "cancelled",
+  "unknown",
+] as const;
+export type CanonicalCompletionStatus = (typeof CANONICAL_COMPLETION_STATUSES)[number];
+
+export const CANONICAL_RECORD_KINDS = [
+  "session",
+  "prompt",
+  "skill_invocation",
+  "execution_fact",
+  "normalization_run",
+] as const;
+export type CanonicalRecordKind = (typeof CANONICAL_RECORD_KINDS)[number];
+
+export interface CanonicalRawSourceRef {
+  path?: string;
+  line?: number;
+  event_type?: string;
+  raw_id?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CanonicalRecordBase {
+  record_kind: CanonicalRecordKind;
+  schema_version: CanonicalSchemaVersion;
+  normalizer_version: string;
+  normalized_at: string;
+  platform: CanonicalPlatform;
+  capture_mode: CanonicalCaptureMode;
+  raw_source_ref: CanonicalRawSourceRef;
+}
+
+export interface CanonicalSessionRecordBase extends CanonicalRecordBase {
+  source_session_kind: CanonicalSourceSessionKind;
+  session_id: string;
+}
+
+export interface CanonicalSessionRecord extends CanonicalSessionRecordBase {
+  record_kind: "session";
+  started_at?: string;
+  ended_at?: string;
+  external_session_id?: string;
+  parent_session_id?: string;
+  agent_id?: string;
+  agent_type?: string;
+  agent_cli?: string;
+  session_key?: string;
+  channel?: string;
+  workspace_path?: string;
+  repo_root?: string;
+  repo_remote?: string;
+  branch?: string;
+  commit_sha?: string;
+  permission_mode?: string;
+  approval_policy?: string;
+  sandbox_policy?: string;
+  provider?: string;
+  model?: string;
+  completion_status?: CanonicalCompletionStatus;
+  end_reason?: string;
+}
+
+export interface CanonicalPromptRecord extends CanonicalSessionRecordBase {
+  record_kind: "prompt";
+  prompt_id: string;
+  occurred_at: string;
+  prompt_text: string;
+  prompt_hash?: string;
+  prompt_kind: CanonicalPromptKind;
+  is_actionable: boolean;
+  prompt_index?: number;
+  parent_prompt_id?: string;
+  source_message_id?: string;
+}
+
+export interface CanonicalSkillInvocationRecord extends CanonicalSessionRecordBase {
+  record_kind: "skill_invocation";
+  skill_invocation_id: string;
+  occurred_at: string;
+  matched_prompt_id?: string;
+  skill_name: string;
+  skill_path?: string;
+  skill_version_hash?: string;
+  invocation_mode: CanonicalInvocationMode;
+  triggered: boolean;
+  confidence: number;
+  tool_name?: string;
+  tool_call_id?: string;
+}
+
+export interface CanonicalExecutionFactRecord extends CanonicalSessionRecordBase {
+  record_kind: "execution_fact";
+  occurred_at: string;
+  prompt_id?: string;
+  tool_calls_json: Record<string, number>;
+  total_tool_calls: number;
+  bash_commands_redacted: string[];
+  assistant_turns: number;
+  errors_encountered: number;
+  input_tokens?: number;
+  output_tokens?: number;
+  duration_ms?: number;
+  completion_status?: CanonicalCompletionStatus;
+  end_reason?: string;
+}
+
+export interface CanonicalNormalizationRunRecord extends CanonicalRecordBase {
+  record_kind: "normalization_run";
+  run_id: string;
+  run_at: string;
+  raw_records_seen: number;
+  canonical_records_written: number;
+  repair_applied: boolean;
+}
+
+export type CanonicalRecord =
+  | CanonicalSessionRecord
+  | CanonicalPromptRecord
+  | CanonicalSkillInvocationRecord
+  | CanonicalExecutionFactRecord
+  | CanonicalNormalizationRunRecord;