@systemdox/mcp-server 0.1.45 → 0.1.47

package/dist/lib/memory-sync.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+
+// src/lib/memory-sync.ts
+import { createHash } from "crypto";
+
+// src/lib/person-values.ts
+var PHONE = "phone";
+var EMAIL = "email";
+var HOME_PATH = "home-path";
+var NATIONAL_PREFIX = "+44";
+var W = "[\\p{L}\\p{N}_]";
+var D = "\\p{Nd}";
+var WORD_OR = (extra) => `[\\p{L}\\p{N}_${extra}]`;
+var PERSON_ID = "(?:(?:con|ctc)_[0-9A-Za-z]{10,40}|usr_[0-9A-Za-z-]{10,40})";
+var PERSON_TOKEN = `\`${PERSON_ID}\`(?:[ \\t]*\\([^()\\n]*\\))?`;
+var BEFORE = `(?<!${WORD_OR("+.:/\\\\\\-")})(?<!${D}[ -])`;
+var AFTER = `(?!${WORD_OR(":/\\\\")}|\\.${D}|[ -]?${D}|-${W})`;
+var E164 = `${BEFORE}\\+${D}+(?:[ -]${D}+)*${AFTER}`;
+var NATIONAL = `${BEFORE}0${D}*(?:[ -]${D}+)*${AFTER}`;
+var GROUP_SIZES = /* @__PURE__ */ new Set([2, 3, 4, 5, 6]);
+var ATEXT = "[A-Za-z0-9!#$%&'*+/=?^_{|}~\\-]";
+var EMAIL_RE = "(?<![A-Za-z0-9!#$%&*+/=?^_{|}~.@\\-])[A-Za-z0-9_]" + ATEXT + "*(?:\\." + ATEXT + "+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9\\-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,63}(?![A-Za-z0-9\\-]|\\.[A-Za-z0-9])";
+var HOME_PREFIX = "(?:[A-Za-z]:\\\\+Users\\\\+|[A-Za-z]:/+Users/+|/Users/|/home/)";
+var HOME = `(?<!${WORD_OR(".~:/\\\\$}\\-")})${HOME_PREFIX}[^\\\\/\\s"'\`<>|:*?]+`;
+var KEY_PREFIX = `(?<!${W})(?:pweb_[a-z]+_key_|sk-ant-|sk_live_|rk_live_|github_pat_|gh[pousr]_|sntrys_|xox[baprs]-)[A-Za-z0-9_\\-]{4,}`;
+var global = (source, flags = "") => new RegExp(source, `gu${flags}`);
+var whole = (source, flags = "") => new RegExp(`^(?:${source})$`, `u${flags}`);
+function lineOf(text, start) {
+  let line = 1;
+  for (let i = text.indexOf("\n"); i !== -1 && i < start; i = text.indexOf("\n", i + 1)) line++;
+  return line;
+}
+function phoneShape(value) {
+  const groups = value.replace(/^\++/, "").split(/[ -]/);
+  const digits = [...groups.join("")];
+  if (value.startsWith("+")) return digits.length >= 8 && digits.length <= 15 && digits[0] !== "0";
+  if (digits.length < 10 || digits.length > 11) return false;
+  return groups.length === 1 || groups.slice(1).every((g) => GROUP_SIZES.has([...g].length));
+}
+function normalise(kind, value) {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (kind === PHONE) {
+    if (!(whole(E164).test(v) || whole(NATIONAL).test(v)) || !phoneShape(v)) {
+      throw new Error("not a phone number");
+    }
+    const digits = v.replace(/[ -]/g, "");
+    return digits.startsWith("+") ? digits : NATIONAL_PREFIX + digits.slice(1);
+  }
+  if (kind === EMAIL) {
+    if (!whole(EMAIL_RE).test(v)) throw new Error("not an email address");
+    return v.toLowerCase();
+  }
+  throw new Error(`not a value kind: ${JSON.stringify(kind)}`);
+}
+function findPersonValues(text) {
+  if (typeof text !== "string" || !text) return [];
+  const skipped = [...text.matchAll(global(PERSON_TOKEN))].map((m) => [m.index, m.index + m[0].length]);
+  const found = [];
+  const add = (kind, m, normalised) => {
+    const start = m.index;
+    const end = start + m[0].length;
+    if (skipped.some(([s, e]) => s <= start && end <= e)) return;
+    if (found.some((f) => f.start < end && start < f.end)) return;
+    found.push({ kind, value: m[0], normalised, line: lineOf(text, start), start, end });
+  };
+  for (const m of text.matchAll(global(EMAIL_RE))) add(EMAIL, m, m[0].toLowerCase());
+  for (const source of [E164, NATIONAL]) {
+    for (const m of text.matchAll(global(source))) {
+      if (phoneShape(m[0])) add(PHONE, m, normalise(PHONE, m[0]));
+    }
+  }
+  for (const m of text.matchAll(global(HOME, "i"))) add(HOME_PATH, m, m[0]);
+  return found.sort((a, b) => a.start - b.start);
+}
+
+// src/lib/memory-sync.ts
+var INDEX_FILE = "MEMORY.md";
+var SHAREABLE_TYPES = ["feedback", "project", "reference"];
+var FILE_PATH_RE = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+var CONFLICT_COPY_RE = /\.local-\d{4}-\d{2}-\d{2}(?:-\d+)?\.md$/;
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function isFilePath(path) {
+  return path.length <= 512 && FILE_PATH_RE.test(path) && !path.split("/").some((s) => s === "." || s === "..");
+}
+function isConflictCopy(path) {
+  return CONFLICT_COPY_RE.test(path.split("/").pop() ?? path);
+}
+var BLOCK_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+var YAML_FALSE = /* @__PURE__ */ new Set(["false", "False", "FALSE", "no", "No", "NO", "off", "Off", "OFF"]);
+function readFrontmatter(text) {
+  const m = BLOCK_RE.exec(text);
+  if (!m) return void 0;
+  const front = { shareFalse: false };
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
+    if (!kv) continue;
+    const raw = kv[2].replace(/[ \t]+#.*$/, "");
+    const quoted = /^(["'])(.*)\1$/.exec(raw);
+    const value = quoted ? quoted[2] : raw;
+    if (kv[1] === "type") front.type = value.trim().toLowerCase();
+    if (kv[1] === "share") front.shareFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
+  }
+  return front;
+}
+function isShareable(path, text) {
+  if (isConflictCopy(path) || !path.endsWith(".md")) return false;
+  const front = readFrontmatter(text);
+  if (front?.shareFalse) return false;
+  if (path === INDEX_FILE) return true;
+  return !!front && SHAREABLE_TYPES.includes(front.type ?? "");
+}
+function addShareFalse(text) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const m = BLOCK_RE.exec(text);
+  if (!m) return `---${eol}share: false${eol}---${eol}${text}`;
+  const lines = m[1].split(/\r?\n/).filter((l) => !/^share[ \t]*:/.test(l));
+  lines.push("share: false");
+  const closing = m[0].slice(m[0].lastIndexOf("---"));
+  return `---${eol}${lines.join(eol)}${eol}${closing}${text.slice(m[0].length)}`;
+}
+function localDate(now) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}`;
+}
+function conflictCopyName(path, date, taken) {
+  const stem = path.replace(/\.md$/, "");
+  for (let n = 1; ; n++) {
+    const name = `${stem}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
+    if (!taken.has(name.toLowerCase())) return name;
+  }
+}
+function decide(path, base, team, local) {
+  if (team === local) return "unchanged";
+  if (team === base) return local === void 0 ? "delete-team" : "local";
+  if (local === base) return team === void 0 ? "delete-local" : "team";
+  if (path === INDEX_FILE && team !== void 0 && local !== void 0) return "index";
+  if (team === void 0) return "local";
+  if (local === void 0) return "team";
+  return "conflict";
+}
+function decideAll(input) {
+  const localHashes = Object.fromEntries(Object.entries(input.local).map(([p, t]) => [p, sha256(t)]));
+  const paths = /* @__PURE__ */ new Set([...Object.keys(input.base), ...Object.keys(input.team), ...Object.keys(localHashes)]);
+  const rows = {};
+  const needed = /* @__PURE__ */ new Set();
+  for (const path of [...paths].sort()) {
+    if (input.excluded.has(path)) continue;
+    const row = decide(path, input.base[path], input.team[path], localHashes[path]);
+    rows[path] = row;
+    if (row === "team" || row === "conflict" || row === "index") needed.add(input.team[path]);
+    if (row === "index" && input.base[path]) needed.add(input.base[path]);
+  }
+  return { rows, needed: [...needed] };
+}
+function planMerge(input, rows, texts) {
+  const plan = {
+    manifest: {},
+    upload: {},
+    writes: {},
+    deletes: [],
+    pulled: [],
+    pushed: [],
+    deletedHere: [],
+    deletedFromTeam: [],
+    conflicts: [],
+    indexTeamLines: []
+  };
+  const taken = new Set(input.taken);
+  const teamText = (path) => {
+    const text = texts[input.team[path]];
+    if (text === void 0) throw new Error(`the team's ${path} could not be read`);
+    return text;
+  };
+  for (const path of input.excluded) if (input.team[path]) plan.manifest[path] = input.team[path];
+  for (const [path, row] of Object.entries(rows)) {
+    const team = input.team[path];
+    const local = input.local[path];
+    switch (row) {
+      case "unchanged":
+        if (team) plan.manifest[path] = team;
+        break;
+      case "local":
+        plan.manifest[path] = sha256(local);
+        plan.upload[path] = local;
+        plan.pushed.push(path);
+        break;
+      case "delete-team":
+        plan.deletedFromTeam.push(path);
+        break;
+      case "team":
+        plan.manifest[path] = team;
+        plan.writes[path] = teamText(path);
+        plan.pulled.push(path);
+        break;
+      case "delete-local":
+        plan.deletes.push(path);
+        plan.deletedHere.push(path);
+        break;
+      case "conflict": {
+        const copy = conflictCopyName(path, input.date, taken);
+        taken.add(copy.toLowerCase());
+        plan.manifest[path] = team;
+        plan.writes[path] = teamText(path);
+        plan.writes[copy] = local;
+        plan.conflicts.push({ path, copy });
+        break;
+      }
+      case "index": {
+        const base = input.base[path] ? texts[input.base[path]] : void 0;
+        const merged = mergeIndex(base, teamText(path), local);
+        const hash = sha256(merged.text);
+        plan.manifest[path] = hash;
+        if (merged.text !== local) {
+          plan.writes[path] = merged.text;
+          plan.pulled.push(path);
+        }
+        if (hash !== team) {
+          plan.upload[path] = merged.text;
+          plan.pushed.push(path);
+        }
+        plan.indexTeamLines.push(...merged.teamLines);
+        break;
+      }
+    }
+  }
+  return plan;
+}
+var LINK_RE = /\]\(\s*<?([^)\s>]+)>?(?:\s+["'(][^)]*)?\)/;
+function entries(lines) {
+  const seen = /* @__PURE__ */ new Map();
+  return lines.map((line) => {
+    const link = LINK_RE.exec(line);
+    const id = link ? `link:${link[1]}` : `text:${line}`;
+    const n = seen.get(id) ?? 0;
+    seen.set(id, n + 1);
+    return { key: n ? `${id}#${n}` : id, line };
+  });
+}
+var splitLines = (text) => text.split(/\r?\n/);
+function mergeIndex(base, team, local) {
+  const eol = local.includes("\r\n") ? "\r\n" : "\n";
+  const b = new Map(entries(base === void 0 ? [] : splitLines(base)).map((e) => [e.key, e.line]));
+  const teamEntries = entries(splitLines(team));
+  const t = new Map(teamEntries.map((e) => [e.key, e.line]));
+  const localEntries = entries(splitLines(local));
+  const result = [];
+  const teamLines = [];
+  for (const e of localEntries) {
+    const was = b.get(e.key);
+    const theirs = t.get(e.key);
+    if (theirs === e.line || theirs === was) result.push(e);
+    else if (e.line === was) {
+      if (theirs !== void 0) result.push({ key: e.key, line: theirs });
+    } else {
+      result.push(e);
+      if (theirs !== void 0) teamLines.push(theirs);
+    }
+  }
+  const baseEntries = entries(base === void 0 ? [] : splitLines(base));
+  const localKeys = new Set(localEntries.map((e) => e.key));
+  const replacedHere = /* @__PURE__ */ new Map();
+  baseEntries.forEach((e, i) => {
+    if (e.key.startsWith("text:") && !t.has(e.key) && !localKeys.has(e.key)) {
+      replacedHere.set(e.key, i ? baseEntries[i - 1].key : "");
+    }
+  });
+  const inResult = (key) => result.findIndex((e) => e.key === key);
+  teamEntries.forEach((e, i) => {
+    if (inResult(e.key) !== -1) return;
+    const was = b.get(e.key);
+    const before = i ? teamEntries[i - 1].key : "";
+    const both = e.key.startsWith("text:") && [...replacedHere].find(([, prev]) => prev === before);
+    if (was === void 0 && both) {
+      replacedHere.delete(both[0]);
+      teamLines.push(e.line);
+    } else if (was === void 0) {
+      let at = -1;
+      for (let j = i - 1; j >= 0 && at === -1; j--) at = inResult(teamEntries[j].key);
+      result.splice(at + 1, 0, e);
+    } else if (e.line !== was) {
+      teamLines.push(e.line);
+    }
+  });
+  return { text: result.map((e) => e.line).join(eol), teamLines };
+}
+var groupKey = (kind, normalised) => `${kind}:${normalised}`;
+function collectValues(files) {
+  const groups = /* @__PURE__ */ new Map();
+  const homePaths = [];
+  const findings = {};
+  for (const path of Object.keys(files).sort()) {
+    const found = findPersonValues(files[path]);
+    findings[path] = found;
+    for (const f of found) {
+      if (f.kind === HOME_PATH) {
+        if (!homePaths.includes(path)) homePaths.push(path);
+        continue;
+      }
+      const key = groupKey(f.kind, f.normalised);
+      const group = groups.get(key);
+      if (group) {
+        if (!group.files.includes(path)) group.files.push(path);
+      } else {
+        groups.set(key, {
+          kind: f.kind,
+          value: f.value,
+          normalised: f.normalised,
+          files: [path],
+          first: { path, line: f.line, text: splitLines(files[path])[f.line - 1].trim() }
+        });
+      }
+    }
+  }
+  return { groups: [...groups.values()], homePaths, findings };
+}
+function personToken(personId, label) {
+  return label ? `\`${personId}\` (${label})` : `\`${personId}\``;
+}
+function rewriteValues(text, findings, replacement) {
+  let out = "";
+  let last = 0;
+  for (const f of [...findings].sort((a, b) => a.start - b.start)) {
+    const to = replacement(f);
+    if (to === void 0) continue;
+    out += text.slice(last, f.start) + to;
+    last = f.end;
+  }
+  return out + text.slice(last);
+}
+function lineDiff(before, after) {
+  const a = splitLines(before);
+  const b = splitLines(after);
+  const out = [];
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === b[i]) continue;
+    if (a[i] !== void 0) out.push(`- ${a[i]}`);
+    if (b[i] !== void 0) out.push(`+ ${b[i]}`);
+  }
+  return out;
+}
+export {
+  INDEX_FILE,
+  SHAREABLE_TYPES,
+  addShareFalse,
+  collectValues,
+  conflictCopyName,
+  decide,
+  decideAll,
+  groupKey,
+  isConflictCopy,
+  isFilePath,
+  isShareable,
+  lineDiff,
+  localDate,
+  mergeIndex,
+  personToken,
+  planMerge,
+  readFrontmatter,
+  rewriteValues,
+  sha256
+};

