dreamteamer 0.6.0

package/src/init.js

@@ -0,0 +1,307 @@
+// dreamteamer init — write the workspace skeleton into the current directory.
+// non-interactive: flags override sensible defaults (RAD phase; prompts later).
+// never compiles — compile is always explicit.
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { dump } from './yaml.js';
+import { slugOrHash } from './template.js';
+import { discoverModules, KINDS } from './compile.js';
+import { Store } from './store.js';
+
+const SKELETON_KINDS = ['collections', 'skills', 'agents', 'commands', 'ui-views'];
+
+const GITIGNORE = `node_modules/
+git_modules/
+.dreamteamer/
+.claude/
+.agents/
+.cursor/
+.env
+media/
+.screenshots/
+`;
+
+// A brand-new workspace with no collections gives a user nothing to run, and makes `compile` warn
+// that the module `init` just created "contributed no recognised sources" — a warning about its own
+// output, which reads as a broken install. One starter collection answers both. `notes` is
+// deliberately the most generic thing a workspace can hold.
+const STARTER_COLLECTION = `name: notes
+storage:
+  path: data/notes
+  codec: md
+  shape: file
+  suffix: note
+id:
+  generate: '{{ created | date }}--{{ title | slug }}'
+  pattern: ^\\d{4}-\\d{2}-\\d{2}--[a-z0-9-]+$
+schema:
+  type: object
+  required:
+    - title
+  properties:
+    title:
+      type: string
+      description: What this note is called.
+    body:
+      type: string
+      format: markdown
+      x-body: true
+      description: The note itself.
+icon: sticky_note_2
+title: Notes
+title_template: '{{ title }}'
+`;
+
+const ENV_EXAMPLE = `# secrets for skills and modules go here (copy to .env; .env is never committed).
+# modules declare the env keys they require in their package.json dreamteamer.env list.
+`;
+
+export function init({ flags = {} } = {}) {
+	const root = process.cwd();
+	const name = flags.name ?? path.basename(root);
+	const dataPath = flags['data-path'] ?? 'data';
+	const harnesses = typeof flags.harnesses === 'string' ? flags.harnesses.split(',').map((s) => s.trim()) : ['claude-code'];
+
+	// package.json: create or update — the single manifest
+	const pkgPath = path.join(root, 'package.json');
+	const pkg = fs.existsSync(pkgPath) ? JSON.parse(fs.readFileSync(pkgPath, 'utf8')) : { name, private: true, version: '0.0.1' };
+	pkg.dreamteamer = {
+		'data-path': dataPath,
+		harnesses,
+		'gitignore-runtime-folder': true,
+		'workspace-module': name, // workspace-owned system sources live in modules/<name>/ — data and logic stay separated
+		'git-modules': {},
+		disable: [],
+		...pkg.dreamteamer,
+	};
+	fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, '\t') + '\n');
+
+	// folder skeleton — the workspace's own sources are an inline module, kinds FLAT at its root
+	const wm = pkg.dreamteamer['workspace-module'];
+	const systemRoot = wm ? path.join(root, 'modules', wm) : root;
+	for (const kind of SKELETON_KINDS) fs.mkdirSync(path.join(systemRoot, kind), { recursive: true });
+	if (wm) {
+		const modulePkg = path.join(systemRoot, 'package.json');
+		if (!fs.existsSync(modulePkg)) {
+			// `files` is the npm publish surface: every kind a module can ship, since a new one here
+			// is an engine change that would otherwise silently stop being packaged.
+			fs.writeFileSync(modulePkg, JSON.stringify({ name: wm, private: true, version: '0.0.1', files: [...KINDS], dreamteamer: {} }, null, '\t') + '\n');
+		}
+	}
+	// one starter collection, so `compile` has something to report instead of warning about the
+	// empty module it just made, and so a fresh workspace has something to run.
+	const starter = path.join(systemRoot, 'collections', 'notes.collection.yaml');
+	if (!fs.existsSync(starter)) fs.writeFileSync(starter, STARTER_COLLECTION);
+	fs.mkdirSync(path.join(root, dataPath), { recursive: true });
+	fs.mkdirSync(path.join(root, 'state'), { recursive: true });
+
+	// seed the operator's user record from the git identity.
+	//
+	// The id MUST be slugOrHash(git user.name) — that is exactly how `@me` resolves in filters and
+	// ui-views (server.js / fsdata.ts), so seeding it from the same source is what makes the core
+	// /inbox view work by construction. A workspace where a user record is authored by hand under a
+	// different id gets an EMPTY inbox with no error (decision 99b) — hence the setup-script step in
+	// any workspace with a second person.
+	//
+	// No `everyone` team is seeded: `teams` was removed from core 2026-07-31. It was a one-record
+	// abstraction with no reader — nothing in the engine, in `check`, or in any view resolved a team.
+	const gitName = tryGit(root, ['config', 'user.name']) ?? 'operator';
+	const gitEmail = tryGit(root, ['config', 'user.email']);
+	const userId = slugOrHash(gitName);
+	const usersDir = path.join(root, dataPath, 'users');
+	fs.mkdirSync(usersDir, { recursive: true });
+	const userFile = path.join(usersDir, `${userId}.user.yaml`);
+	if (!fs.existsSync(userFile)) fs.writeFileSync(userFile, dump({ name: gitName, ...(gitEmail ? { email: gitEmail } : {}) }));
+
+	// .gitignore + .env.example (append-if-missing, never clobber)
+	appendMissing(path.join(root, '.gitignore'), GITIGNORE);
+	if (!fs.existsSync(path.join(root, '.env.example'))) fs.writeFileSync(path.join(root, '.env.example'), ENV_EXAMPLE);
+
+	// one init commit (if we're in a git repo)
+	try {
+		// stdio ignored on purpose: this whole block is best-effort, and execFileSync forwards the
+		// child's stderr to ours by default — so a plain `dreamteamer init` in a non-git folder
+		// printed git's raw "fatal: not a git repository" above our own handled warning.
+		execFileSync('git', ['add', '--all'], { cwd: root, stdio: 'ignore' });
+		execFileSync('git', ['commit', '--quiet', '-m', `dreamteamer: init workspace ${name}`], { cwd: root, stdio: 'ignore' });
+	} catch { console.warn('⚠ not a git repo (or nothing to commit) — init files written, no commit'); }
+
+	console.log(`✔ workspace ${name} initialized — run \`dreamteamer compile\` to materialize the runtime`);
+	return 0;
+}
+
+// dreamteamer install — restore git_modules/ working clones from the committed lockfile map
+export function install({ root, pkg }) {
+	const map = pkg.dreamteamer?.['git-modules'] ?? {};
+	const names = Object.keys(map);
+	if (!names.length) { console.log('✔ no git-modules declared — nothing to restore'); return 0; }
+	fs.mkdirSync(path.join(root, 'git_modules'), { recursive: true });
+	for (const name of names) {
+		const { url, ref = 'main' } = map[name];
+		const dest = path.join(root, 'git_modules', name);
+		if (fs.existsSync(dest)) {
+			const head = tryGit(dest, ['rev-parse', '--abbrev-ref', 'HEAD']);
+			const dirty = tryGit(dest, ['status', '--porcelain']);
+			if (head !== ref) console.warn(`⚠ git_modules/${name}: HEAD is ${head}, lockfile says ${ref} — not touching it${dirty ? ' (dirty)' : ''}`);
+			else console.log(`✔ git_modules/${name} present (${ref})`);
+			continue;
+		}
+		console.log(`… cloning ${url} → git_modules/${name} (${ref})`);
+		execFileSync('git', ['clone', '--branch', ref, url, dest], { stdio: 'inherit' });
+		buildClone(dest, name);
+	}
+	return 0;
+}
+
+// dreamteamer update [<name>] — pull each lockfile-declared git_modules clone forward
+// (ff-only on its recorded ref) and rebuild it. dirty clones are skipped, never touched.
+// the caller (cli) runs compile afterwards — a pulled module may change sources.
+export function update({ root, pkg }, only) {
+	const map = pkg.dreamteamer?.['git-modules'] ?? {};
+	if (only && !map[only]) throw new Error(`"${only}" is not in dreamteamer.git-modules (known: ${Object.keys(map).join(', ') || 'none'})`);
+	const names = only ? [only] : Object.keys(map);
+	if (!names.length) { console.log('✔ no git-modules declared — nothing to update'); return 0; }
+	for (const name of names) {
+		const { ref = 'main' } = map[name];
+		const dest = path.join(root, 'git_modules', name);
+		if (!fs.existsSync(dest)) { console.warn(`⚠ git_modules/${name} missing — run \`dreamteamer install\` first; skipped`); continue; }
+		if (tryGit(dest, ['status', '--porcelain'])) { console.warn(`⚠ git_modules/${name} is dirty — skipped (commit or stash there, then re-run)`); continue; }
+		const before = tryGit(dest, ['rev-parse', '--short', 'HEAD']);
+		try {
+			execFileSync('git', ['pull', '--ff-only', 'origin', ref], { cwd: dest, stdio: 'inherit' });
+		} catch {
+			console.warn(`⚠ git_modules/${name}: ff-only pull of origin/${ref} failed (diverged?) — left at ${before}`);
+			continue;
+		}
+		const after = tryGit(dest, ['rev-parse', '--short', 'HEAD']);
+		if (before === after) { console.log(`✔ git_modules/${name} already up to date (${after})`); continue; }
+		buildClone(dest, name); // deps/dist may have moved with the pull
+		console.log(`✔ git_modules/${name} ${before} → ${after}`);
+	}
+	// dev-clone semantics: these clones SHADOW any node_modules copy of the same module —
+	// what just updated is what runs. npm-channel modules are updated via npm, not here.
+	console.log('… git_modules clones shadow node_modules copies — the updated clones win');
+	for (const m of discoverModules(root, pkg).modules) {
+		if (m.channel === 'npm') console.log(`… npm-channel module ${m.name} is not managed here — \`npm update ${m.name}\` to pull it forward`);
+	}
+	return 0;
+}
+
+// a fresh clone with deps or a prepare/build script needs `npm install` to be usable
+// (deps land; `prepare` runs on install and builds dist). failure warns, never crashes.
+function buildClone(dest, name) {
+	let cp;
+	try { cp = JSON.parse(fs.readFileSync(path.join(dest, 'package.json'), 'utf8')); } catch { return; }
+	if (!cp.dependencies && !cp.scripts?.prepare && !cp.scripts?.build) return;
+	console.log(`… npm install in git_modules/${name}`);
+	const r = spawnSync('npm', ['install', '--no-fund', '--no-audit'], { cwd: dest, stdio: 'inherit' });
+	if (r.status !== 0) console.warn(`⚠ npm install failed in git_modules/${name} (exit ${r.status ?? r.error?.message}) — clone may be unbuilt; fix and re-run npm install there`);
+}
+
+function tryGit(cwd, args) {
+	try { return execFileSync('git', args, { cwd }).toString().trim() || null; } catch { return null; }
+}
+
+function appendMissing(file, block) {
+	const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+	const missing = block.split('\n').filter((l) => l && !existing.split('\n').includes(l));
+	if (missing.length) fs.writeFileSync(file, (existing ? existing.trimEnd() + '\n' : '') + missing.join('\n') + '\n');
+}
+
+// dreamteamer install --clone <url> [name] — clone a module for development AND
+// record it in the committed lockfile map (story 5.3)
+export function installClone(ws, url, name) {
+	if (!url) throw new Error('usage: dreamteamer install --clone <git-url> [name]');
+	name = name && !name.startsWith('--') ? name : path.basename(url, '.git');
+	const dest = path.join(ws.root, 'git_modules', name);
+	if (fs.existsSync(dest)) throw new Error(`git_modules/${name} already exists`);
+	fs.mkdirSync(path.join(ws.root, 'git_modules'), { recursive: true });
+	execFileSync('git', ['clone', url, dest], { stdio: 'inherit' });
+	buildClone(dest, name);
+	const ref = tryGit(dest, ['rev-parse', '--abbrev-ref', 'HEAD']) ?? 'main';
+	const pkgPath = path.join(ws.root, 'package.json');
+	const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+	pkg.dreamteamer['git-modules'] = { ...pkg.dreamteamer['git-modules'], [name]: { url, ref } };
+	fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, '\t') + '\n');
+	execFileSync('git', ['add', 'package.json'], { cwd: ws.root });
+	execFileSync('git', ['commit', '--quiet', '-m', `dreamteamer: install ${name} (git module)`, '--', 'package.json'], { cwd: ws.root });
+	console.log(`✔ git_modules/${name} (ref ${ref})`);
+	console.log('✔ package.json dreamteamer.git-modules updated');
+	return 0;
+}
+
+// ---- attached repos: `repos` records, materialized ON DEMAND ------------------------------
+// A `repos` record declares a related git repo and NOTHING about the schema — the other half of
+// what git_modules fuses together. Modules stay in package.json because compile can't read records
+// until they're restored (no .dreamteamer → no schemas → no readable records); attached repos have
+// no such constraint, so they get to be data.
+
+const relPath = (root, p) => path.relative(root, p) || '.';
+
+/**
+ * Where a declared repo's working tree lives. Pure — never touches disk, so callers can resolve a
+ * path without materializing (that is how `status` reports presence).
+ *
+ * The engine deliberately does NOT know what `identity` means: a workspace may use it to select a
+ * `~/.gitconfig` includeIf folder so the clone commits as the right git user, but that resolution
+ * happens entirely outside the engine. Here it is just a path segment.
+ */
+export function repoPath(ws, fields) {
+	if (fields.path) return path.join(ws.root, fields.path);
+	const base = ws.pkg.dreamteamer?.['repos-path'] ?? 'projects';
+	return fields.identity
+		? path.join(ws.root, base, fields.identity, fields.name)
+		: path.join(ws.root, base, fields.name);
+}
+
+/**
+ * dreamteamer repos ensure <id> — materialize ONE declared repo, idempotently.
+ * Cheap as a stat when already present, so callers never branch on presence themselves.
+ */
+export function ensureRepo(ws, id) {
+	const { fields } = new Store(ws).read('repos', id);
+	return materializeRepo(ws, id, fields);
+}
+
+/** dreamteamer repos ensure --all — explicit opt-in (going offline, grepping across all of them). */
+export function ensureAllRepos(ws) {
+	const out = [];
+	for (const { id, fields } of new Store(ws).readAll('repos')) out.push(materializeRepo(ws, id, fields));
+	return out;
+}
+
+/**
+ * Declared repos and whether each is on disk. Presence is OBSERVED, never stored on the record —
+ * with lazy materialization "is it here?" is the first question anyone asks, and a stored answer
+ * would be wrong the moment someone deletes a folder.
+ */
+export function listRepos(ws) {
+	const out = [];
+	for (const { id, fields } of new Store(ws).readAll('repos')) {
+		const dest = repoPath(ws, fields);
+		out.push({ id, path: relPath(ws.root, dest), present: fs.existsSync(dest) });
+	}
+	return out;
+}
+
+function materializeRepo(ws, id, fields) {
+	const dest = repoPath(ws, fields);
+	const ref = fields.ref ?? 'main';
+	const rp = relPath(ws.root, dest);
+	if (fs.existsSync(dest)) {
+		// same contract as install(): warn on drift, never force-sync, never touch a dirty tree
+		const head = tryGit(dest, ['rev-parse', '--abbrev-ref', 'HEAD']);
+		const dirty = tryGit(dest, ['status', '--porcelain']);
+		if (head && head !== ref) {
+			console.warn(`⚠ ${rp}: HEAD is ${head}, record says ${ref} — not touching it${dirty ? ' (dirty)' : ''}`);
+		}
+		return { id, path: rp, present: true, cloned: false, ref: head ?? ref };
+	}
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	console.log(`… cloning ${fields.url} → ${rp} (${ref})`);
+	execFileSync('git', ['clone', '--branch', ref, fields.url, dest], { stdio: 'inherit' });
+	// NO buildClone() here, unlike install(): a prototype or app repo is not an npm module and
+	// must never have `npm install` run in it as a side effect of being materialized.
+	return { id, path: rp, present: true, cloned: true, ref };
+}

