dreamteamer 0.24.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.24.1",
+	"version": "0.25.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/src/collections-cli.js

@@ -172,8 +172,20 @@ export function collectionCommand(ws, collection, verb, args) {
 			}
 			if (flags.from) throw new Error(`--from imports a file as a record, and "${collection}" is not a \`codec: file\` collection`);
 			const fields = coerceArrays(d, stripMeta(flags));
-			const { id, file } = store.add(collection, fields, { id: flags.id });
-			flags.json ? emit(JSON.stringify({ id, path: rel(ws.root, file) })) : console.log(`✔ ${rel(ws.root, file)}`);
+			const { id, file, idFallback } = store.add(collection, fields, { id: flags.id });
+			flags.json
+				? emit(JSON.stringify({ id, path: rel(ws.root, file), ...(idFallback ? { idFallback } : {}) }))
+				: console.log(`✔ ${rel(ws.root, file)}`);
+			// ⚠ SAY IT, EVERY TIME. The id was derived from a hash because the value it is generated
+			// from carries no a-z0-9 — the write succeeded and the record is fine, but the id is
+			// unreadable and unguessable, and nobody finds that out until they try to type it. By
+			// then other records reference it and renaming is a migration.
+			if (idFallback && !flags.json) {
+				console.warn(`⚠ id "${idFallback.id}" is a hash, not a name — "${idFallback.field}" (${idFallback.value}) has no latin characters to slug.`);
+				console.warn('  give this collection a latin handle: id.generate accepts an ORDERED LIST and takes the first that renders —');
+				console.warn("      id: { generate: ['{{ code }}', '{{ name | slug }}'] }");
+				console.warn('  or pass --id on this write. Renaming later rewrites every reference.');
+			}
 			return 0;
 		}
 		case 'set': {

package/src/commit.js

@@ -415,7 +415,27 @@ function assertResolvable(store, records, matched) {
 	}
 }
 