package/dist/lib/person-values.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Find a person's details in a team memory file (ADR-217 Amendment 2).
+ *
+ * The client's half of the one detector of specs/changes/team-setup/contract.md
+ * ("People"), held with its twin `backend/layers/common/common/person_values.py`
+ * to the shared vectors in `specs/changes/team-setup/person-values.json`
+ * (test/person-values.test.mjs here, backend/tests/test_person_values.py there).
+ * Change one and the other in the same pull request. It finds:
+ *
+ * - **a phone number**: an E.164 number (`+44 7700 900123`), or a national
+ *   number of 10 or 11 digits starting with 0 in the usual groupings
+ *   (`07700 900123`, `020 7946 0321`), normalised to E.164 (+44);
+ * - **an email address**: an RFC 5322 addr-spec in its dot-atom form, without
+ *   comments or a quoted local part, normalised to lower case;
+ * - **a home-folder path**: `C:\Users\<name>`, `/Users/<name>` or
+ *   `/home/<name>`, which the sync rewrites to `~`.
+ *
+ * Anything inside a person token, `` `<con_|ctc_|usr_…>` (<label>) ``, is
+ * skipped, so a file the sync rewrote is never found again. The patterns are
+ * the backend's, character for character; where Python's `\w` and `\d` are
+ * Unicode-aware, these spell the same classes out (`u` flag).
+ *
+ * `findSecrets` mirrors the backend's `secret.key-prefix` rule
+ * (common/authored_skills.py): the first characters of a key, even cut short,
+ * are a secret. The server's other secret rules refuse a whole key at upload
+ * (SYD-K005); a whole key also matches this prefix rule, so the client skips
+ * it either way.
+ *
+ * Pure: no disk, no network, no logging.
+ */
+export declare const PHONE = "phone";
+export declare const EMAIL = "email";
+export declare const HOME_PATH = "home-path";
+export type PersonValueKind = typeof PHONE | typeof EMAIL | typeof HOME_PATH;
+/** The kinds a value can be answered for (openapi ValueKind); a home path is
+ * never answered, only rewritten. */
+export declare const VALUE_KINDS: readonly ["phone", "email"];
+export type ValueKind = (typeof VALUE_KINDS)[number];
+/** The country a national number (leading 0) belongs to. */
+export declare const NATIONAL_PREFIX = "+44";
+export interface Finding {
+    kind: PersonValueKind;
+    /** As written in the file. */
+    value: string;
+    /** E.164 for a phone number, lower case for an email address; for a home
+     * path, the value itself (it is rewritten, never answered). */
+    normalised: string;
+    /** 1-based. */
+    line: number;
+    start: number;
+    end: number;
+}
+export interface SecretFinding {
+    kind: "key-prefix";
+    line: number;
+}
+/** openapi PersonId, unanchored: THE one copy of the pattern on the client.
+ * The person token below and `resolve_person`'s input check
+ * (team-setup-types PERSON_ID_RE) are both built from it, so a change to the
+ * contract's PersonId is this one line (and the backend's `_PERSON_TOKEN`). */
+export declare const PERSON_ID = "(?:(?:con|ctc)_[0-9A-Za-z]{10,40}|usr_[0-9A-Za-z-]{10,40})";
+/** `con_…` (label), `ctc_…` (label), `usr_…` (label): a PersonId in
+ * backticks, with its role label after it. Skipped by the detector. */
+export declare const PERSON_TOKEN = "`(?:(?:con|ctc)_[0-9A-Za-z]{10,40}|usr_[0-9A-Za-z-]{10,40})`(?:[ \\t]*\\([^()\\n]*\\))?";
+/**
+ * The form an answer is keyed by: E.164 for a phone number, lower case for an
+ * email address. Throws when `value` is not one of `kind` (the server answers
+ * SYD-K020 for the same value).
+ */
+export declare function normalise(kind: string, value: string): string;
+/** Every phone number, email address and home-folder path in `text`, in the
+ * order they appear, skipping person tokens. */
+export declare function findPersonValues(text: string): Finding[];
+/** `text` with every home-folder path found replaced by `~`: what the sync
+ * sends instead (`C:\Users\jbloggs\.claude` → `~\.claude`). */
+export declare function rewriteHomePaths(text: string): string;
+/** The kind and line of every key prefix in `text`; never the value. */
+export declare function findSecrets(text: string): SecretFinding[];