package/src/presentation.js

@@ -0,0 +1,190 @@
+// presentation projection — descriptor → "how to render each field" rows, served at
+// GET /api/presentation. this is the ADAPTER INVERSION (review, M3): the mapping the
+// studio's transitional adapter synthesized client-side is genuinely useful, so it moves
+// into the clean contract as an explicit projection; the studio consumes ONE contract and
+// the client adapter shrinks to a thin path translator. shapes deliberately match what
+// the studio components already speak (field {field,type,meta,schema}).
+
+/** the projection for every collection: rows keyed by collection name + collection meta. */
+export function presentation(descriptors) {
+	const collections = [];
+	const fields = {};
+	const relations = [];
+	for (const d of [...descriptors.values()].sort((a, b) => (a.order ?? 999) - (b.order ?? 999))) {
+		collections.push(collectionRow(d));
+		const rows = [];
+		rows.push({
+			field: 'id',
+			type: 'string',
+			meta: { collection: d.name, field: 'id', hidden: true, readonly: true, edit: 'input' },
+			schema: { name: 'id', is_primary_key: true, is_nullable: false },
+		});
+		// Synthesized like `id` above — never a schema property, so it's never written to disk
+		// (unknownFields would reject it) and never touches a collection's real frontmatter
+		// contract. `readonly: true` (not `hidden`) so it's a browse column and sortable; `formHidden`
+		// (studio-only convention, not a Directus concept — ContentDetail filters on it before handing
+		// fields to ItemForm) keeps it OUT of the record form now that PageHeader shows the richer
+		// author/message/date line instead (operator ask 2026-07-27). Computed server-side per
+		// request (server.js) from `git log` on the record's file — null for anything the compiled
+		// `.dreamteamer/` runtime backs (skills/agents/commands/…, gitignored) since there's no
+		// meaningful history to read there.
+		rows.push({
+			field: 'last-modified',
+			type: 'timestamp',
+			meta: { collection: d.name, field: 'last-modified', readonly: true, formHidden: true, view: 'date', view_options: { relative: true } },
+			schema: { name: 'last-modified', is_primary_key: false, is_nullable: true, default_value: null },
+		});
+		for (const [name, prop] of Object.entries(d.schema?.properties ?? {})) {
+			if (name === 'id') continue;
+			rows.push(fieldRow(d, name, prop, new Set(d.schema?.required ?? []).has(name), descriptors));
+			const target = referenceTargetOf(prop);
+			if (target) {
+				relations.push({ collection: d.name, field: name, related_collection: target, list: prop.type === 'array' });
+			}
+		}
+		fields[d.name] = rows;
+	}
+	return { collections, fields, relations };
+}
+
+function collectionRow(d) {
+	const props = d.schema?.properties ?? {};
+	const titleField = ['title', 'name', 'subject'].find((f) => f in props);
+	const meta = { collection: d.name, record_type: d.storage?.suffix ?? d.name };
+	// resolved by compile — a surface renders this and never title-cases an id itself
+	if (typeof d.title === 'string' && d.title.length > 0) meta.title = d.title;
+	if (typeof d.title_template === 'string' && d.title_template.length > 0) meta.title_template = d.title_template;
+	if (titleField) meta.title_field = titleField;
+	if (typeof d.order === 'number') meta.order = d.order;
+	if (Array.isArray(d.list_fields)) meta.list_fields = d.list_fields;
+	if (typeof d.icon === 'string') meta.icon = d.icon;
+	if (typeof d.group === 'string') meta.group = d.group;
+	if (typeof d.description === 'string' && d.description.length > 0) meta.description = d.description;
+	return { collection: d.name, meta, system: d.storage?.base === 'runtime' };
+}
+
+function referenceTargetOf(prop) {
+	const ref = prop.type === 'array' ? prop.items?.['x-reference'] : prop['x-reference'];
+	if (typeof ref !== 'string' || ref === '' || ref === '*') return null;
+	return ref;
+}
+
+/**
+ * The template that renders a VALUE of this field as a human label.
+ *
+ * Authored per-field with `x-title-template`, else INHERITED from the target collection's
+ * `title_template` — because "a company is labelled by its name" is a fact about companies, not
+ * about each of the eleven fields that point at one. Before this, that fact was hand-copied onto
+ * every referencing field as `x-display: '{{ name }}'`; 51 of the 54 sites in this workspace were
+ * exactly what the target already implies.
+ */
+function titleTemplateOf(prop, descriptors) {
+	const own = prop.type === 'array' ? prop.items?.['x-title-template'] : prop['x-title-template'];
+	if (typeof own === 'string' && own.length > 0) return own;
+	const target = referenceTargetOf(prop);
+	const inherited = target ? descriptors.get(target)?.title_template : undefined;
+	return typeof inherited === 'string' && inherited.length > 0 ? inherited : undefined;
+}
+
+function fieldRow(d, name, prop, isRequired, descriptors) {
+	const meta = { collection: d.name, field: name };
+	if (isRequired) meta.required = true;
+	// JSON Schema's own `description` on the property — what the field MEANS, authored in the
+	// module source beside the field. Carried through verbatim so a surface can explain a field
+	// without a second vocabulary (the UI shows it as the property row's tooltip).
+	if (typeof prop.description === 'string' && prop.description.length > 0) meta.description = prop.description;
+	// resolved by compile (titleCase of the field name unless authored) — the label every surface
+	// shows, so no component title-cases a field name on its own.
+	if (typeof prop.title === 'string' && prop.title.length > 0) meta.title = prop.title;
+
+	let type = 'string';
+	const target = referenceTargetOf(prop);
+
+	if (prop['x-body'] === true) {
+		type = 'text';
+		meta.special = ['dt-body'];
+		meta.edit = 'input-rich-text-md';
+	} else if (target && prop.type !== 'array') {
+		meta.special = ['dt-relation-path'];
+	} else if (target && prop.type === 'array') {
+		type = 'json';
+		meta.special = ['dt-relation-path', 'dt-relation-list'];
+	} else if (prop.type === 'array' && prop.items?.type === 'object') {
+		type = 'json';
+		meta.edit = 'list';
+		meta.view = 'list';
+		const listOptions = { fields: optionFieldsOf(prop.items) };
+		if (typeof prop.items['x-title-template'] === 'string') listOptions.template = prop.items['x-title-template'];
+		meta.edit_options = listOptions;
+		meta.view_options = listOptions;
+	} else if (prop.type === 'array') {
+		type = 'json';
+		meta.edit = 'tags';
+		meta.view = 'tags';
+	} else if (prop.type === 'boolean') {
+		type = 'boolean';
+	} else if (prop.type === 'integer') {
+		type = 'integer';
+	} else if (prop.type === 'number') {
+		type = 'float';
+	} else if (prop.type === 'object') {
+		type = 'json';
+		if (prop.properties && Object.keys(prop.properties).length > 0) {
+			meta.edit = 'nested';
+			meta.view = 'nested';
+			const nestedOptions = { fields: optionFieldsOf(prop) };
+			meta.edit_options = nestedOptions;
+			meta.view_options = nestedOptions;
+		}
+	} else if (prop.format === 'date') {
+		type = 'date';
+	} else if (prop.format === 'date-time') {
+		type = 'timestamp';
+	} else if (prop.format === 'markdown') {
+		type = 'text';
+	}
+
+	if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+		meta.edit_options = { choices: prop.enum.map((v) => ({ text: String(v), value: v })) };
+	}
+	const tpl = titleTemplateOf(prop, descriptors);
+	if (typeof tpl === 'string' && tpl.length > 0) meta.view_options = { ...meta.view_options, template: tpl };
+
+	return {
+		field: name,
+		type,
+		meta,
+		schema: { name, is_primary_key: false, is_nullable: !isRequired, default_value: prop.default ?? null },
+	};
+}
+
+// sub-form shape (EditList rows / EditNested objects) derived recursively
+function optionFieldsOf(objSchema) {
+	return Object.entries(objSchema.properties ?? {}).map(([field, prop]) => {
+		const def = { field, name: field, type: 'string' };
+		if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+			def.edit = 'select-dropdown';
+			def.edit_options = { choices: prop.enum.map((v) => ({ text: String(v), value: v })) };
+		} else if (prop.type === 'boolean') {
+			def.type = 'boolean';
+		} else if (prop.type === 'integer' || prop.type === 'number') {
+			def.type = prop.type === 'integer' ? 'integer' : 'float';
+		} else if (prop.type === 'array' && prop.items?.type === 'object') {
+			def.type = 'json';
+			def.edit = 'list';
+			def.edit_options = { fields: optionFieldsOf(prop.items) };
+		} else if (prop.type === 'array') {
+			def.type = 'json';
+			def.edit = 'tags';
+		} else if (prop.type === 'object' && prop.properties && Object.keys(prop.properties).length > 0) {
+			def.type = 'json';
+			def.edit = 'nested';
+			def.edit_options = { fields: optionFieldsOf(prop) };
+		} else if (prop.type === 'object') {
+			def.type = 'json';
+		} else if (prop.format === 'markdown') {
+			def.type = 'text';
+		}
+		return def;
+	});
+}

