@motionode/cli 0.1.2 → 0.2.1

package/lib/project_cmds.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * C1-031: file work and keep project notes from the terminal, as the connected person (same machine token as the rest
+ * of the CLI, or MOTIONODE_TOKEN). The project is --project <uuid or exact name>, or MOTIONODE_PROJECT.
+ *
+ *   motionode deliverables --project P
+ *   motionode work-item create --project P --title T [--description D | --description-file F]
+ *                               [--deliverable R2-1 | --new-deliverable "Name"] [--criteria "a | b"] [--confirmed-new]
+ *   motionode work-item update <code> --project P [--title T] [--description D | --description-file F]   (C1-032)
+ *   motionode notes list --project P
+ *   motionode notes get <uuid> --project P [--html]
+ *   motionode notes create --project P --file F.md [--deliverable R | --ticket T] [--share a@x,b@y] [--category C]
+ *   motionode notes update <uuid> --project P --file F.md
+ */
+
+const fs = require('fs');
+const { agentClient } = require('./agent_api');
+
+function projectOf(args) {
+	const p = (typeof args.project === 'string' && args.project) || process.env.MOTIONODE_PROJECT || '';
+	if (!p) throw new Error('Say which project: --project <uuid or name> (or set MOTIONODE_PROJECT).');
+	return encodeURIComponent(p);
+}
+
+function readText(file) {
+	if (typeof file !== 'string' || !file) throw new Error('Give the content with --file <path>.');
+	return fs.readFileSync(file, 'utf8');
+}
+
+const list = (value) => (typeof value === 'string' ? value.split('|').map((s) => s.trim()).filter(Boolean) : []);
+
+async function deliverables(config, args, { api = agentClient(config), out = console.log } = {}) {
+	const res = await api.get(`/project/${projectOf(args)}/deliverables`);
+	for (const d of res.deliverables || []) out(`${d.displayId || '-'}\t${d.title}${Number(d.isInterrupt) ? ' (Interrupt)' : ''}\t${d.uuid}`);
+	return res;
+}
+
+async function createWorkItem(config, args, { api = agentClient(config), out = console.log } = {}) {
+	if (typeof args.title !== 'string' || !args.title.trim()) throw new Error('Give the work item a --title.');
+	const description = typeof args['description-file'] === 'string' ? readText(args['description-file']) : (typeof args.description === 'string' ? args.description : '');
+	try {
+		const res = await api.post(`/project/${projectOf(args)}/work_items`, {
+			title: args.title,
+			description,
+			deliverable: typeof args.deliverable === 'string' ? args.deliverable : null,
+			newDeliverable: typeof args['new-deliverable'] === 'string' ? args['new-deliverable'] : null,
+			acceptanceCriteria: list(args.criteria),
+			confirmedNew: args['confirmed-new'] === true,
+		});
+		out(`✓ ${res.workItem.displayId || res.workItem.uuid} "${res.workItem.title}" in ${res.deliverable.displayId || ''} ${res.deliverable.title}${res.deliverable.created ? ' (new deliverable)' : ''} — in setup, nothing started`);
+		for (const s of res.similar || []) out(`  similar open work: ${s.displayId || s.uuid} "${s.title}"${s.why ? ` (${s.why})` : ''}`);
+		return res;
+	} catch (err) {
+		// 409: open work already has this title -- the API names it.
+		if (err.status === 409) out('  (pass --confirmed-new if this is genuinely separate)');
+		throw err;
+	}
+}
+
+/** C1-032: change a work item's title and/or description, as the connected person (their edit rights on the project). */
+async function updateWorkItem(config, args, { api = agentClient(config), out = console.log } = {}) {
+	const ref = args._[1];
+	if (!ref) throw new Error('Which work item? motionode work-item update <code> --title T');
+	const patch = {};
+	if (typeof args.title === 'string') patch.title = args.title;
+	if (typeof args['description-file'] === 'string') patch.description = readText(args['description-file']);
+	else if (typeof args.description === 'string') patch.description = args.description;
+	if (typeof args.status === 'string') patch.status = args.status;
+	if (!Object.keys(patch).length) throw new Error('Say what to change: --title and/or --description (or --description-file).');
+	const res = await api.patch(`/project/${projectOf(args)}/work_items/${encodeURIComponent(ref)}`, patch);
+	out(res.changed && res.changed.length
+		? `✓ ${res.workItem.displayId || res.workItem.uuid} "${res.workItem.title}": changed ${res.changed.join(' and ')}`
+		: `= ${res.workItem.displayId || res.workItem.uuid} "${res.workItem.title}": nothing to change`);
+	return res;
+}
+
+async function notes(config, args, { api = agentClient(config), out = console.log } = {}) {
+	const sub = args._[0] || 'list';
+	const project = projectOf(args);
+	if (sub === 'list') {
+		const res = await api.get(`/project/${project}/notes`);
+		for (const n of res.notes || []) out(`${n.uuid}\t${n.title || '(untitled)'}\t${n.entityType}${n.category ? `/${n.category}` : ''}\t${n.chars} chars`);
+		return res;
+	}
+	const uuid = args._[1];
+	if (sub === 'get') {
+		if (!uuid) throw new Error('Which note? motionode notes get <uuid>');
+		const res = await api.get(`/project/${project}/notes/${encodeURIComponent(uuid)}`);
+		out(args.html ? (res.note.html || '') : (res.note.text || ''));
+		return res;
+	}
+	if (sub === 'create') {
+		const res = await api.post(`/project/${project}/notes`, {
+			markdown: readText(args.file),
+			category: typeof args.category === 'string' ? args.category : null,
+			deliverable: typeof args.deliverable === 'string' ? args.deliverable : null,
+			ticket: typeof args.ticket === 'string' ? args.ticket : null,
+			shareWith: typeof args.share === 'string' ? args.share.split(',').map((s) => s.trim()).filter(Boolean) : [],
+		});
+		out(`✓ note ${res.note.uuid} "${res.note.title || ''}" (${res.note.entityType})`);
+		return res;
+	}
+	if (sub === 'update') {
+		if (!uuid) throw new Error('Which note? motionode notes update <uuid> --file F.md');
+		const res = await api.patch(`/project/${project}/notes/${encodeURIComponent(uuid)}`, {
+			markdown: readText(args.file),
+			category: typeof args.category === 'string' ? args.category : null,
+		});
+		out(`✓ updated note ${res.note.uuid} "${res.note.title || ''}"`);
+		return res;
+	}
+	throw new Error(`Unknown: motionode notes ${sub} (list | get | create | update)`);
+}
+
+module.exports = { deliverables, createWorkItem, updateWorkItem, notes, _internals: { projectOf, list } };