package/dist/lib/person-values.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+// src/lib/person-values.ts
+var PHONE = "phone";
+var EMAIL = "email";
+var HOME_PATH = "home-path";
+var VALUE_KINDS = [PHONE, EMAIL];
+var NATIONAL_PREFIX = "+44";
+var W = "[\\p{L}\\p{N}_]";
+var D = "\\p{Nd}";
+var WORD_OR = (extra) => `[\\p{L}\\p{N}_${extra}]`;
+var PERSON_ID = "(?:(?:con|ctc)_[0-9A-Za-z]{10,40}|usr_[0-9A-Za-z-]{10,40})";
+var PERSON_TOKEN = `\`${PERSON_ID}\`(?:[ \\t]*\\([^()\\n]*\\))?`;
+var BEFORE = `(?<!${WORD_OR("+.:/\\\\\\-")})(?<!${D}[ -])`;
+var AFTER = `(?!${WORD_OR(":/\\\\")}|\\.${D}|[ -]?${D}|-${W})`;
+var E164 = `${BEFORE}\\+${D}+(?:[ -]${D}+)*${AFTER}`;
+var NATIONAL = `${BEFORE}0${D}*(?:[ -]${D}+)*${AFTER}`;
+var GROUP_SIZES = /* @__PURE__ */ new Set([2, 3, 4, 5, 6]);
+var ATEXT = "[A-Za-z0-9!#$%&'*+/=?^_{|}~\\-]";
+var EMAIL_RE = "(?<![A-Za-z0-9!#$%&*+/=?^_{|}~.@\\-])[A-Za-z0-9_]" + ATEXT + "*(?:\\." + ATEXT + "+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9\\-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,63}(?![A-Za-z0-9\\-]|\\.[A-Za-z0-9])";
+var HOME_PREFIX = "(?:[A-Za-z]:\\\\+Users\\\\+|[A-Za-z]:/+Users/+|/Users/|/home/)";
+var HOME = `(?<!${WORD_OR(".~:/\\\\$}\\-")})${HOME_PREFIX}[^\\\\/\\s"'\`<>|:*?]+`;
+var KEY_PREFIX = `(?<!${W})(?:pweb_[a-z]+_key_|sk-ant-|sk_live_|rk_live_|github_pat_|gh[pousr]_|sntrys_|xox[baprs]-)[A-Za-z0-9_\\-]{4,}`;
+var global = (source, flags = "") => new RegExp(source, `gu${flags}`);
+var whole = (source, flags = "") => new RegExp(`^(?:${source})$`, `u${flags}`);
+function lineOf(text, start) {
+  let line = 1;
+  for (let i = text.indexOf("\n"); i !== -1 && i < start; i = text.indexOf("\n", i + 1)) line++;
+  return line;
+}
+function phoneShape(value) {
+  const groups = value.replace(/^\++/, "").split(/[ -]/);
+  const digits = [...groups.join("")];
+  if (value.startsWith("+")) return digits.length >= 8 && digits.length <= 15 && digits[0] !== "0";
+  if (digits.length < 10 || digits.length > 11) return false;
+  return groups.length === 1 || groups.slice(1).every((g) => GROUP_SIZES.has([...g].length));
+}
+function normalise(kind, value) {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (kind === PHONE) {
+    if (!(whole(E164).test(v) || whole(NATIONAL).test(v)) || !phoneShape(v)) {
+      throw new Error("not a phone number");
+    }
+    const digits = v.replace(/[ -]/g, "");
+    return digits.startsWith("+") ? digits : NATIONAL_PREFIX + digits.slice(1);
+  }
+  if (kind === EMAIL) {
+    if (!whole(EMAIL_RE).test(v)) throw new Error("not an email address");
+    return v.toLowerCase();
+  }
+  throw new Error(`not a value kind: ${JSON.stringify(kind)}`);
+}
+function findPersonValues(text) {
+  if (typeof text !== "string" || !text) return [];
+  const skipped = [...text.matchAll(global(PERSON_TOKEN))].map((m) => [m.index, m.index + m[0].length]);
+  const found = [];
+  const add = (kind, m, normalised) => {
+    const start = m.index;
+    const end = start + m[0].length;
+    if (skipped.some(([s, e]) => s <= start && end <= e)) return;
+    if (found.some((f) => f.start < end && start < f.end)) return;
+    found.push({ kind, value: m[0], normalised, line: lineOf(text, start), start, end });
+  };
+  for (const m of text.matchAll(global(EMAIL_RE))) add(EMAIL, m, m[0].toLowerCase());
+  for (const source of [E164, NATIONAL]) {
+    for (const m of text.matchAll(global(source))) {
+      if (phoneShape(m[0])) add(PHONE, m, normalise(PHONE, m[0]));
+    }
+  }
+  for (const m of text.matchAll(global(HOME, "i"))) add(HOME_PATH, m, m[0]);
+  return found.sort((a, b) => a.start - b.start);
+}
+function rewriteHomePaths(text) {
+  let out = "";
+  let last = 0;
+  for (const f of findPersonValues(text)) {
+    if (f.kind !== HOME_PATH) continue;
+    out += text.slice(last, f.start) + "~";
+    last = f.end;
+  }
+  return out + text.slice(last);
+}
+function findSecrets(text) {
+  if (typeof text !== "string" || !text) return [];
+  return [...text.matchAll(global(KEY_PREFIX))].map((m) => ({ kind: "key-prefix", line: lineOf(text, m.index) }));
+}
+export {
+  EMAIL,
+  HOME_PATH,
+  NATIONAL_PREFIX,
+  PERSON_ID,
+  PERSON_TOKEN,
+  PHONE,
+  VALUE_KINDS,
+  findPersonValues,
+  findSecrets,
+  normalise,
+  rewriteHomePaths
+};