package/src/record-commands.js

@@ -0,0 +1,84 @@
+// record⇄command evaluation — which bound commands apply to a record (or a list
+// selection), and in which state. a binding is a `command-bindings` record: a m2m
+// join (command × collection) carrying `can-enter` / `can-exit` filter predicates,
+// evaluated with the SAME operator set as list-view filters plus one-hop outbound
+// ref traversal (tier 1). serves `dreamteamer commands for`, GET /api/commands/:name,
+// and (through the extension's api.ts port) the studio's Commands tab.
+import { matchesFilter } from './filter.js';
+
+// memoized `<collection>/<id>` → parsed fields (or null) for ONE evaluation pass:
+// overlapping refs across a 50-record selection parse once, and filter.js stays
+// pure — it never learns about the store, it just gets this callback.
+export function recordResolver(store) {
+	const memo = new Map();
+	return (ref) => {
+		if (memo.has(ref)) return memo.get(ref);
+		let target = null;
+		const slash = typeof ref === 'string' ? ref.indexOf('/') : -1;
+		if (slash > 0) {
+			try {
+				const { fields } = store.read(ref.slice(0, slash), ref.slice(slash + 1));
+				target = { ...fields, id: ref.slice(slash + 1) };
+			} catch { /* dangling ref or unknown collection — narrows, never widens */ }
+		}
+		memo.set(ref, target);
+		return target;
+	};
+}
+
+/**
+ * every command bound to `collection`, evaluated over `ids` (possibly empty).
+ * target=collection bindings need no record — always runnable, invocation carries the
+ * collection name (so a command bound to several collections knows where to write).
+ * target=record bindings get a per-id state:
+ *   done            can-exit passes (the command's post-condition already holds)
+ *   available       can-enter passes (or no can-enter) and can-exit doesn't
+ *   not-applicable  can-enter fails (or the record doesn't resolve)
+ * `invocation` covers the ELIGIBLE ids only, space-separated — a deliberate contract:
+ * the UI shows it verbatim in an editable textarea, so nothing is silently dropped.
+ */
+export function commandsFor(store, collection, ids = []) {
+	store.descriptor(collection); // unknown collection throws here, not deep inside a filter walk
+	const resolve = recordResolver(store);
+	const commands = new Map();
+	for (const { id, fields } of store.readAll('commands')) commands.set(`commands/${id}`, fields);
+	const rows = [];
+	for (const { id: bindingId, fields: b } of store.readAll('command-bindings')) {
+		if (b.collection !== `collections/${collection}`) continue;
+		const cmd = commands.get(b.command);
+		if (!cmd) continue; // compile rejects dangling binding refs; stay safe on a stale runtime
+		const row = {
+			binding: `command-bindings/${bindingId}`,
+			command: b.command,
+			name: cmd.name,
+			description: b.description ?? cmd.description ?? '',
+			'argument-hint': cmd['argument-hint'] ?? null,
+			target: b.target ?? 'record',
+		};
+		if (row.target === 'collection') {
+			rows.push({ ...row, invocation: `/${cmd.name} ${collection}` });
+			continue;
+		}
+		const states = {};
+		for (const id of ids) {
+			const record = resolve(`${collection}/${id}`);
+			let state = 'not-applicable';
+			if (record) {
+				if (b['can-exit'] && matchesFilter(record, b['can-exit'], resolve)) state = 'done';
+				else if (!b['can-enter'] || matchesFilter(record, b['can-enter'], resolve)) state = 'available';
+			}
+			states[id] = state;
+		}
+		const eligible = ids.filter((id) => states[id] === 'available');
+		rows.push({
+			...row,
+			states,
+			eligible,
+			done: ids.filter((id) => states[id] === 'done'),
+			invocation: eligible.length ? `/${cmd.name} ${eligible.map((id) => `${collection}/${id}`).join(' ')}` : null,
+		});
+	}
+	// record commands first (the headline on a record page), then collection commands; name-sorted within
+	rows.sort((a, b) => (a.target === b.target ? a.name.localeCompare(b.name) : a.target === 'collection' ? 1 : -1));
+	return { collection, ids, commands: rows };
+}