package/lib/signals_hook.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * `motionode signals hook <event>`: run by Claude Code hooks (no model, no network;
+ * reads the local inbox that `motionode signals watch` keeps). It puts pending
+ * Motionode signals in front of the agent at a safe point:
+ *   PostToolUse / UserPromptSubmit → add them to the agent's context;
+ *   Stop → refuse to finish while a signal that needs action is unacknowledged
+ *          (never twice in a row: Claude Code's stop_hook_active).
+ * The agent clears a signal with the MCP tool ack_signal.
+ */
+
+const Inbox = require('./inbox');
+
+function readStdin() {
+	return new Promise((resolve) => {
+		if (process.stdin.isTTY) return resolve({});
+		let data = '';
+		process.stdin.setEncoding('utf8');
+		process.stdin.on('data', (c) => { data += c; });
+		process.stdin.on('end', () => { try { resolve(JSON.parse(data || '{}')); } catch (_e) { resolve({}); } });
+		setTimeout(() => resolve({}), 1500);
+	});
+}
+
+function describe(signals) {
+	const lines = signals.slice(0, 8).map((s) => `- [#${s.id} · ${s.kind}${s.requiresAction ? ' · needs action' : ''} · ticket ${s.ticketRef || '?'}] ${String(s.summary || '').replace(/\s+/g, ' ').slice(0, 300)}`);
+	const more = signals.length > 8 ? `\n…and ${signals.length - 8} more (call get_signals).` : '';
+	return `Motionode signals for this work (acknowledge each with the motionode ack_signal tool; set incorporated=true only once your work reflects it):\n${lines.join('\n')}${more}`;
+}
+
+async function run(event) {
+	const input = await readStdin();
+	const dir = input.cwd || process.cwd();
+	const pending = Inbox.read(dir);
+	if (event === 'Stop') {
+		if (input.stop_hook_active) return; // already blocked once; let the agent stop
+		const critical = pending.filter((s) => s.requiresAction);
+		if (!critical.length) return;
+		process.stdout.write(JSON.stringify({
+			decision: 'block',
+			reason: `${describe(critical)}\nBefore finishing: handle these, or acknowledge them with ack_signal and say why they don't apply.`,
+		}));
+		return;
+	}
+	if (!pending.length) return;
+	process.stdout.write(JSON.stringify({
+		hookSpecificOutput: { hookEventName: event, additionalContext: describe(pending) },
+	}));
+}
+
+function printPending() {
+	const pending = Inbox.read(process.cwd());
+	if (!pending.length) { console.log('No Motionode signals waiting for this repository.'); return; }
+	console.log(describe(pending));
+}
+
+module.exports = { run, printPending, describe };

package/lib/signals_watch.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * `motionode signals watch`: one long-lived connection to Motionode's signal
+ * stream (Server-Sent Events). Each pushed signal is written to the local inbox
+ * at once; no model is involved, so this costs no AI credits. Reconnects with a
+ * growing pause when the connection drops.
+ *
+ * Two robustness details, since this runs unattended for hours:
+ *  - the server heartbeats every 20s, but a silent intermediary (a proxy or NAT
+ *    that drops the stream without a FIN/RST) can leave the socket open and
+ *    looking "connected" while nothing ever arrives again. An idle timeout
+ *    (IDLE_TIMEOUT_MS, reset on every chunk received, heartbeats included)
+ *    aborts and reconnects instead of hanging forever.
+ *  - a single 401 could be a transient auth hiccup, not an actual revocation.
+ *    watch() only gives up for good after FATAL_401_STREAK consecutive 401s;
+ *    anything else in between (a real event, or a non-401 error) resets the count.
+ */
+
+const pkg = require('../package.json');
+const Inbox = require('./inbox');
+
+const IDLE_TIMEOUT_MS = 60000;
+const FATAL_401_STREAK = 2;
+
+function parseEvents(buffer) {
+	const events = [];
+	let rest = buffer;
+	let idx;
+	while ((idx = rest.indexOf('\n\n')) >= 0) {
+		const block = rest.slice(0, idx);
+		rest = rest.slice(idx + 2);
+		let event = 'message';
+		const data = [];
+		for (const line of block.split('\n')) {
+			if (line.startsWith(':')) continue;
+			if (line.startsWith('event:')) event = line.slice(6).trim();
+			else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+		}
+		if (data.length) events.push({ event, data: data.join('\n') });
+	}
+	return { events, rest };
+}
+
+async function watchOnce({ base, token, dir, onSignal, onStatus = null }) {
+	const controller = new AbortController();
+	let idleTimer = null;
+	const armIdleTimer = () => {
+		clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => controller.abort(), IDLE_TIMEOUT_MS);
+	};
+
+	armIdleTimer();
+	let resp;
+	try {
+		resp = await fetch(`${base}/api/v1/agent/signals/stream`, {
+			// Same agent name as the MCP server, so the watch and the tools are ONE session (one holder of its claims).
+			headers: { Authorization: `Bearer ${token}`, Accept: 'text/event-stream', 'User-Agent': `motionode-cli/${pkg.version}`, ...require('./agent_api').agentHeaders() },
+			signal: controller.signal,
+		});
+	} catch (err) {
+		clearTimeout(idleTimer);
+		if (err.name === 'AbortError') throw new Error(`No data from Motionode for ${Math.round(IDLE_TIMEOUT_MS / 1000)}s; reconnecting.`);
+		throw err;
+	}
+	if (resp.status === 401) { clearTimeout(idleTimer); throw Object.assign(new Error('Not connected or token revoked.'), { status: 401 }); }
+	if (!resp.ok || !resp.body) { clearTimeout(idleTimer); throw new Error(`Motionode answered ${resp.status}.`); }
+
+	const reader = resp.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = '';
+	try {
+		for (;;) {
+			let value, done;
+			try {
+				({ value, done } = await reader.read());
+			} catch (err) {
+				if (err.name === 'AbortError') throw new Error(`No data from Motionode for ${Math.round(IDLE_TIMEOUT_MS / 1000)}s; reconnecting.`);
+				throw err;
+			}
+			if (done) return;
+			armIdleTimer(); // bytes arrived (an event or a heartbeat ping) -- the connection is alive
+			buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, '\n');
+			const parsed = parseEvents(buffer);
+			buffer = parsed.rest;
+			for (const ev of parsed.events) {
+				// The stream says when it is connected and which work it watches ("ready", then "scope" when that changes):
+				// shown, so a quiet watch reads as connected and waiting, never as stopped.
+				if ((ev.event === 'ready' || ev.event === 'scope') && onStatus) {
+					let info = null;
+					try { info = JSON.parse(ev.data); } catch (_e) { info = null; }
+					onStatus(ev.event, info || {});
+					continue;
+				}
+				// Motionode couldn't read the work or its signals (it retries): said, so silence never means "nothing".
+				if ((ev.event === 'error' || ev.event === 'recovered') && onStatus) {
+					let info = null;
+					try { info = JSON.parse(ev.data); } catch (_e) { info = null; }
+					onStatus(ev.event, info || {});
+					continue;
+				}
+				if (ev.event !== 'signal') continue;
+				let signal = null;
+				try { signal = JSON.parse(ev.data); } catch (_e) { continue; }
+				if (signal && Inbox.add(dir, signal) && onSignal) onSignal(signal);
+			}
+		}
+	} finally {
+		clearTimeout(idleTimer);
+	}
+}
+
+async function watch(config, { dir = process.cwd(), quiet = false } = {}) {
+	const base = String(config.apiUrl || '').replace(/\/+$/, '');
+	const token = process.env.MOTIONODE_TOKEN || config.token;
+	if (!token) {
+		console.error('Not connected. Run "motionode connect" first.');
+		process.exitCode = 1;
+		return;
+	}
+	Inbox.ensureExcluded(dir);
+	// The inbox exists from the start: an empty one means nothing has been sent yet, not that the watch is broken.
+	if (!Inbox.read(dir).length) Inbox.write(dir, []);
+	console.log(`Watching Motionode signals for this repository → ${Inbox.inboxPath(dir)}`);
+	let pause = 2000;
+	let consecutive401s = 0;
+	for (;;) {
+		try {
+			await watchOnce({
+				base,
+				token,
+				dir,
+				onStatus: (event, info) => {
+					pause = 2000;
+					consecutive401s = 0;
+					const n = Number(info.ticketCount) || 0;
+					if (event === 'error') { console.error(`[${new Date().toLocaleTimeString()}] ⚠ ${info.error || "Motionode couldn't read your work; retrying."}`); return; }
+					if (event === 'recovered') { if (!quiet) console.log(`[${new Date().toLocaleTimeString()}] Reading signals again: watching ${n} ticket${n === 1 ? '' : 's'}.`); return; }
+					if (!quiet) console.log(`[${new Date().toLocaleTimeString()}] ${event === 'ready' ? 'Connected' : 'Your work changed'}: watching ${n} ticket${n === 1 ? '' : 's'}.`);
+				},
+				onSignal: (s) => {
+					pause = 2000;
+					consecutive401s = 0;
+					if (!quiet) console.log(`[${new Date().toLocaleTimeString()}] ${s.requiresAction ? '⚠ ' : ''}${s.kind}: ${String(s.summary || '').split('\n')[0].slice(0, 160)}`);
+					if (s.requiresAction) process.stdout.write('\u0007');
+				},
+			});
+			consecutive401s = 0; // a clean connection (even with no signals) means the token is fine
+		} catch (err) {
+			if (err.status === 401) {
+				consecutive401s += 1;
+				if (consecutive401s >= FATAL_401_STREAK) {
+					console.error('Not connected or token revoked. Run "motionode connect".');
+					process.exitCode = 1;
+					return;
+				}
+				if (!quiet) console.error(`Motionode answered 401 (attempt ${consecutive401s}/${FATAL_401_STREAK}); retrying in case it's transient.`);
+			} else {
+				consecutive401s = 0;
+				if (!quiet) console.error(`Signal stream interrupted (${err.message}); reconnecting in ${Math.round(pause / 1000)}s`);
+			}
+		}
+		await new Promise((r) => setTimeout(r, pause));
+		pause = Math.min(pause * 2, 60000);
+	}
+}
+
+module.exports = { watch, parseEvents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionode/cli",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Connect your local repositories to Motionode: work tickets in Cursor, VS Code or any editor while Motionode keeps the work tied to the ticket, its git branches, verification and delivery.",
   "license": "UNLICENSED",
   "bin": {