@motionode/cli 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @motionode/cli
+
+Work Motionode tickets with your own tools — Cursor, VS Code, a terminal —
+while Motionode keeps the work tied to the ticket, its git branches,
+verification and delivery.
+
+```sh
+npm install -g @motionode/cli
+cd path/to/your/clone
+motionode connect          # approve this computer in the browser, link this repo
+motionode dev              # keep running: Motionode sees branches and local changes
+motionode work T11-518     # start the ticket locally; its branch is checked out
+# …edit, commit and push with your own git…
+motionode finish T11-518   # Motionode checks your pushed commits and moves the ticket on
+```
+
+- Git stays yours: fetch, commit and push use your own credentials, and commits
+  carry your own name and email.
+- The CLI only talks to Motionode over outbound HTTPS; it opens no ports.
+- It runs only fixed git operations Motionode can ask for (check out a ticket
+  branch, show a diff, commit and push, move changes onto a ticket branch) —
+  never arbitrary commands.
+- `--api URL` (or `MOTIONODE_API_URL`) points it at another Motionode API.
+- Revoke a computer in Motionode → Settings → Development workflow.

package/bin/motionode.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+
+const Config = require('../lib/config');
+const Commands = require('../lib/commands');
+const Bridge = require('../lib/bridge');
+const { version } = require('../lib/api');
+
+const HELP = `motionode ${version} — work Motionode tickets with your own local tools
+
+  motionode connect [--api URL] [--name NAME]   connect this computer (once) and link the current repo
+  motionode link [--service UUID]               link the current repository folder to a Motionode repository
+  motionode unlink                              unlink the current folder
+  motionode dev                                 keep Motionode in sync (branches, local changes, commit requests)
+  motionode work <ticket>                       start a ticket locally and check out its branches (e.g. T11-518)
+  motionode finish <ticket> [--force] [--note]  you're done: Motionode checks your pushed commits and moves it on
+  motionode status                              what each linked folder has checked out and changed
+  motionode logout                              disconnect this computer
+
+Git stays yours: fetch, commit and push use your own git credentials and identity.`;
+
+function flags(argv) {
+	const out = { _: [] };
+	for (let i = 0; i < argv.length; i += 1) {
+		const a = argv[i];
+		if (a.startsWith('--')) {
+			const key = a.slice(2);
+			const next = argv[i + 1];
+			if (next && !next.startsWith('--')) { out[key] = next; i += 1; } else { out[key] = true; }
+		} else {
+			out._.push(a);
+		}
+	}
+	return out;
+}
+
+async function main() {
+	const [command, ...rest] = process.argv.slice(2);
+	const args = flags(rest);
+	const config = Config.load();
+	if (args.api) config.apiUrl = String(args.api).replace(/\/+$/, '');
+	switch (command) {
+		case 'connect':
+			return Commands.connect(config, { apiUrl: args.api || null, name: args.name || null, service: args.service || null, relogin: !!args.relogin });
+		case 'login':
+			return Commands.login(config, { apiUrl: args.api || null, name: args.name || null });
+		case 'link':
+			return Commands.link(config, { serviceUuid: args.service || null });
+		case 'unlink':
+			return Commands.unlink(config);
+		case 'dev':
+			return Bridge.run(config);
+		case 'work':
+			return Commands.work(config, args._[0]);
+		case 'finish':
+			return Commands.finish(config, args._[0], { force: !!args.force, note: typeof args.note === 'string' ? args.note : null });
+		case 'status':
+			return Commands.status(config);
+		case 'logout':
+			return Commands.logout(config);
+		case '--version':
+		case '-v':
+			console.log(version);
+			return null;
+		default:
+			console.log(HELP);
+			return null;
+	}
+}
+
+main().catch((err) => {
+	console.error(`✗ ${err.message}`);
+	process.exit(1);
+});