package/dist/lib/skills.d.ts

@@ -63,6 +63,26 @@ export declare function isValidPath(path: string): boolean;
 export declare function frontmatterName(skillMd: string): string | undefined;
 /** The default install folder: personal skills, every project (ADR-216 §6 Q1). */
 export declare function defaultSkillDir(name: string): string;
+export interface Walked {
+    files: string[];
+    /** Symlinks and junctions: never followed, never written through. */
+    links: string[];
+    /** Dot-entries a publish leaves out (.env, .vscode/…): never part of a skill. */
+    hidden: string[];
+}
+/** `skipHidden`: a publish leaves dot-entries out; an install must see them,
+ * or an edited dotfile a version ships would be overwritten unseen. */
+export declare function walk(root: string, { skipHidden }: {
+    skipHidden: boolean;
+}, dir?: string, out?: Walked): Promise<Walked>;
+/**
+ * Read `paths` (relative, forward slashes) under `root` exactly as they are
+ * on disk, bytes decoded as UTF-8, held to the server's limits (ADR-216):
+ * at most MAX_FILES files, each text with no NUL and at most MAX_FILE_BYTES,
+ * all together at most MAX_TOTAL_BYTES. Throws naming the first file at
+ * fault. `what` names the thing in the message ("a skill", "the hooks part").
+ */
+export declare function readTextFiles(root: string, paths: string[], what: string): Promise<SkillFileIn[]>;
 /**
  * Read a skill folder exactly as it is on disk (bytes decoded as UTF-8, never
  * re-typed), ready to publish. Throws naming the first file that cannot be

package/dist/lib/skills.js

@@ -56,18 +56,9 @@ async function walk(root, { skipHidden }, dir = root, out = { files: [], links:
   out.files.sort();
   return out;
 }
-async function readSkillDirectory(directory) {
-  const root = resolve(directory);
-  if (!existsSync(join(root, ENTRY_FILE))) {
-    throw new Error(`${root} has no ${ENTRY_FILE}: a skill folder holds SKILL.md at its root`);
-  }
-  const walked = await walk(root, { skipHidden: true });
-  if (walked.links.length) {
-    throw new Error(`${walked.links.join(", ")}: links are not followed; copy the file into the skill folder`);
-  }
-  const paths = walked.files;
+async function readTextFiles(root, paths, what) {
   if (paths.length > MAX_FILES) {
-    throw new Error(`${root} holds ${paths.length} files: a skill holds at most ${MAX_FILES}`);
+    throw new Error(`${root} holds ${paths.length} files: ${what} holds at most ${MAX_FILES}`);
   }
   const decoder = new TextDecoder("utf-8", { fatal: true });
   const files = [];
@@ -77,7 +68,7 @@ async function readSkillDirectory(directory) {
       throw new Error(`${path}: file names may use letters, digits, ".", "_" and "-" only`);
     }
     const raw = await readFile(join(root, ...path.split("/")));
-    if (raw.includes(0)) throw new Error(`${path} is binary: a skill holds text files only`);
+    if (raw.includes(0)) throw new Error(`${path} is binary: ${what} holds text files only`);
     if (raw.length > MAX_FILE_BYTES) {
       throw new Error(`${path} is ${raw.length} bytes: a file holds at most ${MAX_FILE_BYTES}`);
     }
@@ -93,6 +84,18 @@ async function readSkillDirectory(directory) {
     }
     files.push({ path, content });
   }
+  return files;
+}
+async function readSkillDirectory(directory) {
+  const root = resolve(directory);
+  if (!existsSync(join(root, ENTRY_FILE))) {
+    throw new Error(`${root} has no ${ENTRY_FILE}: a skill folder holds SKILL.md at its root`);
+  }
+  const walked = await walk(root, { skipHidden: true });
+  if (walked.links.length) {
+    throw new Error(`${walked.links.join(", ")}: links are not followed; copy the file into the skill folder`);
+  }
+  const files = await readTextFiles(root, walked.files, "a skill");
   const skillMd = files.find((f) => f.path === ENTRY_FILE);
   const name = frontmatterName(skillMd.content);
   if (!name) throw new Error(`${ENTRY_FILE} has no frontmatter name`);
@@ -205,5 +208,7 @@ export {
   isValidName,
   isValidPath,
   readSkillDirectory,
-  sha256
+  readTextFiles,
+  sha256,
+  walk
 };