@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/json-edit.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Editing one property of a JSON or JSONC document in place (#3308): the
+ * rest of the text is left as it was, comments and trailing commas included.
+ */
+
+import { describe, expect, test } from "vitest";
+import { removeProperty, setProperty, valueAt } from "./json-edit";
+import { parseJsonText } from "./jsonc";
+
+const read = (text: string, jsonc = false) => {
+  const r = parseJsonText(text, { jsonc });
+  if (!r.ok) throw new Error(r.message);
+  return r.value;
+};
+
+const JSON_TEXT = `{
+    "name": "w",
+    "members": [
+        { "name": "a", "box": { "services": [] } },
+        {
+            "name": "b",
+            "box": {
+                "intent": "ws-001"
+            }
+        }
+    ]
+}
+`;
+
+const JSONC_TEXT = `{
+  // the workspace
+  "name": "w",
+  "members": [
+    {
+      "name": "b",
+      "box": {
+        "listing": {
+          "title": "Old", // kept as is
+          "line": "one line",
+        },
+      },
+    },
+  ],
+}
+`;
+
+describe("setProperty", () => {
+  test("replaces a value in place and leaves every other byte", () => {
+    const out = setProperty(JSON_TEXT, false, "/members/1/box", "intent", "ws-002");
+    expect(out).toBe(JSON_TEXT.replace('"ws-001"', '"ws-002"'));
+  });
+
+  test("adds a key after the last one, indented like it, and an object value on its own lines", () => {
+    const out = setProperty(JSON_TEXT, false, "/members/1/box", "listing", { title: "B", published: false });
+    expect(out).toContain(`                "intent": "ws-001",\n                "listing": {\n                    "title": "B",\n                    "published": false\n                }\n            }`);
+    expect(read(out)).toEqual({ ...(read(JSON_TEXT) as object), members: [{ name: "a", box: { services: [] } }, { name: "b", box: { intent: "ws-001", listing: { title: "B", published: false } } }] });
+  });
+
+  test("keeps an object on one line on one line", () => {
+    const out = setProperty(JSON_TEXT, false, "/members/0/box", "listing", { title: "A" });
+    expect(out).toContain(`{ "name": "a", "box": { "services": [], "listing": {"title":"A"} } }`);
+    expect(valueAt(read(out), "/members/0/box/listing")).toEqual({ title: "A" });
+  });
+
+  test("fills an empty object", () => {
+    const out = setProperty('{\n  "box": {}\n}\n', false, "/box", "listing", { title: "T" });
+    expect(out).toBe('{\n  "box": {\n    "listing": {\n      "title": "T"\n    }\n  }\n}\n');
+  });
+
+  test("in JSONC, keeps comments with their lines and the trailing comma style", () => {
+    const out = setProperty(JSONC_TEXT, true, "/members/0/box/listing", "published", false);
+    expect(out).toContain(`          "line": "one line",\n          "published": false,\n        },`);
+    const out2 = setProperty(JSONC_TEXT, true, "/members/0/box/listing", "title", "New");
+    expect(out2).toBe(JSONC_TEXT.replace('"Old"', '"New"'));
+    expect(out2).toContain("// kept as is");
+  });
+
+  test("puts a new key after a comment that ends the last property's line", () => {
+    const text = '{\n  "a": 1, // one\n  "b": 2 // two\n}\n';
+    const out = setProperty(text, true, "", "c", 3);
+    expect(out).toBe('{\n  "a": 1, // one\n  "b": 2, // two\n  "c": 3\n}\n');
+  });
+
+  test("keeps CRLF line endings", () => {
+    const text = '{\r\n  "box": {\r\n    "intent": "x"\r\n  }\r\n}\r\n';
+    const out = setProperty(text, false, "/box", "listing", { title: "T" });
+    expect(out).toBe('{\r\n  "box": {\r\n    "intent": "x",\r\n    "listing": {\r\n      "title": "T"\r\n    }\r\n  }\r\n}\r\n');
+  });
+
+  test("refuses when there is no object at the pointer", () => {
+    expect(() => setProperty(JSON_TEXT, false, "/members/5/box", "listing", {})).toThrow(/no object at \/members\/5\/box/);
+  });
+});
+
+describe("removeProperty", () => {
+  test("removes a key with the comma after it, and its line", () => {
+    const text = '{\n  "a": 1,\n  "b": 2,\n  "c": 3\n}\n';
+    expect(removeProperty(text, false, "", "b")).toBe('{\n  "a": 1,\n  "c": 3\n}\n');
+  });
+
+  test("removes the last key with the comma before it", () => {
+    const text = '{\n  "a": 1,\n  "b": 2\n}\n';
+    expect(removeProperty(text, false, "", "b")).toBe('{\n  "a": 1\n}\n');
+  });
+
+  test("removes a key on a one-line object", () => {
+    expect(removeProperty('{ "a": 1, "b": 2 }', false, "", "a")).toBe('{ "b": 2 }');
+    expect(removeProperty('{ "a": 1, "b": 2 }', false, "", "b")).toBe('{ "a": 1 }');
+  });
+
+  test("leaves {} when the only key goes, and the text unchanged when the key is not there", () => {
+    expect(removeProperty('{\n  "box": {\n    "listing": {\n      "a": 1\n    }\n  }\n}', false, "/box/listing", "a")).toBe('{\n  "box": {\n    "listing": {}\n  }\n}');
+    expect(removeProperty('{ "a": 1 }', false, "", "z")).toBe('{ "a": 1 }');
+  });
+
+  test("in JSONC, removes a key with its trailing comma and keeps the comments of the others", () => {
+    const out = removeProperty(JSONC_TEXT, true, "/members/0/box/listing", "line");
+    expect(out).toContain(`"title": "Old", // kept as is\n        },`);
+    expect(valueAt(read(out, true), "/members/0/box/listing")).toEqual({ title: "Old" });
+  });
+});

package/src/workspace/json-edit.ts

@@ -0,0 +1,142 @@
+/**
+ * Edit one property of a JSON or JSONC document in place (#3308), for the
+ * write commands that change a field of the workspace declaration.
+ *
+ * Only the text of the property changed is touched: the rest of the file
+ * keeps its indentation, key order, line endings, comments and trailing
+ * commas. A new property goes after the last one of its object, indented
+ * like it. The caller re-parses the result and compares it with the value it
+ * meant to write, so an edit this module gets wrong is never written.
+ */
+
+import { parseJsonText, pointerToken } from "./jsonc";
+
+export class JsonEditError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "JsonEditError";
+  }
+}
+
+type Parsed = Extract<ReturnType<typeof parseJsonText>, { ok: true }>;
+
+function parse(text: string, jsonc: boolean): Parsed {
+  const r = parseJsonText(text, { jsonc });
+  if (!r.ok) throw new JsonEditError(`the file does not parse: ${r.message} at line ${r.location.line}, column ${r.location.column}`);
+  return r;
+}
+
+/** The value at a JSON Pointer, or undefined. */
+export function valueAt(root: unknown, pointer: string): unknown {
+  if (pointer === "") return root;
+  let at: unknown = root;
+  for (const raw of pointer.slice(1).split("/")) {
+    const token = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (at === null || typeof at !== "object") return undefined;
+    if (Array.isArray(at)) at = at[Number(token)];
+    else at = Object.prototype.hasOwnProperty.call(at, token) ? (at as Record<string, unknown>)[token] : undefined;
+  }
+  return at;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** The text's line ending, and the indentation one level adds (the first indented line's, else two spaces). */
+function style(text: string): { eol: string; unit: string } {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const m = /\n([ \t]+)\S/.exec(text);
+  return { eol, unit: m ? (m[1].startsWith("\t") ? "\t" : m[1]) : "  " };
+}
+
+function lineStart(text: string, offset: number): number {
+  return text.lastIndexOf("\n", offset - 1) + 1;
+}
+
+function lineIndent(text: string, offset: number): string {
+  const start = lineStart(text, offset);
+  return /^[ \t]*/.exec(text.slice(start))![0];
+}
+
+/** The offset of the next character after `from` that is not whitespace or a comment. */
+function skipTrivia(text: string, from: number): number {
+  let i = from;
+  for (;;) {
+    const c = text[i];
+    if (c === " " || c === "\t" || c === "\n" || c === "\r") i++;
+    else if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++;
+    } else if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end < 0 ? text.length : end + 2;
+    } else return i;
+  }
+}
+
+function render(value: unknown, indent: string, unit: string, eol: string): string {
+  return JSON.stringify(value, null, unit).split("\n").join(eol + indent);
+}
+
+/**
+ * Set `key` of the object at `objectPointer` to `value`: replace the value's
+ * text when the key is there, else add the key after the object's last one.
+ * Throws a {@link JsonEditError} when there is no object at the pointer.
+ */
+export function setProperty(text: string, jsonc: boolean, objectPointer: string, key: string, value: unknown): string {
+  const r = parse(text, jsonc);
+  const parent = valueAt(r.value, objectPointer);
+  if (!isObject(parent)) throw new JsonEditError(`there is no object at ${objectPointer || "the root"}`);
+  const { eol, unit } = style(text);
+  const child = r.span(`${objectPointer}/${pointerToken(key)}`);
+  if (child) return text.slice(0, child.start) + render(value, lineIndent(text, child.key ?? child.start), unit, eol) + text.slice(child.end);
+
+  const obj = r.span(objectPointer)!;
+  const parentIndent = lineIndent(text, obj.key ?? obj.start);
+  const keys = Object.keys(parent);
+  if (keys.length === 0) {
+    const indent = parentIndent + unit;
+    return `${text.slice(0, obj.start)}{${eol}${indent}${JSON.stringify(key)}: ${render(value, indent, unit, eol)}${eol}${parentIndent}}${text.slice(obj.end)}`;
+  }
+  const last = r.span(`${objectPointer}/${pointerToken(keys[keys.length - 1])}`)!;
+  const next = skipTrivia(text, last.end);
+  const trailingComma = text[next] === ",";
+  if (lineStart(text, last.key!) === lineStart(text, obj.start)) {
+    // An object on one line stays on one line.
+    const entry = `${JSON.stringify(key)}: ${JSON.stringify(value)}`;
+    return trailingComma ? `${text.slice(0, next + 1)} ${entry},${text.slice(next + 1)}` : `${text.slice(0, last.end)}, ${entry}${text.slice(last.end)}`;
+  }
+  const indent = lineIndent(text, last.key!);
+  const after = trailingComma ? next + 1 : last.end;
+  // After a comment that ends the last property's line, so the comment stays with it.
+  const eolAt = text.indexOf("\n", after);
+  const lineEnd = eolAt < 0 ? text.length : text[eolAt - 1] === "\r" ? eolAt - 1 : eolAt;
+  const at = /^[ \t]*(\/\/.*)?$/.test(text.slice(after, lineEnd)) ? lineEnd : after;
+  const entry = `${eol}${indent}${JSON.stringify(key)}: ${render(value, indent, unit, eol)}`;
+  if (trailingComma) return `${text.slice(0, at)}${entry},${text.slice(at)}`;
+  return `${text.slice(0, last.end)},${text.slice(last.end, at)}${entry}${text.slice(at)}`;
+}
+
+/** Remove `key` from the object at `objectPointer`, with the comma that went with it. Unchanged when the key is not there. */
+export function removeProperty(text: string, jsonc: boolean, objectPointer: string, key: string): string {
+  const r = parse(text, jsonc);
+  const parent = valueAt(r.value, objectPointer);
+  if (!isObject(parent)) throw new JsonEditError(`there is no object at ${objectPointer || "the root"}`);
+  const child = r.span(`${objectPointer}/${pointerToken(key)}`);
+  if (!child) return text;
+  const keys = Object.keys(parent);
+  const obj = r.span(objectPointer)!;
+  if (keys.length === 1) return `${text.slice(0, obj.start)}{}${text.slice(obj.end)}`;
+  const next = skipTrivia(text, child.end);
+  if (text[next] === ",") {
+    const start = lineStart(text, child.key!);
+    const ownLine = /^[ \t]*$/.test(text.slice(start, child.key!));
+    let to = next + 1;
+    const eolAt = text.indexOf("\n", to);
+    if (ownLine && /^[ \t\r]*$/.test(text.slice(to, eolAt < 0 ? text.length : eolAt))) to = eolAt < 0 ? text.length : eolAt + 1;
+    else while (text[to] === " ") to++;
+    return text.slice(0, ownLine ? start : child.key!) + text.slice(to);
+  }
+  // The last property, with no trailing comma: remove from the comma after the one before it.
+  const prev = r.span(`${objectPointer}/${pointerToken(keys[keys.indexOf(key) - 1])}`)!;
+  const comma = skipTrivia(text, prev.end);
+  return text.slice(0, comma) + text.slice(child.end);
+}