package/lib/api.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/** Outbound HTTPS to Motionode's /api/v1/local-dev — the only channel. */
+
+const pkg = require('../package.json');
+
+class ApiError extends Error {
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+	}
+}
+
+function client(config) {
+	const base = String(config.apiUrl || '').replace(/\/+$/, '');
+	async function request(method, pathname, body = null, { timeoutMs = 60000 } = {}) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		let resp;
+		try {
+			resp = await fetch(`${base}/api/v1/local-dev${pathname}`, {
+				method,
+				headers: {
+					'Content-Type': 'application/json',
+					'User-Agent': `motionode-cli/${pkg.version}`,
+					...(config.token ? { Authorization: `Bearer ${config.token}` } : {}),
+				},
+				body: body ? JSON.stringify(body) : undefined,
+				signal: controller.signal,
+			});
+		} catch (err) {
+			if (err.name === 'AbortError') throw new ApiError('Motionode did not answer in time.', 0);
+			throw new ApiError(`Could not reach Motionode at ${base}: ${err.message}`, 0);
+		} finally {
+			clearTimeout(timer);
+		}
+		let data = null;
+		try { data = await resp.json(); } catch (_e) { data = null; }
+		if (!resp.ok || data?.ok === false) {
+			throw new ApiError(data?.error || `Motionode answered ${resp.status}.`, resp.status);
+		}
+		return data || {};
+	}
+	return {
+		get: (p, opts) => request('GET', p, null, opts),
+		post: (p, body, opts) => request('POST', p, body || {}, opts),
+	};
+}
+
+module.exports = { client, ApiError, version: pkg.version };

package/lib/bridge.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * `motionode dev` — keeps Motionode in sync with this machine's linked
+ * repositories: every few seconds it reports each folder's branch and what is
+ * changed but not committed, and it runs the jobs Motionode asks for (check out
+ * a ticket branch, show a diff, commit and push, move changes to a ticket
+ * branch). Only those fixed git operations exist — no arbitrary commands.
+ */
+
+const Git = require('./git');
+const { client } = require('./api');
+const { version } = require('./api');
+
+const HEARTBEAT_MS = 10000;
+
+function log(...args) {
+	const t = new Date().toLocaleTimeString();
+	console.log(`[${t}]`, ...args);
+}
+
+async function collect(config) {
+	const out = [];
+	for (const ws of config.workspaces || []) {
+		try {
+			const st = await Git.status(ws.path);
+			out.push({
+				serviceUuid: ws.serviceUuid,
+				path: ws.path,
+				remoteUrl: await Git.remoteUrl(ws.path),
+				branch: st.branch,
+				headSha: st.headSha,
+				ahead: st.ahead,
+				behind: st.behind,
+				dirtyFiles: st.dirtyFiles,
+			});
+		} catch (err) {
+			out.push({ serviceUuid: ws.serviceUuid, path: ws.path, gitError: err.message });
+		}
+	}
+	return out;
+}
+
+function workspaceFor(config, serviceUuid) {
+	return (config.workspaces || []).find((w) => w.serviceUuid === serviceUuid) || null;
+}
+
+async function runJob(config, job) {
+	const payload = job.payload || {};
+	const ws = workspaceFor(config, payload.serviceUuid);
+	if (!ws) throw new Error(`No folder on this computer is linked to ${payload.serviceName || 'that repository'}. Run \`motionode link\` in it.`);
+	if (job.kind === 'checkout') {
+		const st = await Git.checkout(ws.path, payload.branch);
+		log(`checked out ${payload.branch} in ${ws.path}`);
+		return { branch: st.branch, headSha: st.headSha };
+	}
+	if (job.kind === 'diff') {
+		return Git.diff(ws.path, payload.path || null);
+	}
+	if (job.kind === 'commit') {
+		const res = await Git.commit(ws.path, { branch: payload.branch, message: payload.message, push: payload.push !== false });
+		log(res.nothingToCommit ? `nothing to commit in ${ws.path}${res.pushed ? ' (pushed)' : ''}` : `committed ${String(res.commitSha).slice(0, 7)} in ${ws.path}${res.pushed ? ' and pushed' : ''}`);
+		return res;
+	}
+	if (job.kind === 'move_changes') {
+		const res = await Git.moveChanges(ws.path, payload.branch);
+		log(`moved local changes onto ${payload.branch} in ${ws.path}`);
+		return res;
+	}
+	throw new Error(`Unknown job: ${job.kind}`);
+}
+
+async function handleJobs(config, api, jobs) {
+	for (const job of jobs || []) {
+		try {
+			const result = await runJob(config, job);
+			await api.post(`/jobs/${job.uuid}/result`, { ok: true, result });
+		} catch (err) {
+			log(`job ${job.kind} failed: ${err.message}`);
+			await api.post(`/jobs/${job.uuid}/result`, { ok: false, error: err.message }).catch(() => {});
+		}
+	}
+}
+
+async function run(config) {
+	if (!config.token) throw new Error('This computer is not connected. Run `motionode connect` first.');
+	if (!(config.workspaces || []).length) throw new Error('No folders are linked yet. Run `motionode link` inside a repository.');
+	const api = client(config);
+	log(`Motionode bridge running for ${config.machine?.name || 'this computer'} — ${config.workspaces.length} linked folder(s). Ctrl+C to stop.`);
+	let stopped = false;
+	process.on('SIGINT', () => { stopped = true; log('stopping'); process.exit(0); });
+
+	const beat = async () => {
+		try {
+			const res = await api.post('/heartbeat', { cliVersion: version, workspaces: await collect(config) });
+			await handleJobs(config, api, res.jobs);
+		} catch (err) {
+			log(`heartbeat failed: ${err.message}`);
+		}
+	};
+	await beat();
+	const timer = setInterval(beat, HEARTBEAT_MS);
+	// Long-poll so jobs (a checkout, a commit) start within a second.
+	while (!stopped) {
+		try {
+			const res = await api.get('/jobs?wait=25', { timeoutMs: 40000 });
+			if (res.jobs?.length) {
+				await handleJobs(config, api, res.jobs);
+				await beat();
+			}
+		} catch (err) {
+			if (err.status === 401) {
+				clearInterval(timer);
+				throw new Error('This computer was disconnected from Motionode. Run `motionode connect` again.');
+			}
+			await new Promise((r) => setTimeout(r, 5000));
+		}
+	}
+}
+
+module.exports = { run, collect };

