npm - @ctrl-spc/cs - Versions diffs - 0.2.0 → 0.3.1 - Mend

@ctrl-spc/cs 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +57 -0
package/dist/agents.js +6 -0
package/dist/companion-ui.js +205 -3
package/dist/companion.js +23 -1
package/dist/config.js +14 -1
package/dist/env.js +10 -0
package/dist/mcp.js +2332 -0
package/dist/package-version.js +10 -0
package/dist/presence-heartbeat.js +13 -0
package/dist/presence.js +70 -8
package/dist/supabase.js +4 -1
package/package.json +9 -3

package/README.md ADDED Viewed

@@ -0,0 +1,57 @@
+# @ctrl-spc/cs
+The `cs` command keeps your computer online for **CTRL+SPC** so your coding
+agents can be reached, and opens the **Companion** — a small local app for
+signing in and attaching your codebases to your projects.
+## Install
+```sh
+npm i -g @ctrl-spc/cs && cs
+```
+That's it. The `&& cs` opens your browser straight to sign-in — you barely touch
+the terminal:
+```
+Welcome to CTRL+SPC — opening your browser to sign in…
+```
+In the browser you'll:
+1. **Sign in** (or sign up on the web).
+2. **Attach a codebase** — point a project at a folder on this computer that has
+   a git remote.
+3. **Open the web app** — create work items and hand them to an agent.
+Your folder paths stay on this computer; only path-free identifiers (a git
+remote URL) are shared.
+## Stay online
+```sh
+cs autostart on
+```
+Comes online automatically at login, with no window. Turn it off with
+`cs autostart off`.
+## Commands
+```
+cs                Open the Companion app (the front door)
+cs open           Open the Companion app in your browser
+cs login          Sign in from the terminal and link this computer
+cs start          Come online now, no window (used by auto-start)
+cs status         Show sign-in state, computer, and detected agents
+cs autostart on   Come online automatically at login
+cs autostart off  Stop coming online at login
+cs logout         Sign this computer out
+cs help           Show this help
+```
+## Requirements
+- Node.js >= 22.
+Not sure what a piece does? Open the Companion (`cs`) and click **How it works**.

package/dist/agents.js CHANGED Viewed

