@motionode/cli 0.2.0 → 0.2.3

package/README.md

@@ -9,9 +9,9 @@ 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
+motionode work T9-99       # 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
+motionode finish T9-99     # Motionode checks your pushed commits and moves the ticket on
 ```
 
 - Git stays yours: fetch, commit and push use your own credentials, and commits
@@ -23,6 +23,21 @@ motionode finish T11-518   # Motionode checks your pushed commits and moves the
 - `motionode use <url>` points every terminal at another Motionode API until `motionode use production`; `--api URL` or `MOTIONODE_API_URL` overrides it for one run. `motionode where` shows the current one.
 - Revoke a computer in Motionode → Settings → Development workflow.
 
+## Newer commands (0.2.3)
+
+- `motionode doctor` prints where this terminal stands in one screen (which Motionode, who is connected and for which
+  organization, git identity, remote, branch, the linked project and repository, the ticket the branch belongs to and whether local
+  work is open) and the next command to run. Paste it to Mo or your project manager when something does not work.
+- `motionode work <ticket> [--project NAME]` / `motionode finish <ticket> [--project NAME]`: a ticket code is only unique inside one
+  organization. The code resolves inside your own projects, preferring the project of the folder you are in; when two of your
+  projects share it, the answer lists them and you pick with `--project` or the ticket id. The output always names the ticket and
+  the project it acted on.
+- `motionode work` ends with "Ready" or "Not ready"; it never reports success before the branch is checked out. After a step was
+  finished, `motionode work` reopens a session so you can keep pushing fixes, and `motionode finish` records them as a new version.
+- `motionode finish <ticket> --no-changes --note "why"` finishes your step when the work already exists and nothing needs to
+  change. `finish` only ever completes a step you hold and started.
+- `--help` (also `connect --help`) prints help and never starts a login.
+
 ## Repositories Motionode hosts
 
 A repository Motionode hosts lives privately in Motionode's GitHub, so your own

package/bin/motionode.js

@@ -15,10 +15,13 @@ const HELP = `motionode ${version} — work Motionode tickets with your own loca
   motionode clone <service | owner/repo> [dir]  clone a Motionode-hosted repository through Motionode (no GitHub
                                                 access needed: this computer's connection signs git in)
   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 work <ticket> [--project P]         start a ticket locally and check out its branches (e.g. T9-99); a code
+                                                shared by several projects resolves to this folder's project, or --project
+  motionode finish <ticket> [--force] [--note]  you're done: Motionode checks your pushed commits and completes YOUR step
+                        [--no-changes]          (nothing needs to change: the work already exists; give a --note why)
   motionode status                              what each linked folder has checked out and changed
   motionode where                               which Motionode this terminal talks to
+  motionode doctor                              where this terminal stands (API, person, git identity, branch, ticket) and what to run next
   motionode use <url|production>                switch which Motionode the CLI talks to (remembered)
   motionode logout                              disconnect this computer
 
@@ -64,6 +67,18 @@ function flags(argv) {
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
 	const args = flags(rest);
+	// Help is printed before anything else runs: `connect --help` must never start a login.
+	if (!command || command === 'help' || command === '--help' || command === '-h' || args.help || rest.includes('-h')) {
+		console.log(HELP);
+		return null;
+	}
+	/**
+	 * A server named for `connect` is the one this computer keeps using: the work
+	 * panel prints `motionode connect --api …` once, and every command after it
+	 * must stay on that Motionode rather than fall back to production
+	 * (QA-20261023T234000Z).
+	 */
+	if (command === 'connect' && typeof args.api === 'string') Config.useApi(args.api);
 	// --api (or MOTIONODE_API_URL) picks the Motionode — and its own saved connection.
 	const config = Config.load(typeof args.api === 'string' ? args.api : null);
 	switch (command) {
@@ -83,9 +98,9 @@ async function main() {
 		case 'dev':
 			return Bridge.run(config);
 		case 'work':
-			return Commands.work(config, args._[0]);
+			return Commands.work(config, args._[0], { project: typeof args.project === 'string' ? args.project : null });
 		case 'finish':
-			return Commands.finish(config, args._[0], { force: !!args.force, note: typeof args.note === 'string' ? args.note : null });
+			return Commands.finish(config, args._[0], { force: !!args.force, noChanges: !!args['no-changes'], note: typeof args.note === 'string' ? args.note : null, project: typeof args.project === 'string' ? args.project : null });
 		case 'status':
 			return Commands.status(config);
 		case 'use': {
@@ -94,6 +109,8 @@ async function main() {
 			console.log(`✓ Using ${api}${next.token ? '' : ' — run "motionode connect" in a repository folder to connect this computer to it'}`);
 			return null;
 		}
+		case 'doctor':
+			return require('../lib/doctor').doctor(config);
 		case 'where':
 			console.log(`${config.apiUrl}${config.token ? ` — connected as ${config.user?.name || config.user?.email || 'you'} (${config.machine?.name || 'this computer'})` : ' — not connected'}`);
 			return null;

package/lib/api.js

@@ -5,9 +5,10 @@
 const pkg = require('../package.json');
 
 class ApiError extends Error {
-	constructor(message, status) {
+	constructor(message, status, data = null) {
 		super(message);
 		this.status = status;
+		this.data = data;
 	}
 }
 
@@ -37,7 +38,7 @@ function client(config) {
 		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);
+			throw new ApiError(data?.error || `Motionode answered ${resp.status}.`, resp.status, data);
 		}
 		return data || {};
 	}

package/lib/bridge.js

@@ -9,6 +9,7 @@
  */
 
 const Git = require('./git');
+const { worktreePath } = require('./commands');
 const { client } = require('./api');
 const { version } = require('./api');
 
@@ -51,6 +52,24 @@ async function runJob(config, job) {
 	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') {
+		/**
+		 * In --worktrees mode `motionode work` owns the ticket's branch in its own
+		 * folder, so checking it out in the linked folder conflicts with that
+		 * worktree (QA-20261023T235400Z). Create/reuse the same folder instead.
+		 * An older job may carry no ticketDisplayId, and an older CLI may have
+		 * made the folder under a different name: either way, use the worktree
+		 * that already has the branch.
+		 */
+		if (ws.worktrees) {
+			const existing = await Git.worktreeOnBranch(ws.path, payload.branch);
+			const dir = existing || (payload.ticketDisplayId ? worktreePath(ws, payload.ticketDisplayId) : null);
+			if (dir) {
+				const wt = await Git.worktreeFor(ws.path, payload.branch, dir);
+				log(`checked out ${payload.branch} in ${wt.path}`);
+				const st = await Git.status(wt.path);
+				return { branch: st.branch, headSha: st.headSha, path: wt.path };
+			}
+		}
 		const st = await Git.checkout(ws.path, payload.branch);
 		log(`checked out ${payload.branch} in ${ws.path}`);
 		return { branch: st.branch, headSha: st.headSha };

package/lib/commands.js

@@ -65,8 +65,26 @@ async function link(config, { serviceUuid = null, dir = process.cwd(), worktrees
 	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) : [];
+		const remoteUrl = await Git.remoteUrl(root);
+		const remote = Git.normalizeRepoUrl(remoteUrl);
+		/**
+		 * A clone made with `motionode clone` has this Motionode's git proxy as its
+		 * remote, not GitHub's URL; recognize the repository behind it instead of
+		 * asking the person to choose what they just cloned
+		 * (QA-20261023T234000Z).
+		 */
+		const { proxiedRepoOf, ownerRepoOf } = require('./git_credential');
+		const proxied = proxiedRepoOf(config, remoteUrl);
+		const sameRepo = (repoUrl) => {
+			if (!proxied || !repoUrl) return false;
+			const ref = ownerRepoOf(repoUrl);
+			return !!ref
+				&& ref.owner.toLowerCase() === proxied.owner.toLowerCase()
+				&& ref.repo.toLowerCase() === proxied.repo.toLowerCase();
+		};
+		const matches = remote
+			? services.filter((s) => Git.normalizeRepoUrl(s.repoUrl) === remote || sameRepo(s.repoUrl))
+			: [];
 		if (matches.length === 1) pick = matches[0];
 		else {
 			const list = matches.length ? matches : services;
@@ -96,7 +114,12 @@ async function connect(config, opts = {}) {
 	let relogin = !config.token || opts.relogin;
 	if (!relogin) {
 		// A computer revoked in Motionode keeps its old token here; connecting again must replace it.
-		try { await client(config).get('/me'); } catch (err) {
+		try {
+			const me = await client(config).get('/me');
+			// Never silently reuse a connection that may belong to someone else (a shared computer keeps one per Motionode).
+			console.log(`Already connected to ${config.apiUrl} as ${me.user?.name || me.user?.email || 'someone'}${me.user?.email ? ` <${me.user.email}>` : ''} on ${me.machine?.name || config.machine?.name || 'this computer'}.`);
+			console.log('If that is not you: run `motionode logout`, then `motionode connect` again.');
+		} catch (err) {
 			if (err.status !== 401) throw err;
 			console.log('This computer was disconnected from Motionode — connecting it again.');
 			relogin = true;
@@ -106,7 +129,7 @@ async function connect(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).');
+	console.log('and use `motionode work <ticket>` to start a ticket (e.g. motionode work T9-99).');
 }
 
 async function unlink(config, { dir = process.cwd() } = {}) {
@@ -117,9 +140,24 @@ async function unlink(config, { dir = process.cwd() } = {}) {
 	console.log(before === config.workspaces.length ? 'This folder was not linked.' : `✓ Unlinked ${root}`);
 }
 
+async function printWorkspaceStatus(ws, dir, label = null) {
+	try {
+		const st = await Git.status(dir);
+		const ticket = /^ai\/ticket-/.test(st.branch || '') ? `  ticket ${st.branch.replace(/^ai\/ticket-/, '')}` : '';
+		console.log(`\n${ws.projectName} / ${ws.serviceName}${label ? ` (${label})` : ''}\n  ${dir}\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` : ''}`);
+		const gitName = require('./doctor').gitConfig(dir, 'user.name');
+		const gitEmail = require('./doctor').gitConfig(dir, 'user.email');
+		console.log(`  commits as ${gitName || '(no user.name)'}${gitEmail ? ` <${gitEmail}>` : ' (no user.email)'}`);
+		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}${label ? ` (${label})` : ''}\n  ${dir}\n  git: ${err.message}`);
+	}
+}
+
 async function status(config) {
 	if (!config.token) {
-		console.log('Not connected. Run `motionode connect`.');
+		console.log(`Not connected to ${config.apiUrl}. Run \`motionode connect\`${config.apiUrl === Config.PRODUCTION_API ? ' (or `motionode use <api address>` first when you work on another Motionode)' : ''}.`);
 		return;
 	}
 	console.log(`Motionode: ${config.apiUrl} — ${config.user?.name || config.user?.email || ''} on ${config.machine?.name || os.hostname()}`);
@@ -127,15 +165,18 @@ async function status(config) {
 		console.log('No linked folders. Run `motionode link` inside a repository.');
 		return;
 	}
+	for (const ws of config.workspaces) await printWorkspaceStatus(ws, ws.path);
+	/**
+	 * Standing inside a ticket worktree: it is the same service's checkout, on
+	 * the ticket's branch, and the linked folder's own line above still describes
+	 * the folder. Show the checkout the person is actually working in too.
+	 */
+	const here = await Git.isRepo(process.cwd());
+	if (!here || config.workspaces.some((ws) => Config.samePath(ws.path, here))) 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}`);
+		if (await Git.isWorktreeOf(ws.path, here)) {
+			await printWorkspaceStatus(ws, here, 'worktree');
+			return;
 		}
 	}
 }
@@ -146,6 +187,21 @@ function worktreePath(ws, ticketRef) {
 	return path.join(path.dirname(ws.path), `${path.basename(ws.path)}.worktrees`, String(ticketRef).replace(/[^A-Za-z0-9._-]/g, '_'));
 }
 
+/**
+ * How to get a service whose repository has no linked folder here. A Motionode-hosted
+ * repository is private to Motionode, so its GitHub URL is not a clone the person can use:
+ * clone it through Motionode, against the server this command is already talking to.
+ */
+function cloneGuidance(b) {
+	if (b?.motionodeHosted) {
+		return b.repo
+			? `no linked folder here — clone it through Motionode: \`motionode clone ${b.repo}\`, then run \`motionode link\``
+			: 'no linked folder here — clone it through Motionode with `motionode clone <owner/repo>`, then run `motionode link`';
+	}
+	if (b?.cloneUrl) return `no linked folder here — \`git clone ${b.cloneUrl}\`, then run \`motionode link\``;
+	return 'no linked folder here — clone the repository, then run `motionode link`';
+}
+
 /** What `motionode finish` tells the person was recorded (the same facts the web confirmation shows). */
 function finishLines(res) {
 	const lines = [`✓ ${res.summary || 'Build finished.'}`];
@@ -157,47 +213,128 @@ function finishLines(res) {
 	return lines;
 }
 
-async function work(config, ref) {
-	if (!ref) throw new Error('Which ticket? e.g. motionode work T11-518');
+/**
+ * The project of the linked folder (or ticket worktree) the person stands in, as a hint: a ticket code is only unique inside one
+ * organization, so it narrows a code shared by several of their projects. An explicit `--project` is sent separately and is strict.
+ */
+async function folderProject(config) {
+	const here = await Git.isRepo(process.cwd()).catch(() => null);
+	if (!here) return null;
+	let ws = Config.workspaceForPath(config, here);
+	if (!ws) {
+		for (const candidate of config.workspaces || []) {
+			if (await Git.isWorktreeOf(candidate.path, here).catch(() => false)) { ws = candidate; break; }
+		}
+	}
+	return ws?.projectUuid || null;
+}
+
+/** What to say after an answer that listed several tickets for one code. */
+function ambiguityTip(err) {
+	return err?.data?.ambiguous ? '  Or run it from the folder of the right project, or add --project "<project name>".' : null;
+}
+
+/** The line that says exactly which ticket (and project) a command acted on. */
+function ticketLabel(lw, ref) {
+	const code = lw?.ticketDisplayId || ref;
+	return `${code}${lw?.ticketTitle ? ` "${lw.ticketTitle}"` : ''}${lw?.projectName ? ` in ${lw.projectName}` : ''}`;
+}
+
+async function work(config, ref, { project = null } = {}) {
+	if (!ref) throw new Error('Which ticket? e.g. motionode work T9-99');
 	const api = client(config);
-	const res = await api.post(`/tickets/${encodeURIComponent(ref)}/work`, {});
+	let res;
+	try {
+		res = await api.post(`/tickets/${encodeURIComponent(ref)}/work`, { project: project || undefined, projectHint: (await folderProject(config)) || undefined });
+	} catch (err) {
+		console.log(`✗ ${err.message}`);
+		if (ambiguityTip(err)) console.log(ambiguityTip(err));
+		process.exitCode = 1;
+		return;
+	}
 	const lw = res.localWork || {};
-	console.log(`✓ ${lw.ticketDisplayId || ref} ${lw.ticketTitle || ''} — Build is yours, working locally.`);
+	const stepName = res.stepName || 'The step';
+	const code = lw.ticketDisplayId || ref;
+	console.log(`${ticketLabel(lw, ref)} — ${res.continued ? `${stepName} is already done; you can keep pushing fixes.` : `${stepName} is yours, working locally.`} (${config.apiUrl})`);
+	if (lw.isMine === false) {
+		// Somebody else's open session: pushes from here are refused until theirs ends.
+		console.log(`\n✗ This ticket is open locally for someone else, so pushes from you would be refused. Ask them to finish or stop first.`);
+		process.exitCode = 1;
+		return;
+	}
+	let failed = 0;
+	const checkedOut = [];
+	const elsewhere = [];
 	for (const b of lw.branches || []) {
 		const ws = (config.workspaces || []).find((w) => w.serviceUuid === b.serviceUuid);
+		if (b.exists === false || (b.available === false && b.reason !== 'timeout')) {
+			// Nothing to check out: say so, never print a checkout that cannot work.
+			failed += 1;
+			console.log(`  ✗ ${b.serviceName}: the branch ${b.branch || '(none)'} is not on the server${b.reason ? ` (${b.reason})` : ''}. Run \`motionode work ${code}\` again in a moment; if it keeps failing, ask your project manager.`);
+			continue;
+		}
 		if (!ws) {
-			console.log(`  ${b.serviceName}: ${b.branch}  (no linked folder here — clone ${b.cloneUrl || 'the repo'} and run \`motionode link\`)`);
+			// Not linked on this computer: not a failure for a person who only works on another of the ticket's repositories.
+			elsewhere.push(b.serviceName);
+			console.log(`  • ${b.serviceName}: ${b.branch}  (${cloneGuidance(b)})`);
 			continue;
 		}
 		try {
 			if (ws.worktrees) {
-				const dir = worktreePath(ws, lw.ticketDisplayId || ref);
+				const dir = worktreePath(ws, code);
 				const wt = await Git.worktreeFor(ws.path, b.branch, dir);
-				console.log(`  ${b.serviceName}: ${wt.created ? 'created' : 'reused'} a worktree on ${b.branch} in ${wt.path}`);
+				checkedOut.push(b.serviceName);
+				console.log(`  ✓ ${b.serviceName}: ${wt.created ? 'created' : 'reused'} a worktree on ${b.branch} in ${wt.path}`);
 				console.log(`    Open ${wt.path} in your tool; your linked folder ${ws.path} is untouched.`);
 			} else {
 				await Git.checkout(ws.path, b.branch);
-				console.log(`  ${b.serviceName}: checked out ${b.branch} in ${ws.path}`);
+				checkedOut.push(b.serviceName);
+				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}`);
+			failed += 1;
+			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.');
+			} else if (/couldn.t find remote ref/i.test(err.message)) {
+				console.log(`    The ticket branch is not on the repository yet. \`motionode work ${code}\` asks Motionode to create it from the base branch: run it again in a minute. If it keeps saying this, ask your project manager (the repository may not be set up).`);
 			}
 		}
 	}
-	console.log('\nCommit with your own git and push to the ticket branch. When you are done: motionode finish ' + (lw.ticketDisplayId || ref));
+	for (const problem of res.branchProblems || []) console.log(`  ! ${problem}`);
+	// A stage the server could not complete (the step itself not started): never end "Ready" over it. The branch stage is already
+	// reported repository by repository above.
+	const failedStages = (res.stages || []).filter((st) => st && st.ok === false && st.key !== 'branches');
+	for (const st of failedStages) console.log(`  ✗ ${st.detail || `${st.key} did not complete`}`);
+	if (failed || failedStages.length) {
+		const reasons = [];
+		if (failed) reasons.push(`${failed} repositor${failed === 1 ? 'y' : 'ies'} could not be checked out`);
+		if (failedStages.length) reasons.push(`${failedStages.length === 1 ? 'a step' : `${failedStages.length} steps`} did not start`);
+		console.log(`\n✗ Not ready: ${reasons.join(' and ')} (see above). Fix that, then run \`motionode work ${code}\` again.`);
+		// The server's own last paragraph says what to do about it (it is the one that names the problem).
+		const advice = failedStages.length ? String(res.summary || '').split('\n\n').pop().trim() : '';
+		if (advice) console.log(advice);
+		process.exitCode = 1;
+		return;
+	}
+	if (!checkedOut.length) {
+		console.log(`\n✗ Nothing is checked out: none of this ticket's repositories is linked on this computer. Clone and link one (see above), then run \`motionode work ${code}\` again.`);
+		process.exitCode = 1;
+		return;
+	}
+	console.log(`\n✓ Ready${elsewhere.length ? ` in ${checkedOut.join(', ')} (not on this computer: ${elsewhere.join(', ')})` : ''}. Commit with your own git and push to the ticket branch. When you are done: motionode finish ${code}`);
 }
 
-async function finish(config, ref, { force = false, note = null } = {}) {
-	if (!ref) throw new Error('Which ticket? e.g. motionode finish T11-518');
+async function finish(config, ref, { force = false, note = null, project = null, noChanges = false } = {}) {
+	if (!ref) throw new Error('Which ticket? e.g. motionode finish T9-99');
 	const api = client(config);
 	try {
-		console.log(`Checking the ticket branch and telling Motionode ${ref} is built…`);
-		const res = await api.post(`/tickets/${encodeURIComponent(ref)}/finish`, { force, note });
+		console.log(`Checking the ticket branch and telling Motionode ${ref} is built… (${config.apiUrl})`);
+		const res = await api.post(`/tickets/${encodeURIComponent(ref)}/finish`, { force, note, noChanges, project: project || undefined, projectHint: (await folderProject(config)) || undefined });
 		finishLines(res).forEach((l) => console.log(l));
 	} catch (err) {
 		console.log(`✗ ${err.message}`);
+		if (ambiguityTip(err)) console.log(ambiguityTip(err));
 		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.');
 		}
@@ -210,4 +347,4 @@ async function logout(config) {
 	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, worktreePath, finishLines };
+module.exports = { login, link, connect, unlink, status, work, finish, logout, worktreePath, finishLines, cloneGuidance, folderProject, ticketLabel };

package/lib/doctor.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * `motionode doctor`: where this terminal stands, in one screen, and the next command to run. Read-only: it never starts,
+ * finishes or changes anything.
+ */
+
+const Config = require('./config');
+const Git = require('./git');
+const { client, version } = require('./api');
+
+/** One git config value as the person's own git reads it in this folder, or null. */
+function gitConfig(dir, key) {
+	try {
+		return require('child_process').execFileSync('git', ['config', key], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+	} catch (_e) {
+		return null;
+	}
+}
+
+async function doctor(config) {
+	const lines = [];
+	const todo = [];
+	lines.push(`CLI           ${version}`);
+	lines.push(`Motionode     ${config.apiUrl}${config.apiUrl === Config.PRODUCTION_API ? ' (production, the default)' : ''}`);
+
+	let me = null;
+	if (!config.token) {
+		lines.push('Connected     no');
+		todo.push('motionode connect');
+	} else {
+		try {
+			me = await client(config).get('/me');
+			lines.push(`Connected     yes, as ${me.user?.name || me.user?.email || 'you'}${me.user?.email ? ` <${me.user.email}>` : ''} on ${me.machine?.name || config.machine?.name || 'this computer'}`);
+			if (me.organizations?.length) lines.push(`Organization  ${me.organizations.join(', ')}`);
+			lines.push(`Projects      ${(me.projects || []).map((p) => p.name).join(', ') || 'none you can work on locally'}`);
+		} catch (err) {
+			lines.push(`Connected     no: ${err.message}`);
+			todo.push(err.status === 401 ? 'motionode connect --relogin' : 'motionode where   (check the address; use `motionode use <api address>` to change it)');
+		}
+	}
+
+	const root = await Git.isRepo(process.cwd()).catch(() => null);
+	if (!root) {
+		lines.push('Folder        not inside a git repository');
+		todo.push('cd into your clone (or: motionode clone <owner/repo>), then motionode link');
+	} else {
+		const name = gitConfig(root, 'user.name');
+		const email = gitConfig(root, 'user.email');
+		lines.push(`Git identity  ${name || '(no user.name)'}${email ? ` <${email}>` : ' (no user.email)'}`);
+		if (!name || !email) todo.push('git config user.name "Your Name" && git config user.email you@example.com');
+		const remote = await Git.remoteUrl(root);
+		lines.push(`Remote        ${remote || '(no origin remote)'}`);
+		let st = null;
+		try { st = await Git.status(root); } catch (_e) { /* not readable */ }
+		lines.push(`Branch        ${st?.branch || '(none)'}${st ? `   ${st.dirtyFiles.length} uncommitted, ${st.ahead || 0} to push` : ''}`);
+		let ws = Config.workspaceForPath(config, root);
+		if (!ws) {
+			for (const candidate of config.workspaces || []) {
+				if (await Git.isWorktreeOf(candidate.path, root).catch(() => false)) { ws = candidate; break; }
+			}
+		}
+		lines.push(`Linked to     ${ws ? `${ws.projectName} / ${ws.serviceName}` : 'nothing (this folder is not linked)'}`);
+		if (!ws && config.token) todo.push('motionode link');
+		// A ticket branch is ai/ticket-<code>[-<ticket id>][-<slug>]; the code is what the person (and the server) know it by.
+		const code = /^ai\/ticket-(T\d+-\d+)(?:-.*)?$/.exec(st?.branch || '')?.[1] || null;
+		if (code && ws && config.token) {
+			try {
+				const res = await client(config).get(`/tickets/${encodeURIComponent(code)}?projectHint=${encodeURIComponent(ws.projectUuid || '')}`);
+				const t = res.ticket || {};
+				lines.push(`Ticket        ${t.ticketDisplayId || code} "${t.ticketTitle || ''}" in ${t.projectName || ws.projectName}`);
+				// An older server does not say whose session it is: then it is only "open", never claimed as someone else's.
+				const mine = Boolean(t.active && t.isMine === true);
+				const others = Boolean(t.active && t.isMine === false);
+				lines.push(`Local work    ${mine ? 'open: you can push and finish' : (others ? 'open for someone else: your pushes to this branch are refused' : (t.active ? 'open (this server does not say whose)' : 'not open: git push to this branch is refused'))}`);
+				todo.push(mine ? `motionode finish ${t.ticketDisplayId || code}   (when you have pushed)` : (others ? 'ask whoever has it open to finish or stop first' : (t.active ? `motionode finish ${t.ticketDisplayId || code}   (when you have pushed)` : `motionode work ${t.ticketDisplayId || code}`)));
+			} catch (err) {
+				lines.push(`Ticket        branch ${st.branch}: ${err.message}`);
+			}
+		} else if (ws && config.token) {
+			todo.push('motionode work <ticket>');
+		}
+	}
+	console.log(lines.join('\n'));
+	console.log(`\nNext: ${todo.length ? `\n  ${todo.join('\n  ')}` : 'nothing to fix. Run motionode work <ticket> to start a ticket.'}`);
+}
+
+module.exports = { doctor, gitConfig };

package/lib/git.js

@@ -31,6 +31,24 @@ async function isRepo(dir) {
 	return r.ok ? r.stdout.trim() : null;
 }
 
+/**
+ * Whether `dir` is a checkout of the same repository as `linked` — either the
+ * same folder or a worktree of it. A worktree's git dir lives under the main
+ * repository's `.git/worktrees`, but it shares the common dir with the folder.
+ */
+async function isWorktreeOf(linked, dir) {
+	const [a, b] = await Promise.all([
+		run(linked, ['rev-parse', '--git-common-dir'], { allowFail: true }),
+		run(dir, ['rev-parse', '--git-common-dir'], { allowFail: true }),
+	]);
+	if (!a.ok || !b.ok) return false;
+	const real = (base, out) => {
+		const p = path.resolve(base, String(out || '').trim());
+		try { return fs.realpathSync(p); } catch (_e) { return p; }
+	};
+	return real(linked, a.stdout) === real(dir, b.stdout);
+}
+
 async function remoteUrl(dir) {
 	const r = await run(dir, ['remote', 'get-url', 'origin'], { allowFail: true });
 	return r.ok ? r.stdout.trim() : null;
@@ -112,20 +130,48 @@ async function checkout(dir, branch) {
 	return status(dir);
 }
 
+/** Where `branch` is already checked out, when a worktree of this repository has it. */
+async function worktreeOnBranch(dir, branch) {
+	const r = await run(dir, ['worktree', 'list', '--porcelain'], { allowFail: true });
+	if (!r.ok) return null;
+	let current = null;
+	for (const raw of r.stdout.split('\n')) {
+		const line = raw.replace(/\r$/, '');
+		if (line.startsWith('worktree ')) current = line.slice('worktree '.length);
+		else if (current && line === `branch refs/heads/${branch}`) return current;
+	}
+	return null;
+}
+
+async function refreshWorktree(path, branch) {
+	await run(path, ['fetch', 'origin', branch], { allowFail: true });
+	await run(path, ['merge', '--ff-only', `origin/${branch}`], { allowFail: true });
+	return { path, created: false };
+}
+
 /**
  * A separate folder (git worktree) on a ticket's branch, so two tickets of one repository never share a working tree.
  * Reuses the folder when this ticket already has one. Returns { path, created }.
  */
 async function worktreeFor(dir, branch, path) {
-	const fs = require('fs');
 	if (fs.existsSync(path)) {
 		const r = await run(path, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true });
-		if (r.ok && String(r.stdout || '').trim() === branch) {
-			await run(path, ['fetch', 'origin', branch], { allowFail: true });
-			await run(path, ['merge', '--ff-only', `origin/${branch}`], { allowFail: true });
-			return { path, created: false };
+		if (r.ok && String(r.stdout || '').trim() === branch) return refreshWorktree(path, branch);
+	}
+	/**
+	 * A branch is checked out in one worktree at a time, and an earlier CLI can have made the ticket's folder under a
+	 * different name. Reuse the checkout that already has the branch instead of asking git to make a second one (fatal:
+	 * already used by worktree). The existing folder, and anything uncommitted in it, is left as it is.
+	 */
+	const existing = await worktreeOnBranch(dir, branch);
+	if (existing) {
+		if (!fs.existsSync(existing)) {
+			throw new Error(`${branch} is registered to ${existing}, but that folder is missing. Run \`git worktree prune\` in ${dir}, then run \`motionode work <ticket>\` again.`);
 		}
-		throw new Error(`${path} exists and is not a checkout of ${branch}`);
+		return refreshWorktree(existing, branch);
+	}
+	if (fs.existsSync(path)) {
+		throw new Error(`${path} exists and is not a checkout of ${branch}. Move that folder aside, then run \`motionode work <ticket>\` again.`);
 	}
 	await run(dir, ['fetch', 'origin', branch]);
 	if (await hasLocalBranch(dir, branch)) await run(dir, ['worktree', 'add', path, branch]);
@@ -199,4 +245,4 @@ async function moveChanges(dir, branch) {
 	return { moved: true, branch };
 }
 
-module.exports = { run, isRepo, remoteUrl, normalizeRepoUrl, status, checkout, worktreeFor, diff, commit, moveChanges };
+module.exports = { run, isRepo, isWorktreeOf, remoteUrl, normalizeRepoUrl, status, checkout, worktreeFor, worktreeOnBranch, diff, commit, moveChanges };

package/lib/git_credential.js

@@ -76,6 +76,24 @@ function ownerRepoOf(value) {
 	return m ? { owner: m[1], repo: m[2] } : null;
 }
 
+/**
+ * owner/repo behind a Motionode git-proxy URL on this Motionode
+ * (`<api>/git/<owner>/<repo>.git`), or null for any other remote. The clone
+ * `motionode clone` makes has this remote, and `motionode link` needs the
+ * repository it stands for (QA-20261023T234000Z).
+ */
+function proxiedRepoOf(config, remoteUrl) {
+	try {
+		const remote = new URL(String(remoteUrl || ''));
+		const api = new URL(String(config?.apiUrl || ''));
+		if (remote.host.toLowerCase() !== api.host.toLowerCase()) return null;
+		const m = remote.pathname.match(/^\/git\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+		return m ? { owner: decodeURIComponent(m[1]), repo: decodeURIComponent(m[2]) } : null;
+	} catch (_e) {
+		return null;
+	}
+}
+
 /** The git config that makes this CLI the credential helper for one folder (never global). */
 function helperConfig(config) {
 	const bin = path.resolve(__dirname, '..', 'bin', 'motionode.js');
@@ -131,4 +149,4 @@ async function clone(config, target, dir = null) {
 	return null;
 }
 
-module.exports = { helper, clone, parseCredentialInput, isForThisMotionode, proxyUrl, ownerRepoOf, helperConfig };
+module.exports = { helper, clone, parseCredentialInput, isForThisMotionode, proxyUrl, ownerRepoOf, proxiedRepoOf, helperConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionode/cli",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "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": {