@ctrl-spc/cs 0.1.0 → 0.2.0

package/dist/env.js

@@ -10,3 +10,8 @@ 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;
+/** 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;
+/** 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';

package/dist/folders.js

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+/** Native folder chooser per OS. Same commands the v1 companion uses. */
+function pickerCommand() {
+    if (process.platform === 'darwin') {
+        return {
+            command: 'osascript',
+            args: [
+                '-e', 'tell application "Finder"',
+                '-e', 'activate',
+                '-e', 'set selectedFolder to choose folder with prompt "Choose a project folder for CTRL+SPC"',
+                '-e', 'return POSIX path of selectedFolder',
+                '-e', 'end tell',
+            ],
+        };
+    }
+    if (process.platform === 'win32') {
+        const script = [
+            'Add-Type -AssemblyName System.Windows.Forms',
+            '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+            '$dialog.Description = "Choose a project folder for CTRL+SPC"',
+            'if ($dialog.ShowDialog() -eq "OK") { $dialog.SelectedPath }',
+        ].join('; ');
+        return { command: 'powershell.exe', args: ['-NoProfile', '-STA', '-Command', script] };
+    }
+    return {
+        command: 'zenity',
+        args: ['--file-selection', '--directory', '--title=Choose a project folder for CTRL+SPC'],
+    };
+}
+function run(command, args) {
+    return new Promise((resolve, reject) => {
+        // windowsHide keeps the PowerShell launcher from flashing a console.
+        execFile(command, args, { windowsHide: true }, (err, stdout) => {
+            if (err)
+                reject(err);
+            else
+                resolve(stdout.toString());
+        });
+    });
+}
+/** Opens the OS folder picker; resolves to the chosen absolute path, or null if
+ *  the user cancelled. Test override: CTRL_SPC_V2_FOLDER_PICKER_PATH. */
+export async function chooseFolder() {
+    if (process.env.CTRL_SPC_V2_FOLDER_PICKER_PATH)
+        return process.env.CTRL_SPC_V2_FOLDER_PICKER_PATH;
+    try {
+        const { command, args } = pickerCommand();
+        const selected = (await run(command, args)).trim();
+        // osascript returns a trailing-slash POSIX path; normalize it.
+        return (process.platform === 'darwin' ? selected.replace(/\/$/, '') : selected) || null;
+    }
+    catch (err) {
+        if (/cancel/i.test(err.message))
+            return null;
+        throw err;
+    }
+}
+/** Reads `origin`'s fetch URL from a folder's git config, or null if the folder
+ *  isn't a git repo or has no origin remote. Best-effort — never throws. */
+export async function detectGitRemote(folder) {
+    try {
+        return (await run('git', ['-C', folder, 'remote', 'get-url', 'origin'])).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/git-remote.js

@@ -0,0 +1,79 @@
+/**
+ * Git remote canonicalization for the v2 companion.
+ *
+ * `normalizeRemoteUrl` is ported VERBATIM from the v1 CLI (`cli/src/git.ts`) so
+ * v2 stores a codebase's identity exactly the way the product does ("same remote
+ * = same codebase everywhere"). It is duplicated, not imported: cli-v2 is the
+ * isolated `@ctrl-spc/cs` package and must not depend on the v1 package for this
+ * ~12-line pure function.
+ */
+/**
+ * Normalizes a git remote URL to a canonical `host/path` key (no scheme,
+ * lowercase throughout — hosts are case-insensitive and GitHub/GitLab paths
+ * redirect case-insensitively, so one repo should always map to one key).
+ * Non-default ports are kept (`host:port/path`); 22/443/80 are stripped.
+ *
+ *   git@github.com:User/Repo.git      -> github.com/user/repo
+ *   https://github.com/User/Repo/     -> github.com/user/repo
+ *   ssh://git@Host.com:2222/x/y.git   -> host.com:2222/x/y
+ *   https://user:pass@host/x/y.git    -> host/x/y
+ */
+export function normalizeRemoteUrl(raw) {
+    let s = raw.trim();
+    const scp = /^(?:[^@/]+@)([^:/]+):(?!\/\/)(.+)$/.exec(s); // scp-like git@host:path
+    if (scp)
+        s = `${scp[1]}/${scp[2]}`;
+    else {
+        s = s.replace(/^[a-z+]+:\/\//i, ''); // scheme
+        s = s.replace(/^[^@/]+(?::[^@/]*)?@/, ''); // user[:pass]@
+    }
+    s = s.replace(/\/+$/, '').replace(/\.git$/i, '');
+    s = s.replace(/^([^/:]+):(22|443|80)(?=\/)/, '$1'); // default ports
+    return s.toLowerCase();
+}
+/**
+ * A git remote can only become a codebase if it's a real HOSTED repository
+ * (`host/path`). Normalization strips scheme + credentials, but a local/file
+ * path SURVIVES normalization as a bare path — so guard against those
+ * explicitly, keeping absolute local paths out of the cloud and out of hosted
+ * browser JS (the product's path-privacy invariant). Rejects when:
+ *   - the raw scheme is `file:` or `local:`, or
+ *   - the value contains ANY whitespace or backslash (a path smuggled after a
+ *     valid host, e.g. `github.com/a/b /Users/x`, or a UNC path), or
+ *   - the value has no `/` (a bare host like `github.com` isn't a codebase), or
+ *   - the normalized value is an absolute or Windows-drive path (`/…`, `c:\…`), or
+ *   - the host segment (before the first `/`) starts with `.` (relative path like
+ *     `../repo`), or contains/starts with a backslash (UNC path like
+ *     `\\server.local\share`), or is not a domain (has no `.`).
+ *
+ * MUST stay byte-identical in logic to the web's `gitRemoteIdentity.ts`
+ * `isHostedRemote` — same guard, both sides.
+ */
+export function isHostedRemote(raw, normalized) {
+    if (/^(file|local):/i.test(raw.trim()))
+        return false;
+    if (/[\s\\]/.test(normalized))
+        return false; // no whitespace or backslash anywhere (path smuggle / UNC)
+    if (!normalized.includes('/'))
+        return false; // must have a path segment — a bare host isn't a codebase
+    if (normalized.startsWith('/'))
+        return false;
+    if (/^[a-z]:[\\/]/i.test(normalized))
+        return false; // c:\ or c:/ drive path
+    const host = normalized.split('/', 1)[0];
+    if (host.startsWith('.'))
+        return false; // relative path (../repo, ./x)
+    if (host.includes('\\'))
+        return false; // UNC / Windows path (\\server\share)
+    return host.includes('.');
+}
+/**
+ * The canonical `host/path` identity for a git remote when it's a hosted repo,
+ * else `null`. Single entry point combining normalize + the hosted guard — used
+ * both by the companion (early UX feedback at folder-choose time) and by the
+ * write path (defense-in-depth before insert).
+ */
+export function hostedRemoteIdentity(raw) {
+    const normalized = normalizeRemoteUrl(raw);
+    return isHostedRemote(raw, normalized) ? normalized : null;
+}

package/dist/index.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import { login } from './login.js';
 import { runDaemon } from './daemon.js';
+import { openCompanion } from './companion.js';
 import { autostartOn, autostartOff } from './autostart.js';
 import { detectAgents } from './agents.js';
 import { getMachineIdentity, clearSession } from './config.js';
 import { getClient, NotLoggedIn } from './supabase.js';
 const HELP = `cs — CTRL+SPC
 
-  cs                Sign in if needed, then come online (front door)
-  cs login          Sign in with your browser and link this computer
-  cs start          Come online now (sign in first with \`cs login\`)
+  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
@@ -30,25 +32,12 @@ async function status() {
         console.log(err instanceof NotLoggedIn ? 'Not signed in. Run `cs login`.' : `Session error: ${err.message}`);
     }
 }
-/** Front door: ensure signed in, then run the presence agent. */
-async function up() {
-    try {
-        await getClient();
-    }
-    catch (err) {
-        if (!(err instanceof NotLoggedIn))
-            throw err;
-        await login();
-        if (process.exitCode)
-            return; // sign-in failed; message already printed
-    }
-    return runDaemon();
-}
 async function main() {
     const cmd = process.argv[2];
     const arg = process.argv[3];
     switch (cmd) {
-        case undefined: return up();
+        case undefined: return openCompanion();
+        case 'open': return openCompanion();
         case 'login': return login();
         case 'start': return runDaemon();
         case 'status': return status();

package/dist/presence.js

@@ -0,0 +1,144 @@
+import { platform } from 'node:os';
+import { getClient } from './supabase.js';
+import { getMachineIdentity, supersededMachineIds, clearSupersededMachineIds } from './config.js';
+import { detectAgents } from './agents.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();
+        }
+        catch { /* stay down until the next tick */ }
+    }
+}
+/** 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);
+        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. */
+export async function stopPresence({ markOffline = true } = {}) {
+    const p = presence;
+    if (!p)
+        return;
+    presence = null;
+    clearInterval(p.hb);
+    clearInterval(p.cp);
+    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.2.0",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"