-export function commitPending(store, { only = [], message, dryRun = false } = {}) {
+export function commitPending(store, opts = {}) {
+	// ⚠ THE WHOLE VERB TAKES THE WRITE LOCK, PLANNING INCLUDED — not just the two git calls at the
+	// end. `dt commit` was the one write path that took no lock at all: it sampled `git status`,
+	// planned a sweep from what it saw, then ran `git add` and `git commit`. Two sessions doing that
+	// at once collide on `.git/index.lock` and `HEAD`, which are repository-wide and do not care
+	// that the records are unrelated — and the loser is not told, so its records stay on disk,
+	// uncommitted, for the next unscoped commit to sweep under someone else's subject.
+	//
+	// The lock has to cover the PLAN as well as the write, because a plan built from a `git status`
+	// taken before a sibling's commit describes a tree that no longer exists by the time it is
+	// applied. Serialising only the git calls would trade a lock collision for a stale plan, which
+	// is the same loss wearing a quieter failure.
+	//
+	// This matters more than it reads: since auto-commit was turned off, a write does not commit, so
+	// the window between writing a record and publishing it is a whole session rather than
+	// milliseconds — and this vault family is routinely operated by several concurrent sessions.
+	if (opts.dryRun) return commitPlan(store, opts);   // reads only; nothing to serialize
+	return store.withWriteLock(() => commitPlan(store, opts));
+}
+
+function commitPlan(store, { only = [], message, dryRun = false } = {}) {
 	// Targets are resolved BEFORE anything is committed, so one bad target in a list of good ones
 	// leaves the whole tree untouched rather than committing a prefix of what was asked for.
 	const targets = parseTargets(store.descriptors, only);

package/src/compile.js

@@ -1832,13 +1832,46 @@ export function staleness(root) {
 	let pkg = {};
 	try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* no pkg */ }
 	const wm = pkg.dreamteamer?.['workspace-module'];
-	const roots = [...(wm ? [] : [root]), ...discoverModules(root, pkg).modules.map((m) => m.root)];
-	for (const r of roots) {
+	const found = discoverModules(root, pkg);
+	// ⚠ A DISABLED ENTITY IS NOT A NEW ONE, AND THIS IS THE DIFFERENCE BETWEEN A WARNING AND A LIE.
+	// `compile` skips every source named by an ENTITY-LEVEL `dreamteamer.disable` entry
+	// (`<module>/<entity>`) before `addEntry`, so that file's path never becomes a manifest source.
+	// This scan used to have no knowledge of that filter, so it found the file on disk, found it
+	// absent from `known`, and reported it `(new, uncompiled)` — permanently, because every future
+	// compile skips it exactly the same way. The workspace was told to run a compile that could not
+	// possibly clear the warning, at every tool entry, for as long as the disable stood.
+	//
+	// Two consuming workspaces were sitting in that state when this was found, one of them with a
+	// clean compile seconds earlier. The MODULE-level form (a bare name) needs no handling here:
+	// `discoverModules` drops the whole module, so its files are never walked at all.
+	//
+	// The root itself, when a workspace declares no `workspace-module`, is not a named module, so no
+	// `<module>/<entity>` entry can address its sources — it is walked unfiltered, as before.
+	const disabledEntities = new Set((pkg.dreamteamer?.disable ?? []).filter((d) => typeof d === 'string' && d.includes('/')));
+	const roots = [...(wm ? [] : [{ name: null, root }]), ...found.modules.map((m) => ({ name: m.name, root: m.root }))];
+	for (const { name: moduleName, root: r } of roots) {
 		for (const kind of KINDS) {
 			const dir = kindDir(r, kind);
 			if (!fs.existsSync(dir)) continue;
 			for (const f of walk(dir)) {
-				if (isProofFixture(kind, path.relative(dir, f).split(path.sep).join('/'))) continue;
+				const rel = path.relative(dir, f).split(path.sep).join('/');
+				if (isProofFixture(kind, rel)) continue;
+				// The SAME id derivation `compile` uses, so the two can never disagree about which
+				// file a disable entry names.
+				//
+				// ⚠ AND THE TWO KINDS DERIVE IT DIFFERENTLY. `compile` walks collections recursively,
+				// so a collection's id is its whole relative path (it may carry a namespace segment,
+				// `<ns>/<name>`); every other kind it reads with a flat `readdirSync`, so the entity
+				// is the TOP-LEVEL entry and a folder-shaped one — a skill is a directory holding
+				// `SKILL.md` — is named by the folder alone. Matching the full path for those meant a
+				// disabled SKILL still counted as stale, because `working-with-tasks/SKILL.md` is not
+				// `working-with-tasks`. Caught against a real workspace whose disable list held one
+				// of each: the ui-view cleared and the skill did not.
+				if (moduleName) {
+					const relEntity = kind === 'collections' ? rel : rel.split('/')[0];
+					const entityId = relEntity.replace(/\.[^.]+\.(yaml|md|json)$/, '');
+					if (disabledEntities.has(`${moduleName}/${entityId}`)) continue;
+				}
 				const relPath = path.relative(root, f);
 				if (!known.has(relPath)) stale.push(`${relPath} (new, uncompiled)`);
 			}

package/src/server.js

@@ -131,7 +131,7 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 		// branch is here, at the surface, exactly as the CLI's interceptor is.
 		if (store.descriptors.get(req.params.name)?.storage?.base === 'runtime') {
 			const out = systemWrite(ws, store, req);
-			reload();
+			if (!out?.dryRun) reload();
 			return res.json(out);
 		}
 		const { id: explicitId, ...fields } = req.body ?? {};
@@ -142,7 +142,7 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 	api.patch('/collections/:name/records/*id', (req, res) => {
 		if (store.descriptors.get(req.params.name)?.storage?.base === 'runtime') {
 			const out = systemWrite(ws, store, req);
-			reload();
+			if (!out?.dryRun) reload();
 			return res.json(out);
 		}
 		// clients may echo synthetic response keys back on save (id/path/last-modified/the two
@@ -182,7 +182,7 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 	api.delete('/collections/:name/records/*id', (req, res) => {
 		if (store.descriptors.get(req.params.name)?.storage?.base === 'runtime') {
 			const out = systemWrite(ws, store, req);
-			reload();
+			if (!out?.dryRun) reload();
 			return res.json(out);
 		}
 		store.rm(req.params.name, idParam(req), { force: req.query.force === 'true' });
@@ -224,7 +224,9 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 	const schemaOp = (fn) => (req, res, next) => {
 		try {
 			const out = fn(req);
-			reload();
+			// A dry run wrote nothing, so there is nothing to reload — and reloading would imply to
+			// every reader that something changed.
+			if (!out?.dryRun) reload();
 			res.json(out);
 		} catch (e) { next(e); }
 	};
@@ -250,9 +252,14 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 	// `…/name` rather than a body key, because renaming a field is a DIFFERENT act from editing one:
 	// it rewrites the key in every record and in every descriptor, view and binding that names it.
 	api.patch('/collections/:name/fields/:field/name', schemaOp((req) =>
-		renameField(ws, store, req.params.name, req.params.field, String(req.body?.to ?? ''), { moduleId: moduleParam(req) })));
-	api.delete('/collections/:name/fields/:field', schemaOp((req) =>
-		removeField(ws, store, req.params.name, req.params.field, { moduleId: moduleParam(req) })));
+		renameField(ws, store, req.params.name, req.params.field, String(req.body?.to ?? ''),
+			{ moduleId: moduleParam(req), dryRun: wantsDryRun(req) })));
+	api.delete('/collections/:name/fields/:field', schemaOp((req) => {
+		// `removeField` computes no plan, so a dry-run request is refused rather than performed —
+		// clearing a value out of every record is the last thing to guess at.
+		if (wantsDryRun(req)) throw new DryRunUnsupported('fields:rm');
+		return removeField(ws, store, req.params.name, req.params.field, { moduleId: moduleParam(req) });
+	}));
 
 	// per-record revision diff + revert (M3: git already has the data; this exposes it)
 	api.get('/history-diff/:name/*id', (req, res) => {
@@ -273,6 +280,7 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 	// error contract: store errors are 400 (validation) / 404 (missing) / 409 (referenced)
 	app.use((err, req, res, next) => {
 		const msg = err.message ?? String(err);
+		if (err instanceof DryRunUnsupported) return res.status(400).json({ error: msg, 'dry-run': 'unsupported' });
 		const code = err instanceof CompileError ? 400
 			: /no such record/.test(msg) ? 404
 			: /referenced by|already exists/.test(msg) ? 409 : 400;
@@ -333,11 +341,53 @@ function moduleParam(req) {
  * name; renaming any of them is a cross-repo activation failure, so the new operations are new
  * exports beside them.
  */
+// ⚠ A CLIENT ASKING FOR A PLAN MUST NEVER GET A WRITE. `?dry-run=true` was read by nothing here:
+// the query string was parsed for `force` and nothing else, so every request asking what a
+// destructive verb WOULD do performed it instead — a module removal, a collection moved between
+// modules, a field renamed across every record and descriptor that names it. The CLI has taken
+// `--dry-run` on those verbs since the plan/apply split, which is exactly what makes the omission
+// dangerous: the two surfaces are documented as the same operation, so a client has every reason to
+// believe the flag is honoured.
+//
+// Three ops can produce a plan (`removeModule`, `moveCollection`, `renameField` — each returns
+// `{…plan, dryRun: true}` and touches nothing). For anything else the answer is a REFUSAL, never a
+// write: an op that cannot describe itself must not be guessed at, and returning a 200 with an empty
+// plan would read as "this would change nothing", which is the opposite of the truth.
+export function wantsDryRun(req) {
+	const v = req?.query?.['dry-run'];
+	return v === true || v === 'true' || v === '1';
+}
+
+/** The `<kind>:<verb>` pairs whose op accepts `dryRun` and returns a plan instead of writing. */
+export const DRY_RUNNABLE = new Set(['modules:rm', 'collections:move', 'fields:rename']);
+
+export class DryRunUnsupported extends Error {
+	constructor(what) {
+		super(`dry-run is not supported for ${what} — supported: ${[...DRY_RUNNABLE].join(', ')}. `
+			+ 'Nothing was written; re-send without dry-run to perform it.');
+		this.status = 400;
+		this.dryRunUnsupported = what;
+	}
+}
+
 function systemWrite(ws, store, req) {
 	const kind = req.params.name;
 	const id = req.params.id ? idParam(req) : undefined;
 	const moduleId = moduleParam(req);
 	const b = req.body ?? {};
+	const dryRun = wantsDryRun(req);
+	if (dryRun) {
+		// Decide from the SAME shape the dispatch below uses, so the two can never disagree about
+		// which op a request reaches — a refusal that names a different verb than the one that would
+		// have run is worse than no refusal.
+		if (req.method === 'DELETE' && kind === 'modules') {
+			return removeModule(ws, store, id, { force: req.query.force === 'true', dryRun: true });
+		}
+		if (req.method === 'PATCH' && kind === 'collections' && typeof b.module === 'string') {
+			return moveCollection(ws, store, id, b.module, { dryRun: true });
+		}
+		throw new DryRunUnsupported(`${kind}:${req.method.toLowerCase()}`);
+	}
 	if (req.method === 'POST') {
 		if (kind === 'collections') return createCollection(ws, store, { ...b, moduleId });
 		if (kind === 'modules') return createModule(ws, store, b);

package/src/store.js

@@ -502,7 +502,15 @@ export class Store {
 		// the KEYS, not a copy of them: `generateId` iterates this once and only for a `{{ seq }}`
 		// template, so materializing the whole id list was an O(N) allocation per add that almost
 		// every collection threw away unread.
-		const id = explicitId ?? generateId(d.id?.generate ?? '{{ name | slug }}', fields, this.ids(collection).keys());
+		// An id derived from a hash rather than from readable text is reported back to the caller, not
+		// swallowed — see the `slug` filter's note. The write still happens: an id must be produced,
+		// and refusing here would break every workspace whose values are not latin. What must not
+		// happen is that nobody is told.
+		let idFallback = null;
+		const id = explicitId ?? generateId(
+			d.id?.generate ?? '{{ name | slug }}', fields, this.ids(collection).keys(),
+			{ onFallback: (f) => { idFallback = f; } },
+		);
 		if (d.id?.pattern && !patternRe(d.id.pattern).test(id)) {
 			throw new Error(`id "${id}" does not match pattern ${d.id.pattern} — nothing was written.`);
 		}
@@ -545,7 +553,7 @@ export class Store {
 			}, d.storage.repo ?? '.');
 			// LAST, after the commit: the key it is re-stated under carries the sha, and `commit` moves it
 			this._indexAdd(collection, memo, id, file);
-			return { id, file };
+			return { id, file, idFallback };
 		});
 	}
 
@@ -1003,13 +1011,35 @@ export class Store {
 		return { touched, rewrites, skipped, ambiguous, restore };
 	}
 
+	/** Where the cross-process write lock lives.
+	 *
+	 *  ⚠ IT BELONGS TO THE REPOSITORY, NOT TO THE CHECKOUT. What it protects is `.git/index.lock`
+	 *  and `HEAD` — both of which are SHARED by every worktree of a repo, while `.dreamteamer/` is
+	 *  gitignored build output that each checkout has its own copy of. A lock in the runtime folder
+	 *  therefore serialized a single checkout against itself and left two worktrees of one repo free
+	 *  to collide on exactly the files it exists to guard. `--git-common-dir` is the one path that
+	 *  resolves to the same place from the primary and from every linked worktree.
+	 *
+	 *  The runtime folder stays the fallback, because a workspace need not be a git repo at all and
+	 *  a store that cannot lock is worse than one that locks narrowly. */
+	writeLockPath() {
+		if (this._lockPath) return this._lockPath;
+		let dir = null;
+		try {
+			const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: this.root, stdio: QUIET }).toString().trim();
+			if (common) dir = path.resolve(this.root, common);
+		} catch { /* not a git repo — fall back to the runtime folder */ }
+		this._lockPath = path.join(dir ?? this.runtime, '.dreamteamer-write-lock');
+		return this._lockPath;
+	}
+
 	// ---- write serialization + rollback (review finding 3; reinstates the v2 commit
 	// queue idea in sync form). within ONE process Node's sync fs/exec already serializes;
 	// the lock guards CLI-beside-server cross-process races on .git/index.lock. a commit
 	// failure UNDOES the write, so "one mutation = one commit" fails CLOSED and
 	// "nothing was written" stays true.
 	withWriteLock(fn) {
-		const lock = path.join(this.runtime, '.write-lock');
+		const lock = this.writeLockPath();
 		fs.mkdirSync(path.dirname(lock), { recursive: true });
 		const deadline = Date.now() + 5000;
 		for (;;) {

package/src/template.js

@@ -5,7 +5,21 @@
 // mutable fields.
 const SEQ = '__DT_SEQ__';
 
-export function generateId(tpl, fields, existingIds = []) {
+/** Render ONE template, or throw if a field it names is missing. The list form loops over this. */
+export function generateId(tpl, fields, existingIds = [], opts = {}) {
+	// ⚠ AN ORDERED LIST IS "USE THIS, ELSE THAT" — the only way a descriptor can express a readable
+	// latin handle WITHOUT forcing a required field onto every record. `id.generate` takes a string
+	// or a list of them, and the FIRST template whose fields are all present wins; a template that
+	// names a missing field is skipped, not fatal, until the last one, whose error is the one the
+	// writer sees. Before this, a missing field threw before any fallback could run and an unknown
+	// `default` filter threw too, so `{{ code }} else {{ name | slug }}` was inexpressible and the
+	// only workaround was passing --id on every single add.
+	if (Array.isArray(tpl)) {
+		for (let i = 0; i < tpl.length; i++) {
+			try { return generateId(tpl[i], fields, existingIds, opts); }
+			catch (e) { if (i === tpl.length - 1) throw e; }
+		}
+	}
 	const created = new Date();
 	let sawSeq = false;
 	let seqPad = 0;
@@ -25,7 +39,7 @@ export function generateId(tpl, fields, existingIds = []) {
 				if (name === 'pad') seqPad = Number(arg) || 0;
 				continue; // filters never transform the seq placeholder itself
 			}
-			value = applyFilter(name, arg, value);
+			value = applyFilter(name, arg, value, { field: head, onFallback: opts.onFallback });
 		}
 		if (value instanceof Date) value = fmtDate(value, 'YYYY-MM-DD');
 		return String(value);
@@ -45,12 +59,25 @@ export function generateId(tpl, fields, existingIds = []) {
 	return prefix + (seqPad ? n.padStart(seqPad, '0') : n) + suffix;
 }
 
-function applyFilter(name, arg, value) {
+function applyFilter(name, arg, value, ctx = {}) {
 	switch (name) {
 		case 'date': return fmtDate(asDate(value), arg || 'YYYY-MM-DD');
 		// ids are paths: no colons (windows-hostile, ungreppable) — 2026-07-25T13-39-17
 		case 'datetime': return asDate(value).toISOString().slice(0, 19).replace(/:/g, '-');
-		case 'slug': return slugOrHash(String(value));
+		// ⚠ THE SILENCE IS THE DEFECT, NOT THE ERGONOMICS. A value with no a-z0-9 in it — any Hebrew,
+		// Arabic, Cyrillic or CJK name — has nothing to slug, so this falls back to a deterministic
+		// hash and THE WRITE SUCCEEDS. That is worse than a refusal: `x1a2b3c4` lands, passes
+		// `check`, gets referenced by other records, and is discovered only when a person reads the
+		// tree, by which point renaming it is a migration. The fallback still happens (an id must be
+		// produced, and existing records keep theirs), but it is no longer silent: the caller is
+		// handed the field, the value and the id so a writer can say so.
+		case 'slug': {
+			const out = slugOrHash(String(value));
+			if (ctx.onFallback && out !== slug(String(value))) {
+				ctx.onFallback({ field: ctx.field, value: String(value), id: out });
+			}
+			return out;
+		}
 		case 'pad': return String(value).padStart(Number(arg) || 0, '0');
 		case 'basename': return String(value).split('/').pop();
 		default: throw new Error(`unknown id-template filter "${name}"`);