@systemdox/mcp-server 0.1.44 → 0.1.46

package/dist/install-skill.js

@@ -34,6 +34,28 @@ var ResponseCache = class {
 };
 
 // src/lib/api-client.ts
+var SystemDoxApiError = class extends Error {
+  constructor(status, text) {
+    super(`SystemDox API error ${status}: ${text}`);
+    this.status = status;
+    this.text = text;
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = void 0;
+    }
+    this.body = body;
+    const code = body?.code;
+    this.code = typeof code === "string" ? code : /\b(SYD-[A-Z]\d{3})\b/.exec(text)?.[1];
+  }
+  status;
+  text;
+  code;
+  body;
+};
+var TEAM_SETUP = "/v1/team-setup";
+var seg = (s) => encodeURIComponent(String(s));
 var SystemDoxApiClient = class {
   config;
   cache;
@@ -55,10 +77,7 @@ var SystemDoxApiClient = class {
     const cached = this.cache.get(cacheKey);
     if (cached !== void 0) return cached;
     const res = await this.fetchRaw(path, params);
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${body}`);
-    }
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
     const data = await res.json();
     this.cache.set(cacheKey, data);
     return data;
@@ -67,10 +86,7 @@ var SystemDoxApiClient = class {
    * latest now, not the one cached before someone published another. */
   async getFresh(path) {
     const res = await this.fetchRaw(path);
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${body}`);
-    }
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
     return await res.json();
   }
   async post(path, body) {
@@ -92,12 +108,101 @@ var SystemDoxApiClient = class {
       },
       body: JSON.stringify(body)
     });
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${text}`);
-    }
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
     return await res.json();
   }
+  // ── Team setup (ADR-217, specs/changes/team-setup/openapi.yaml) ──────────
+  // One method per operationId. Every read skips the cache: setup, sync and
+  // plugin-path act on what the workspace holds now.
+  /** getOwnTeamSetup: the key's own workspace, named in `workspace`. */
+  getOwnTeamSetup() {
+    return this.getFresh(TEAM_SETUP);
+  }
+  getTeamSetup(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
+  }
+  getMarketplace(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/marketplace.json`);
+  }
+  getPart(workspace, part) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}`);
+  }
+  publishPartVersion(workspace, part, files) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}/versions`, { files });
+  }
+  getPartVersion(workspace, part, version) {
+    return this.getFresh(
+      `${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}/versions/${seg(version)}`
+    );
+  }
+  getSetupSkills(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/skills`);
+  }
+  setSetupSkills(workspace, skills) {
+    return this.put(`${TEAM_SETUP}/${seg(workspace)}/skills`, { skills });
+  }
+  getPlugin(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/plugin`);
+  }
+  /** getPluginZip: the zip's bytes as served, and its X-Content-SHA256
+   * header. The caller checks the BYTES against the hash it was given. */
+  async getPluginZip(workspace, version) {
+    const res = await fetch(
+      this.buildUrl(`${TEAM_SETUP}/${seg(workspace)}/plugin/versions/${seg(version)}/zip`),
+      {
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-API-Key": this.config.apiKey,
+          Accept: "application/zip"
+        }
+      }
+    );
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
+    return { bytes: Buffer.from(await res.arrayBuffer()), sha256: res.headers.get("x-content-sha256") };
+  }
+  listMemoryProjects(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/memory`);
+  }
+  getMemory(workspace, project) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}`);
+  }
+  /** pushMemoryVersion: a stale base throws SystemDoxApiError with status 409,
+   * code SYD-K010 and `body.currentVersion`. */
+  pushMemoryVersion(workspace, project, body) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/versions`, body);
+  }
+  getMemoryVersion(workspace, project, version) {
+    return this.getFresh(
+      `${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/versions/${seg(version)}`
+    );
+  }
+  findMissingBlobs(workspace, project, hashes) {
+    return this.post(
+      `${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs/missing`,
+      { hashes }
+    );
+  }
+  uploadBlobs(workspace, project, blobs) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs`, { blobs });
+  }
+  readBlobs(workspace, project, hashes) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs/read`, { hashes });
+  }
+  listValueAnswers(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/values`);
+  }
+  lookupValues(workspace, values) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/values`, { values });
+  }
+  answerValues(workspace, answers) {
+    return this.put(`${TEAM_SETUP}/${seg(workspace)}/values`, { answers });
+  }
+  fileMemoryPeople(workspace, people) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/people`, { people });
+  }
+  resolvePerson(workspace, personId) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/people/${seg(personId)}`);
+  }
   invalidateCache(path) {
     if (path) {
       this.cache.invalidate(this.buildUrl(path).toString());

package/dist/lib/api-client.d.ts

@@ -1,4 +1,18 @@
 import type { ServerConfig } from "./config.js";
+import type { BlobRefusal, FileIn, FoundValue, Manifest, Marketplace, MemoryProjectSummary, MemoryVersion, PartDetail, PartName, PartPublished, PartVersionFiles, Person, PluginVersion, TeamSetup, ValueAnswer, ValueAnswerListed, ValueAnswerResults } from "./team-setup-types.js";
+/**
+ * A refused API call. The message keeps the form every caller has always
+ * shown (`SystemDox API error <status>: <body>`), so an SYD- code in the body
+ * reaches the user as the server wrote it; `code` and `body` are there for a
+ * caller that acts on one (a 409's `currentVersion`, a 503's SYD-K019).
+ */
+export declare class SystemDoxApiError extends Error {
+    readonly status: number;
+    readonly text: string;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(status: number, text: string);
+}
 export declare class SystemDoxApiClient {
     private config;
     private cache;
@@ -11,6 +25,73 @@ export declare class SystemDoxApiClient {
     post<T>(path: string, body: unknown): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     private mutate;
+    /** getOwnTeamSetup: the key's own workspace, named in `workspace`. */
+    getOwnTeamSetup(): Promise<TeamSetup>;
+    getTeamSetup(workspace: string): Promise<TeamSetup>;
+    getMarketplace(workspace: string): Promise<Marketplace>;
+    getPart(workspace: string, part: PartName): Promise<PartDetail>;
+    publishPartVersion(workspace: string, part: PartName, files: FileIn[]): Promise<PartPublished>;
+    getPartVersion(workspace: string, part: PartName, version: number | "latest"): Promise<PartVersionFiles>;
+    getSetupSkills(workspace: string): Promise<{
+        skills: string[];
+    }>;
+    setSetupSkills(workspace: string, skills: string[]): Promise<{
+        skills: string[];
+    }>;
+    getPlugin(workspace: string): Promise<{
+        name: string;
+        versions: PluginVersion[];
+    }>;
+    /** getPluginZip: the zip's bytes as served, and its X-Content-SHA256
+     * header. The caller checks the BYTES against the hash it was given. */
+    getPluginZip(workspace: string, version: number | "latest"): Promise<{
+        bytes: Buffer;
+        sha256: string | null;
+    }>;
+    listMemoryProjects(workspace: string): Promise<{
+        projects: MemoryProjectSummary[];
+    }>;
+    getMemory(workspace: string, project: string): Promise<MemoryVersion>;
+    /** pushMemoryVersion: a stale base throws SystemDoxApiError with status 409,
+     * code SYD-K010 and `body.currentVersion`. */
+    pushMemoryVersion(workspace: string, project: string, body: {
+        baseVersion: number;
+        manifest: Manifest;
+        spaceId?: string;
+    }): Promise<MemoryVersion>;
+    getMemoryVersion(workspace: string, project: string, version: number | "latest"): Promise<MemoryVersion>;
+    findMissingBlobs(workspace: string, project: string, hashes: string[]): Promise<{
+        missing: string[];
+    }>;
+    uploadBlobs(workspace: string, project: string, blobs: {
+        sha256: string;
+        content: string;
+    }[]): Promise<{
+        stored: string[];
+        refused: BlobRefusal[];
+    }>;
+    readBlobs(workspace: string, project: string, hashes: string[]): Promise<{
+        blobs: {
+            sha256: string;
+            content: string;
+        }[];
+        remaining: string[];
+    }>;
+    listValueAnswers(workspace: string): Promise<{
+        answers: ValueAnswerListed[];
+    }>;
+    lookupValues(workspace: string, values: FoundValue[]): Promise<{
+        answers: ValueAnswer[];
+    }>;
+    answerValues(workspace: string, answers: (FoundValue & {
+        answer: "ours" | "member";
+        label?: string;
+    })[]): Promise<ValueAnswerResults>;
+    fileMemoryPeople(workspace: string, people: {
+        values: FoundValue[];
+        label: string;
+    }[]): Promise<ValueAnswerResults>;
+    resolvePerson(workspace: string, personId: string): Promise<Person>;
     invalidateCache(path?: string): void;
     private buildUrl;
     private fetchRaw;

package/dist/lib/api-client.js

@@ -31,6 +31,28 @@ var ResponseCache = class {
 };
 
 // src/lib/api-client.ts
+var SystemDoxApiError = class extends Error {
+  constructor(status, text) {
+    super(`SystemDox API error ${status}: ${text}`);
+    this.status = status;
+    this.text = text;
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = void 0;
+    }
+    this.body = body;
+    const code = body?.code;
+    this.code = typeof code === "string" ? code : /\b(SYD-[A-Z]\d{3})\b/.exec(text)?.[1];
+  }
+  status;
+  text;
+  code;
+  body;
+};
+var TEAM_SETUP = "/v1/team-setup";
+var seg = (s) => encodeURIComponent(String(s));
 var SystemDoxApiClient = class {
   config;
   cache;
@@ -52,10 +74,7 @@ var SystemDoxApiClient = class {
     const cached = this.cache.get(cacheKey);
     if (cached !== void 0) return cached;
     const res = await this.fetchRaw(path, params);
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${body}`);
-    }
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
     const data = await res.json();
     this.cache.set(cacheKey, data);
     return data;
