@ctrl-spc/cs 0.1.0 → 0.3.0

package/README.md

@@ -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

@@ -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/codebases.js

@@ -0,0 +1,108 @@
+import { hostedRemoteIdentity } from './git-remote.js';
+/** Raised when a folder's git remote isn't a real hosted repository URL, so it
+ *  can't become a codebase. The route surfaces it as a 400 refusal. */
+export class NotHostedRemoteError extends Error {
+    constructor(message = "This folder's git remote isn't a hosted repository URL, so it can't become a codebase.") {
+        super(message);
+        this.name = 'NotHostedRemoteError';
+    }
+}
+/**
+ * The codebases registered on one project.
+ *
+ * Rows live in the isolated `cliv2_codebases` table (org-scoped RLS mirroring
+ * `public.projects`, so this returns every codebase on the project — a codebase
+ * is shared project state visible to every member of the project's org, not a
+ * per-user list). `project_id` references a shared `projects` row by value with
+ * no FK — the v2 surface stays decoupled from v1-owned schema. Only path-free
+ * identities (canonical remote + derived name) are stored, never an absolute
+ * local path (each user's local folder path stays in the CLI's local config).
+ */
+export async function listCodebases(client, projectId) {
+    const { data, error } = await client
+        .from('cliv2_codebases')
+        .select('id, git_remote_url, name')
+        .eq('project_id', projectId)
+        .order('created_at', { ascending: true });
+    if (error)
+        throw new Error(error.message);
+    return (data ?? []).map((row) => ({
+        id: row.id,
+        gitRemoteUrl: row.git_remote_url,
+        name: row.name,
+    }));
+}
+/**
+ * A display name from a canonical `host/path` remote: its last `/` segment.
+ * E.g. `github.com/acme/web` → `web`. Throws rather than ever returning an
+ * empty name (the table's `name` column is `not null`, non-blank).
+ */
+export function deriveCodebaseName(identity) {
+    const name = identity.split('/').pop()?.trim() ?? '';
+    if (!name)
+        throw new Error(`Could not derive a codebase name from "${identity}".`);
+    return name;
+}
+/**
+ * Add a codebase to a project by its git remote URL. The raw remote is
+ * canonicalized to `host/path` (stripping scheme, credentials, `.git`, trailing
+ * slash) BEFORE insert, so only a path-free, shareable identity reaches the
+ * cloud and the unique dedupe key actually holds ("same remote = same
+ * codebase"). A remote that isn't a real hosted repo is refused
+ * (NotHostedRemoteError) and never inserted. `added_by` defaults to auth.uid().
+ *
+ * Returns `{ added: false }` on a unique-violation — the dedupe key is now
+ * (project_id, git_remote_url), so this fires when ANY org member has already
+ * added this remote to the project — a no-op dedupe, never surfaced as an error.
+ */
+export async function addCodebase(client, projectId, gitRemoteUrl) {
+    const identity = hostedRemoteIdentity(gitRemoteUrl);
+    if (!identity)
+        throw new NotHostedRemoteError();
+    const name = deriveCodebaseName(identity);
+    const { error } = await client
+        .from('cliv2_codebases')
+        .insert({ project_id: projectId, git_remote_url: identity, name });
+    if (error) {
+        if (error.code === '23505')
+            return { added: false }; // dedupe: already on the project
+        throw new Error(error.message);
+    }
+    return { added: true };
+}
+/**
+ * Remove a codebase from its project — Phase 3. Deletes the ORG-SHARED
+ * `cliv2_codebases` row by id, so the codebase disappears for every member of
+ * the project's org (its RLS `using` = org membership, so any member may delete;
+ * no extra scoping needed here).
+ *
+ * Deliberately narrow: this deletes ONLY the codebase row. It does NOT touch
+ * per-machine availability (`cliv2_codebase_locations`) or the local folder
+ * mapping (`codebase-paths.json`) — those are per-repo truth, kept so a later
+ * re-add of the same remote shows this computer located again for free.
+ */
+export async function removeCodebase(client, codebaseId) {
+    const { error } = await client.from('cliv2_codebases').delete().eq('id', codebaseId);
+    if (error)
+        throw new Error(error.message);
+}
+/**
+ * Record that THIS machine has a codebase's folder checked out — Phase 2
+ * per-machine availability. Upserts one path-free row into the owner-scoped
+ * `cliv2_codebase_locations` table on `(user_id, machine_id, git_remote_url)`,
+ * refreshing `updated_at`. `user_id` defaults to `auth.uid()` server-side — the
+ * client never sets it — and RLS confines the row to the signed-in user's own
+ * machines (a user's availability is private, mirroring `cliv2_agents`).
+ *
+ * `identity` MUST already be a canonical `host/path` remote (the caller
+ * re-derives it from the folder via `hostedRemoteIdentity`). An absolute local
+ * path is NEVER sent — only the identity + this machine's id, honoring the
+ * product's path-privacy invariant.
+ */
+export async function reportLocated(client, machineId, identity) {
+    const { error } = await client
+        .from('cliv2_codebase_locations')
+        .upsert({ machine_id: machineId, git_remote_url: identity, updated_at: new Date().toISOString() }, { onConflict: 'user_id,machine_id,git_remote_url' });
+    if (error)
+        throw new Error(error.message);
+}