@ctrl-spc/cs 0.1.0 → 0.3.0

package/dist/presence.js

@@ -0,0 +1,206 @@
+import { platform } from 'node:os';
+import { getClient } from './supabase.js';
+import { getMachineIdentity, supersededMachineIds, clearSupersededMachineIds } from './config.js';
+import { detectAgents } from './agents.js';
+import { startToolsServer, stopToolsServer, toolsServerStatus, registerWithClaude, registerWithCodex, unregisterFromClaude, unregisterFromCodex, agentRegStatus, heartbeatOpenSessions, setToolsClient, } from './mcp.js';
+import { HEARTBEAT_INTERVAL_MS, COMMAND_POLL_INTERVAL_MS } from './env.js';
+let presence = null;
+/** In-flight guard: startPresence yields to the event loop (network setSession)
+ *  before `presence` is assigned, so a plain `if (presence)` check lets two
+ *  concurrent callers both build interval pairs — the first pair then leaks and
+ *  keeps heartbeating "online" past sign-out. Concurrent callers await this. */
+let starting = null;
+export function isPresenceRunning() {
+    return presence !== null;
+}
+async function heartbeat(p) {
+    try {
+        const { error } = await p.client
+            .from('cliv2_agents')
+            .upsert({
+            user_id: p.userId,
+            machine_id: p.identity.id,
+            machine_name: p.identity.name,
+            agents: p.agents,
+            platform: p.platform,
+            last_seen_at: new Date().toISOString(),
+        }, { onConflict: 'user_id,machine_id' });
+        if (error)
+            throw error;
+    }
+    catch (err) {
+        // Most likely a rotated/expired session or a network blip. Rebuild the
+        // client from disk (picks up any refreshed token) and try next tick.
+        console.warn(`heartbeat failed, will retry: ${err.message}`);
+        try {
+            p.client = await getClient();
+            // FIX 2: flow the rebuilt client (fresh/refreshed token) into the tools
+            // session-lifecycle heartbeat too, so a wedged token can't leave the session
+            // heartbeat 401ing forever (the CLI-v1 stale-token root cause). No-op unless
+            // the tools server is running.
+            setToolsClient(p.client);
+        }
+        catch { /* stay down until the next tick */ }
+    }
+    // Re-attempt agent registration each heartbeat for any detected agent still
+    // idle or failed, while the tools server is up. Registration otherwise fires
+    // only ONCE at startPresence against that instant's detectAgents(): an agent
+    // installed AFTER sign-in would stay 'idle' forever (badge stuck "connecting…")
+    // and a 'failed' registration would never retry (making the "will retry" copy a
+    // lie). registerWithX's double-kick guard skips agents already 'registering',
+    // and 'registered' agents aren't retried, so this is safe to call every tick.
+    // Runs only in the presence process and stops when presence stops (this is the
+    // heartbeat, whose interval stopPresence clears).
+    // ponytail: a genuinely-unregisterable agent retries every ~10s indefinitely;
+    // add backoff if that churn ever matters.
+    const server = toolsServerStatus();
+    if (server.running) {
+        const status = agentRegStatus();
+        for (const agent of detectAgents()) {
+            if (status[agent] !== 'idle' && status[agent] !== 'failed')
+                continue;
+            if (agent === 'claude')
+                registerWithClaude(server.port);
+            else
+                registerWithCodex(server.port);
+        }
+        // D2b: while the tools server is up, keep every open work session's
+        // last_seen_at fresh so the web presence "working" chip stays lit while
+        // agents work. Best-effort/no-throw, exactly like the block above.
+        await heartbeatOpenSessions();
+    }
+}
+/** Delete cloud rows for machine ids this install has migrated off of, so an old
+ *  per-install id can't linger as a duplicate "offline" row for the same box.
+ *  Runs after the first heartbeat, so the new row already exists throughout. */
+async function cleanupSupersededRows(p) {
+    const stale = supersededMachineIds();
+    if (!stale.length)
+        return;
+    try {
+        // Reap BOTH per-machine_id tables in the same pass so they stay consistent:
+        // the orphaned cliv2_agents row (an offline duplicate) AND any orphaned
+        // cliv2_codebase_locations rows — otherwise the web would show a codebase as
+        // "not on any of your computers" while the companion still shows it located.
+        // The companion re-reports located from its local codebase-paths on the next
+        // add/locate, so a plain delete of the stale rows is enough. Only clear the
+        // marker once BOTH deletes succeed, so a partial failure retries next start.
+        const agents = await p.client.from('cliv2_agents').delete().in('machine_id', stale);
+        if (agents.error)
+            throw agents.error;
+        const locations = await p.client.from('cliv2_codebase_locations').delete().in('machine_id', stale);
+        if (locations.error)
+            throw locations.error;
+        clearSupersededMachineIds();
+    }
+    catch (err) {
+        // Best-effort — the orphaned rows are the pre-fix state. Retried next start.
+        console.warn(`superseded-row cleanup failed, will retry: ${err.message}`);
+    }
+}
+async function pollCommands(p) {
+    try {
+        const { data, error } = await p.client
+            .from('cliv2_commands')
+            .update({ status: 'ack', acked_at: new Date().toISOString() })
+            .eq('machine_id', p.identity.id)
+            .eq('status', 'pending')
+            .select('id, command');
+        if (error)
+            throw error;
+        for (const cmd of data ?? [])
+            console.log(`Acked ${cmd.command} (${cmd.id})`);
+    }
+    catch (err) {
+        console.warn(`command poll failed, will retry: ${err.message}`);
+    }
+}
+/** Come online. Throws NotLoggedIn (from getClient) if no session — callers in
+ *  the companion guard for that; the terminal daemon lets it surface. No-op if
+ *  already running. */
+export async function startPresence() {
+    if (presence)
+        return { machineName: presence.identity.name, agents: presence.agents };
+    if (starting)
+        return starting;
+    starting = (async () => {
+        const identity = getMachineIdentity();
+        const agents = detectAgents();
+        const client = await getClient();
+        const { data } = await client.auth.getUser();
+        const userId = data.user?.id;
+        if (!userId)
+            throw new Error('Signed-in user could not be resolved. Sign in again.');
+        const p = {
+            client,
+            userId,
+            identity,
+            agents,
+            platform: platform(),
+            hb: setInterval(() => { }, HEARTBEAT_INTERVAL_MS),
+            cp: setInterval(() => { }, COMMAND_POLL_INTERVAL_MS),
+        };
+        clearInterval(p.hb);
+        clearInterval(p.cp);
+        presence = p;
+        await heartbeat(p);
+        await cleanupSupersededRows(p);
+        p.hb = setInterval(() => void heartbeat(p), HEARTBEAT_INTERVAL_MS);
+        p.cp = setInterval(() => void pollCommands(p), COMMAND_POLL_INTERVAL_MS);
+        // Bring up the local ctrl-spc MCP tools server and register it into Claude
+        // so any agent run on this machine has the tools with zero setup. Strictly
+        // best-effort: a tools-server or registration failure must never break the
+        // presence heartbeat above, so it's caught and warned like everything here.
+        try {
+            await startToolsServer({ client, userId, machineId: identity.id });
+            if (agents.includes('claude'))
+                registerWithClaude(toolsServerStatus().port);
+            if (agents.includes('codex'))
+                registerWithCodex(toolsServerStatus().port);
+        }
+        catch (err) {
+            console.warn(`Agent tools server did not start: ${err.message}`);
+        }
+        return { machineName: identity.name, agents };
+    })();
+    try {
+        return await starting;
+    }
+    finally {
+        starting = null;
+    }
+}
+/** Go offline. Best-effort stamps last_seen_at into the past so the web sheet
+ *  reads offline immediately instead of waiting out the freshness window. Pass
+ *  `unregister` (logout only, never plain shutdown) to also remove the ctrl-spc
+ *  entry from each detected agent's config. */
+export async function stopPresence({ markOffline = true, unregister = false } = {}) {
+    const p = presence;
+    if (!p)
+        return;
+    presence = null;
+    clearInterval(p.hb);
+    clearInterval(p.cp);
+    // On logout (unregister), scrub the ctrl-spc entry from each detected agent's
+    // config so a logged-out machine leaves no dead server that would read "failed
+    // to connect" on the next agent run. Fire-and-forget best-effort — never blocks
+    // logout. On a plain SIGINT shutdown the entries are intentionally left in place
+    // (the caller passes no `unregister`); the badge just reads not-connected
+    // because the server below is torn down.
+    if (unregister) {
+        if (p.agents.includes('claude'))
+            void unregisterFromClaude();
+        if (p.agents.includes('codex'))
+            void unregisterFromCodex();
+    }
+    await stopToolsServer().catch((err) => console.warn(`Agent tools server did not stop cleanly: ${err.message}`));
+    if (markOffline) {
+        try {
+            await p.client
+                .from('cliv2_agents')
+                .update({ last_seen_at: new Date(0).toISOString() })
+                .eq('machine_id', p.identity.id);
+        }
+        catch { /* ignore — a stale timestamp already reads as offline */ }
+    }
+}

