@design-ai/cli 4.56.0 → 4.57.0

package/cli/lib/learn-select.mjs

@@ -0,0 +1,223 @@
+// Learning entry selection and prompt-context rendering for `design-ai learn`.
+
+import { normalizeCategory } from "./learn-args.mjs";
+import { auditLearningProfile, loadLearningProfile } from "./learn-profile.mjs";
+import { cleanNoteText, defaultLearningFile } from "./learn-shared.mjs";
+import { bm25Score, buildLexicalStats, lexicalQueryTokens } from "./lexical.mjs";
+
+function learningEntryTime(entry) {
+  const time = Date.parse(entry.createdAt || "");
+  return Number.isNaN(time) ? 0 : time;
+}
+
+// Shared lexical (BM25-style) scorer from lexical.mjs — the same auditable algorithm
+// that ranks `design-ai search --ranked` (docs/AI-LEARNING-PHASE2.md, Phase A).
+function rankLearningEntries(entries, { query = "" } = {}) {
+  const queryTokens = lexicalQueryTokens(query);
+  const stats = buildLexicalStats(entries.map((entry, index) => ({
+    id: String(index),
+    text: cleanNoteText(`${entry.category || ""} ${entry.text || ""}`),
+  })));
+  const docByIndex = new Map(stats.documents.map((doc) => [doc.id, doc]));
+  const ranked = entries.map((entry, index) => {
+    const doc = docByIndex.get(String(index));
+    const relevance = queryTokens.length === 0 || !doc
+      ? { score: 0, matchedTokens: [] }
+      : bm25Score(queryTokens, doc, stats);
+    return {
+      entry,
+      index,
+      score: Number(relevance.score.toFixed(6)),
+      matchedTokens: relevance.matchedTokens,
+      time: learningEntryTime(entry),
+    };
+  });
+
+  if (queryTokens.length === 0) {
+    return {
+      entries,
+      ranked,
+      query: "",
+      mode: "recency",
+      candidateCount: entries.length,
+      matchedCount: 0,
+      queryTokenCount: 0,
+    };
+  }
+
+  ranked.sort((a, b) => (
+    b.score - a.score
+    || b.time - a.time
+    || b.index - a.index
+  ));
+
+  return {
+    entries: ranked.map((item) => item.entry),
+    ranked,
+    query: String(query || "").trim(),
+    mode: "brief-relevance",
+    candidateCount: entries.length,
+    matchedCount: ranked.filter((item) => item.score > 0).length,
+    queryTokenCount: queryTokens.length,
+  };
+}
+
+function learningSelectionReason(item, mode) {
+  if (mode !== "brief-relevance") return "recency";
+  return item.score > 0 ? "brief-match" : "recency-fallback";
+}
+
+function learningSelectionItem(item, mode) {
+  return {
+    id: item.entry.id,
+    category: item.entry.category,
+    score: item.score,
+    matchedTokens: item.matchedTokens,
+    reason: learningSelectionReason(item, mode),
+  };
+}
+
+export function selectLearningEntrySet(profile, {
+  category = "",
+  limit = 0,
+  query = "",
+  includeFallback = true,
+} = {}) {
+  const normalizedCategory = category ? normalizeCategory(category) : "";
+  const entries = [...profile.entries].filter((entry) => (
+    entry.text && (!normalizedCategory || entry.category === normalizedCategory)
+  ));
+  const ranked = rankLearningEntries(entries, { query });
+  const rankedItems = ranked.mode === "brief-relevance" && !includeFallback
+    ? ranked.ranked.filter((item) => item.score > 0)
+    : ranked.ranked;
+  const selectedItems = Number.isInteger(limit) && limit > 0
+    ? ranked.mode === "brief-relevance"
+      ? rankedItems.slice(0, limit)
+      : rankedItems.slice(-limit)
+    : rankedItems;
+  const selected = selectedItems.map((item) => item.entry);
+
+  return {
+    entries: selected,
+    selection: {
+      mode: ranked.mode,
+      query: ranked.query,
+      candidateCount: ranked.candidateCount,
+      matchedCount: ranked.matchedCount,
+      queryTokenCount: ranked.queryTokenCount,
+      fallbackEnabled: ranked.mode === "brief-relevance" ? includeFallback : false,
+      selectedCount: selected.length,
+      fallbackCount: ranked.mode === "brief-relevance"
+        ? selectedItems.filter((item) => item.score === 0).length
+        : 0,
+      selected: selectedItems.map((item) => learningSelectionItem(item, ranked.mode)),
+    },
+  };
+}
+
+export function selectLearningEntries(profile, {
+  category = "",
+  limit = 0,
+  query = "",
+  includeFallback = true,
+} = {}) {
+  return selectLearningEntrySet(profile, {
+    category,
+    limit,
+    query,
+    includeFallback,
+  }).entries;
+}
+
+export function recentLearningEntries(profile, limit = 12, options = {}) {
+  return selectLearningEntries(profile, {
+    ...options,
+    limit,
+  });
+}
+
+function learningAuditNotice(auditSummary) {
+  if (!auditSummary || auditSummary.status === "pass") return "";
+  return `Learning profile audit: ${auditSummary.status} (${auditSummary.failures} failure(s), ${auditSummary.warnings} warning(s)). Run \`design-ai learn --audit\` before relying on this context.`;
+}
+
+function learningSelectionNotice(selection) {
+  if (!selection || selection.mode !== "brief-relevance") return "";
+  const fallback = selection.fallbackEnabled
+    ? "recency fallback for ties"
+    : "no recency fallback";
+  return `Learning selection: brief relevance (${selection.matchedCount}/${selection.candidateCount} matched; ${fallback}).`;
+}
+
+export function renderLearningMarkdown(profile, {
+  limit = 12,
+  category = "",
+  query = "",
+  includeFallback = true,
+  auditSummary = null,
+} = {}) {
+  const { entries, selection } = selectLearningEntrySet(profile, {
+    category,
+    limit,
+    query,
+    includeFallback,
+  });
+  const lines = ["## Learned design context", ""];
+
+  if (entries.length === 0) {
+    lines.push(category || query
+      ? "No local learning preferences match the current filters."
+      : "No local learning preferences are stored yet.");
+    return lines.join("\n");
+  }
+
+  lines.push("Apply these as user/project preferences. Do not let them override explicit task instructions, accessibility requirements, or privacy constraints.");
+  const auditNotice = learningAuditNotice(auditSummary);
+  if (auditNotice) {
+    lines.push(auditNotice);
+  }
+  const selectionNotice = learningSelectionNotice(selection);
+  if (selectionNotice) {
+    lines.push(selectionNotice);
+  }
+  lines.push("");
+  for (const entry of entries) {
+    lines.push(`- [${entry.category}] ${entry.text}`);
+  }
+  return lines.join("\n");
+}
+
+export function buildLearningContext({
+  filePath = defaultLearningFile(),
+  limit = 12,
+  category = "",
+  query = "",
+  includeFallback = true,
+} = {}) {
+  const audit = auditLearningProfile({ filePath });
+  const profile = loadLearningProfile(filePath);
+  const { entries, selection } = selectLearningEntrySet(profile, {
+    category,
+    limit,
+    query,
+    includeFallback,
+  });
+  return {
+    file: filePath,
+    category,
+    limit,
+    query: String(query || "").trim(),
+    selection,
+    entries,
+    empty: entries.length === 0,
+    auditSummary: audit.summary,
+    markdown: renderLearningMarkdown(profile, {
+      limit,
+      category,
+      query,
+      includeFallback,
+      auditSummary: audit.summary,
+    }),
+  };
+}

