dreamteamer 0.26.0 → 0.28.0

package/src/presentation.js

@@ -82,6 +82,10 @@ function collectionRow(d) {
 	// it — the extension reads the presentation contract, not raw descriptors.
 	if (typeof d.sort_field === 'string') meta.sort_field = d.sort_field;
 
+	// The collection's PARTITION, and the reserved value `system` is how a surface knows to draw this
+	// collection as the workspace's machinery rather than in the record tree. It is carried in `meta`
+	// beside the other presentation keys because that is the question it answers; the top-level
+	// `system` below answers a different one and they must never be folded together.
 	if (typeof d.group === 'string') meta.group = d.group;
 	if (typeof d.description === 'string' && d.description.length > 0) meta.description = d.description;
 	// ⚠ `system` IS NOT `readonly`, AND SAYING SO COST A RELEASE. Until 0.19.0 the two were the
@@ -107,10 +111,25 @@ function collectionRow(d) {
 	//      already answers with its own sentence naming the fix, which is the contract the schema
 	//      surfaces are built on.
 	//
-	// `system` STAYS and is unchanged: the CLI and REST dispatch key on it, and it is what puts a
-	// kind in the schema surface rather than the data one. A consumer that disables editing must
-	// key on `meta.readonly` (per field, as `id`, `last-modified` and relation mirrors do) or on
-	// the verb it is about to offer — never on `system`.
+	// `system` STAYS and is unchanged: the CLI and REST dispatch key on it. A consumer that disables
+	// editing must key on `meta.readonly` (per field, as `id`, `last-modified` and relation mirrors
+	// do) or on the verb it is about to offer — never on `system`.
+	//
+	// ⚠ AND `system` IS NO LONGER WHAT PUTS A KIND ON THE SCHEMA SURFACE — that clause stood here
+	// until `repos` and belongs to `meta.group` now. TWO QUESTIONS, KEPT SEPARATE, exactly as
+	// `buildCollectionsIndex` in src/harnesses.js keeps them:
+	//
+	//   `system`       decides HOW A WRITE IS PERFORMED. Is this collection's storage the compiled
+	//                  runtime? The CLI and the REST layer dispatch on it, and a surface that gets
+	//                  it wrong answers 400 to a write the store would have accepted.
+	//   `meta.group`   decides WHERE THE COLLECTION IS DRAWN. Its reserved value `system` says this
+	//                  is the workspace's machinery rather than one of its domain nouns, and folds
+	//                  the collection out of the record tree and onto the schema surface.
+	//
+	// The two agreed for every collection until `repos` — machinery whose records are ordinary,
+	// hand-edited files under `data/` — and it is why they must never be collapsed into one: a
+	// surface routing a `repos` write by the partition sends it to the system write path, whose
+	// entity ops know no such kind, and the write dies as a 400. Measured.
 	const system = d.storage?.base === 'runtime';
 	return { collection: d.name, meta, system };
 }

package/src/ref.js

@@ -1,15 +1,37 @@
-// split "<collection>/<id>" against the DECLARED collections — longest prefix at a "/" boundary,
-// because both collection names and ids may contain slashes (namespaces; path-shaped ids).
+// The words a collection answers to on the command line: its declared name and its `singular`
+// (compile stamps one on every descriptor — derived by inflection, authorable where inflection is
+// wrong — and refuses two collections whose words collide). `dt add task …` and `dt add tasks …`
+// are the same call. ⚠ TYPED INPUT ONLY: a reference VALUE inside a record (`tasks/kickoff`) is
+// parsed by namespace.js's parseRef against declared names and never learns the singular, so
+// `task/kickoff` in a field stays the dangling reference `check` reports it as.
+function* words(descriptors) {
+	for (const [name, d] of descriptors) {
+		yield [name, name];
+		if (d?.singular && d.singular !== name) yield [d.singular, name];
+	}
+}
+
+/** The declared collection a typed word names — the name itself or its singular — else null. */
+export function canonicalCollection(descriptors, word) {
+	if (descriptors.has(word)) return word;
+	for (const [w, name] of words(descriptors)) if (w === word) return name;
+	return null;
+}
+
+// split "<collection>/<id>" against the DECLARED collections and their singulars — longest prefix
+// at a "/" boundary, because both collection names and ids may contain slashes (namespaces;
+// path-shaped ids). The collection returned is always the declared NAME, whichever word was typed.
 export function splitRef(descriptors, ref) {
 	let best = null;
-	for (const name of descriptors.keys()) {
-		if (ref === name || ref.startsWith(name + '/')) {
-			if (!best || name.length > best.length) best = name;
+	let bestName = null;
+	for (const [w, name] of words(descriptors)) {
+		if (ref === w || ref.startsWith(w + '/')) {
+			if (!best || w.length > best.length) { best = w; bestName = name; }
 		}
 	}
 	if (!best) throw new Error(`unknown collection in reference "${ref}" (known: ${[...descriptors.keys()].sort().join(', ')})`);
 	if (ref === best) throw new Error(`reference "${ref}" names a collection but no record id`);
-	return { collection: best, id: ref.slice(best.length + 1) };
+	return { collection: bestName, id: ref.slice(best.length + 1) };
 }
 
 /**

package/src/schema-ops.js

@@ -755,6 +755,9 @@ const COLLECTION_SETTABLE = {
 	title: (v) => String(v),
 	title_template: (v) => String(v),
 	icon: (v) => String(v),
+	// The collection's partition. `group=system` is the reserved value: it moves the collection out
+	// of the block's domain listing and onto a surface's schema surface, and changes nothing about
+	// where its records live or whether they can be written.
 	group: (v) => String(v),
 	sort_field: (v) => String(v),
 	order: (v) => {

package/src/workspace.js

@@ -49,3 +49,53 @@ export function nestedAsModule(outer, inner) {
 		.split(path.sep)
 		.some((seg) => MODULE_SEGMENTS.has(seg));
 }
+
+/** The VS Code-family extension for this workspace, as the editor learns of it: a recommendation
+ *  in `.vscode/extensions.json`, which VS Code, Cursor and code-server all read on open and offer to
+ *  install. Written by `init` and kept current by `compile`, because a compiled workspace that never
+ *  names its editor left a first-run agent searching a registry for the id (measured 2026-09-24:
+ *  three install attempts, two of them into a directory the running editor did not read). An
+ *  existing file is MERGED, never replaced: a file the operator authored (comments included) is left
+ *  alone whenever it already names the extension; one that does not is re-read as JSON and gains the
+ *  id, and one that is neither is left with a warning rather than clobbered. */
+export const EDITOR_EXTENSION_ID = 'dreamteamer.dreamteamer-vscode';
+export function ensureEditorRecommendation(root, warn = console.warn) {
+	const file = path.join(root, '.vscode', 'extensions.json');
+	if (!fs.existsSync(file)) {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.writeFileSync(file, JSON.stringify({ recommendations: [EDITOR_EXTENSION_ID] }, null, '\t') + '\n');
+		return 'written';
+	}
+	const text = fs.readFileSync(file, 'utf8');
+	if (text.includes(EDITOR_EXTENSION_ID)) return 'present';
+	let parsed;
+	try { parsed = JSON.parse(text); } catch {
+		warn(`⚠ .vscode/extensions.json does not recommend ${EDITOR_EXTENSION_ID} and is not plain JSON, so it was left alone — add the id to its "recommendations" by hand`);
+		return 'left';
+	}
+	if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) { warn(`⚠ .vscode/extensions.json is not an object — left alone; add ${EDITOR_EXTENSION_ID} to "recommendations" by hand`); return 'left'; }
+	parsed.recommendations = [...(Array.isArray(parsed.recommendations) ? parsed.recommendations : []), EDITOR_EXTENSION_ID];
+	fs.writeFileSync(file, JSON.stringify(parsed, null, '\t') + '\n');
+	return 'merged';
+}
+
+/** `.env.example` lists every env key the installed modules declare — the file the missing-key
+ *  warning points at, which used to carry two comment lines and none of the keys it was cited for.
+ *  Append-only and idempotent: a key already named in the file (as `KEY=` or `# KEY`) is not added
+ *  again, and nothing an operator wrote is touched. Values never appear here — an example does. */
+export function ensureEnvExample(root, entries, header = '') {
+	if (!entries.length) return [];
+	const file = path.join(root, '.env.example');
+	const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : header;
+	const named = new Set([...existing.matchAll(/^\s*#?\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)].map((m) => m[1]));
+	const added = [];
+	let out = existing;
+	for (const e of entries) {
+		if (named.has(e.key)) continue;
+		const who = e.modules?.length ? ` (module ${e.modules.join(', ')})` : '';
+		out = out.trimEnd() + `\n\n# ${e.description ?? `declared by ${e.modules.join(', ')}`}${e.description ? who : ''}\n${e.key}=${e.example ?? ''}\n`;
+		added.push(e.key);
+	}
+	if (added.length) fs.writeFileSync(file, out.replace(/^\n+/, ''));
+	return added;
+}