my-patina 0.4.0 → 0.6.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { Command } from "commander";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
 import { dirname as dirname4, join as join7, resolve } from "path";
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync7, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import yaml3 from "js-yaml";
 
 // src/detect.ts
@@ -35,7 +35,7 @@ function render(template, vars) {
 }
 
 // src/upgrade.ts
-import { existsSync as existsSync3, mkdirSync, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
 import { join as join3, dirname as dirname2 } from "path";
 
 // src/checksums.ts
@@ -163,8 +163,122 @@ var CONTENT_SUBDIRS = ["notes", "skills", "posts"];
 var MODULE_MANAGED_FILES = Object.fromEntries(MODULES.map((m) => [m.id, m.managedPaths]));
 var MODULE_CONTENT_FILES = Object.fromEntries(MODULES.map((m) => [m.id, m.contentFileNames]));
 
+// src/sections.ts
+function hasFences(content) {
+  return parseSections(content).length > 0;
+}
+function parseSections(content) {
+  const sections = [];
+  const startRe = /<!-- patina:([a-z0-9-]+):start -->/g;
+  let match;
+  while ((match = startRe.exec(content)) !== null) {
+    const id = match[1];
+    const startIdx = match.index;
+    const afterStart = match.index + match[0].length;
+    const endMarker = `<!-- patina:${id}:end -->`;
+    const endIdx = content.indexOf(endMarker, afterStart);
+    if (endIdx === -1) {
+      continue;
+    }
+    let innerStart = afterStart;
+    if (content[innerStart] === "\r") innerStart++;
+    if (content[innerStart] === "\n") innerStart++;
+    let innerEnd = endIdx;
+    if (innerEnd > 0 && content[innerEnd - 1] === "\n") innerEnd--;
+    if (innerEnd > 0 && content[innerEnd - 1] === "\r") innerEnd--;
+    const inner = content.slice(innerStart, innerEnd).replace(/\r\n/g, "\n");
+    sections.push({
+      id,
+      inner,
+      start: startIdx,
+      end: endIdx + endMarker.length
+    });
+  }
+  return sections;
+}
+function renderSection(id, innerContent) {
+  return `<!-- patina:${id}:start -->
+${innerContent}
+<!-- patina:${id}:end -->`;
+}
+function mergeSections(existing, newSections, storedChecksums, relativePath, overwrite) {
+  const existingSections = parseSections(existing);
+  const outcomes = [];
+  const existingMap = new Map(
+    existingSections.map((s) => [s.id, s])
+  );
+  let result = existing;
+  const replacements = [];
+  for (const section of existingSections) {
+    const { id, inner } = section;
+    if (id in newSections) {
+      const newInner = newSections[id];
+      const storedKey = `${relativePath}:${id}`;
+      const storedHash = storedChecksums[storedKey];
+      const currentHash = hashContent(inner);
+      if (overwrite.has(id)) {
+        const normalized = newInner.replace(/\r\n/g, "\n");
+        replacements.push({
+          start: section.start,
+          end: section.end,
+          replacement: renderSection(id, normalized)
+        });
+        outcomes.push({ id, outcome: "updated", newChecksum: hashContent(normalized) });
+      } else if (storedHash && currentHash !== storedHash) {
+        outcomes.push({ id, outcome: "skipped", newChecksum: storedHash });
+      } else {
+        const normalized = newInner.replace(/\r\n/g, "\n");
+        const normalizedHash = hashContent(normalized);
+        if (normalizedHash === currentHash) {
+          outcomes.push({ id, outcome: "unchanged", newChecksum: currentHash });
+        } else {
+          replacements.push({
+            start: section.start,
+            end: section.end,
+            replacement: renderSection(id, normalized)
+          });
+          outcomes.push({ id, outcome: "updated", newChecksum: normalizedHash });
+        }
+      }
+    } else {
+      outcomes.push({ id, outcome: "unchanged", newChecksum: hashContent(inner) });
+    }
+  }
+  replacements.sort((a, b) => b.start - a.start);
+  for (const { start, end, replacement } of replacements) {
+    result = result.slice(0, start) + replacement + result.slice(end);
+  }
+  for (const [id, innerContent] of Object.entries(newSections)) {
+    if (!existingMap.has(id)) {
+      const normalized = innerContent.replace(/\r\n/g, "\n");
+      const block = renderSection(id, normalized);
+      result = result.endsWith("\n") ? result + block + "\n" : result + "\n" + block + "\n";
+      outcomes.push({ id, outcome: "added", newChecksum: hashContent(normalized) });
+    }
+  }
+  return { content: result, sections: outcomes };
+}
+function inspectSections(relativePath, existing, storedChecksums) {
+  const sections = parseSections(existing);
+  const editedIds = [];
+  for (const { id, inner } of sections) {
+    const storedKey = `${relativePath}:${id}`;
+    const storedHash = storedChecksums[storedKey];
+    if (!storedHash) {
+      continue;
+    }
+    if (hashContent(inner) !== storedHash) {
+      editedIds.push(id);
+    }
+  }
+  return editedIds;
+}
+
 // src/upgrade.ts
-function writeManagedFile(targetDir, relativePath, newContent, storedChecksums) {
+function writeManagedFile(targetDir, relativePath, newContent, storedChecksums, overwrite) {
+  if (hasFences(newContent)) {
+    return writeSectionedFile(targetDir, relativePath, newContent, storedChecksums, overwrite ?? /* @__PURE__ */ new Set());
+  }
   const fullPath = join3(targetDir, relativePath);
   const newChecksum = hashContent(newContent);
   if (!existsSync3(fullPath)) {
@@ -180,9 +294,51 @@ function writeManagedFile(targetDir, relativePath, newContent, storedChecksums)
   }
   return { outcome: "skipped", checksum: storedHash };
 }
+function writeSectionedFile(targetDir, relativePath, newContent, storedChecksums, overwrite) {
+  const fullPath = join3(targetDir, relativePath);
+  if (!existsSync3(fullPath)) {
+    mkdirSync(dirname2(fullPath), { recursive: true });
+    writeFileSync(fullPath, newContent, "utf8");
+    const sections2 = parseSections(newContent).map((s) => ({
+      id: s.id,
+      outcome: "added",
+      newChecksum: hashContent(s.inner)
+    }));
+    return { outcome: "added", checksum: hashContent(newContent), sections: sections2 };
+  }
+  const existingContent = readFileSync4(fullPath, "utf8");
+  if (!hasFences(existingContent)) {
+    const currentHash = hashFile(fullPath);
+    const storedHash = storedChecksums[relativePath];
+    if (!storedHash || currentHash === storedHash) {
+      writeFileSync(fullPath, newContent, "utf8");
+      const sections2 = parseSections(newContent).map((s) => ({
+        id: s.id,
+        outcome: "added",
+        newChecksum: hashContent(s.inner)
+      }));
+      return { outcome: "updated", checksum: hashContent(newContent), sections: sections2 };
+    } else {
+      return { outcome: "skipped", checksum: storedHash ?? currentHash, sections: void 0 };
+    }
+  }
+  const newSectionMap = {};
+  for (const s of parseSections(newContent)) {
+    newSectionMap[s.id] = s.inner;
+  }
+  const { content: mergedContent, sections } = mergeSections(
+    existingContent,
+    newSectionMap,
+    storedChecksums,
+    relativePath,
+    overwrite
+  );
+  writeFileSync(fullPath, mergedContent, "utf8");
+  return { outcome: "updated", checksum: hashContent(mergedContent), sections };
+}
 
 // src/state.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
 var STATE_FILENAME = ".patina-state.json";
 function normalizeChecksums(checksums) {
@@ -195,7 +351,7 @@ function normalizeChecksums(checksums) {
 function readState(root, profile) {
   const statePath = join4(root, STATE_FILENAME);
   if (existsSync4(statePath)) {
-    const raw = readFileSync4(statePath, "utf8");
+    const raw = readFileSync5(statePath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -242,6 +398,23 @@ function touch(targetDir, relativePath) {
   mkdirSync2(dirname3(full), { recursive: true });
   writeFileSync3(full, "", "utf8");
 }
+var MANIFEST_REQUIRED_FIELDS = ["name", "label", "reflect_hook", "description", "installed"];
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const parsed = yaml2.load(match[1]);
+  if (typeof parsed !== "object" || parsed === null) return null;
+  return parsed;
+}
+function validateManifestFrontmatter(moduleName, content) {
+  const fm = extractFrontmatter(content);
+  if (!fm) throw new Error(`Module "${moduleName}" manifest has missing or unparseable frontmatter`);
+  for (const field of MANIFEST_REQUIRED_FIELDS) {
+    if (!fm[field]) {
+      throw new Error(`Module "${moduleName}" manifest is missing required field "${field}"`);
+    }
+  }
+}
 function profileToVars(profile, liProfileUrl) {
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   return {
@@ -329,9 +502,16 @@ async function scaffold(opts) {
     ...baseManagedFiles(vars, editor, targetDir),
     ...modules.flatMap((m) => moduleManagedFiles(m, vars))
   ];
+  for (const module of modules) {
+    const manifestEntry = managedFiles.find(([p2]) => p2 === `.claude/modules/${module}/manifest.md`);
+    if (manifestEntry) validateManifestFrontmatter(module, manifestEntry[1]);
+  }
   for (const [relativePath, content] of managedFiles) {
-    const { checksum } = writeManagedFile(targetDir, relativePath, content, {});
-    checksums[relativePath] = checksum;
+    const result = writeManagedFile(targetDir, relativePath, content, {});
+    checksums[relativePath] = result.checksum;
+    for (const s of result.sections ?? []) {
+      checksums[`${relativePath}:${s.id}`] = s.newChecksum;
+    }
   }
   const baseDirs = ["notes", "skills", "posts"];
   for (const dir of baseDirs) {
@@ -353,7 +533,7 @@ ${STATE_FILENAME}
 }
 
 // src/validate.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6, readdirSync } from "fs";
 import { join as join6, relative, sep, basename } from "path";
 var NOTES = CONTENT_SUBDIRS[0];
 var SKILLS = CONTENT_SUBDIRS[1];
@@ -425,7 +605,7 @@ function checkSkillNotes(root, profile) {
   const noteSlugs = new Set(noteFiles.map((f) => basename(f, ".md")));
   const issues = [];
   for (const skillFile of listMarkdownFiles(skillsDir)) {
-    const content = readFileSync5(skillFile, "utf8");
+    const content = readFileSync6(skillFile, "utf8");
     const links = extractWikiLinks(content);
     for (const { target, line } of links) {
       if (!noteSlugs.has(target)) {
@@ -452,7 +632,7 @@ function checkWikiLinks(root, profile) {
     ...listMarkdownFiles(postsDir)
   ];
   for (const file of filesToScan) {
-    const content = readFileSync5(file, "utf8");
+    const content = readFileSync6(file, "utf8");
     const links = extractWikiLinks(content);
     for (const { target, line } of links) {
       if (!noteSlugs.has(target)) {
@@ -472,7 +652,7 @@ function checkExclusions(root, profile) {
   const notesDir = join6(contentDir, NOTES);
   const exclusionsPath = join6(notesDir, "exclusions.md");
   if (!existsSync5(exclusionsPath)) return [];
-  const content = readFileSync5(exclusionsPath, "utf8");
+  const content = readFileSync6(exclusionsPath, "utf8");
   const items = parseExclusions(content);
   if (items.length === 0) return [];
   const skillsDir = join6(contentDir, SKILLS);
@@ -484,7 +664,7 @@ function checkExclusions(root, profile) {
   const issues = [];
   const seen = /* @__PURE__ */ new Set();
   for (const file of filesToScan) {
-    const fileContent = readFileSync5(file, "utf8");
+    const fileContent = readFileSync6(file, "utf8");
     const lines = fileContent.split("\n");
     for (let i = 0; i < lines.length; i++) {
       const lineText = lines[i];
@@ -721,6 +901,15 @@ function writeProfile(cwd, profile) {
 function removeManagedFileIfUnmodified(targetDir, rel, stored) {
   const fullPath = join7(targetDir, rel);
   if (!existsSync6(fullPath)) return "deleted";
+  const fileContent = readFileSync7(fullPath, "utf8");
+  if (hasFences(fileContent)) {
+    const editedIds = inspectSections(rel, fileContent, stored);
+    if (editedIds.length > 0) {
+      return "kept";
+    }
+    unlinkSync(fullPath);
+    return "deleted";
+  }
   const currentHash = hashFile(fullPath);
   const storedHash = stored[rel];
   if (storedHash && currentHash !== storedHash) {
@@ -762,7 +951,7 @@ async function runUpdate(cwd) {
     await runValidate(cwd, profile);
   }
 }
-function applyProfileUpdate(cwd, profile, fields) {
+function applyProfileUpdate(cwd, profile, fields, overwrite) {
   const updatedProfile = {
     ...profile,
     name: fields.name.trim(),
@@ -785,10 +974,19 @@ function applyProfileUpdate(cwd, profile, fields) {
   ];
   const updated = [];
   const skipped = [];
+  const keptSections = [];
   for (const [rel, content] of files) {
-    const { outcome, checksum } = writeManagedFile(cwd, rel, content, stored);
-    newChecksums[rel] = checksum;
-    if (outcome === "skipped") {
+    const result = writeManagedFile(cwd, rel, content, stored, overwrite);
+    newChecksums[rel] = result.checksum;
+    for (const s of result.sections ?? []) {
+      const sKey = `${rel}:${s.id}`;
+      if (s.outcome !== "skipped") newChecksums[sKey] = s.newChecksum;
+      else {
+        newChecksums[sKey] = stored[sKey] ?? "";
+        keptSections.push(sKey);
+      }
+    }
+    if (result.outcome === "skipped") {
       skipped.push(rel);
     } else {
       updated.push(rel);
@@ -802,7 +1000,7 @@ function applyProfileUpdate(cwd, profile, fields) {
   writeState(cwd, { checksums: newChecksums });
   const profileToWrite = stripLegacyChecksums(updatedProfile);
   writeProfile(cwd, profileToWrite);
-  return { profile: profileToWrite, updated, skipped };
+  return { profile: profileToWrite, updated, skipped, keptSections };
 }
 async function runUpdateProfile(cwd, profile) {
   console.log("");
@@ -855,7 +1053,7 @@ async function runUpdateProfile(cwd, profile) {
     },
     { onCancel }
   );
-  const { updated, skipped } = applyProfileUpdate(cwd, profile, {
+  const fields = {
     name: identity.name,
     title: identity.title ?? "",
     roleDescription: identity.roleDescription ?? "",
@@ -864,11 +1062,52 @@ async function runUpdateProfile(cwd, profile) {
     companyName: work.companyName ?? "",
     website: work.website ?? "",
     companyDescription: work.companyDescription ?? ""
-  });
+  };
+  const overwriteSet = /* @__PURE__ */ new Set();
+  const previewProfile = {
+    ...profile,
+    name: fields.name.trim(),
+    title: fields.title.trim(),
+    role_description: fields.roleDescription.trim() || void 0,
+    job_description_url: fields.jobDescriptionUrl.trim() || void 0,
+    work: {
+      self_employed: fields.selfEmployed,
+      company_name: fields.companyName.trim() || (fields.selfEmployed ? "Freelance" : ""),
+      website: fields.website.trim() || void 0,
+      company_description: fields.companyDescription.trim() || void 0
+    }
+  };
+  const previewVars = profileToVars(previewProfile);
+  const storedChecksums = readState(cwd, profile).checksums;
+  const previewFiles = [
+    ...baseManagedFiles(previewVars, previewProfile.editor, cwd),
+    ...previewProfile.modules.flatMap((m) => moduleManagedFiles(m, previewVars))
+  ];
+  for (const [rel, content] of previewFiles) {
+    if (hasFences(content)) {
+      const fullPath = join7(cwd, rel);
+      if (existsSync6(fullPath)) {
+        const existingContent = readFileSync7(fullPath, "utf8");
+        const editedIds = inspectSections(rel, existingContent, storedChecksums);
+        for (const sectionId of editedIds) {
+          const confirmed = await p.confirm({
+            message: `Section '${sectionId}' in ${rel} has been manually edited. Overwrite?`,
+            initialValue: false
+          });
+          if (p.isCancel(confirmed)) onCancel();
+          if (confirmed) overwriteSet.add(sectionId);
+        }
+      }
+    }
+  }
+  const { updated, skipped, keptSections } = applyProfileUpdate(cwd, profile, fields, overwriteSet);
   const summaryLines = [];
   if (updated.length > 0) {
     summaryLines.push(chalk.hex("#94A3B8")(`Updated: ${updated.join(", ")}`));
   }
+  if (keptSections.length > 0) {
+    summaryLines.push(chalk.hex("#FFAB2E")(`Kept your edits: ${keptSections.join(", ")}`));
+  }
   if (skipped.length > 0) {
     summaryLines.push(chalk.hex("#FFAB2E")(`Kept your edits: ${skipped.join(", ")}`));
   }
@@ -883,6 +1122,7 @@ function applyModuleChanges(cwd, profile, toAdd, toRemove, moduleInputs) {
   const skippedFiles = [];
   const deleted = [];
   const kept = [];
+  const keptSections = [];
   for (const module of toAdd) {
     const def = getModule(module);
     if (def?.onAdd) {
@@ -891,9 +1131,17 @@ function applyModuleChanges(cwd, profile, toAdd, toRemove, moduleInputs) {
     const vars = profileToVars(updatedProfile);
     const contentDir = updatedProfile.content_dir;
     for (const [rel, content] of moduleManagedFiles(module, vars)) {
-      const { outcome, checksum } = writeManagedFile(cwd, rel, content, newChecksums);
-      newChecksums[rel] = checksum;
-      if (outcome === "skipped") {
+      const result = writeManagedFile(cwd, rel, content, newChecksums);
+      newChecksums[rel] = result.checksum;
+      for (const s of result.sections ?? []) {
+        const sKey = `${rel}:${s.id}`;
+        if (s.outcome !== "skipped") newChecksums[sKey] = s.newChecksum;
+        else {
+          newChecksums[sKey] = newChecksums[sKey] ?? "";
+          keptSections.push(sKey);
+        }
+      }
+      if (result.outcome === "skipped") {
         skippedFiles.push(rel);
       } else {
         added.push(rel);
@@ -919,6 +1167,10 @@ function applyModuleChanges(cwd, profile, toAdd, toRemove, moduleInputs) {
       if (result === "deleted") {
         deleted.push(rel);
         delete newChecksums[rel];
+        const prefix = rel + ":";
+        for (const key of Object.keys(newChecksums)) {
+          if (key.startsWith(prefix)) delete newChecksums[key];
+        }
       } else {
         kept.push(rel);
       }
@@ -931,7 +1183,7 @@ function applyModuleChanges(cwd, profile, toAdd, toRemove, moduleInputs) {
   writeState(cwd, { checksums: newChecksums });
   const finalProfile = stripLegacyChecksums(updatedProfile);
   writeProfile(cwd, finalProfile);
-  return { profile: finalProfile, added, skipped: skippedFiles, deleted, kept };
+  return { profile: finalProfile, added, skipped: skippedFiles, deleted, kept, keptSections };
 }
 async function runUpdateModules(cwd, profile) {
   const currentModules = profile.modules ?? [];
@@ -970,9 +1222,10 @@ async function runUpdateModules(cwd, profile) {
       liProfileUrl = url.trim();
     }
   }
-  const { added: addedFiles, skipped: skippedFiles, deleted: deletedFiles, kept: keptFiles } = applyModuleChanges(cwd, profile, toAdd, toRemove, { linkedin: { liProfileUrl } });
+  const { added: addedFiles, skipped: skippedFiles, deleted: deletedFiles, kept: keptFiles, keptSections: keptSectionKeys } = applyModuleChanges(cwd, profile, toAdd, toRemove, { linkedin: { liProfileUrl } });
   const summaryLines = [];
   if (addedFiles.length > 0) summaryLines.push(chalk.hex("#94A3B8")(`Added: ${addedFiles.join(", ")}`));
+  if (keptSectionKeys.length > 0) summaryLines.push(chalk.hex("#FFAB2E")(`Kept your edits: ${keptSectionKeys.join(", ")}`));
   if (skippedFiles.length > 0) summaryLines.push(chalk.hex("#FFAB2E")(`Kept your edits: ${skippedFiles.join(", ")}`));
   if (deletedFiles.length > 0) summaryLines.push(chalk.hex("#94A3B8")(`Removed: ${deletedFiles.join(", ")}`));
   if (keptFiles.length > 0) summaryLines.push(chalk.hex("#FFAB2E")(`Kept your edited files: ${keptFiles.join(", ")}`));
@@ -1001,7 +1254,7 @@ function registerCommands(_program) {
 // src/cli.ts
 import chalk2 from "chalk";
 var program = new Command();
-program.name("patina").description("Personal professional knowledge graph \u2014 setup and management");
+program.name("patina").description("Personal professional knowledge graph \u2014 setup and management").allowExcessArguments(true);
 program.command("validate").description("Check your patina for broken links and excluded items").action(() => {
   try {
     const cwd = process.cwd();

package/dist/templates/CLAUDE.md

@@ -2,6 +2,7 @@
 
 This file is loaded automatically each session to give you context about who you're working with and how this patina is organised.
 
+<!-- patina:profile:start -->
 ## Who you're working with
 
 **Name:** {{USER_NAME}}
@@ -11,6 +12,7 @@ This file is loaded automatically each session to give you context about who you
 {{ROLE_DESCRIPTION}}
 
 {{COMPANY_DESCRIPTION}}
+<!-- patina:profile:end -->
 
 ## What patina is
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-patina",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Personal professional knowledge graph — setup and management",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.0",
     "chalk": "^5.3.0",
-    "commander": "^12.1.0",
+    "commander": "^15.0.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
@@ -28,8 +28,8 @@
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "tsup": {
     "entry": [