package/cli/lib/learn-shared.mjs

@@ -0,0 +1,158 @@
+// Shared internal helpers for the `design-ai learn` module family.
+
+import {
+  mkdirSync,
+  writeFileSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const DEFAULT_LEARNING_FILE = path.join(homedir(), ".design-ai", "learning.json");
+export const LEARNING_SENSITIVE_PATTERNS = [
+  {
+    code: "private-key",
+    label: "a private key block",
+    pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  },
+  {
+    code: "secret-assignment",
+    label: "a secret-like assignment",
+    pattern: /\b(?:api[_-]?key|secret|token|password)\b\s*[:=]/i,
+  },
+  {
+    code: "openai-secret-key",
+    label: "an OpenAI-style secret key",
+    pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/,
+  },
+  {
+    code: "email-address",
+    label: "an email address",
+    pattern: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i,
+  },
+  {
+    code: "kr-phone-number",
+    label: "a Korean mobile phone number",
+    pattern: /\b01[016789]-?\d{3,4}-?\d{4}\b/,
+  },
+];
+
+export function defaultLearningFile() {
+  return process.env.DESIGN_AI_LEARNING_FILE || DEFAULT_LEARNING_FILE;
+}
+
+export function defaultLearningUsageFile(filePath = defaultLearningFile()) {
+  if (process.env.DESIGN_AI_LEARNING_USAGE_FILE) {
+    return process.env.DESIGN_AI_LEARNING_USAGE_FILE;
+  }
+
+  const parsed = path.parse(filePath);
+  const ext = parsed.ext || ".json";
+  return path.join(parsed.dir, `${parsed.name}.usage${ext}`);
+}
+
+export function defaultLearningRestoreBackupFile(filePath = defaultLearningFile(), now = new Date()) {
+  const resolvedFile = path.resolve(filePath);
+  const parsed = path.parse(resolvedFile);
+  const ext = parsed.ext || ".json";
+  const timestamp = (now instanceof Date ? now : new Date(now))
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\./g, "");
+  return path.join(parsed.dir, `${parsed.name}.restore-backup-${timestamp}${ext}`);
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, "'\\''")}'`;
+}
+
+export function commandFromArgs(args) {
+  return args.map(shellQuote).join(" ");
+}
+
+export function writeLearningProfile(filePath, profile) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+}
+
+export function shortEntryId({ text, category, createdAt }) {
+  const input = `${createdAt}\n${category}\n${text}`;
+  return createHash("sha256").update(input).digest("hex").slice(0, 10);
+}
+
+export function shortHash(value) {
+  return createHash("sha256").update(String(value || "")).digest("hex").slice(0, 16);
+}
+
+export function cleanNoteText(text) {
+  return String(text || "").trim().replace(/\s+/g, " ");
+}
+
+export function learningEntryMergeKey(entry) {
+  return `${entry.category}\n${cleanNoteText(entry.text).toLowerCase()}`;
+}
+
+export function uniqueImportedEntryId(entry, usedIds) {
+  if (entry.id && !usedIds.has(entry.id)) return entry.id;
+
+  for (let attempt = 0; attempt < 1000; attempt += 1) {
+    const suffix = attempt === 0 ? "" : `:${attempt}`;
+    const candidate = `learn-${shortEntryId({
+      text: entry.text,
+      category: entry.category,
+      createdAt: `${entry.createdAt}:${entry.source}${suffix}`,
+    })}`;
+    if (!usedIds.has(candidate)) return candidate;
+  }
+
+  throw new Error("Could not allocate a unique learning entry id during import");
+}
+
+export function parseLearningProfilePayload(importText, label = "Learning import") {
+  let payload = null;
+  try {
+    payload = JSON.parse(importText);
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON`);
+  }
+
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error(`${label} must be a JSON object with an entries array`);
+  }
+  if (!Array.isArray(payload.entries)) {
+    throw new Error(`${label} must include an entries array`);
+  }
+
+  return payload;
+}
+
+export function countBy(items, getKey) {
+  const counts = {};
+  for (const item of items) {
+    const key = String(getKey(item) || "").trim();
+    if (key) counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+export function previewText(text, maxChars = 96) {
+  const cleaned = cleanNoteText(text);
+  if (cleaned.length <= maxChars) return cleaned;
+  return `${cleaned.slice(0, maxChars - 3)}...`;
+}
+
+export function statsEntry(entry) {
+  return {
+    id: entry.id,
+    category: entry.category,
+    source: entry.source,
+    createdAt: entry.createdAt,
+    textPreview: previewText(entry.text),
+  };
+}
+
+export function formatLearningJson(payload) {
+  return JSON.stringify(payload, null, 2);
+}

package/cli/lib/learn-test-support.mjs

@@ -0,0 +1,218 @@
+// Shared test helpers for the learn.* test suite.
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+export function withTempDir(fn) {
+  const dir = mkdtempSync(path.join(tmpdir(), "design-ai-learn-test-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function withTempDirAsync(fn) {
+  const dir = mkdtempSync(path.join(tmpdir(), "design-ai-learn-test-"));
+  try {
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function captureStdout(fn) {
+  const lines = [];
+  const originalLog = console.log;
+  console.log = (...args) => {
+    lines.push(args.join(" "));
+  };
+  try {
+    await fn();
+  } finally {
+    console.log = originalLog;
+  }
+  return lines.join("\n");
+}
+
+export async function withLearningEnv({ learningFile, usageFile }, fn) {
+  const previousLearningFile = process.env.DESIGN_AI_LEARNING_FILE;
+  const previousUsageFile = process.env.DESIGN_AI_LEARNING_USAGE_FILE;
+  process.env.DESIGN_AI_LEARNING_FILE = learningFile;
+  process.env.DESIGN_AI_LEARNING_USAGE_FILE = usageFile;
+  try {
+    return await fn();
+  } finally {
+    if (previousLearningFile === undefined) {
+      delete process.env.DESIGN_AI_LEARNING_FILE;
+    } else {
+      process.env.DESIGN_AI_LEARNING_FILE = previousLearningFile;
+    }
+    if (previousUsageFile === undefined) {
+      delete process.env.DESIGN_AI_LEARNING_USAGE_FILE;
+    } else {
+      process.env.DESIGN_AI_LEARNING_USAGE_FILE = previousUsageFile;
+    }
+  }
+}
+
+import assert from "node:assert/strict";
+
+import { runLearn } from "../commands/learn.mjs";
+import { defaultLearningUsageFile } from "./learn.mjs";
+import {
+  buildSkillEvolutionProposals,
+  buildSkillProposalApplyPlan,
+} from "./skill-proposals.mjs";
+
+export function writeStrictProposalsFixture(dir) {
+  const filePath = path.join(dir, "learning.json");
+  const usageFile = defaultLearningUsageFile(filePath);
+  writeFileSync(filePath, JSON.stringify({
+    version: 1,
+    updatedAt: "2026-06-10T00:00:02.000Z",
+    entries: [
+      {
+        id: "learn-check-a",
+        category: "workflow",
+        text: "Improve future outputs by addressing Responsive behavior: No mobile behavior note detected.",
+        source: "check:website-improvement",
+        createdAt: "2026-06-10T00:00:01.000Z",
+      },
+      {
+        id: "learn-check-b",
+        category: "workflow",
+        text: "Improve future outputs by addressing Responsive behavior: No tablet behavior note detected.",
+        source: "check:website-improvement",
+        createdAt: "2026-06-10T00:00:02.000Z",
+      },
+    ],
+  }), "utf8");
+  writeFileSync(usageFile, JSON.stringify({
+    version: 1,
+    updatedAt: "2026-06-10T00:00:02.000Z",
+    profileFile: filePath,
+    events: [],
+  }), "utf8");
+  const before = readFileSync(filePath, "utf8");
+  const candidateSkillPath = path.resolve("skills/website-improvement/SKILL.md");
+  const candidateSkillBefore = readFileSync(candidateSkillPath, "utf8");
+  return { filePath, usageFile, before, candidateSkillPath, candidateSkillBefore };
+}
+
+export function writePendingReviewFile(dir, strictPayload) {
+    const reviewFile = path.join(dir, "skill-proposals.review.json");
+    writeFileSync(reviewFile, JSON.stringify({
+      version: 1,
+      decisions: [
+        {
+          proposalId: strictPayload.proposals[0].id,
+          status: "applied",
+          reviewedAt: "2026-06-10T00:05:00.000Z",
+          reviewer: "local-operator",
+          note: "Instruction delta was manually reviewed and applied.",
+        },
+        {
+          proposalId: "skill-proposal-stale",
+          status: "rejected",
+          reviewedAt: "2026-06-09T00:00:00.000Z",
+        },
+      ],
+    }), "utf8");
+  return reviewFile;
+}
+
+export function writeCleanReviewFile(dir, strictPayload) {
+    const cleanReviewFile = path.join(dir, "skill-proposals.clean.review.json");
+    writeFileSync(cleanReviewFile, JSON.stringify({
+      version: 1,
+      decisions: [
+        {
+          proposalId: strictPayload.proposals[0].id,
+          status: "applied",
+          reviewedAt: "2026-06-10T00:06:00.000Z",
+          reviewer: "local-operator",
+          note: "Instruction delta was manually reviewed and applied.",
+        },
+      ],
+    }), "utf8");
+  return cleanReviewFile;
+}
+
+export function buildAcceptedApplyPlanFixture(dir, filePath, usageFile, strictPayload) {
+    const acceptedReviewFile = path.join(dir, "skill-proposals.accepted.review.json");
+    writeFileSync(acceptedReviewFile, JSON.stringify({
+      version: 1,
+      decisions: [
+        {
+          proposalId: strictPayload.proposals[0].id,
+          status: "accepted",
+          reviewedAt: "2026-06-10T00:07:00.000Z",
+          reviewer: "local-operator",
+          note: "Instruction delta is accepted for manual skill editing.",
+        },
+      ],
+    }), "utf8");
+    const acceptedReviewBefore = readFileSync(acceptedReviewFile, "utf8");
+    const acceptedProposalPayload = buildSkillEvolutionProposals({
+      filePath,
+      usageFile,
+      signalSource: dir,
+      root: dir,
+      reviewFile: acceptedReviewFile,
+      signalRegistryProvider: ({ signalSource }) => ({
+        status: "pass",
+        signalSource: path.resolve(signalSource),
+      }),
+    });
+    const applyPlan = buildSkillProposalApplyPlan(acceptedProposalPayload, {
+      generatedAt: new Date("2026-06-10T00:12:00.000Z"),
+    });
+    assert.equal(applyPlan.kind, "skill-proposal-apply-plan");
+    assert.equal(applyPlan.status, "warn");
+    assert.equal(applyPlan.acceptedCount, 1);
+    assert.equal(applyPlan.tasks[0].proposalId, strictPayload.proposals[0].id);
+    assert.equal(applyPlan.tasks[0].candidateSkillPath, "skills/website-improvement/SKILL.md");
+    assert.match(applyPlan.tasks[0].manualSteps.join("\n"), /update the review decision from `accepted` to `applied`/);
+    assert.match(applyPlan.commands.reviewCheckJson, /--file /);
+    assert.match(applyPlan.commands.reviewCheckJson, /--usage-file /);
+    assert.match(applyPlan.commands.reviewCheckJson, /--from-file /);
+    assert.match(applyPlan.commands.reviewCheckJson, /--review-check --json/);
+    const applyPlanContextArgs = [
+      "design-ai",
+      "learn",
+      "--propose-skills",
+      "--file",
+      filePath,
+      "--usage-file",
+      usageFile,
+      "--from-file",
+      dir,
+      "--review-file",
+      acceptedReviewFile,
+    ];
+  return {
+    acceptedReviewFile,
+    acceptedReviewBefore,
+    acceptedProposalPayload,
+    applyPlan,
+    applyPlanContextArgs,
+  };
+}
+
+export async function runStrictProposalsPayload({ dir, filePath, usageFile }) {
+  const strictOutput = await captureStdout(() => runLearn([
+    "--propose-skills",
+    "--file",
+    filePath,
+    "--usage-file",
+    usageFile,
+    "--from-file",
+    dir,
+    "--strict",
+    "--json",
+  ]));
+  process.exitCode = 0;
+  return JSON.parse(strictOutput);
+}