package/src/workspace/jsonc.ts

@@ -31,6 +31,13 @@ export type JsonParseResult =
        * `key` is set. Falls back to the nearest ancestor that has a position.
        */
       locate(pointer: string, key?: boolean): TextLocation;
+      /**
+       * Where the value at `pointer` is in the text, as offsets: its key's
+       * opening quote (null for an array item or the root), the value's first
+       * character, and the offset just past its last. Undefined when there is
+       * no value at `pointer`. For editing the text in place (#3308).
+       */
+      span(pointer: string): { key: number | null; start: number; end: number } | undefined;
     }
   | { ok: false; message: string; location: TextLocation };
 
@@ -63,6 +70,7 @@ export function parseJsonText(text: string, options: JsonParseOptions): JsonPars
   };
 
   const values = new Map<string, number>();
+  const ends = new Map<string, number>();
   const keys = new Map<string, number>();
   let i = text.charCodeAt(0) === 0xfeff ? 1 : 0;
 
@@ -113,6 +121,12 @@ export function parseJsonText(text: string, options: JsonParseOptions): JsonPars
   function parseValue(pointer: string): unknown {
     skip();
     values.set(pointer, i);
+    const value = parseAt(pointer);
+    ends.set(pointer, i);
+    return value;
+  }
+
+  function parseAt(pointer: string): unknown {
     const c = text[i];
     if (c === "{") return parseObject(pointer);
     if (c === "[") return parseArray(pointer);
@@ -223,6 +237,12 @@ export function parseJsonText(text: string, options: JsonParseOptions): JsonPars
           if (p === "") return toLocation(0);
         }
       },