@@ -64,10 +83,7 @@ var SystemDoxApiClient = class {
    * latest now, not the one cached before someone published another. */
   async getFresh(path) {
     const res = await this.fetchRaw(path);
-    if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${body}`);
-    }
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
     return await res.json();
   }
   async post(path, body) {
@@ -89,12 +105,101 @@ var SystemDoxApiClient = class {
       },
       body: JSON.stringify(body)
     });
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`SystemDox API error ${res.status}: ${text}`);
-    }
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
     return await res.json();
   }
+  // ── Team setup (ADR-217, specs/changes/team-setup/openapi.yaml) ──────────
+  // One method per operationId. Every read skips the cache: setup, sync and
+  // plugin-path act on what the workspace holds now.
+  /** getOwnTeamSetup: the key's own workspace, named in `workspace`. */
+  getOwnTeamSetup() {
+    return this.getFresh(TEAM_SETUP);
+  }
+  getTeamSetup(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
+  }
+  getMarketplace(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/marketplace.json`);
+  }
+  getPart(workspace, part) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}`);
+  }
+  publishPartVersion(workspace, part, files) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}/versions`, { files });
+  }
+  getPartVersion(workspace, part, version) {
+    return this.getFresh(
+      `${TEAM_SETUP}/${seg(workspace)}/parts/${seg(part)}/versions/${seg(version)}`
+    );
+  }
+  getSetupSkills(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/skills`);
+  }
+  setSetupSkills(workspace, skills) {
+    return this.put(`${TEAM_SETUP}/${seg(workspace)}/skills`, { skills });
+  }
+  getPlugin(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/plugin`);
+  }
+  /** getPluginZip: the zip's bytes as served, and its X-Content-SHA256
+   * header. The caller checks the BYTES against the hash it was given. */
+  async getPluginZip(workspace, version) {
+    const res = await fetch(
+      this.buildUrl(`${TEAM_SETUP}/${seg(workspace)}/plugin/versions/${seg(version)}/zip`),
+      {
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-API-Key": this.config.apiKey,
+          Accept: "application/zip"
+        }
+      }
+    );
+    if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
+    return { bytes: Buffer.from(await res.arrayBuffer()), sha256: res.headers.get("x-content-sha256") };
+  }
+  listMemoryProjects(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/memory`);
+  }
+  getMemory(workspace, project) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}`);
+  }
+  /** pushMemoryVersion: a stale base throws SystemDoxApiError with status 409,
+   * code SYD-K010 and `body.currentVersion`. */
+  pushMemoryVersion(workspace, project, body) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/versions`, body);
+  }
+  getMemoryVersion(workspace, project, version) {
+    return this.getFresh(
+      `${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/versions/${seg(version)}`
+    );
+  }
+  findMissingBlobs(workspace, project, hashes) {
+    return this.post(
+      `${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs/missing`,
+      { hashes }
+    );
+  }
+  uploadBlobs(workspace, project, blobs) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs`, { blobs });
+  }
+  readBlobs(workspace, project, hashes) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/memory/${seg(project)}/blobs/read`, { hashes });
+  }
+  listValueAnswers(workspace) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/values`);
+  }
+  lookupValues(workspace, values) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/values`, { values });
+  }
+  answerValues(workspace, answers) {
+    return this.put(`${TEAM_SETUP}/${seg(workspace)}/values`, { answers });
+  }
+  fileMemoryPeople(workspace, people) {
+    return this.post(`${TEAM_SETUP}/${seg(workspace)}/people`, { people });
+  }
+  resolvePerson(workspace, personId) {
+    return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}/people/${seg(personId)}`);
+  }
   invalidateCache(path) {
     if (path) {
       this.cache.invalidate(this.buildUrl(path).toString());
@@ -124,5 +229,6 @@ var SystemDoxApiClient = class {
   }
 };
 export {
-  SystemDoxApiClient
+  SystemDoxApiClient,
+  SystemDoxApiError
 };

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|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|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|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
 };