dreamteamer 0.26.0 → 0.28.0

package/src/containers.js

@@ -0,0 +1,422 @@
+// containers.js — `containers` and `images` as verbs over the Docker Engine API. The one storage
+// DRIVER in core: a workspace becomes a running container (`dt start container <name> --template
+// <t>`), the person opens code-server at a loopback URL, and the same record verbs — list · get ·
+// add · rm — answer over Docker instead of over a folder of files.
+//
+// WHY THIS IS CORE AND NOT A MODULE. A module ships collections, skills, commands and views INTO a
+// workspace; every one of them needs a compiled runtime to exist. This runs BEFORE any workspace
+// exists — `npm i -g dreamteamer && dt setup && dt start container …` on a machine with nothing
+// but Docker Desktop — and a module has no place to stand there. That is the "could a module do it"
+// question, answered: no, because the thing being made IS the workspace.
+//
+// WHY THERE IS NO DEPENDENCY. The Engine API is HTTP over a Unix socket (a named pipe on Windows),
+// and `node:http` takes `socketPath`. Measured 2026-09-24 against Docker Desktop 29.3.1 / API 1.54:
+// /version, /containers/json and /images/json all answered from a bare `node -e`. The ONE call the
+// API makes awkward is `POST /build`, which wants a tar stream Node core cannot produce — so
+// templates ship PREBUILT (a registry pull is `POST /images/create`, streamed JSON lines) and a
+// local build is the `docker` CLI Docker Desktop installs anyway, never this file.
+//
+// WHAT A DRIVER COLLECTION IS NOT. Not records: nothing under `data/`, nothing `dt commit` sees,
+// nothing `dt check` reads, no history (Docker keeps its own). It is not compiled into
+// `.dreamteamer/collections` either — these two nouns resolve HERE, ahead of workspace discovery,
+// so `dt list containers` answers identically inside a workspace and on a bare host.
+//
+// TEST KNOBS, stated once: `DT_DOCKER_SOCKET` points the client at any socket (a fake in tests);
+// `DT_HOME` relocates `~/.dreamteamer`; `DT_HEALTH_TIMEOUT=0` skips the wait for code-server's
+// /healthz. None is documented in help — they are how the suite drives this file without Docker.
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { parseEnvValues } from './env-vars.js';
+import { emit } from './collections-cli.js';
+
+// ---- the two nouns, singular and plural --------------------------------------------------------
+// The operator's spelling is `dt start container hq-dana` and `dt list containers`; both resolve.
+// This is the singular map for the driver collections ONLY — the general rule ("every record verb
+// accepts the singular, derived from the descriptor") is a filed feature, not this file's job.
+export const NOUNS = { containers: 'containers', container: 'containers', images: 'images', image: 'images' };
+export const DRIVER_VERBS = new Set(['list', 'get', 'add', 'rm', 'start', 'stop', 'open']);
+export const LIFECYCLE_VERBS = new Set(['start', 'stop', 'open']);
+
+/** `containers`, `container`, `containers/<id>` → { collection, id }; null when the word is not ours. */
+export function driverTarget(word) {
+	if (!word || word.startsWith('--')) return null;
+	const slash = word.indexOf('/');
+	const noun = slash === -1 ? word : word.slice(0, slash);
+	const collection = NOUNS[noun];
+	if (!collection) return null;
+	return { collection, id: slash === -1 ? undefined : word.slice(slash + 1) };
+}
+
+// ---- host configuration: ~/.dreamteamer/.env ---------------------------------------------------
+export const HOST_DEFAULTS = {
+	DT_PORT_BASE: '8100',       // NOT 8080: that is code-server's in-container port, `dt start`'s REST default, and the old dev image's exposed port — three things on one number
+	DT_BIND: '127.0.0.1',       // loopback only; a remote tier puts auth in front before this changes
+	DT_REGISTRY: 'dreamteamer', // `<registry>/<template>:<tag>` is the image a template name resolves to
+	DT_TEMPLATE_TAG: 'latest',
+};
+
+export function hostDir() { return process.env.DT_HOME ?? path.join(os.homedir(), '.dreamteamer'); }
+
+/** Defaults, then the file, then the process env — the same precedence a shell would give. */
+export function hostEnv() {
+	const file = path.join(hostDir(), '.env');
+	// parseEnvValues answers a Map — spread it as entries, or the file silently contributes nothing.
+	const fromFile = fs.existsSync(file) ? Object.fromEntries(parseEnvValues(fs.readFileSync(file, 'utf8'))) : {};
+	const out = { ...HOST_DEFAULTS, ...fromFile };
+	for (const k of Object.keys(process.env)) if (k.startsWith('DT_') && process.env[k] !== undefined) out[k] = process.env[k];
+	return out;
+}
+
+// ---- the Engine API client ---------------------------------------------------------------------
+export function socketPath() {
+	if (process.env.DT_DOCKER_SOCKET) return process.env.DT_DOCKER_SOCKET;
+	if (process.platform === 'win32') return '//./pipe/docker_engine';
+	for (const p of ['/var/run/docker.sock', path.join(os.homedir(), '.docker', 'run', 'docker.sock')]) {
+		try { if (fs.statSync(p).isSocket()) return p; } catch { /* next */ }
+	}
+	return '/var/run/docker.sock';
+}
+
+function unreachable(sock) {
+	const hint = process.platform === 'darwin' ? ' — is Docker Desktop running? `open -a Docker` starts it' : ' — is the Docker daemon running?';
+	return new Error(`Docker is not reachable at ${sock}${hint}. \`dt setup\` checks this and says what is missing.`);
+}
+
+/** One request. Resolves { status, body } where body is parsed JSON when the response is JSON,
+ *  else the raw text. `onLine` receives each JSON line of a streaming response (a pull). */
+export function api(method, urlPath, body, { onLine } = {}) {
+	const sock = socketPath();
+	return new Promise((resolve, reject) => {
+		const payload = body === undefined ? undefined : JSON.stringify(body);
+		const req = http.request({
+			socketPath: sock, method, path: urlPath,
+			headers: payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {},
+		}, (res) => {
+			let text = '';
+			let pending = '';
+			res.setEncoding('utf8');
+			res.on('data', (chunk) => {
+				text += chunk;
+				if (!onLine) return;
+				pending += chunk;
+				const lines = pending.split('\n');
+				pending = lines.pop();
+				for (const l of lines) if (l.trim()) { try { onLine(JSON.parse(l)); } catch { /* not JSON */ } }
+			});
+			res.on('end', () => {
+				const isJson = /json/.test(res.headers['content-type'] ?? '');
+				let parsed = text;
+				if (isJson && !onLine) { try { parsed = text ? JSON.parse(text) : null; } catch { parsed = text; } }
+				resolve({ status: res.statusCode, body: parsed });
+			});
+		});
+		req.on('error', (e) => reject(e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? unreachable(sock) : e));
+		if (payload) req.write(payload);
+		req.end();
+	});
+}
+
+/** Throw the daemon's own sentence on a non-2xx, so a refusal reads as Docker's rather than ours. */
+function ok(res, what) {
+	if (res.status >= 200 && res.status < 400) return res.body;
+	const msg = res.body && typeof res.body === 'object' && res.body.message ? res.body.message : String(res.body ?? '').trim();
+	throw new Error(`${what}: Docker answered ${res.status}${msg ? ` — ${msg}` : ''}`);
+}
+
+const LABEL = { workspace: 'dreamteamer.workspace', template: 'dreamteamer.template', person: 'dreamteamer.person', ports: 'dreamteamer.ports', modules: 'dreamteamer.modules' };
+const filters = (label) => encodeURIComponent(JSON.stringify({ label: [label] }));
+
+// ---- images ------------------------------------------------------------------------------------
+export function imageRef(template, env = hostEnv()) {
+	// `DT_IMAGE_<template>=<ref>` pins one template to any image, which is how a local build or a
+	// private registry is reached without the registry default changing for every other template.
+	return env[`DT_IMAGE_${template}`] ?? `${env.DT_REGISTRY}/${template}:${env.DT_TEMPLATE_TAG}`;
+}
+
+const imageRow = (i) => ({
+	image: (i.RepoTags ?? []).find((t) => t !== '<none>:<none>') ?? i.Id.slice(7, 19),
+	template: i.Labels?.[LABEL.template] ?? '',
+	ports: i.Labels?.[LABEL.ports] ?? '',
+	modules: i.Labels?.[LABEL.modules] ?? '',
+	size_mb: Math.round((i.Size ?? 0) / 1e6),
+	created: i.Created ? new Date(i.Created * 1000).toISOString().slice(0, 10) : '',
+	id: i.Id,
+});
+
+export async function listImages() {
+	const body = ok(await api('GET', `/images/json?filters=${filters(LABEL.template)}`), 'list images');
+	return body.map(imageRow).sort((a, b) => a.image.localeCompare(b.image));
+}
+
+export async function inspectImage(ref) {
+	const res = await api('GET', `/images/${encodeURIComponent(ref)}/json`);
+	return res.status === 404 ? null : ok(res, `get image ${ref}`);
+}
+
+export async function pullImage(ref, log = console.error) {
+	const [name, tag] = splitTag(ref);
+	let last = '';
+	const res = await api('POST', `/images/create?fromImage=${encodeURIComponent(name)}&tag=${encodeURIComponent(tag)}`, undefined, {
+		onLine: (l) => { if (l.status && l.status !== last) { last = l.status; log(`  … ${l.status}${l.id ? ` ${l.id}` : ''}`); } if (l.error) throw new Error(l.error); },
+	});
+	if (res.status !== 200) throw new Error(`pull ${ref}: Docker answered ${res.status} — ${String(res.body).trim()}. A local build is \`docker build -t ${ref} …\`, or pin DT_IMAGE_<template> in ${path.join(hostDir(), '.env')}`);
+}
+
+function splitTag(ref) {
+	const at = ref.lastIndexOf(':');
+	const slash = ref.lastIndexOf('/');
+	return at > slash ? [ref.slice(0, at), ref.slice(at + 1)] : [ref, 'latest'];
+}
+
+// ---- containers --------------------------------------------------------------------------------
+const containerRow = (c) => {
+	const name = (c.Names?.[0] ?? '').replace(/^\//, '');
+	const port = (c.Ports ?? []).find((p) => p.PublicPort)?.PublicPort;
+	return {
+		name, template: c.Labels?.[LABEL.template] ?? '', state: c.State, status: c.Status,
+		editor_url: port ? editorUrl(port) : '', image: c.Image, person: c.Labels?.[LABEL.person] ?? '',
+		created: c.Created ? new Date(c.Created * 1000).toISOString().slice(0, 16).replace('T', ' ') : '', id: c.Id,
+	};
+};
+const editorUrl = (port) => `http://localhost:${port}/?folder=/workspace`;
+const volumeNames = (name) => ({ workspace: `dreamteamer-${name}-workspace`, home: `dreamteamer-${name}-home`, files: `dreamteamer-${name}-files` });
+
+export async function listContainers() {
+	const body = ok(await api('GET', `/containers/json?all=1&filters=${filters(LABEL.workspace)}`), 'list containers');
+	return body.map(containerRow).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function inspectContainer(name) {
+	const res = await api('GET', `/containers/${encodeURIComponent(name)}/json`);
+	if (res.status === 404) return null;
+	const c = ok(res, `get container ${name}`);
+	if (!c.Config?.Labels?.[LABEL.workspace]) throw new Error(`"${name}" is a Docker container but not a dreamteamer workspace (no ${LABEL.workspace} label) — this verb only touches containers it made`);
+	return c;
+}
+
+/** The shape `dt get container <name>` prints: the categorised view over `docker inspect`. */
+export function containerDetail(c) {
+	const binding = Object.values(c.HostConfig?.PortBindings ?? {}).flat()[0];
+	const mounts = Object.fromEntries((c.Mounts ?? []).filter((m) => m.Type === 'volume').map((m) => [m.Destination, m.Name]));
+	return {
+		name: c.Name.replace(/^\//, ''), id: c.Id.slice(0, 12),
+		template: c.Config.Labels[LABEL.template] ?? '', image: c.Config.Image,
+		state: c.State?.Status, started: c.State?.StartedAt, restarts: c.RestartCount ?? 0,
+		bind: binding?.HostIp ?? '', port: binding ? Number(binding.HostPort) : undefined,
+		editor_url: binding ? editorUrl(binding.HostPort) : '',
+		volumes: { workspace: mounts['/workspace'] ?? '', home: mounts['/home/node'] ?? '', files: mounts['/files'] ?? '' },
+		person: c.Config.Labels[LABEL.person] ?? '', created: c.Created, labels: c.Config.Labels,
+	};
+}
+
+/** The lowest host port from DT_PORT_BASE upward that no dreamteamer container already holds. */
+export async function allocatePort(env = hostEnv()) {
+	const base = Number(env.DT_PORT_BASE);
+	if (!Number.isInteger(base) || base < 1024) throw new Error(`DT_PORT_BASE must be an integer port above 1023 (got "${env.DT_PORT_BASE}")`);
+	const all = ok(await api('GET', `/containers/json?all=1&filters=${filters(LABEL.workspace)}`), 'list containers');
+	const taken = new Set(all.flatMap((c) => (c.Ports ?? []).map((p) => p.PublicPort)).filter(Boolean));
+	// A stopped container publishes nothing in /containers/json, so read its binding from inspect —
+	// otherwise the second workspace lands on the first one's port the moment the first is stopped.
+	for (const c of all) if (c.State !== 'running') {
+		const d = await api('GET', `/containers/${c.Id}/json`);
+		for (const b of Object.values(d.body?.HostConfig?.PortBindings ?? {}).flat()) taken.add(Number(b.HostPort));
+	}
+	let port = base;
+	while (taken.has(port)) port++;
+	return port;
+}
+
+function person(flags, env) {
+	const git = (k) => { try { return execFileSync('git', ['config', '--global', k], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+	const name = flags.name ?? env.DT_PERSON_NAME ?? git('user.name');
+	const email = flags.email ?? env.DT_PERSON_EMAIL ?? git('user.email');
+	return { name, email };
+}
+
+/** Create-if-absent and start. Idempotent: a second call on an existing name starts it and prints
+ *  the same URL. Never injects a token — the person logs in INSIDE, once, and the home volume keeps it. */
+export async function startContainer(name, flags, log = console.log) {
+	if (!/^[a-z0-9][a-z0-9_.-]*$/.test(name)) throw new Error(`"${name}" is not a container name — lowercase letters, digits, "-", "_" and "."; e.g. hq-dana`);
+	const env = hostEnv();
+	let c = await inspectContainer(name);
+	if (!c) {
+		const template = typeof flags.template === 'string' ? flags.template : undefined;
+		if (!template) throw new Error(`container "${name}" does not exist yet — name the template that makes it: dt start container ${name} --template <t> (dt list images shows the templates present)`);
+		const ref = imageRef(template, env);
+		let img = await inspectImage(ref);
+		if (!img) { log(`… pulling ${ref}`); await pullImage(ref, log); img = await inspectImage(ref); }
+		if (!img) throw new Error(`image ${ref} is still absent after the pull`);
+		const labels = img.Config?.Labels ?? {};
+		const inner = Number(labels[LABEL.ports] ?? 8080);
+		const port = await allocatePort(env);
+		const who = person(flags, env);
+		const vols = volumeNames(name);
+		const body = {
+			Image: ref,
+			Labels: { [LABEL.workspace]: name, [LABEL.template]: template, [LABEL.person]: who.name },
+			Env: [
+				`DT_WORKSPACE=${name}`, `DT_TEMPLATE=${template}`, 'FILES_FOLDER=/files',
+				...(who.name ? [`GIT_AUTHOR_NAME=${who.name}`, `GIT_COMMITTER_NAME=${who.name}`] : []),
+				...(who.email ? [`GIT_AUTHOR_EMAIL=${who.email}`, `GIT_COMMITTER_EMAIL=${who.email}`] : []),
+			],
+			ExposedPorts: { [`${inner}/tcp`]: {} },
+			HostConfig: {
+				PortBindings: { [`${inner}/tcp`]: [{ HostIp: env.DT_BIND, HostPort: String(port) }] },
+				Mounts: [
+					{ Type: 'volume', Source: vols.workspace, Target: '/workspace' },
+					{ Type: 'volume', Source: vols.home, Target: '/home/node' },
+					{ Type: 'volume', Source: vols.files, Target: '/files' },
+				],
+				RestartPolicy: { Name: 'unless-stopped' },
+			},
+		};
+		ok(await api('POST', `/containers/create?name=${encodeURIComponent(name)}`, body), `create container ${name}`);
+		c = await inspectContainer(name);
+		log(`✔ created ${name} from ${ref} · ${env.DT_BIND}:${port} → ${inner} · volumes ${Object.values(vols).join(', ')}`);
+	}
+	if (c.State?.Status !== 'running') {
+		const res = await api('POST', `/containers/${c.Id}/start`);
+		if (res.status !== 204 && res.status !== 304) ok(res, `start container ${name}`);
+		c = await inspectContainer(name);
+	}
+	const detail = containerDetail(c);
+	await waitHealthy(detail, log);
+	log(`✔ container ${name} · ${detail.state} · ${detail.editor_url}`);
+	if (!flags['no-open'] && detail.editor_url) openUrl(detail.editor_url);
+	return detail;
+}
+
+/** Poll code-server's /healthz so the URL printed is one that already answers. */
+async function waitHealthy(detail, log) {
+	const seconds = process.env.DT_HEALTH_TIMEOUT !== undefined ? Number(process.env.DT_HEALTH_TIMEOUT) : 90;
+	if (!seconds || !detail.port) return;
+	const until = Date.now() + seconds * 1000;
+	let told = false;
+	while (Date.now() < until) {
+		const up = await new Promise((r) => {
+			const req = http.get({ host: detail.bind || '127.0.0.1', port: detail.port, path: '/healthz', timeout: 2000 }, (res) => { res.resume(); r(res.statusCode < 500); });
+			req.on('error', () => r(false)); req.on('timeout', () => { req.destroy(); r(false); });
+		});
+		if (up) return;
+		if (!told) { log('… waiting for the editor to answer (first start compiles the workspace)'); told = true; }
+		await new Promise((r) => setTimeout(r, 1500));
+	}
+	log(`⚠ the editor did not answer within ${seconds}s — \`docker logs ${detail.name}\` says why`);
+}
+
+function openUrl(url) {
+	const cmd = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url];
+	try { spawn(cmd[0], cmd.slice(1), { stdio: 'ignore', detached: true }).unref(); } catch { /* printing the URL is the contract; opening it is a courtesy */ }
+}
+
+export async function stopContainer(name) {
+	const c = await inspectContainer(name);
+	if (!c) throw new Error(`no container "${name}" — dt list containers`);
+	const res = await api('POST', `/containers/${c.Id}/stop?t=10`);
+	if (res.status !== 204 && res.status !== 304) ok(res, `stop container ${name}`);
+	return containerDetail(await inspectContainer(name));
+}
+
+/** Plain `rm` keeps the three volumes — the workspace, the login, the files. `--force` removes them too. */
+export async function removeContainer(name, { force = false } = {}, log = console.log) {
+	const c = await inspectContainer(name);
+	if (!c) throw new Error(`no container "${name}" — dt list containers`);
+	const vols = containerDetail(c).volumes;
+	if (c.State?.Status === 'running') await api('POST', `/containers/${c.Id}/stop?t=10`);
+	ok(await api('DELETE', `/containers/${c.Id}?v=false`), `rm container ${name}`);
+	const named = Object.values(vols).filter(Boolean);
+	if (force) {
+		for (const v of named) { const r = await api('DELETE', `/volumes/${encodeURIComponent(v)}`); if (r.status !== 204 && r.status !== 404) ok(r, `rm volume ${v}`); }
+		log(`✔ removed ${name} and its volumes ${named.join(', ')}`);
+	} else {
+		log(`✔ removed ${name} · kept volumes ${named.join(', ')} (dt rm container ${name} --force removes them too; dt start container ${name} --template <t> reattaches them)`);
+	}
+}
+
+// ---- setup: the host's board -------------------------------------------------------------------
+export async function setup(flags, log = console.log) {
+	const dir = hostDir();
+	const file = path.join(dir, '.env');
+	fs.mkdirSync(dir, { recursive: true });
+	const existing = fs.existsSync(file) ? Object.fromEntries(parseEnvValues(fs.readFileSync(file, 'utf8'))) : {};
+	const missing = Object.entries(HOST_DEFAULTS).filter(([k]) => !(k in existing));
+	if (missing.length) {
+		const header = fs.existsSync(file) ? '' : '# dreamteamer host configuration — read by `dt setup`, `dt start container` and friends.\n# DT_IMAGE_<template>=<ref> pins a template to an image; DT_PERSON_NAME / DT_PERSON_EMAIL are the git identity containers get.\n';
+		fs.appendFileSync(file, header + missing.map(([k, v]) => `${k}=${v}`).join('\n') + '\n');
+	}
+	const board = [];
+	board.push(`host env    ${file} · ${missing.length ? `${missing.length} default(s) written` : 'present'}`);
+	let docker;
+	try {
+		const v = ok(await api('GET', '/version'), 'docker version');
+		docker = `docker      ${v.Version} · api ${v.ApiVersion} · ${v.Os}/${v.Arch} · ${socketPath()}`;
+	} catch (e) {
+		board.push(`docker      ✖ ${e.message}`);
+		for (const l of board) log(l);
+		return 1;
+	}
+	board.push(docker);
+	const images = await listImages();
+	board.push(`templates   ${images.length ? images.map((i) => `${i.template} (${i.image})`).join(', ') : 'none present — dt add image --template <t> pulls one'}`);
+	const template = typeof flags.template === 'string' ? flags.template : undefined;
+	if (template) {
+		const ref = imageRef(template);
+		if (!(await inspectImage(ref))) { log(`… pulling ${ref}`); await pullImage(ref, log); board.push(`pulled      ${ref}`); } else board.push(`present     ${ref}`);
+	}
+	const running = (await listContainers()).filter((c) => c.state === 'running');
+	board.push(`containers  ${running.length} running${running.length ? ' — ' + running.map((c) => `${c.name} ${c.editor_url}`).join(', ') : ''}`);
+	for (const l of board) log(l);
+	return 0;
+}
+
+// ---- the verb surface `cli.js` hands over ------------------------------------------------------
+const table = (rows, cols) => {
+	if (!rows.length) return '(none)';
+	const w = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+	return rows.map((r) => cols.map((c, i) => String(r[c] ?? '').padEnd(w[i])).join('  ').trimEnd()).join('\n');
+};
+
+/** `dt <verb> <container|containers|image|images>[/<id>] [<id>] [flags]` → exit code. */
+export async function driverCommand(verb, target, args) {
+	const { flags, pos } = parseFlags(args);
+	const id = target.id ?? pos[0];
+	const json = flags.json === true;
+	const col = target.collection;
+	if (!DRIVER_VERBS.has(verb)) throw new Error(`\`${verb}\` is not a verb on ${col} — list · get · add · rm${col === 'containers' ? ' · start · stop · open' : ''}`);
+	if (col === 'images') {
+		if (LIFECYCLE_VERBS.has(verb)) throw new Error(`\`${verb}\` is a container verb — an image is started by starting a container from it: dt start container <name> --template <t>`);
+		if (verb === 'list') { const rows = await listImages(); json ? emit(JSON.stringify(rows, null, 2)) : console.log(table(rows, ['template', 'image', 'size_mb', 'ports', 'created'])); return 0; }
+		if (verb === 'get') { if (!id) throw new Error('dt get image <ref>'); const i = await inspectImage(id); if (!i) throw new Error(`no image "${id}"`); emit(JSON.stringify(json ? i : imageRow({ ...i, Labels: i.Config?.Labels, Created: Date.parse(i.Created) / 1000 }), null, 2)); return 0; }
+		if (verb === 'add') { const t = typeof flags.template === 'string' ? flags.template : undefined; if (!t) throw new Error('dt add image --template <t> pulls the template\'s image'); const ref = imageRef(t); console.log(`… pulling ${ref}`); await pullImage(ref); console.log(`✔ ${ref}`); return 0; }
+		if (verb === 'rm') { if (!id) throw new Error('dt rm image <ref>'); ok(await api('DELETE', `/images/${encodeURIComponent(id)}${flags.force ? '?force=true' : ''}`), `rm image ${id}`); console.log(`✔ removed image ${id}`); return 0; }
+	}
+	// containers
+	if (verb === 'list') { const rows = await listContainers(); json ? emit(JSON.stringify(rows, null, 2)) : console.log(table(rows, ['name', 'template', 'state', 'editor_url', 'person', 'created'])); return 0; }
+	if (!id) throw new Error(`dt ${verb} container <name>${verb === 'start' || verb === 'add' ? ' --template <t>' : ''}`);
+	if (verb === 'get') { const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}" — dt list containers`); emit(JSON.stringify(json ? c : containerDetail(c), null, 2)); return 0; }
+	if (verb === 'start' || verb === 'add') { const d = await startContainer(id, flags); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
+	if (verb === 'stop') { const d = await stopContainer(id); console.log(`✔ stopped ${id} · volumes kept`); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
+	if (verb === 'open') { const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}"`); const d = containerDetail(c); if (!d.editor_url) throw new Error(`${id} publishes no port`); console.log(d.editor_url); if (!flags['no-open']) openUrl(d.editor_url); return 0; }
+	if (verb === 'rm') { await removeContainer(id, { force: flags.force === true }); return 0; }
+	return 1;
+}
+
+/** A local flag parser: `--k v`, `--k=v`, bare `--k` → true. Kept here rather than importing the
+ *  record parser's promotion rules — a repeated flag on these verbs is a mistake, not an array. */
+export function parseFlags(args) {
+	const flags = {}; const pos = [];
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (!a.startsWith('--')) { pos.push(a); continue; }
+		const eq = a.indexOf('=');
+		if (eq > -1) flags[a.slice(2, eq)] = a.slice(eq + 1);
+		else if (i + 1 < args.length && !args[i + 1].startsWith('--')) flags[a.slice(2)] = args[++i];
+		else flags[a.slice(2)] = true;
+	}
+	return { flags, pos };
+}
+
+export const CONTAINER_FLAGS = ['template', 'name', 'email', 'no-open', 'json', 'force'];

package/src/harnesses.js

@@ -25,6 +25,12 @@ export const STAMP = '<!-- generated by dreamteamer compile — do not edit; sou
 export const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 export const END = '<!-- dreamteamer:end -->';
 
+// A SECOND managed block, deliberately not folded into the orientation one. Separate delimiters
+// keep the orientation block's asserted size budget meaningful, and let `dreamteamer.md` be removed
+// on its own without the removal touching anything generated from the schema.
+export const INSTRUCTIONS_BEGIN = '<!-- dreamteamer:instructions:begin -->';
+export const INSTRUCTIONS_END = '<!-- dreamteamer:instructions:end -->';
+
 export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown', workspaceModule = '' }) {
 	const outputs = [];
 	// ⚠ SEPARATE from `outputs`: these are USER-OWNED root files carrying a managed block, and the
@@ -92,9 +98,34 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	block('GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
+	// ---- the operator's own rules, one source, every harness -------------------------
+	// Rendered VERBATIM. Nothing here reformats, wraps or summarises it: it is the operator's prose,
+	// and the whole value is that what he wrote is what every agent reads.
+	//
+	// ⚠ `enabled ? instructions : null` mirrors the orientation calls above, and the null branch is
+	// load-bearing twice: a harness switched off has its block removed, and so does a workspace that
+	// deletes its dreamteamer.md — `instructions` is null in that case and the same branch runs.
+	//
+	// ⚠ NOT through the local `block()` helper: that pushes the filename onto `blocks`, and these
+	// three files are already on it from their orientation calls above — pushing twice would hand
+	// git the same pathspec twice (schema-ops.regeneratedOutputs is the reader).
+	// ⚠ `|| null`, NOT `?? null`. `.trimEnd()` on a whitespace-only source yields `''`, which is not
+	// nullish — so the three Markdown files got an empty BEGIN/END pair while the cursor rule, which
+	// tests the string for truthiness below, omitted the part entirely. An empty source means no
+	// block, everywhere.
+	const instructions = entries.get('instructions.md')?.bytes?.toString('utf8').trimEnd() || null;
+	const instructionsBlock = (file, enabled) =>
+		writeBlock(root, file, enabled ? instructions : null, { begin: INSTRUCTIONS_BEGIN, end: INSTRUCTIONS_END, above: BEGIN });
+	instructionsBlock('CLAUDE.md', on('claude-code'));
+	instructionsBlock('AGENTS.md', on('codex') || on('pi'));
+	instructionsBlock('GEMINI.md', on('gemini-cli'));
+
 	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
 	if (on('cursor')) {
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule)}\n\n${STAMP}\n`;
+		// ⚠ `.mdc` is written WHOLE by `write()`, not through `writeBlock`, so removal is automatic: a
+		// compile with no dreamteamer.md simply rewrites the file without the part.
+		const instructionsPart = instructions ? `${INSTRUCTIONS_BEGIN}\n${instructions}\n${INSTRUCTIONS_END}\n\n` : '';
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${instructionsPart}${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -142,7 +173,16 @@ const NOTEBOOK_PLANS = [
 function notebooklmBlock(entries, version) {
 	const index = buildCollectionsIndex(entries);
 	const modules = buildModulesIndex(entries);
-	const data = index.filter((c) => !c.system);
+	// ⚠ `generated`, NOT `systemGroup` — the same split the orientation block's system line makes,
+	// asked for the opposite reason. There the question is presentational ("group it out of the
+	// domain listing"); HERE it is a STORAGE question, because every number and name below has to
+	// describe what `dt export notebooklm` will actually ship, and the export ships by storage
+	// (`storage.base !== 'runtime'` — export-notebooklm.js). Reading the partition here made this file
+	// say "exports 1 collections" and list only `notes` for a workspace whose export shipped
+	// `repos.md` as a second source and headed a `## module: System` group for it in the schema map
+	// — so the persona generated from this line would not know about a source it had been given.
+	// The count and the export are pinned to each other by a test (notebooklm-harness.test.js).
+	const data = index.filter((c) => !c.generated);
 	const withheldCollections = data.filter((c) => c.sensitive).map((c) => c.name);
 	const withheldFields = data.flatMap((c) => c.sensitiveFields.map((f) => `${c.name}.${f}`));
 	const exported = data.filter((c) => !c.sensitive);
@@ -245,10 +285,16 @@ function buildCollectionsIndex(entries) {
 		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { /* unparseable descriptor */ }
 		index.push({
 			name: d.name ?? m[1],
-			// DERIVED, never a hardcoded name list: `runtime` is exactly the schema-ops set
-			// (collections, commands, skills, agents, ui-views, command-bindings,
-			// collection-templates, modules) and stays right in a workspace shipping others.
-			system: d.storage?.base === 'runtime',
+			// ⚠ TWO QUESTIONS, KEPT SEPARATE. `systemGroup` answers "is this machinery, group it out
+			// of the domain listing"; `generated` answers "is this build output the hand-edit warning
+			// is about" — they agreed until `repos`, machinery whose records are still real files
+			// under `data/`. The partition is AUTHORED (`group: system` on the descriptor, ten core
+			// collections carry it), never derived from storage: a workspace collection may be its
+			// own apparatus, and a runtime-stored one may not be. An unparseable descriptor (`d = {}`
+			// from the catch above) carries neither key and answers false to both, which leaves it in
+			// the domain listing — the visible failure rather than the silent one.
+			systemGroup: d.group === 'system',
+			generated: d.storage?.base === 'runtime',
 			description: flat(d.description),
 			useWhen: flat(d.use_when),
 			module: d.module ?? '',
@@ -354,10 +400,10 @@ function collectionsSection(index, modules, workspaceModule) {
 		'collection\'s `write:` line names only what the store REFUSES — required fields that have no',
 		'default (a defaulted one is filled in for you), closed enums with their size, one example.',
 	];
-	const data = index.filter((c) => !c.system);
+	const data = index.filter((c) => !c.systemGroup);
 	const isWs = (m) => m.path === `modules/${workspaceModule}/`;
 	const groups = modules
-		.filter((m) => { const own = index.filter((c) => c.module === m.id); return own.some((c) => !c.system) || (!own.length && (m.skills.length || m.commands.length || m.bin.length || m.proofs.length)); })
+		.filter((m) => { const own = index.filter((c) => c.module === m.id); return own.some((c) => !c.systemGroup) || (!own.length && (m.skills.length || m.commands.length || m.bin.length || m.proofs.length)); })
 		.sort((a, b) => (isWs(b) - isWs(a)) || a.title.localeCompare(b.title));
 	for (const m of groups) {
 		const where = [`\`${m.id}\``, m.path ? m.path.replace(/\/$/, '') : 'the workspace root', ...(m.namespaces.length ? [`namespaces: ${m.namespaces.join(' · ')}`] : [])];
@@ -370,13 +416,19 @@ function collectionsSection(index, modules, workspaceModule) {
 			if (c.write) lines.push(`    write: ${c.write}`);
 		}
 	}
-	const system = index.filter((c) => c.system).map((c) => c.name);
+	const sys = index.filter((c) => c.systemGroup);
+	const system = sys.filter((c) => c.generated).map((c) => c.name);
+	const kept = sys.filter((c) => !c.generated).map((c) => c.name);
 	// ⚠ THIS LINE IS THE FIRST THING A SESSION READS about the system collections, and until 0.19.0
 	// it said "schema-ops only", which named an internal module and a grammar that no longer exists.
 	// It now names the VERBS and the one policy difference, because an agent that knows the verbs
-	// exist still has to be told that these commit and records do not.
-	if (system.length) {
-		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`set-field\`/\`rm-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes). Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}`);
+	// exist still has to be told that these commit and records do not. And it is PARTITIONED on
+	// `generated`, not `systemGroup`: the partition only answers the grouping question, so a system
+	// collection whose records are real files (`repos`) gets its own trailing clause instead of being
+	// told "it is build output" — a sentence that was false of it and is false of the next data-backed
+	// system collection too, since the split is derived rather than naming one.
+	if (sys.length) {
+		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`set-field\`/\`rm-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes).${system.length ? ` Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}.` : ''}${kept.length ? ` Machinery whose records are real files you edit like any other: ${kept.join(' · ')}` : ''}`);
 	}
 	return lines;
 }
@@ -527,22 +579,35 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 
 // managed block in a USER-OWNED root file. content=null removes the block; a file left
 // empty (or whitespace) after removal is deleted — we created it, we clean it up.
-function writeBlock(root, filename, content) {
+function writeBlock(root, filename, content, { begin = BEGIN, end = END, above } = {}) {
 	const file = path.join(root, filename);
 	const exists = fs.existsSync(file);
 	if (content == null) {
 		if (!exists) return;
 		let text = fs.readFileSync(file, 'utf8');
-		if (!text.includes(BEGIN)) return;
-		text = text.replace(new RegExp(`\\n?\\n?${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}\\n?`), '\n');
+		if (!text.includes(begin)) return;
+		text = text.replace(new RegExp(`\\n?\\n?${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}\\n?`), '\n');
 		if (text.trim() === '') fs.rmSync(file);
 		else fs.writeFileSync(file, text);
 		return;
 	}
-	const block = `${BEGIN}\n${content}\n${END}`;
+	const block = `${begin}\n${content}\n${end}`;
+	// ⚠ A FUNCTION REPLACEMENT, never the string. `String.prototype.replace` reads `$&`, `` $` ``,
+	// `$'` and `$1` out of a STRING replacement and substitutes around the match — so a block whose
+	// content carries any of them is silently rewritten on the way in, and `$'…'` is ordinary bash in
+	// a file about shell commands. Measured: `use $'\n'` rendered as `use ` + the entire preamble.
+	// A function replacement is taken literally, which is what "verbatim" has to mean.
+	const insert = (replacement) => () => replacement;
 	let text = exists ? fs.readFileSync(file, 'utf8') : '';
-	if (text.includes(BEGIN)) text = text.replace(new RegExp(`${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}`), block);
-	else text = (text.trimEnd() + '\n\n' + block + '\n').replace(/^\n+/, '');
+	if (text.includes(begin)) {
+		text = text.replace(new RegExp(`${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}`), insert(block));
+	} else if (above && text.includes(above)) {
+		// ⚠ ORDER IS THE CONTRACT, not a preference. The rules must be read BEFORE the schema
+		// orientation, and a harness that truncates a long context file truncates the tail.
+		text = text.replace(above, insert(`${block}\n\n${above}`));
+	} else {
+		text = (text.trimEnd() + '\n\n' + block + '\n').replace(/^\n+/, '');
+	}
 	fs.writeFileSync(file, text);
 }
 

package/src/init.js

@@ -8,6 +8,7 @@ import { discoverModules, KINDS } from './compile.js';
 import { KNOWN_HARNESSES } from './harnesses.js';
 import { Store } from './store.js';
 import { envContext, renderTemplate } from './env-vars.js';
+import { ensureEditorRecommendation } from './workspace.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -147,8 +148,10 @@ export function init({ flags = {} } = {}) {
 	// A workspace that needs people as records ships its own collection (a module's `contacts` already
 	// does), and reads the operator from git where it needs one. `teams` went the same way 2026-07-31.
 
-	// .gitignore + .env.example (append-if-missing, never clobber)
+	// .gitignore + .env.example (append-if-missing, never clobber) + the editor recommendation, so
+	// the first window opened on this workspace offers the extension instead of leaving it to be found
 	appendMissing(path.join(root, '.gitignore'), GITIGNORE);
+	ensureEditorRecommendation(root);
 	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)