package/lib/commands.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const os = require('os');
+const readline = require('readline');
+const { execFile } = require('child_process');
+const Config = require('./config');
+const Git = require('./git');
+const { client, version } = require('./api');
+
+function ask(question) {
+	const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
+}
+
+function openBrowser(url) {
+	const cmd = process.platform === 'win32' ? 'cmd' : (process.platform === 'darwin' ? 'open' : 'xdg-open');
+	const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+	execFile(cmd, args, { windowsHide: true }, () => {});
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Device-code login: approve this computer in the browser once. */
+async function login(config, { apiUrl = null, name = null } = {}) {
+	if (apiUrl) config.apiUrl = apiUrl.replace(/\/+$/, '');
+	const api = client({ ...config, token: null });
+	const machineName = name || os.hostname();
+	const start = await api.post('/device/start', { machineName, platform: `${process.platform}-${process.arch}` });
+	console.log('');
+	console.log(`  Approve this computer in Motionode: ${start.verificationUrl}`);
+	console.log(`  Code: ${start.userCode}`);
+	console.log('');
+	openBrowser(start.verificationUrl);
+	const until = Date.now() + start.expiresIn * 1000;
+	while (Date.now() < until) {
+		await sleep((start.interval || 3) * 1000);
+		const poll = await api.post('/device/poll', { deviceCode: start.deviceCode, cliVersion: version });
+		if (poll.status === 'approved') {
+			config.token = poll.token;
+			config.machine = poll.machine;
+			config.user = poll.user;
+			Config.save(config);
+			console.log(`✓ Connected as ${poll.user?.name || poll.user?.email || 'you'} (${poll.machine?.name}).`);
+			return config;
+		}
+		if (poll.status === 'denied') throw new Error('The connection was declined in the browser.');
+		if (poll.status === 'expired' || poll.status === 'invalid') throw new Error('The code expired. Run `motionode connect` again.');
+	}
+	throw new Error('The code expired. Run `motionode connect` again.');
+}
+
+/** Link the current folder to a Motionode repository (matched by its git remote when possible). */
+async function link(config, { serviceUuid = null, dir = process.cwd() } = {}) {
+	const root = await Git.isRepo(dir);
+	if (!root) throw new Error('This folder is not a git repository. Run `motionode link` inside your clone.');
+	const api = client(config);
+	const me = await api.get('/me');
+	const services = [];
+	for (const project of me.projects || []) {
+		for (const svc of project.services || []) services.push({ ...svc, projectUuid: project.uuid, projectName: project.name });
+	}
+	if (!services.length) throw new Error('You have no projects with AI building enabled to work on locally.');
+	let pick = serviceUuid ? services.find((s) => s.uuid === serviceUuid) : null;
+	if (!pick) {
+		const remote = Git.normalizeRepoUrl(await Git.remoteUrl(root));
+		const matches = remote ? services.filter((s) => Git.normalizeRepoUrl(s.repoUrl) === remote) : [];
+		if (matches.length === 1) pick = matches[0];
+		else {
+			const list = matches.length ? matches : services;
+			if (!matches.length && remote) console.log(`No Motionode repository has this folder's remote (${remote}). Choose one:`);
+			list.forEach((s, i) => console.log(`  ${i + 1}) ${s.projectName} → ${s.name}${s.repoUrl ? `  (${s.repoUrl})` : ''}`));
+			const answer = Number(await ask('Number: '));
+			pick = list[answer - 1];
+			if (!pick) throw new Error('Nothing linked.');
+		}
+	}
+	config.workspaces = (config.workspaces || []).filter((w) => !Config.samePath(w.path, root) && w.serviceUuid !== pick.uuid);
+	config.workspaces.push({
+		path: root,
+		serviceUuid: pick.uuid,
+		serviceName: pick.name,
+		projectUuid: pick.projectUuid,
+		projectName: pick.projectName,
+	});
+	Config.save(config);
+	console.log(`✓ ${root} → ${pick.projectName} / ${pick.name}`);
+	return pick;
+}
+
+async function connect(config, opts = {}) {
+	if (!config.token || opts.relogin) await login(config, opts);
+	if (await Git.isRepo(process.cwd())) await link(config, { serviceUuid: opts.service || null });
+	console.log('');
+	console.log('Next: keep `motionode dev` running so Motionode sees your branches and local changes,');
+	console.log('and use `motionode work <ticket>` to start a ticket (e.g. motionode work T11-518).');
+}
+
+async function unlink(config, { dir = process.cwd() } = {}) {
+	const root = (await Git.isRepo(dir)) || dir;
+	const before = (config.workspaces || []).length;
+	config.workspaces = (config.workspaces || []).filter((w) => !Config.samePath(w.path, root));
+	Config.save(config);
+	console.log(before === config.workspaces.length ? 'This folder was not linked.' : `✓ Unlinked ${root}`);
+}
+
+async function status(config) {
+	if (!config.token) {
+		console.log('Not connected. Run `motionode connect`.');
+		return;
+	}
+	console.log(`Motionode: ${config.apiUrl} — ${config.user?.name || config.user?.email || ''} on ${config.machine?.name || os.hostname()}`);
+	if (!(config.workspaces || []).length) {
+		console.log('No linked folders. Run `motionode link` inside a repository.');
+		return;
+	}
+	for (const ws of config.workspaces) {
+		try {
+			const st = await Git.status(ws.path);
+			const ticket = /^ai\/ticket-/.test(st.branch || '') ? `  ticket ${st.branch.replace(/^ai\/ticket-/, '')}` : '';
+			console.log(`\n${ws.projectName} / ${ws.serviceName}\n  ${ws.path}\n  branch ${st.branch || '(none)'}${ticket}`);
+			console.log(`  ${st.dirtyFiles.length} uncommitted file(s)${st.ahead ? `, ${st.ahead} commit(s) not pushed` : ''}${st.behind ? `, ${st.behind} behind` : ''}`);
+			for (const f of st.dirtyFiles.slice(0, 15)) console.log(`    ${f.status.padEnd(8)} ${f.path}`);
+		} catch (err) {
+			console.log(`\n${ws.projectName} / ${ws.serviceName}\n  ${ws.path}\n  git: ${err.message}`);
+		}
+	}
+}
+
+/** Start (or resume) a ticket locally and check its branches out here. */
+async function work(config, ref) {
+	if (!ref) throw new Error('Which ticket? e.g. motionode work T11-518');
+	const api = client(config);
+	const res = await api.post(`/tickets/${encodeURIComponent(ref)}/work`, {});
+	const lw = res.localWork || {};
+	console.log(`✓ ${lw.ticketDisplayId || ref} ${lw.ticketTitle || ''} — Build is yours, working locally.`);
+	for (const b of lw.branches || []) {
+		const ws = (config.workspaces || []).find((w) => w.serviceUuid === b.serviceUuid);
+		if (!ws) {
+			console.log(`  ${b.serviceName}: ${b.branch}  (no linked folder here — clone ${b.cloneUrl || 'the repo'} and run \`motionode link\`)`);
+			continue;
+		}
+		try {
+			await Git.checkout(ws.path, b.branch);
+			console.log(`  ${b.serviceName}: checked out ${b.branch} in ${ws.path}`);
+		} catch (err) {
+			console.log(`  ${b.serviceName}: could not check out ${b.branch} — ${err.message}`);
+			if (/denied|403|401|authentication|permission/i.test(err.message)) {
+				console.log('    Your git account has no access to this repository. Ask your project manager for access.');
+			}
+		}
+	}
+	console.log('\nCommit with your own git and push to the ticket branch. When you are done: motionode finish ' + (lw.ticketDisplayId || ref));
+}
+
+async function finish(config, ref, { force = false, note = null } = {}) {
+	if (!ref) throw new Error('Which ticket? e.g. motionode finish T11-518');
+	const api = client(config);
+	try {
+		const res = await api.post(`/tickets/${encodeURIComponent(ref)}/finish`, { force, note });
+		console.log(`✓ ${res.summary || 'Build finished.'}`);
+	} catch (err) {
+		console.log(`✗ ${err.message}`);
+		if (/not on the ticket branch|not pushed|uncommitted/i.test(err.message)) {
+			console.log('  Commit and push (git commit, git push), or run with --force to finish anyway.');
+		}
+		process.exitCode = 1;
+	}
+}
+
+async function logout(config) {
+	Config.save({ apiUrl: config.apiUrl, token: null, machine: null, user: null, workspaces: config.workspaces || [] });
+	console.log('✓ Disconnected this computer. (Remove it in Motionode Settings → Development workflow to revoke it there too.)');
+}
+
+module.exports = { login, link, connect, unlink, status, work, finish, logout };

package/lib/config.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * ~/.motionode/config.json — the machine token, the API it talks to, and which
+ * local folders are which Motionode repositories. Folder paths never leave this
+ * machine except as the label shown to their owner in Motionode.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DIR = process.env.MOTIONODE_HOME || path.join(os.homedir(), '.motionode');
+const FILE = path.join(DIR, 'config.json');
+const DEFAULT_API = process.env.MOTIONODE_API_URL || 'https://api.motionode.com';
+
+function load() {
+	try {
+		const raw = JSON.parse(fs.readFileSync(FILE, 'utf8'));
+		return {
+			apiUrl: raw.apiUrl || DEFAULT_API,
+			token: raw.token || null,
+			machine: raw.machine || null,
+			user: raw.user || null,
+			workspaces: Array.isArray(raw.workspaces) ? raw.workspaces : [],
+		};
+	} catch (_e) {
+		return { apiUrl: DEFAULT_API, token: null, machine: null, user: null, workspaces: [] };
+	}
+}
+
+function save(config) {
+	fs.mkdirSync(DIR, { recursive: true });
+	fs.writeFileSync(FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+function samePath(a, b) {
+	const norm = (p) => path.resolve(p).replace(/[\\/]+$/, '');
+	return process.platform === 'win32' ? norm(a).toLowerCase() === norm(b).toLowerCase() : norm(a) === norm(b);
+}
+
+function workspaceForPath(config, dir) {
+	return (config.workspaces || []).find((w) => samePath(w.path, dir)) || null;
+}
+
+module.exports = { DIR, FILE, DEFAULT_API, load, save, samePath, workspaceForPath };

package/lib/git.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * The fixed git operations the CLI runs — nothing else. Everything uses the
+ * developer's own git: their credentials (credential helper / SSH keys) to
+ * fetch and push, and their own user.name / user.email on commits.
+ */
+
+const { execFile } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_DIFF_CHARS = 400000;
+
+function run(cwd, args, { allowFail = false, timeoutMs = 120000 } = {}) {
+	return new Promise((resolve, reject) => {
+		execFile('git', args, { cwd, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+			if (err && !allowFail) {
+				const message = String(stderr || err.message || '').trim() || `git ${args[0]} failed`;
+				const e = new Error(message);
+				e.stderr = stderr;
+				return reject(e);
+			}
+			return resolve({ ok: !err, stdout: String(stdout || ''), stderr: String(stderr || '') });
+		});
+	});
+}
+
+async function isRepo(dir) {
+	const r = await run(dir, ['rev-parse', '--show-toplevel'], { allowFail: true });
+	return r.ok ? r.stdout.trim() : null;
+}
+
+async function remoteUrl(dir) {
+	const r = await run(dir, ['remote', 'get-url', 'origin'], { allowFail: true });
+	return r.ok ? r.stdout.trim() : null;
+}
+
+/** github.com/owner/repo from https / ssh / credentials-in-URL forms. */
+function normalizeRepoUrl(url) {
+	let u = String(url || '').trim();
+	if (!u) return null;
+	u = u.replace(/^git@([^:]+):/, 'https://$1/');
+	u = u.replace(/^ssh:\/\/git@/, 'https://');
+	u = u.replace(/^https?:\/\/[^@/]+@/, 'https://');
+	u = u.replace(/^https?:\/\//, '');
+	u = u.replace(/\.git$/, '').replace(/\/+$/, '');
+	return u.toLowerCase();
+}
+
+/** Branch, head, ahead/behind and the files changed but not committed. */
+async function status(dir) {
+	const s = await run(dir, ['status', '--porcelain=v1', '-b', '--untracked-files=all']);
+	const lines = s.stdout.split('\n').filter(Boolean);
+	let branch = null;
+	let ahead = 0;
+	let behind = 0;
+	const files = [];
+	for (const line of lines) {
+		if (line.startsWith('## ')) {
+			const head = line.slice(3);
+			const m = head.match(/^([^.\s]+(?:\.[^.\s]+)*?)(?:\.\.\.(\S+))?(?:\s+\[(.*)\])?$/);
+			branch = m ? m[1] : head.split(/\s|\.\.\./)[0];
+			if (branch === 'HEAD' || /^No commits yet on /.test(head)) branch = head.replace(/^No commits yet on /, '') || null;
+			const info = m?.[3] || '';
+			const a = info.match(/ahead (\d+)/);
+			const b = info.match(/behind (\d+)/);
+			ahead = a ? Number(a[1]) : 0;
+			behind = b ? Number(b[1]) : 0;
+			continue;
+		}
+		const code = line.slice(0, 2);
+		const file = line.slice(3).replace(/^"|"$/g, '').split(' -> ').pop();
+		const kind = code === '??' ? 'added'
+			: code.includes('D') ? 'removed'
+				: code.includes('A') ? 'added'
+					: code.includes('R') ? 'renamed'
+						: 'modified';
+		files.push({ path: file, status: kind, additions: 0, deletions: 0 });
+	}
+	// +/- for tracked files.
+	const num = await run(dir, ['diff', 'HEAD', '--numstat'], { allowFail: true });
+	if (num.ok) {
+		const stats = new Map();
+		for (const l of num.stdout.split('\n').filter(Boolean)) {
+			const [add, del, ...rest] = l.split('\t');
+			stats.set(rest.join('\t'), { additions: Number(add) || 0, deletions: Number(del) || 0 });
+		}
+		for (const f of files) {
+			const st = stats.get(f.path);
+			if (st) Object.assign(f, st);
+		}
+	}
+	const headSha = (await run(dir, ['rev-parse', 'HEAD'], { allowFail: true })).stdout.trim() || null;
+	return { branch, headSha, ahead, behind, dirtyFiles: files };
+}
+
+async function hasLocalBranch(dir, branch) {
+	const r = await run(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], { allowFail: true });
+	return r.ok;
+}
+
+/** Fetch and switch to a branch (creating it to track origin when missing). Uncommitted changes come along when git allows. */
+async function checkout(dir, branch) {
+	await run(dir, ['fetch', 'origin', branch]);
+	if (await hasLocalBranch(dir, branch)) {
+		await run(dir, ['switch', branch]);
+		await run(dir, ['merge', '--ff-only', `origin/${branch}`], { allowFail: true });
+	} else {
+		await run(dir, ['switch', '-c', branch, '--track', `origin/${branch}`]);
+	}
+	return status(dir);
+}
+
+/** The uncommitted diff, including new files. */
+async function diff(dir, onlyPath = null) {
+	const args = ['diff', 'HEAD'];
+	if (onlyPath) args.push('--', onlyPath);
+	const tracked = await run(dir, args, { allowFail: true });
+	let out = tracked.stdout;
+	const untracked = await run(dir, ['ls-files', '--others', '--exclude-standard'], { allowFail: true });
+	for (const file of untracked.stdout.split('\n').filter(Boolean)) {
+		if (onlyPath && file !== onlyPath) continue;
+		if (out.length > MAX_DIFF_CHARS) break;
+		let content = '';
+		try {
+			const full = path.join(dir, file);
+			if (fs.statSync(full).size > 512 * 1024) { content = '(large file not shown)'; } else { content = fs.readFileSync(full, 'utf8'); }
+		} catch (_e) { content = '(unreadable)'; }
+		const lines = content.split(/\r?\n/);
+		out += `--- /dev/null\n+++ b/${file}\n@@ -0,0 +1,${lines.length} @@\n${lines.map((l) => `+${l}`).join('\n')}\n`;
+	}
+	const truncated = out.length > MAX_DIFF_CHARS;
+	return { diff: truncated ? out.slice(0, MAX_DIFF_CHARS) : out, truncated };
+}
+
+/** Commit everything changed on `branch` with the developer's identity; push when asked. */
+async function commit(dir, { branch, message, push = true }) {
+	const st = await status(dir);
+	if (branch && st.branch !== branch) {
+		throw new Error(`This folder is on ${st.branch || 'no branch'}, not the ticket branch ${branch}. Check it out first (motionode work <ticket>).`);
+	}
+	let commitSha = null;
+	let nothingToCommit = false;
+	if (st.dirtyFiles.length) {
+		await run(dir, ['add', '-A']);
+		await run(dir, ['commit', '-m', message || 'Work from Motionode CLI']);
+		commitSha = (await run(dir, ['rev-parse', 'HEAD'])).stdout.trim();
+	} else {
+		nothingToCommit = true;
+	}
+	let pushed = false;
+	if (push) {
+		await run(dir, ['push', '-u', 'origin', st.branch || branch]);
+		pushed = true;
+	}
+	return { commitSha, pushed, nothingToCommit };
+}
+
+/** Carry uncommitted changes from wherever they are onto `branch`. */
+async function moveChanges(dir, branch) {
+	const st = await status(dir);
+	if (st.branch === branch) return { moved: false, branch };
+	const dirty = st.dirtyFiles.length > 0;
+	if (dirty) await run(dir, ['stash', 'push', '-u', '-m', `motionode: move to ${branch}`]);
+	try {
+		await checkout(dir, branch);
+	} catch (err) {
+		if (dirty) await run(dir, ['stash', 'pop'], { allowFail: true });
+		throw err;
+	}
+	if (dirty) {
+		const pop = await run(dir, ['stash', 'pop'], { allowFail: true });
+		if (!pop.ok) {
+			throw new Error(`Switched to ${branch}, but your changes conflict with it. They are kept in git stash — resolve with \`git stash pop\`.`);
+		}
+	}
+	return { moved: true, branch };
+}
+
+module.exports = { run, isRepo, remoteUrl, normalizeRepoUrl, status, checkout, diff, commit, moveChanges };

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@motionode/cli",
+  "version": "0.1.0",
+  "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": {
+    "motionode": "bin/motionode.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}