package/dist/projects.js

@@ -0,0 +1,32 @@
+import { readMappings, writeMapping } from './config.js';
+/**
+ * The signed-in user's projects, each merged with this machine's mapping.
+ *
+ * Projects come from the shared product `projects` table via the user's RLS
+ * (org-scoped — the same rows the web app sees). The per-machine folder + remote
+ * come from a LOCAL file (config.ts), never the cloud, so absolute paths never
+ * leave this machine — the product's path-privacy invariant. The v2 CLI thus
+ * only READS shared product data and never writes outside its own local state.
+ */
+export async function loadProjects(client) {
+    const { data, error } = await client
+        .from('projects')
+        .select('id, name, git_remote_url')
+        .order('created_at', { ascending: true });
+    if (error)
+        throw new Error(error.message);
+    const mappings = readMappings();
+    return (data ?? []).map((project) => {
+        const mapping = mappings[project.id];
+        return {
+            id: project.id,
+            name: project.name ?? 'Untitled project',
+            localPath: mapping?.localPath ?? null,
+            gitRemoteUrl: mapping?.gitRemoteUrl ?? project.git_remote_url ?? null,
+        };
+    });
+}
+/** Saves this machine's mapping for one project — locally, never uploaded. */
+export function saveMapping(projectId, mapping) {
+    writeMapping(projectId, mapping);
+}

