oh-my-llmwikimode 1.0.0

package/src/wiki/lesson-proposal-manager.js

@@ -0,0 +1,331 @@
+/**
+ * B1 Auto Lesson Proposal — Proposal Manager
+ *
+ * Manages lesson proposal artifacts:
+ * - list proposals
+ * - get a specific proposal
+ * - apply a proposal (user-approved promotion to lesson)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getWikiPaths, ensureWikiStructure } from "./store.js";
+import { writeLessonTemplate, sanitizeYamlString } from "./lesson-template.js";
+import { PROPOSAL_DIR } from "./lesson-proposal-analyzer.js";
+
+function compareStrings(left, right) {
+  return String(left ?? "").localeCompare(String(right ?? ""));
+}
+
+function ensureProposalDir(wikiRoot) {
+  const dir = path.join(wikiRoot, PROPOSAL_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+const VALID_ID_RE = /^lp_[A-Za-z0-9_-]+$/;
+
+function isValidProposalId(id) {
+  return typeof id === "string" && VALID_ID_RE.test(id);
+}
+
+const ALLOWED_ENTRY_PREFIXES = ["inbox", "problems", "editorial/lessons"];
+
+/**
+ * Returns true only when targetPath is a descendant of basePath.
+ * Equality is rejected because callers expect a concrete entry path, not the root itself.
+ */
+function isStrictlyInsidePath(basePath, targetPath) {
+  const relative = path.relative(basePath, targetPath);
+  return (
+    relative !== "" &&
+    relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+/**
+ * Validates that an entry path is safe to read within the wiki root.
+ *
+ * Checks:
+ * - Path is a non-empty string
+ * - Path is relative (not absolute)
+ * - Path is within allowed directories (inbox/, problems/, editorial/lessons/)
+ * - Path stays within wiki root before and after symlink resolution
+ * - Path does not point to a symlink (only when the file exists)
+ *
+ * @param {string} wikiRoot - Absolute path to wiki root
+ * @param {string} entryPath - Relative entry path to validate
+ * @returns {{safe: boolean, error?: string, resolvedPath?: string}}
+ */
+function validateEntryPath(wikiRoot, entryPath) {
+  if (!entryPath || typeof entryPath !== "string") {
+    return { safe: false, error: "Entry path must be a non-empty string" };
+  }
+
+  if (path.isAbsolute(entryPath)) {
+    return { safe: false, error: `Entry path must be relative, got absolute: ${entryPath}` };
+  }
+
+  // Check allowed prefix first (before resolution, for clear error messages)
+  const normalizedEntry = entryPath.replace(/\\/g, "/");
+  const hasAllowedPrefix = ALLOWED_ENTRY_PREFIXES.some(
+    (prefix) => normalizedEntry === prefix || normalizedEntry.startsWith(prefix + "/")
+  );
+  if (!hasAllowedPrefix) {
+    return {
+      safe: false,
+      error: `Entry path must be within allowed directories (inbox, problems, editorial/lessons): ${entryPath}`,
+    };
+  }
+
+  const absoluteWikiRoot = path.resolve(wikiRoot);
+  const resolvedPath = path.resolve(absoluteWikiRoot, entryPath);
+
+  if (!isStrictlyInsidePath(absoluteWikiRoot, resolvedPath)) {
+    return { safe: false, error: `Entry path resolves outside wiki root before symlink resolution: ${entryPath}` };
+  }
+
+  let realWikiRoot;
+  try {
+    realWikiRoot = fs.realpathSync(absoluteWikiRoot);
+  } catch (error) {
+    return {
+      safe: false,
+      error: `Wiki root cannot be resolved safely: ${wikiRoot} (${error.message})`,
+    };
+  }
+
+  let realResolvedPath;
+  try {
+    realResolvedPath = fs.realpathSync(resolvedPath);
+  } catch (error) {
+    return {
+      safe: false,
+      error: `Entry path does not exist or cannot be resolved safely: ${entryPath} (${error.message})`,
+    };
+  }
+
+  if (!isStrictlyInsidePath(realWikiRoot, realResolvedPath)) {
+    return { safe: false, error: `Entry path resolves outside wiki root after symlink resolution: ${entryPath}` };
+  }
+
+  const realRelative = path.relative(realWikiRoot, realResolvedPath).replace(/\\/g, "/");
+  const hasAllowedRealPrefix = ALLOWED_ENTRY_PREFIXES.some(
+    (prefix) => realRelative === prefix || realRelative.startsWith(prefix + "/")
+  );
+  if (!hasAllowedRealPrefix) {
+    return {
+      safe: false,
+      error: `Entry path resolves outside allowed directories after symlink resolution: ${entryPath}`,
+    };
+  }
+
+  // Reject direct symlink entries. Parent symlink escapes are handled by realpath checks above.
+  try {
+    const stat = fs.lstatSync(resolvedPath);
+    if (stat.isSymbolicLink()) {
+      return { safe: false, error: `Entry path is a symlink, rejected for security: ${entryPath}` };
+    }
+  } catch (error) {
+    return {
+      safe: false,
+      error: `Entry path cannot be inspected safely: ${entryPath} (${error.message})`,
+    };
+  }
+
+  return { safe: true, resolvedPath: realResolvedPath };
+}
+
+
+/**
+ * List all lesson proposals.
+ */
+export function listProposals(wikiRoot) {
+  try {
+    const dir = path.join(wikiRoot, PROPOSAL_DIR);
+    if (!fs.existsSync(dir)) {
+      return { success: true, proposals: [], count: 0 };
+    }
+
+    const files = fs.readdirSync(dir)
+      .filter((f) => f.endsWith(".json"))
+      .sort(compareStrings);
+
+    const proposals = [];
+    for (const file of files) {
+      try {
+        const content = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+        proposals.push({
+          id: content.id,
+          status: content.status,
+          proposed_title: content.proposed_title,
+          created_at: content.created_at,
+          evidence: content.evidence,
+        });
+      } catch {
+        // Skip malformed
+      }
+    }
+
+    proposals.sort((a, b) => compareStrings(a.created_at, b.created_at));
+
+    return { success: true, proposals, count: proposals.length };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Get a specific proposal by ID.
+ */
+export function getProposal(wikiRoot, id) {
+  try {
+    if (!id || typeof id !== "string") {
+      return { success: false, error: "Proposal ID is required" };
+    }
+    if (!isValidProposalId(id)) {
+      return { success: false, error: `Invalid proposal ID: ${id}` };
+    }
+
+    const filePath = path.join(wikiRoot, PROPOSAL_DIR, `${id}.json`);
+    if (!fs.existsSync(filePath)) {
+      return { success: false, error: `Proposal not found: ${id}` };
+    }
+
+    const content = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    return { success: true, proposal: content };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Apply a proposal — user-approved promotion to lesson.
+ *
+ * This creates a new lesson file in editorial/lessons/ using the lesson template.
+ * It does NOT modify the original entry/entries.
+ * The proposal artifact is preserved but its status changes to "applied".
+ */
+export function applyProposal(wikiRoot, id, options = {}) {
+  try {
+    if (!id || typeof id !== "string") {
+      return { success: false, error: "Proposal ID is required" };
+    }
+    if (!isValidProposalId(id)) {
+      return { success: false, error: `Invalid proposal ID: ${id}` };
+    }
+
+    const proposalResult = getProposal(wikiRoot, id);
+    if (!proposalResult.success) {
+      return proposalResult;
+    }
+
+    const proposal = proposalResult.proposal;
+
+    if (proposal.status === "applied") {
+      return { success: false, error: "Proposal already applied" };
+    }
+
+    if (proposal.status !== "review_required") {
+      return { success: false, error: `Cannot apply proposal with status: ${proposal.status}` };
+    }
+
+    // Build lesson from proposal (sanitize title for defense-in-depth)
+    const rawTitle = proposal.proposed_title || "Untitled Lesson";
+    const title = sanitizeYamlString(rawTitle) || "Untitled Lesson";
+    const sections = proposal.template_sections || {};
+
+    // Extract tags from evidence entries if available
+    const tags = [];
+    if (proposal.evidence?.entry_paths?.length > 0) {
+      // Try to read tags from referenced entries (skip unsafe paths)
+      for (const entryPath of proposal.evidence.entry_paths) {
+        const validation = validateEntryPath(wikiRoot, entryPath);
+        if (!validation.safe) {
+          continue;
+        }
+        try {
+          if (fs.existsSync(validation.resolvedPath)) {
+            const content = fs.readFileSync(validation.resolvedPath, "utf-8");
+            const tagMatch = content.match(/^tags:\s*\n((?:\s+-\s.+\n?)+)/m);
+            if (tagMatch) {
+              const entryTags = tagMatch[1]
+                .split("\n")
+                .map((line) => line.trim().replace(/^-\s*/, ""))
+                .filter(Boolean);
+              tags.push(...entryTags);
+            }
+          }
+        } catch {
+          // Ignore read errors
+        }
+      }
+    }
+
+    const uniqueTags = [...new Set(tags)].slice(0, 10);
+
+    // Deterministic fallback chain: explicit override > proposal timestamp > evidence timestamps > empty.
+    const now = options.now
+      ? new Date(options.now).toISOString()
+      : (proposal.created_at || proposal.evidence?.last_seen || proposal.evidence?.first_seen || "");
+
+    // Collision-safe title: append proposal id suffix so repeated applies
+    // of the same conceptual title never overwrite an existing lesson.
+    const safeTitle = `${title} (${id})`;
+
+    // Pre-compute lesson path to check for existing file before writing.
+    const lessonsDir = path.join(wikiRoot, "editorial", "lessons");
+    const safeName = safeTitle
+      .toLowerCase()
+      .replace(/[^a-z0-9\p{L}\p{N}]+/gu, "-")
+      .replace(/^-+|-+$/g, "");
+    const lessonFilePath = path.join(lessonsDir, `${safeName}.md`);
+
+    if (fs.existsSync(lessonFilePath)) {
+      return { success: false, error: `Lesson file already exists: ${lessonFilePath}` };
+    }
+
+    // Write lesson using template
+    const lessonResult = writeLessonTemplate(wikiRoot, {
+      title: safeTitle,
+      tags: uniqueTags,
+      source: "lesson-proposal",
+      summary: `Auto-generated from usage pattern (${proposal.evidence?.usage_count || 0} events)`,
+      sections: {
+        whenToUse: sections.when_to_use || sections.whenToUse || "",
+        principles: sections.principles || "",
+        checklist: Array.isArray(sections.checklist) ? sections.checklist.join("\n") : sections.checklist || "",
+        examples: sections.examples || "",
+        failurePatterns: sections.failure_patterns || sections.failurePatterns || "",
+      },
+      createdAt: now,
+    });
+
+    if (!lessonResult.success) {
+      return lessonResult;
+    }
+
+    // Update proposal status to applied (preserve artifact)
+    const updatedProposal = {
+      ...proposal,
+      status: "applied",
+      applied_at: now,
+      applied_by: options.actor || "cli",
+      lesson_path: lessonResult.path,
+    };
+
+    const proposalPath = path.join(wikiRoot, PROPOSAL_DIR, `${id}.json`);
+    fs.writeFileSync(proposalPath, JSON.stringify(updatedProposal, null, 2), "utf-8");
+
+    return {
+      success: true,
+      proposal_id: id,
+      lesson_path: lessonResult.path,
+      message: `Applied proposal ${id} to ${lessonResult.path}`,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}

package/src/wiki/lesson-template.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * B1 Agent School — Lesson Template Contract
+ *
+ * Generates deterministic lesson Markdown with the five required sections:
+ * 1. When to use
+ * 2. Principles
+ * 3. Checklist
+ * 4. Examples
+ * 5. Failure patterns
+ */
+
+export const LESSON_SECTIONS = [
+  "when-to-use",
+  "principles",
+  "checklist",
+  "examples",
+  "failure-patterns",
+];
+
+export const LESSON_TEMPLATE_VERSION = 1;
+
+/**
+ * Sanitize a string for safe YAML frontmatter use.
+ * - Replaces newlines with spaces
+ * - Strips control characters (except tab)
+ * - Trims whitespace
+ *
+ * @param {string} value
+ * @returns {string} Cleaned text value
+ */
+export function sanitizeYamlString(value) {
+  const str = String(value);
+  return str
+    .replace(/\r\n|\r|\n/g, " ")
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, " ")
+    .trim();
+}
+
+/**
+ * Convert a value to its YAML-safe representation for frontmatter output.
+ * Sanitizes the input, then applies double-quoting if the result contains
+ * characters unsafe for bare YAML scalars (e.g. ": ", "#", leading special chars).
+ *
+ * @param {*} value
+ * @returns {string} YAML-safe value string
+ */
+function toYamlValue(value) {
+  const clean = sanitizeYamlString(value);
+
+  if (
+    clean === "" ||
+    /^[:\-#?\[\]{}&*!|>'"]/.test(clean) ||
+    clean.includes(": ") ||
+    clean.includes(" #")
+  ) {
+    const escaped = clean.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return `"${escaped}"`;
+  }
+
+  return clean;
+}
+
+/**
+ * Render a lesson template as Markdown string.
+ *
+ * @param {Object} options
+ * @param {string} options.title - Lesson title (required)
+ * @param {string[]} options.tags - Tags array
+ * @param {string} options.source - Source identifier
+ * @param {string} [options.summary] - Short summary
+ * @param {Object} [options.sections] - Section content overrides
+ * @param {string} [options.sections.whenToUse]
+ * @param {string} [options.sections.principles]
+ * @param {string} [options.sections.checklist]
+ * @param {string} [options.sections.examples]
+ * @param {string} [options.sections.failurePatterns]
+ * @param {string} [options.createdAt] - ISO timestamp
+ * @returns {string} Markdown content
+ */
+export function renderLessonTemplate(options = {}) {
+  const title = sanitizeYamlString(options.title || "Untitled Lesson") || "Untitled Lesson";
+  const tags = Array.isArray(options.tags)
+    ? options.tags.map((tag) => sanitizeYamlString(tag))
+    : [];
+  const source = sanitizeYamlString(options.source || "manual") || "manual";
+  const summary = sanitizeYamlString(options.summary || "");
+  const sections = options.sections || {};
+  const createdAt = sanitizeYamlString(options.createdAt || "");
+
+  const frontmatter = {
+    title,
+    tags,
+    source,
+    status: "lesson",
+    kind: "lesson",
+    created_at: createdAt,
+    updated_at: createdAt,
+    lesson_template_version: LESSON_TEMPLATE_VERSION,
+    ...(summary ? { summary } : {}),
+  };
+
+  const fmLines = ["---"];
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (Array.isArray(value)) {
+      fmLines.push(`${key}:`);
+      for (const item of value) {
+        fmLines.push(`  - ${toYamlValue(item)}`);
+      }
+    } else {
+      fmLines.push(`${key}: ${toYamlValue(value)}`);
+    }
+  }
+  fmLines.push("---");
+  fmLines.push("");
+
+  const sectionContent = {
+    "when-to-use": sections.whenToUse || sections["when-to-use"] || "",
+    principles: sections.principles || "",
+    checklist: sections.checklist || "",
+    examples: sections.examples || "",
+    "failure-patterns": sections.failurePatterns || sections["failure-patterns"] || "",
+  };
+
+  const bodyLines = [];
+  for (const sectionKey of LESSON_SECTIONS) {
+    const heading = sectionKey
+      .split("-")
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(" ");
+    bodyLines.push(`## ${heading}`);
+    bodyLines.push("");
+    const content = sectionContent[sectionKey];
+    if (content) {
+      bodyLines.push(content);
+    } else {
+      bodyLines.push("_(Add content here)_");
+    }
+    bodyLines.push("");
+  }
+
+  return [...fmLines, ...bodyLines].join("\n");
+}
+
+/**
+ * Write a lesson template to the editorial/lessons/ directory.
+ *
+ * @param {string} wikiRoot
+ * @param {Object} options - Same as renderLessonTemplate
+ * @returns {{success: boolean, path?: string, error?: string}}
+ */
+export function writeLessonTemplate(wikiRoot, options = {}) {
+  try {
+    const title = String(options.title || "untitled").trim();
+    if (!title || title === "untitled") {
+      return { success: false, error: "Lesson title is required" };
+    }
+
+    const lessonsDir = path.join(wikiRoot, "editorial", "lessons");
+    fs.mkdirSync(lessonsDir, { recursive: true });
+
+    const safeName = title
+      .toLowerCase()
+      .replace(/[^a-z0-9\p{L}\p{N}]+/gu, "-")
+      .replace(/^-+|-+$/g, "");
+    const filename = `${safeName}.md`;
+    const filePath = path.join(lessonsDir, filename);
+
+    const content = renderLessonTemplate(options);
+    fs.writeFileSync(filePath, content, "utf-8");
+
+    return {
+      success: true,
+      path: `editorial/lessons/${filename}`,
+      fullPath: filePath,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}