dreamteamer 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.20.0",
+	"version": "0.21.0",
 	"description": "A workspace compiler for coding agents — schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",

package/skills/using-dreamteamer/references/collections.md

@@ -227,6 +227,45 @@ Two gates around it:
 - ⚠ **An overlay can add fields but cannot remove an inherited one.** If the shape is wrong for
   the module rather than just for this workspace, fix the base.
 
+## `x-choices` — what an enum VALUE looks like
+
+An enum value carries a label and nothing else by default: a surface gets `{ text, value }` and
+draws the value. `x-choices` is an OPTIONAL sparse map, keyed by the value, that gives a surface
+more to draw with — a board grouping by the field, a dropdown in a form, anything reading
+`edit_options.choices`.
+
+```yaml
+lane:
+  type: string
+  enum: [alpha, bravo, charlie]
+  x-choices:
+    alpha:
+      label: Alpha team          # what a surface shows; the stored VALUE is still `alpha`
+      description: the one that ships
+      icon: rocket               # a codicon name …
+      color: charts.blue         # a theme colour id — the accent
+      background: charts.blue    #   … and the fill
+    bravo:
+      icon: assets/icons/lucide/anchor   # … OR a reference to a `codec: file` record
+```
+
+- **Sparse and additive.** Decorate one value, or none. A value with no entry projects exactly as it
+  did before this keyword existed, so adding it changes nothing that already works.
+- **`enum` still owns the value set AND its order.** A map key cannot add, remove or reorder a
+  value — which matters, because a grouped view takes its band order from the enum.
+- **Five keys, and only five** — `label` · `description` · `icon` · `color` · `background`, each an
+  optional string. Anything else in an entry is dropped: the projection copies by name, so a
+  descriptor cannot inject keys into a contract every surface reads.
+- **`label` becomes `text`.** So a workspace can relabel a value without touching the value, and no
+  stored record moves.
+- **`icon` is a codicon name or a reference to a record of a `codec: file` collection.** A codicon
+  name never contains a slash and a record reference always does, so the surface decides which
+  without a second keyword.
+- **Colours are theme colour ids, not hex.** A hex is authored against one theme and wrong in the
+  other.
+- **Both mistakes warn rather than fail** — a key that is not one of the enum's values, and the
+  keyword on a field with no enum. See the message catalog below.
+
 ## the reference contract — `x-reference` across the module graph
 
 Every `x-reference` target must be one of: a **core** collection (the entity kinds plus `repos`)
