dreamteamer 0.27.0 → 0.29.0

package/src/compile.js

@@ -16,7 +16,8 @@ import {
 	baseNameOf, singular, namespaceOf } from './namespace.js';
 // circular on paper in earlier versions — safe: both sides only
 // call at run time, same pattern as store.js ↔ compile.js.
-import { runHarnessAdapters } from './harnesses.js';
+import { runHarnessAdapters, BEGIN, END, INSTRUCTIONS_BEGIN, INSTRUCTIONS_END } from './harnesses.js';
+import { ensureEditorRecommendation, ensureEnvExample } from './workspace.js';
 import { satisfies } from './semver.js';
 import { parseEnvValues } from './env-vars.js';
 import { DERIVED_KINDS, readManifest, runtimeDir, engineId, engineVersion } from './runtime.js';
@@ -676,7 +677,9 @@ export function compile({ root, pkg }) {
 	// what every message in this engine already calls it. Defined HERE, above the namespace pass,
 	// because a namespace error has to name the module by the id the fix is typed with.
 	const moduleId = (n) => slug(String(n).replace(/^@[^/]+\//, ''));
+	const channelOf = new Map(sources.map((s) => [s.name, s.channel]));
 	const declaredEnv = new Map(); // env key -> [module names]
+	const envMeta = new Map();     // env key -> { description, example } — the first module to say wins
 	const moduleIgnores = new Map(); // module name -> non-source folders it declares (strayKindDirs)
 	const moduleDeps = new Map();  // module name -> [module names]      — HARD, must be acyclic
 	const modulePeers = new Map(); // module name -> [collection names]  — SOFT, cannot cycle
@@ -717,9 +720,17 @@ export function compile({ root, pkg }) {
 			if (ok === false) console.warn(`⚠ module ${source.name} declares engine "${range}" — running engine is ${engineVer} (out of range; compile continues)`);
 			else if (ok === null) console.warn(`⚠ module ${source.name}: engine range "${range}" not understood by the built-in checker (see src/semver.js) — not verified`);
 		}
-		for (const k of mpkg.dreamteamer?.env ?? []) {
+		// `dreamteamer.env`: a bare key name, or `{ name, description, example }` so the warning and
+		// `.env.example` can say what the key IS and what a value looks like — a bare `WORK_CALENDARS`
+		// told a first-run operator nothing about ids, addresses or display names (2026-09-24).
+		const envDecl = mpkg.dreamteamer?.env ?? [];
+		if (!Array.isArray(envDecl)) fail(`module "${source.name}": dreamteamer.env must be a list of key names or { name, description, example } objects (got ${JSON.stringify(envDecl)})`);
+		for (const entry of envDecl) {
+			const k = typeof entry === 'string' ? entry : entry?.name;
+			if (typeof k !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) fail(`module "${source.name}": dreamteamer.env entry ${JSON.stringify(entry)} — a key is an identifier (A-Z, 0-9, _) as a string or as { name, description, example }`);
 			if (!declaredEnv.has(k)) declaredEnv.set(k, []);
 			declaredEnv.get(k).push(source.name);
+			if (typeof entry === 'object' && !envMeta.has(k)) envMeta.set(k, { description: entry.description ? String(entry.description) : undefined, example: entry.example !== undefined ? String(entry.example) : undefined });
 		}
 		// Gathered here because mpkg is already parsed; refused below, next to the workspace's own
 		// declaration. The classic layout pushes the ROOT itself as an inline source, whose
@@ -758,7 +769,8 @@ export function compile({ root, pkg }) {
 			const present = new Set([...parsedEnv].filter(([, v]) => v.trim() !== '').map(([k]) => k));
 			for (const [k, mods] of declaredEnv) {
 				if (present.has(k)) continue;
-				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k} — missing from .env (see .env.example)`);
+				const about = envMeta.get(k)?.description ? ` (${envMeta.get(k).description})` : '';
+				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k}${about} — missing from .env (see .env.example)`);
 			}
 			for (const k of declaredVars) {
 				if (present.has(k)) continue;
@@ -767,6 +779,17 @@ export function compile({ root, pkg }) {
 		}
 	}
 
+	// Two root files kept current on every compile, both cheap and both about the FIRST run of a
+	// stranger: `.env.example` lists every declared key with its description, so the warning above
+	// points at a file that actually names them; `.vscode/extensions.json` recommends the editor
+	// extension, so the first window offers it. Both are append/merge-only — nothing authored moves.
+	{
+		const added = ensureEnvExample(root, [...declaredEnv].map(([key, mods]) => ({ key, modules: mods, ...(envMeta.get(key) ?? {}) })),
+			'# secrets for skills and modules go here (copy to .env; .env is never committed).\n# modules declare the env keys they require in their package.json dreamteamer.env list.\n');
+		if (added.length) console.log(`✔ .env.example now names ${added.join(', ')}`);
+		ensureEditorRecommendation(root);
+	}
+
 	// ---- local-assets and postinstall: what `dt install` will do to a checkout -------
 	// `local-assets` are the gitignored heavy folders a checkout SHARES by symlink instead of
 	// duplicating — a browser profile dir, a model cache. Declared, never discovered. Every
@@ -1093,6 +1116,7 @@ export function compile({ root, pkg }) {
 	let mergedCount = 0;
 	let templatedCount = 0;
 	const storageEntries = []; // {name, path, base} per collection — checked for overlap after the loop
+	const wordEntries = [];    // {name, word: singular} per collection — checked for collisions after the loop
 	// Merged descriptors are held, NOT dumped, until every one of them exists: a relation spans two
 	// collections, and the second is not merged yet when the first is reached. So this loop resolves
 	// and validates each descriptor on its own, `materializeRelations` runs over the whole set, and
@@ -1285,8 +1309,14 @@ export function compile({ root, pkg }) {
 			if (raw === '*') {
 				// The workspace module is the orchestrating parent and may reference anything —
 				// including modules that do not exist yet, which is what `tasks.item` means.
-				// Anywhere else a wildcard is a cross-module surface no declaration can cover.
-				if (!groupModules.includes(wsModuleName)) {
+				// Anywhere else a wildcard is a cross-module surface no declaration can cover — and
+				// it is the MODULE AUTHOR's to cover, so the warning is raised only where the author
+				// is: a module in this tree (inline). A module installed from npm or a clone is
+				// somebody else's source; warning its consumers about it on every compile told a
+				// first-run operator four things they could not fix (2026-09-24). The module's own
+				// CI, compiling it alone, still sees them.
+				const authoredHere = groupModules.some((m) => (channelOf.get(m) ?? 'inline') === 'inline');
+				if (!groupModules.includes(wsModuleName) && authoredHere) {
 					console.warn(`⚠ collection ${name}: field "${at}" uses x-reference: '*' outside the workspace module — an unverifiable cross-module surface; name the collections it may target`);
 				}
 				continue;
@@ -1380,6 +1410,16 @@ export function compile({ root, pkg }) {
 		// for `meta.title_field`, promoted to an authorable field. Reference fields pointing here
 		// inherit it (presentation.js), which is what replaces 51 hand-written `x-display` lines.
 		merged.title_template ??= `{{ ${['title', 'name', 'subject'].find((f) => f in labelProps) ?? 'id'} }}`;
+		// The word the CLI accepts beside the name (`dt add task …`). DERIVED by the same inflection
+		// the storage suffix already uses, with the namespace kept (`rnd/projects` → `rnd/project`),
+		// so the two never disagree; AUTHORED where inflection is wrong (`people` → `person`).
+		// Collisions are refused after the loop, once every descriptor has one.
+		if (merged.singular !== undefined && (typeof merged.singular !== 'string' || !merged.singular.trim())) fail(`collection "${name}": \`singular\` must be a non-empty string`);
+		if (merged.singular === undefined) {
+			const ns = namespaceOf(name, namespaces);
+			merged.singular = ns ? `${ns}/${singular(baseNameOf(name, namespaces))}` : singular(name);
+		}
+		wordEntries.push({ name, word: merged.singular });
 		for (const [fieldName, prop] of Object.entries(labelProps)) {
 			if (!prop || typeof prop !== 'object' || Array.isArray(prop)) continue;
 			prop.title ??= titleCase(fieldName);
@@ -1445,6 +1485,19 @@ export function compile({ root, pkg }) {
 	// `owns-data` module prefix and any authored override all already applied). See
 	// namespace.storageOverlaps for what this silently did before it was checked.
 	for (const p of storageOverlaps(storageEntries)) fail(p);
+	// Two collections that answer to one word would make `dt add <word>` a coin toss, so the set of
+	// words — every name and every singular — must be injective. Refused with both names, because
+	// the fix is an authored `singular:` on one of them and the author needs to know which two.
+	{
+		const owners = new Map(); // word -> name
+		for (const { name } of wordEntries) owners.set(name, name);
+		for (const { name, word } of wordEntries) {
+			if (word === name) continue;
+			const other = owners.get(word);
+			if (other && other !== name) fail(`collections "${name}" and "${other}" both answer to the word "${word}" (a name or a singular) — author \`singular:\` on one of them so \`dt add ${word}\` names exactly one collection`);
+			owners.set(word, name);
+		}
+	}
 
 	// ---- modules, projected ---------------------------------------------------------
 	// One record per discovered module, written from what discovery and the package pass already
@@ -1526,6 +1579,19 @@ export function compile({ root, pkg }) {
 		counts.modules = (counts.modules ?? 0) + 1;
 	}
 
+	// ---- the workspace's own hand-written instructions -------------------------------
+	// ONE source, rendered verbatim into every harness's instruction file. It is registered as a
+	// manifest entry for exactly one reason: `staleness` walks manifest sources, so a file that is
+	// not one can be edited forever without `dt status` ever saying the harness files lag it — and a
+	// silent lag on the file carrying the operator's rules is the worst possible thing to be silent
+	// about. The runtime copy is never read by anything; the manifest ENTRY is the whole point.
+	const instructionsPath = path.join(root, INSTRUCTIONS_SOURCE);
+	if (fs.existsSync(instructionsPath)) {
+		const bytes = fs.readFileSync(instructionsPath);
+		refuseManagedMarkers(bytes.toString('utf8'), rel(instructionsPath));
+		entries.set('instructions.md', { sources: [{ path: rel(instructionsPath), hash: sha256(bytes) }], bytes });
+	}
+
 	// ---- unresolved references are compile errors (an agent's declared skills)
 	const skillIds = new Set([...entries.keys()].filter((k) => k.startsWith('skills/')).map((k) => k.split('/')[1]));
 	for (const [rt, e] of entries) {
@@ -1877,6 +1943,14 @@ export function staleness(root) {
 			}
 		}
 	}
+	// ⚠ `dreamteamer.md` is a compile source that is NOT under a KIND directory, so the walk above
+	// cannot reach it — and its CREATION is the one moment that matters most: day one in an adopting
+	// workspace, when no harness file carries an instructions block yet. Every later EDIT was already
+	// caught by the manifest-source walk at the top of this function; only the first write was silent,
+	// and it reported `.dreamteamer is fresh` while the rules reached no agent at all.
+	if (fs.existsSync(path.join(root, INSTRUCTIONS_SOURCE)) && !known.has(INSTRUCTIONS_SOURCE)) {
+		stale.push(`${INSTRUCTIONS_SOURCE} (new, uncompiled)`);
+	}
 	return { compiled: true, stale, manifest };
 }
 
@@ -1965,6 +2039,42 @@ function descriptorAjv() {
 	return _descriptorAjv;
 }
 
+// ⚠ A MANAGED MARKER INSIDE `dreamteamer.md` IS A REFUSAL, not something to escape around.
+// The file is rendered VERBATIM into a managed block, and `writeBlock` finds that block by the FIRST
+// occurrence of its begin marker anywhere in the file — so a marker quoted inside the rendered text
+// is found before the real delimiter. Both directions were measured on a fixture:
+//
+//   - quoting the ORIENTATION pair: the orientation pass rewrites the quoted region, the instructions
+//     pass that runs immediately after restores it from source, and the real orientation block is
+//     never touched again. It silently keeps describing the schema of the day it was written, while
+//     `compile` exits 0 and `status` reports the runtime fresh.
+//   - quoting the INSTRUCTIONS end marker: the block is closed at the quote and a second end line is
+//     appended, so all three committed root files grow by ~40 bytes and one duplicated line per
+//     compile, without ever reaching a fixed point.
+//
+// Escaping the markers on the way out is the alternative, and it is not one: the whole promise of
+// this file is that what was written is what every agent reads, and an escaped marker is not that.
+// A rule ABOUT the block describes it instead of quoting it.
+/** The one hand-written root source. Named once: `compile` reads it and `staleness` looks for it. */
+export const INSTRUCTIONS_SOURCE = 'dreamteamer.md';
+
+const MANAGED_MARKERS = [
+	['the orientation block', BEGIN],
+	['the orientation block', END],
+	['the instructions block', INSTRUCTIONS_BEGIN],
+	['the instructions block', INSTRUCTIONS_END],
+];
+
+function refuseManagedMarkers(text, srcPath) {
+	const lines = text.split('\n');
+	for (const [i, line] of lines.entries()) {
+		for (const [which, marker] of MANAGED_MARKERS) {
+			if (!line.includes(marker)) continue;
+			fail(`${srcPath}:${i + 1}: contains the managed marker ${marker}, which delimits ${which} in the harness files. This source is rendered verbatim into that block, so the quoted copy is found before the real delimiter and the block is rewritten around the wrong place. Describe the block instead of quoting its marker.`);
+		}
+	}
+}
+
 function fail(msg) {
 	throw new CompileError(`compile error: ${msg}`);
 }