package/src/records.js

@@ -0,0 +1,73 @@
+// shared record primitives — parsing, id patterns, error formatting — used by
+// both the validating store (hard, write-time) and check (soft, report-only).
+import fs from 'node:fs';
+import path from 'node:path';
+import { load } from './yaml.js';
+
+export function parseRecord(file, d, bodyField) {
+	return parseRecordText(fs.readFileSync(file, 'utf8'), d, bodyField);
+}
+
+export function parseRecordText(text, d, bodyField) {
+	const codec = d.storage.codec ?? 'md';
+	if (codec === 'yaml') return load(text) ?? {};
+	if (codec === 'json') return JSON.parse(text);
+	let fields = {};
+	let body = text;
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+	if (m) {
+		fields = load(m[1]) ?? {};
+		body = text.slice(m[0].length);
+	}
+	if (bodyField && body.trim()) fields[bodyField] = body;
+	return fields;
+}
+
+// id patterns may use unicode property escapes — compile with the u flag
+export function patternRe(pattern) {
+	try { return new RegExp(pattern, 'u'); } catch { return new RegExp(pattern); }
+}
+
+// ajv errors, humanized: echo the offending value (the one datum the reader needs)
+export function fmtAjvError(e, fields) {
+	const fieldPath = e.instancePath.slice(1).replace(/\//g, '.');
+	const value = fieldPath ? fieldPath.split('.').reduce((v, k) => v?.[k], fields) : undefined;
+	if (e.keyword === 'enum') return `field ${fieldPath}: "${value}" not in enum [${e.params.allowedValues.join(', ')}]`;
+	return `field ${fieldPath || '(root)'}: ${JSON.stringify(value) ?? ''} ${e.message}`.trim();
+}
+
+// unknown keys relative to a schema that declares properties (typo detector)
+export function unknownFields(schema, fields) {
+	const props = schema?.properties ?? {};
+	if (!Object.keys(props).length) return [];
+	return Object.keys(fields).filter((k) => !(k in props));
+}
+
+// ---- shared reader primitives (review finding 11: walk/EXT existed 2-4×, diverging) ----
+
+export const EXT = { md: '.md', yaml: '.yaml', json: '.json' };
+
+const JUNK_DIRS = new Set(['__pycache__', 'node_modules']);
+const JUNK_FILE = /\.(pyc|pyo)$|^\.DS_Store$/;
+
+// THE collection walk — junk-excluding everywhere (store/check used to see .pyc files
+// compile deliberately skipped; one walk, one verdict).
+export function* walk(dir) {
+	for (const name of fs.readdirSync(dir).sort()) {
+		if (name.startsWith('.') || JUNK_DIRS.has(name)) continue;
+		if (JUNK_FILE.test(name)) continue;
+		const p = path.join(dir, name);
+		if (fs.statSync(p).isDirectory()) yield* walk(p);
+		else yield p;
+	}
+}
+
+// ids are PATHS — but only downward ones. traversal segments, absolute paths and
+// backslashes are rejected before any fs join (review finding 1: an escaping --id
+// wrote a record outside the repo and orphaned others inside it).
+export function assertSafeId(id) {
+	if (typeof id !== 'string' || id === '') throw new Error(`invalid id "${id}" — nothing was written.`);
+	if (id.startsWith('/') || id.includes('\\') || id.split('/').some((s) => s === '' || s === '.' || s === '..')) {
+		throw new Error(`invalid id "${id}" — ids are relative paths, no "."/".." segments, no leading slash. nothing was written.`);
+	}
+}