+      span(pointer) {
+        const start = values.get(pointer);
+        const end = ends.get(pointer);
+        if (start === undefined || end === undefined) return undefined;
+        return { key: keys.get(pointer) ?? null, start, end };
+      },
     };
   } catch (err) {
     if (!(err instanceof JsonSyntaxError)) throw err;

package/src/workspace/kinds.ts

@@ -45,8 +45,34 @@ export interface FileProbe {
    * `live {` block is found without parsing HCL (#2545).
    */
   anyBlock?: { in: string[]; blocks: string[] };
+  /**
+   * A file directly in the directory whose name matches one of `in` parses
+   * as JSON and has a value at one of `pointers`, each a JSON Pointer. This
+   * is how an app member's `package.json` with a `start` script is found
+   * without claiming every Node package (#3151).
+   */
+  anyJsonKey?: { in: string[]; pointers: string[] };
+}
+
+/** A string, integer or boolean field a kind declares for its members (#3151). */
+export interface ScalarKindField {
+  type: "string" | "integer" | "boolean";
+  description: string;
+  /** The value a member that doesn't set the field gets; null when the kind gives none. */
+  default?: string | number | boolean;
+  /** For a string field, a regular expression the value must match. */
+  pattern?: string;
 }
 
+/** An object field: named scalar fields, each with its own default (#3151). */
+export interface ObjectKindField {
+  type: "object";
+  description: string;
+  properties: Record<string, ScalarKindField>;
+}
+
+export type KindField = ScalarKindField | ObjectKindField;
+
 /** What a kind's probe checks in a directory. */
 export type KindProbe =
   /** Files, or blocks in files, sit directly in the directory. */
@@ -99,6 +125,8 @@ export interface MemberKind {
   packageDir?: string;
   /** How `workspace graph` reads a member of this kind (#2874); unset, the member is `kind-not-run`. */
   graph?: KindGraph;
+  /** The fields a member entry of this kind may set, with their defaults (#3151); unset, the kind declares none. */
+  fields?: Record<string, KindField>;
 }
 
 export interface KindRegistry {
@@ -187,8 +215,18 @@ export function builtinKindRegistry(): KindRegistry {
 export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): boolean {
   if ("directory" in kind.probe) return true;
   if ("chantProject" in kind.probe) return holdsChantProject(tree, dir);
-  const { anyFile, anyBlock } = kind.probe;
+  const { anyFile, anyBlock, anyJsonKey } = kind.probe;
   if (anyFile && filesMatching(tree, dir, anyFile).length > 0) return true;
+  if (anyJsonKey) {
+    for (const file of filesMatching(tree, dir, anyJsonKey.in)) {
+      try {
+        const json = JSON.parse(tree.read(file)) as unknown;
+        if (anyJsonKey.pointers.some((p) => atPointer(json, p) !== undefined)) return true;
+      } catch {
+        // A file that isn't JSON is no evidence either way.
+      }
+    }
+  }
   if (anyBlock) {
     const opener = new RegExp(`^\\s*(?:${anyBlock.blocks.map(escapeRegExp).join("|")})\\s*\\{`, "m");
     for (const file of filesMatching(tree, dir, anyBlock.in)) {
@@ -227,6 +265,17 @@ function filesMatching(tree: WorkspaceTree, dir: string, names: readonly string[
   return out.sort();
 }
 
+/** The value at JSON Pointer `pointer` in `json`, or undefined when there is none. */
+function atPointer(json: unknown, pointer: string): unknown {
+  let at: unknown = json;
+  for (const raw of pointer.split("/").slice(1)) {
+    const token = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, token)) return undefined;
+    at = (at as Record<string, unknown>)[token];
+  }
+  return at;
+}
+
 function escapeRegExp(text: string): string {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -337,7 +386,7 @@ export function parseKindData(text: string, source: string): KindData {
   const problems: string[] = [];
   const kinds: MemberKind[] = [];
   const seen = new Set<string>();
-  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph }[] }).kinds) {
+  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph; fields?: Record<string, KindField> }[] }).kinds) {
     if (BUILTIN_KIND_NAMES.includes(k.name)) {
       problems.push(`${source}: kind ${k.name} is built in and can't be supplied by a package`);
       continue;
@@ -353,13 +402,16 @@ export function parseKindData(text: string, source: string): KindData {
       probe: {
         ...(k.probe.anyFile ? { anyFile: [...k.probe.anyFile] } : {}),
         ...(k.probe.anyBlock ? { anyBlock: { in: [...k.probe.anyBlock.in], blocks: [...k.probe.anyBlock.blocks] } } : {}),
+        ...(k.probe.anyJsonKey ? { anyJsonKey: { in: [...k.probe.anyJsonKey.in], pointers: [...k.probe.anyJsonKey.pointers] } } : {}),
       },
       precedence: k.precedence,
       shape: "member",
       outputs: { from: "declared", names: [...(k.outputs ?? [])] },
       source,
       ...(k.graph ? { graph: { lexicon: k.graph.lexicon, config: structuredClone(k.graph.config) } } : {}),
+      ...(k.fields ? { fields: structuredClone(k.fields) } : {}),
     });
+    for (const problem of fieldDefaultProblems(k.fields ?? {})) problems.push(`${source}: kind ${k.name} ${problem}`);
   }
   return { kinds, problems };
 }