@@ -37,3 +37,9 @@ function resolve(agent) {
 export function detectAgents() {
     return AGENTS.filter((a) => resolve(a) !== null);
 }
+/** Absolute path to an agent's binary (PATH first, then well-known fallbacks),
+ *  or null when it isn't installed. Used to invoke `claude mcp add` at the same
+ *  binary `detectAgents()` found. */
+export function agentPath(agent) {
+    return resolve(agent);
+}

package/dist/companion-ui.js CHANGED Viewed

@@ -220,6 +220,10 @@ code, .mono { font-family: var(--font-mono); }
 .codebase-actions { display: flex; align-items: center; gap: var(--sp-2); flex-shrink: 0; }
 .codebases-empty { font-size: var(--text-sm); color: var(--faint); }
 .form-note { color: var(--ok); font-size: var(--text-sm); min-height: 1.1em; }
+.empty-cta { display: flex; flex-direction: column; align-items: center; gap: var(--sp-3); text-align: center; padding: var(--sp-6) var(--sp-4); border: 1px dashed var(--border-strong); border-radius: var(--r-md); }
+.empty-cta.is-compact { padding: var(--sp-5) var(--sp-4); gap: var(--sp-2); }
+.empty-cta-title { font-weight: 600; }
+.empty-cta .muted { font-size: var(--text-sm); max-width: 46ch; }
 .pill {
   display: inline-flex; align-items: center; flex-shrink: 0; white-space: nowrap;
   font-size: var(--text-xs); font-weight: 500; padding: 2px 10px; border-radius: 20px;
@@ -227,6 +231,19 @@ code, .mono { font-family: var(--font-mono); }
 }
 .pill-ok { color: var(--ok); border-color: var(--ok); }
 .locate-match { min-height: 1.2em; }
+/* --- agent tools badge (feature 05: passive, read-only) --- */
+.agent-tools {
+  display: flex; align-items: center; gap: var(--sp-3);
+  border: 1px solid var(--border); border-radius: var(--r-md);
+  padding: var(--sp-3) var(--sp-4); background: var(--surface);
+}
+.agent-tools-dot { width: 9px; height: 9px; border-radius: 50%; flex-shrink: 0; background: var(--faint); }
+.agent-tools-dot.is-on { background: var(--ok); }
+/* Amber "connecting…" while async registration is in flight (no amber token). */
+.agent-tools-dot.is-wait { background: #e0a020; }
+.agent-tools-title { font-weight: 600; }
+.agent-tools-sub { font-size: var(--text-xs); color: var(--muted); margin-top: 2px; }
 </style>
 </head>
 <body>
@@ -274,7 +291,82 @@ async function boot() {
   else renderSignIn(r.data || {});
 }
+/** The passive "Agent tools" badge (feature 05). Read-only: no button, no
+ *  action. Reflects the lifecycle state the server computed in /api/session —
+ *  connecting (amber, async registration in flight) / connected / couldn't-
+ *  connect, plus the signed-out and no-agent off-states. */
+function agentToolsBadge(state) {
+  state = state || { connected: false, reason: 'signed-out', agent: '', server: 'ctrl-spc' };
+  const reason = state.reason;
+  const box = el('div', 'agent-tools');
+  let dotCls = 'agent-tools-dot';
+  if (reason === 'connected') dotCls += ' is-on';
+  else if (reason === 'connecting') dotCls += ' is-wait';
+  const dot = el('span', dotCls);
+  const body = el('div');
+  let title, sub;
+  if (reason === 'connected') {
+    title = 'Agent tools: connected \\u2713';
+    sub = (state.agent || 'Claude') + ' \\u00b7 ' + (state.server || 'ctrl-spc');
+  } else if (reason === 'connecting') {
+    title = 'Agent tools: connecting\\u2026';
+    sub = state.agent || '';
+  } else if (reason === 'failed') {
+    title = 'Agent tools: not connected';
+    sub = "couldn't connect the tools \\u2014 will retry";
+  } else if (reason === 'no-agent') {
+    title = 'Agent tools: not connected';
+    sub = 'No supported agent (Claude or Codex) found on this machine';
+  } else {
+    title = 'Agent tools: not connected';
+    sub = 'sign in to connect';
+  }
+  body.append(el('div', 'agent-tools-title', title));
+  body.append(el('div', 'agent-tools-sub mono', sub));
+  box.append(dot, body);
+  return box;
+}
+// The badge must flip connecting\\u2192connected on its own (Claude registers in
+// ~7s) with no page reload. A light 2s poll of /api/session swaps ONLY the badge
+// element in place — never a full home re-render, which would disrupt the
+// codebases list, open dialogs, and focus. Guards against overlapping fetches and
+// stops itself once the badge leaves the DOM (home torn down).
+let badgePollTimer = null;
+let badgePolling = false;
+function stopBadgePoll() {
+  if (badgePollTimer) { clearInterval(badgePollTimer); badgePollTimer = null; }
+}
+async function pollBadgeOnce() {
+  if (badgePolling) return;
+  const badge = document.getElementById('agent-tools');
+  if (!badge) { stopBadgePoll(); return; }
+  badgePolling = true;
+  try {
+    const r = await api('/api/session');
+    // Home may have been torn down while the fetch was in flight.
+    if (!badge.isConnected) return;
+    if (!(r.data && r.data.signedIn)) { stopBadgePoll(); return; }
+    const fresh = agentToolsBadge(r.data.agentTools);
+    fresh.id = 'agent-tools';
+    fresh.style.marginBottom = 'var(--sp-5)';
+    badge.replaceWith(fresh);
+  } catch (e) {
+    /* transient — try again next tick */
+  } finally {
+    badgePolling = false;
+  }
+}
+function startBadgePoll() {
+  stopBadgePoll();
+  badgePollTimer = setInterval(pollBadgeOnce, 2000);
+}
 function renderSignIn(session) {
+  stopBadgePoll(); // the sign-in badge is static — no lifecycle to poll
   app.replaceChildren();
   const wrap = el('div', 'auth');
   const card = el('div', 'auth-card');
@@ -312,7 +404,7 @@ function renderSignIn(session) {
   const signup = el('a', 'auth-switch', 'Sign up on the web \\u2197');
   signup.href = WEB_URL; signup.target = '_blank'; signup.rel = 'noopener noreferrer';
-  card.append(form, signup);
+  card.append(form, signup, agentToolsBadge(session.agentTools));
   wrap.append(card);
   app.append(wrap);
 }
@@ -322,7 +414,13 @@ function renderHome(session) {
   const bar = el('header', 'titlebar');
   bar.append(logo());
   const spacer = el('span', null); spacer.style.flex = '1'; bar.append(spacer);
+  const help = el('button', 'btn btn-ghost', 'How it works');
+  help.addEventListener('click', function () { openHowItWorks(help); });
+  bar.append(help);
   bar.append(el('span', 'mono muted', session.email || ''));
+  const web = el('a', 'btn', 'Open the web app \\u2197');
+  web.href = WEB_URL; web.target = '_blank'; web.rel = 'noopener noreferrer';
+  bar.append(web);
   const out = el('button', 'btn btn-ghost', 'Sign out');
   out.addEventListener('click', async function () {
     out.disabled = true;
@@ -332,6 +430,10 @@ function renderHome(session) {
   bar.append(out);
   const main = el('main', 'home');
+  const tools = agentToolsBadge(session.agentTools);
+  tools.id = 'agent-tools';
+  tools.style.marginBottom = 'var(--sp-5)';
+  main.append(tools);
   main.append(el('h1', 'home-title', 'Projects'));
   const sub = el('p', 'home-sub muted');
   sub.append(document.createTextNode('Map each project to its folder on '));
@@ -343,6 +445,9 @@ function renderHome(session) {
   app.append(bar, main);
   loadProjects(list);
+  // Keep the badge honest as async registration settles (connecting \\u2192 connected),
+  // swapping only the badge element — never the whole home view.
+  startBadgePoll();
 }
 async function loadProjects(list) {
@@ -350,7 +455,16 @@ async function loadProjects(list) {
   const r = await api('/api/projects');
   if (!r.ok) { list.replaceChildren(el('p', 'empty', (r.data && r.data.error) || 'Could not load projects.')); return; }
   const projects = (r.data && r.data.projects) || [];
-  if (projects.length === 0) { list.replaceChildren(el('p', 'empty', 'No projects yet. Create one in the web app.')); return; }
+  if (projects.length === 0) {
+    const box = el('div', 'empty-cta');
+    box.append(el('div', 'empty-cta-title', 'No projects yet'));
+    box.append(el('p', 'muted', 'A project holds your codebases. Create your first one in the web app, then come back here to attach a codebase.'));
+    const cta = el('a', 'btn btn-primary', 'Create your first project in the web app \\u2197');
+    cta.href = WEB_URL; cta.target = '_blank'; cta.rel = 'noopener noreferrer';
+    box.append(cta);
+    list.replaceChildren(box);
+    return;
+  }
   list.replaceChildren.apply(list, projects.map(function (p) { return projectRow(p, list); }));
 }
@@ -411,7 +525,20 @@ async function loadCodebases(p, container) {
   }
   const codebases = (r.data && r.data.codebases) || [];
   if (codebases.length === 0) {
-    container.replaceChildren(el('p', 'codebases-empty', 'No codebases yet. Add one from a folder that has a git remote.'));
+    const box = el('div', 'empty-cta is-compact');
+    box.append(el('p', 'muted', 'No codebases yet. Point ' + p.name + ' at a folder on this computer that has a git remote.'));
+    const cta = el('button', 'btn btn-primary', 'Add your first codebase');
+    cta.type = 'button';
+    cta.addEventListener('click', function () {
+      // Route return-focus to a control that SURVIVES the codebase-list refresh
+      // (this cta is inside the container and gets destroyed by loadCodebases),
+      // mirroring the Remove button's focus guard.
+      const section = container.closest('.project-codebases');
+      const survivingAdd = section && section.querySelector('.project-codebases-head button');
+      openAddCodebaseDialog(p, function () { loadCodebases(p, container); }, survivingAdd || cta);
+    });
+    box.append(cta);
+    container.replaceChildren(box);
     return;
   }
   container.replaceChildren.apply(container, codebases.map(function (c) { return codebaseRow(c, p, container); }));
@@ -528,6 +655,81 @@ function openRemoveCodebaseDialog(p, codebase, onRemoved, returnFocus) {
   });
 }
+/** The re-openable "How it works" reference (Phase 3). Static explainer of the
+ *  three surfaces — the CLI, this Companion, and the web app — in the shared
+ *  overlay shell (same header/body/footer + Escape/backdrop close as the other
+ *  dialogs). Content only, no API. */
+function openHowItWorks(returnFocus) {
+  const backdrop = el('div', 'overlay-backdrop');
+  const panel = el('div', 'overlay-center');
+  const dialog = el('div', 'dialog');
+  const header = el('header', 'dialog-header');
+  const heading = el('div', 'dialog-heading');
+  heading.append(el('h2', null, 'How CTRL+SPC works'));
+  const closeBtn = el('button', 'dialog-close');
+  closeBtn.type = 'button'; closeBtn.setAttribute('aria-label', 'Close');
+  closeBtn.append(xIcon());
+  header.append(heading, closeBtn);
+  const body = el('div', 'dialog-body');
+  function section(titleNode, descText, extraNode) {
+    const wrap = el('div');
+    wrap.style.display = 'flex'; wrap.style.flexDirection = 'column'; wrap.style.gap = 'var(--sp-1)';
+    wrap.append(titleNode, el('p', 'muted', descText));
+    if (extraNode) wrap.append(extraNode);
+    return wrap;
+  }
+  // CLI section — inline command names in mono, matching the approved wireframe.
+  const cliWrap = el('div');
+  cliWrap.style.display = 'flex'; cliWrap.style.flexDirection = 'column'; cliWrap.style.gap = 'var(--sp-1)';
+  const cliTitle = el('h3', null, 'The CLI ');
+  cliTitle.append(el('code', 'mono', 'cs'));
+  const cliDesc = el('p', 'muted');
+  cliDesc.append(document.createTextNode('A small program on this computer. It keeps this computer online so your agents can be reached, and it opens this Companion. Run '));
+  cliDesc.append(el('code', 'mono', 'cs'));
+  cliDesc.append(document.createTextNode(' anytime to open it; '));
+  cliDesc.append(el('code', 'mono', 'cs autostart on'));
+  cliDesc.append(document.createTextNode(' keeps it running in the background.'));
+  cliWrap.append(cliTitle, cliDesc);
+  body.append(cliWrap);
+  const compTitle = el('h3', null, 'The Companion ');
+  const compHint = el('span', 'muted', '(this app)'); compHint.style.fontWeight = '400';
+  compTitle.append(compHint);
+  body.append(section(compTitle,
+    'Local setup for this computer. Sign in, and attach your codebases — folders on this computer that have a git remote — to your projects. Paths stay on your computer.'));
+  const webLink = el('a', 'btn btn-primary', 'Open the web app \\u2197');
+  webLink.href = WEB_URL; webLink.target = '_blank'; webLink.rel = 'noopener noreferrer';
+  webLink.style.alignSelf = 'flex-start'; webLink.style.marginTop = 'var(--sp-1)';
+  body.append(section(el('h3', null, 'The web app'),
+    'Where the work happens. See your projects, create work items, hand a work item to an agent, and tell the agent what to do with it: explore the code, write a document or a plan, answer questions, and more.',
+    webLink));
+  const footer = el('div', 'dialog-footer');
+  const doneBtn = el('button', 'btn', 'Close'); doneBtn.type = 'button';
+  footer.append(doneBtn);
+  dialog.append(header, body, footer);
+  panel.append(dialog);
+  backdrop.append(panel);
+  document.body.append(backdrop);
+  doneBtn.focus();
+  function close() {
+    backdrop.remove();
+    document.removeEventListener('keydown', onKey);
+    if (returnFocus && returnFocus.focus) returnFocus.focus();
+  }
+  function onKey(e) { if (e.key === 'Escape') { e.preventDefault(); close(); } }
+  document.addEventListener('keydown', onKey);
+  backdrop.addEventListener('mousedown', function (e) { if (e.target === backdrop) close(); });
+  closeBtn.addEventListener('click', close);
+  doneBtn.addEventListener('click', close);
+}
 /** Screens 8 & 9: locate a not-here codebase on THIS computer. Pick a folder;
  *  if its git remote canonicalizes to the codebase's identity, its path is saved
  *  locally and this computer is reported as having the codebase. A non-matching

package/dist/companion.js CHANGED Viewed

@@ -5,6 +5,8 @@ import { openBrowser } from './browser.js';
 import { companionToken, getMachineIdentity, readSession, clearSession, readCodebasePaths, writeCodebasePath } from './config.js';
 import { getClient, signIn, NotLoggedIn } from './supabase.js';
 import { startPresence, stopPresence } from './presence.js';
+import { detectAgents } from './agents.js';
+import { toolsServerStatus, agentRegStatus, badgeReason } from './mcp.js';
 import { loadProjects, saveMapping } from './projects.js';
 import { listCodebases, addCodebase, reportLocated, removeCodebase, NotHostedRemoteError } from './codebases.js';
 import { hostedRemoteIdentity } from './git-remote.js';
@@ -37,6 +39,8 @@ async function isOurCompanion(token) {
  * points the browser at it; otherwise becomes the resident server itself.
  */
 export async function openCompanion() {
+    if (!readSession())
+        console.log('Welcome to CTRL+SPC — opening your browser to sign in…');
     await serveCompanion({ open: true });
 }
 /**
@@ -150,6 +154,21 @@ async function readBody(req) {
 function str(value) {
     return typeof value === 'string' ? value : '';
 }
+/** The passive "Agent tools" badge state for the companion (feature 05). Phase 3
+ *  gives it an honest lifecycle — connecting / connected / couldn't-connect — on
+ *  top of the signed-out and no-agent off-states. The branching itself lives in
+ *  the pure `badgeReason` (mcp.ts) so it's unit-testable; this only gathers the
+ *  live signals: whether we're signed in, which supported agents are installed,
+ *  whether the tools server is up, and each agent's registration status. */
+function agentToolsState(signedIn) {
+    const installed = detectAgents().filter((a) => a === 'claude' || a === 'codex');
+    return badgeReason({
+        signedIn,
+        installed,
+        serverRunning: toolsServerStatus().running,
+        status: agentRegStatus(),
+    });
+}
 async function handle(req, res, token) {
     if (!allowedHost(req.headers.host)) {
         res.writeHead(421, { 'Content-Type': 'text/plain' }).end('Misdirected request.');
@@ -202,6 +221,7 @@ async function handleApi(req, res, path, query) {
             machineName: machine.name,
             platform: process.platform,
             version: VERSION,
+            agentTools: agentToolsState(email !== null),
         });
         return;
     }
@@ -229,7 +249,9 @@ async function handleApi(req, res, path, query) {
         return;
     }
     if (req.method === 'POST' && path === '/api/logout') {
-        await stopPresence({ markOffline: true });
+        // Logout also unregisters ctrl-spc from the detected agents (Phase 3), so no
+        // dead server entry is left behind for the next agent run.
+        await stopPresence({ markOffline: true, unregister: true });
         clearSession();
         json(res, 200, { ok: true });
         return;

package/dist/config.js CHANGED Viewed

@@ -199,7 +199,20 @@ export function writeCodebasePath(identity, localPath) {
  * On disk (not per-process) so `cs open` and the resident server agree on it.
  */
 export function companionToken() {
-    const path = filePath('companion-token');
+    return persistentToken('companion-token');
+}
+/**
+ * Stable per-install MCP tools-server token, same contract as companionToken.
+ * The loopback /mcp endpoint requires it, and it is embedded in the URL that
+ * registration writes into Claude/Codex configs — so only clients CTRL+SPC
+ * registered (or that can read this 0600 file) can reach the tools, not any
+ * process that happens to find the loopback port.
+ */
+export function mcpToken() {
+    return persistentToken('mcp-token');
+}
+function persistentToken(name) {
+    const path = filePath(name);
     if (existsSync(path)) {
         try {
             const token = readFileSync(path, 'utf8').trim();

package/dist/env.js CHANGED Viewed

@@ -10,8 +10,18 @@ export const SUPABASE_KEY = process.env.CTRL_SPC_SUPABASE_KEY || 'sb_publishable
 export const HEARTBEAT_INTERVAL_MS = 10_000;
 /** Command (ping) poll cadence. */
 export const COMMAND_POLL_INTERVAL_MS = 3_000;
+/** How long a work session stays "working" after the agent's last ctrl-spc tool
+ *  call, with no further activity. The companion keeps last_seen_at fresh within
+ *  this window; once it lapses (agent finished, Ctrl-C'd, crashed, or asleep) the
+ *  session is flipped to 'ended' so the board chip clears. Must exceed the
+ *  heartbeat interval and the web's freshness window. */
+export const SESSION_TTL_MS = 120_000;
 /** Companion GUI port. Distinct from the v1 CLI's companion (4573) so an
  *  installed v1 and the v2 experiment never contend for the same port. */
 export const COMPANION_PORT = Number(process.env.CTRL_SPC_V2_COMPANION_PORT) || 4577;
+/** Local `ctrl-spc` MCP tools-server port. Fixed so the value written into
+ *  Claude's config stays stable across restarts. Distinct from the v2 companion
+ *  (4577) and both v1 ports (MCP 4571, companion 4573) so nothing contends. */
+export const TOOLS_SERVER_PORT = Number(process.env.CTRL_SPC_V2_TOOLS_PORT) || 4579;
 /** Where "Sign up on the web" and the app's own sign-in live. */
 export const WEB_APP_URL = process.env.CTRL_SPC_WEB_URL || 'https://ctrl-spc.com';