package/dist/supabase.js

@@ -1,12 +1,32 @@
 import { createClient } from '@supabase/supabase-js';
 import { SUPABASE_URL, SUPABASE_KEY } from './env.js';
-import { readSession, writeSession } from './config.js';
+import { readSession, writeSession, getMachineIdentity } from './config.js';
 export class NotLoggedIn extends Error {
     constructor(message = 'Not logged in. Run `cs login` first.') {
         super(message);
         this.name = 'NotLoggedIn';
     }
 }
+/**
+ * Sign in with email + password and persist the session to disk (shared with
+ * the terminal CLI via session.json). Used by the companion GUI's sign-in form,
+ * whose CSP keeps its page confined to this local server — the exchange with
+ * Supabase happens here, server-side, not in the browser.
+ */
+export async function signIn(email, password) {
+    const client = createClient(SUPABASE_URL, SUPABASE_KEY, {
+        auth: { persistSession: false, autoRefreshToken: false },
+        global: { fetch: retryingFetch },
+    });
+    const { data, error } = await client.auth.signInWithPassword({ email, password });
+    if (error)
+        throw new Error(error.message);
+    if (!data.session || !data.user?.email)
+        throw new Error('Sign-in did not return a session.');
+    writeSession({ access_token: data.session.access_token, refresh_token: data.session.refresh_token });
+    getMachineIdentity(); // ensure a stable machine id exists post sign-in
+    return { email: data.user.email };
+}
 /**
  * Network-layer retry — the v1 CLI's most valuable robustness trick. Retries
  * only fetch-level failures (DNS/wifi drop surface as TypeError); real HTTP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"
@@ -21,7 +21,9 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@supabase/supabase-js": "^2.110.1"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@supabase/supabase-js": "^2.110.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",