@@ -370,14 +422,15 @@ export interface PackageKinds extends KindData {
 }
 
 /**
- * Where a package's `exports` send `./workspace-kinds`, or undefined when
- * the package doesn't export that subpath. Only the literal key counts: a
- * `./*` pattern maps the subpath to code, which chant never runs for kinds.
+ * Where a package's `exports` send `./workspace-kinds` (or another data
+ * subpath, such as `./workspace-principals`), or undefined when the package
+ * doesn't export it. Only the literal key counts: a `./*` pattern maps the
+ * subpath to code, which chant never runs for plugin data.
  */
-export function kindsExportTarget(pkg: Record<string, unknown>): string | undefined | { problem: string } {
+export function kindsExportTarget(pkg: Record<string, unknown>, subpath: string = KINDS_SUBPATH): string | undefined | { problem: string } {
   const exports = pkg.exports;
   if (!exports || typeof exports !== "object" || Array.isArray(exports)) return undefined;
-  const entry = (exports as Record<string, unknown>)[KINDS_SUBPATH];
+  const entry = (exports as Record<string, unknown>)[subpath];
   if (entry === undefined) return undefined;
   let target: unknown = entry;
   if (target && typeof target === "object" && !Array.isArray(target)) {
@@ -385,10 +438,10 @@ export function kindsExportTarget(pkg: Record<string, unknown>): string | undefi
     target = conditions.default ?? conditions.import ?? conditions.require;
   }
   if (typeof target !== "string") {
-    return { problem: `exports["${KINDS_SUBPATH}"] must name one file, as a string or a "default" condition` };
+    return { problem: `exports["${subpath}"] must name one file, as a string or a "default" condition` };
   }
   if (!target.startsWith("./") || !target.endsWith(".json")) {
-    return { problem: `exports["${KINDS_SUBPATH}"] is ${target}; it must name a .json file inside the package, since chant reads kinds as data and never runs a package's code` };
+    return { problem: `exports["${subpath}"] is ${target}; it must name a .json file inside the package, since chant reads plugin data as data and never runs a package's code` };
   }
   return target;
 }
@@ -499,6 +552,37 @@ export interface LoadedKinds {
   problems: KindLoadProblem[];
 }
 
+/**
+ * The directory a pin's plugin data is read from: an installed package at
+ * the pinned version, looked up from `workspaceRoot`, or a path pin's
+ * directory, checked against its integrity digest when it has one. Null for
+ * a pin that names neither. Shared by the kinds and the principal classes
+ * (#3080), so both read a pin the same way.
+ */
+export function pinnedPackageDir(pin: PinLike, workspaceRoot: string): { dir: string; source: string } | { problem: string } | null {
+  if (pin.package) {
+    const dir = findInstalledPackage(pin.package, workspaceRoot);
+    if (!dir) return { problem: `pinned package ${pin.package} is not installed; install it to read the kinds it supplies` };
+    let installed: unknown;
+    try {
+      installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
+    } catch {
+      installed = undefined;
+    }
+    if (pin.version && installed !== pin.version) return { problem: `${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed` };
+    return { dir, source: pin.package };
+  }
+  if (pin.path) {
+    const dir = join(workspaceRoot, ...pin.path.split("/"));
+    if (pin.integrity) {
+      const checked = checkPinIntegrity(dir, pin.integrity, pin.path);
+      if (!checked.ok) return { problem: checked.message };
+    }
+    return { dir, source: pin.path };
+  }
+  return null;
+}
+
 /**
  * Build the registry for a workspace: the built-in kinds plus the kinds
  * every pin publishes. `workspaceRoot` is the absolute workspace root; a
@@ -514,38 +598,13 @@ export function loadKindRegistry(pins: readonly PinLike[], workspaceRoot: string
   const owner = new Map<string, string>();
   const clashing = new Set<string>();
   pins.forEach((pin, i) => {
-    let dir: string | undefined;
-    let source: string;
-    if (pin.package) {
-      source = pin.package;
-      dir = findInstalledPackage(pin.package, workspaceRoot);
-      if (!dir) {
-        problems.push({ pin: i, message: `pinned package ${pin.package} is not installed; install it to read the kinds it supplies` });
-        return;
-      }
-      let installed: unknown;
-      try {
-        installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
-      } catch {
-        installed = undefined;
-      }
-      if (pin.version && installed !== pin.version) {
-        problems.push({ pin: i, message: `${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed` });
-        return;
-      }
-    } else if (pin.path) {
-      source = pin.path;
-      dir = join(workspaceRoot, ...pin.path.split("/"));
-      if (pin.integrity) {
-        const checked = checkPinIntegrity(dir, pin.integrity, pin.path);
-        if (!checked.ok) {
-          problems.push({ pin: i, message: checked.message });
-          return;
-        }
-      }
-    } else {
+    const found = pinnedPackageDir(pin, workspaceRoot);
+    if (found === null) return;
+    if ("problem" in found) {
+      problems.push({ pin: i, message: found.problem });
       return;
     }
+    const { dir, source } = found;
     const read = readPackageKinds(dir, source);
     for (const p of read.problems) problems.push({ pin: i, message: p });
     for (const k of read.kinds) {
@@ -583,3 +642,106 @@ export function kindsFileShips(packageDir: string, file: string): boolean {
     return rel === e || rel.startsWith(`${e}/`);
   });
 }
+
+// ── Member fields (#3151) ────────────────────────────────────────────────────
+
+/** A value a member sets, or a kind's default: what a scalar field holds. */
+export type FieldValue = string | number | boolean;
+
+/** Why a value doesn't fit `field`, phrased to follow "the value", or undefined when it fits. */
+function scalarProblem(field: ScalarKindField, value: unknown): string | undefined {
+  const ok = field.type === "integer" ? typeof value === "number" && Number.isInteger(value) : typeof value === field.type;
+  if (!ok) return `is ${JSON.stringify(value)}, and the field is ${field.type === "integer" ? "an integer" : `a ${field.type}`}`;
+  if (field.pattern !== undefined && typeof value === "string") {
+    let re: RegExp;
+    try {
+      re = new RegExp(field.pattern, "u");
+    } catch {
+      return undefined; // Reported once, against the kind, by fieldDefaultProblems.
+    }
+    if (!re.test(value)) return `is ${JSON.stringify(value)}, which does not match ${field.pattern}`;
+  }
+  return undefined;
+}
+
+/** What is wrong with a kind's own field declarations: a pattern that isn't a regular expression, or a default of the wrong type. */
+function fieldDefaultProblems(fields: Record<string, KindField>): string[] {
+  const out: string[] = [];
+  const scalar = (name: string, f: ScalarKindField) => {
+    if (f.pattern !== undefined) {
+      try {
+        new RegExp(f.pattern, "u");
+      } catch {
+        out.push(`declares field ${name} with pattern ${f.pattern}, which is not a regular expression`);
+        return;
+      }
+    }
+    if (f.default === undefined) return;
+    const problem = scalarProblem(f, f.default);
+    if (problem) out.push(`declares field ${name} whose default ${problem}`);
+  };
+  for (const [name, f] of Object.entries(fields)) {
+    if (f.type === "object") for (const [inner, g] of Object.entries(f.properties)) scalar(`${name}.${inner}`, g);
+    else scalar(name, f);
+  }
+  return out;
+}
+
+/** One problem with a member's fields: the field's path under `fields` (`scripts/start`), and why. */
+export interface MemberFieldProblem {
+  path: string;
+  message: string;
+}
+
+export interface MemberFields {
+  /** Every field the kind declares, set from the entry or its default (null when it has none); null when the kind declares no fields. */
+  fields: Record<string, FieldValue | null | Record<string, FieldValue | null>> | null;
+  problems: MemberFieldProblem[];
+}
+
+/**
+ * A member's fields (#3151): the ones its entry sets, checked against what
+ * its kind declares, with every other declared field at its default. A field
+ * the kind doesn't declare, or a value of the wrong type, is a problem, and
+ * the field reads as its default. A kind no registry knows has no fields to
+ * check against, so it reads as null with no problem (WSP003 reports it).
+ */
+export function resolveMemberFields(kind: MemberKind | undefined, given: Record<string, unknown> | null): MemberFields {
+  if (kind === undefined) return { fields: null, problems: [] };
+  const declared = kind.fields;
+  const problems: MemberFieldProblem[] = [];
+  if (declared === undefined) {
+    if (given !== null) problems.push({ path: "", message: `kind ${kind.name} declares no fields, and the entry sets ${Object.keys(given).join(", ") || "an empty fields block"}` });
+    return { fields: null, problems };
+  }
+  const set = given ?? {};
+  for (const name of Object.keys(set)) {
+    if (!(name in declared)) problems.push({ path: name, message: `kind ${kind.name} declares no field ${name}; its fields are ${Object.keys(declared).join(", ")}` });
+  }
+  const scalar = (path: string, field: ScalarKindField, value: unknown): FieldValue | null => {
+    if (value !== undefined) {
+      const problem = scalarProblem(field, value);
+      if (!problem) return value as FieldValue;
+      problems.push({ path, message: `field ${path.replace("/", ".")} ${problem}` });
+    }
+    return field.default ?? null;
+  };
+  const fields: NonNullable<MemberFields["fields"]> = {};
+  for (const [name, field] of Object.entries(declared)) {
+    if (field.type !== "object") {
+      fields[name] = scalar(name, field, set[name]);
+      continue;
+    }
+    const raw = set[name];
+    let inner: Record<string, unknown> = {};
+    if (raw !== undefined) {
+      if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) inner = raw as Record<string, unknown>;
+      else problems.push({ path: name, message: `field ${name} is ${JSON.stringify(raw)}, and the field is an object` });
+    }
+    for (const key of Object.keys(inner)) {
+      if (!(key in field.properties)) problems.push({ path: `${name}/${key}`, message: `kind ${kind.name} declares no field ${name}.${key}; ${name} has ${Object.keys(field.properties).join(", ")}` });
+    }
+    fields[name] = Object.fromEntries(Object.entries(field.properties).map(([key, f]) => [key, scalar(`${name}/${key}`, f, inner[key])]));
+  }
+  return { fields, problems };
+}