@@ -291,6 +330,8 @@ collection author actually meets. (⚠ = warning: it compiled, and you should st
 | `cyclic module dependencies: a → b → a` | concept-level links declared as module deps | the collection belongs in `peerDependencies` |
 | relation refusals (`stamps a mirror onto…`, `declared on both sides…`) | the relation rules | `data-modeling.md` Part VI |
 | ⚠ `x-unique on "f" is inert` | a relation keyword with no relation — nothing enforces it | declare the inverse, or drop it |
+| ⚠ `x-choices on "f" has an entry for "k"` | it decorates enum VALUES and `k` is not one — a typo, or a value since removed | fix the spelling, or drop the entry |
+| ⚠ `x-choices on "f" is inert` | the keyword on a field that declares no enum — nothing reads it | give the field an enum, or drop the keyword |
 | ⚠ `collection … has no description` | it renders as a bare name in the orientation block every session loads | write the sentence (`data-modeling.md` §18) |
 | ⚠ `module "…" contributed no recognised sources` | its folders match no kind and it ships no UI bundle | usually a layout or naming mistake |
 | ⚠ `module X: <channel> copy shadows <channel> copy` | the same module delivered twice — the more local wins (npm-link semantics) | intended for dev; otherwise remove one |

package/src/compile.js

@@ -1315,6 +1315,25 @@ export function compile({ root, pkg }) {
 			if (h['x-unique'] === true && h['x-inverse'] === undefined && h['x-inverse-of'] === undefined) {
 				console.warn(`⚠ collection ${name}: x-unique on "${fieldName}" is inert — it is a RELATION keyword, enforced only while the store maintains a mirror, and this field declares no x-inverse. Nothing constrains the value. Declare the relation (dreamteamer update-field ${name} --name ${fieldName} --inverse) or drop x-unique.`);
 			}
+			// `x-choices` decorates ENUM VALUES (presentation.js#choiceRow, 0.21.0), and both ways of
+			// getting it wrong are SILENT: a key that is not a value decorates nothing, and the keyword
+			// on a non-enum field is read by no one at all. Either way the author sees no error and no
+			// decoration — on a surface they are probably not looking at while editing the descriptor.
+			// ⚠ WARNINGS, not failures, for the same reason as x-unique directly above: neither breaks
+			// anything today, and a descriptor mid-edit must stay compilable.
+			const choices = h['x-choices'];
+			if (choices && typeof choices === 'object' && !Array.isArray(choices)) {
+				const values = Array.isArray(h.enum) ? h.enum.map(String) : null;
+				if (!values) {
+					console.warn(`⚠ collection ${name}: x-choices on "${fieldName}" is inert — it decorates the values of an enum, and this field declares no enum. Nothing reads it.`);
+				} else {
+					// Named per offending key rather than "some keys are wrong", and the legal values are
+					// quoted so the fix needs no second lookup — the same shape as every other warning here.
+					for (const k of Object.keys(choices)) {
+						if (!values.includes(k)) console.warn(`⚠ collection ${name}: x-choices on "${fieldName}" has an entry for "${k}", which is not one of its enum values (${values.join(', ')}) — it decorates nothing. Fix the spelling, or drop the entry.`);
+					}
+				}
+			}
 		}
 		const rt = path.join('collections', `${name}.collection.yaml`);
 		entries.set(rt, { sources: descriptorSources, bytes: Buffer.from(dump(merged)) });

package/src/presentation.js

@@ -152,6 +152,33 @@ function titleTemplateOf(prop, descriptors) {
 	return typeof first === 'string' && first.length > 0 && inherited.every((v) => v === first) ? first : undefined;
 }
 
+// The keys a descriptor may attach to an enum VALUE through `x-choices` (0.21.0), beyond the label.
+// Copied BY NAME rather than spread: a descriptor is authored data, and spreading whatever it
+// happens to carry would let a workspace inject arbitrary keys into a contract every surface reads.
+// One line is the whole vocabulary, which is also what makes it readable from the consuming side.
+//
+// `icon` is a codicon name OR a reference to a record of a `codec: file` collection — the surface
+// decides which by whether it resolves as a reference, so no second keyword and no set of known
+// collection names. `color`/`background` are theme colour ids for the same reason a hex is not one:
+// a hex is authored against one theme and wrong in the other.
+const CHOICE_KEYS = ['description', 'icon', 'color', 'background'];
+
+/**
+ * One `choices` row: `{ text, value }` as it has always been, plus whatever `x-choices` declared.
+ *
+ * ⚠ PURELY ADDITIVE. A value with no entry projects byte-identically to what it projected before
+ * this existed, which is the only reason not one of the descriptors already in the wild had to
+ * change. `label` arrives as `text` — the key every surface already reads — so a workspace can
+ * relabel a value without touching the value, and a stored record never moves.
+ */
+function choiceRow(v, entry) {
+	const row = { text: String(entry?.label ?? v), value: v };
+	if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+		for (const k of CHOICE_KEYS) if (typeof entry[k] === 'string' && entry[k].length > 0) row[k] = entry[k];
+	}
+	return row;
+}
+
 function fieldRow(d, name, prop, isRequired, descriptors) {
 	const meta = { collection: d.name, field: name };
 	if (isRequired) meta.required = true;
@@ -233,7 +260,7 @@ function fieldRow(d, name, prop, isRequired, descriptors) {
 	}
 
 	if (Array.isArray(prop.enum) && prop.enum.length > 0) {
-		meta.edit_options = { choices: prop.enum.map((v) => ({ text: String(v), value: v })) };
+		meta.edit_options = { choices: prop.enum.map((v) => choiceRow(v, prop['x-choices']?.[v])) };
 	}
 	const tpl = titleTemplateOf(prop, descriptors);
 	if (typeof tpl === 'string' && tpl.length > 0) meta.view_options = { ...meta.view_options, template: tpl };