@ctrl-spc/cli 1.3.1 → 1.3.3

package/dist/roles.js

@@ -0,0 +1,18 @@
+export const ROLE_SUGGESTIONS = [
+    { slug: 'ios-app', label: 'iOS app' },
+    { slug: 'android-app', label: 'Android app' },
+    { slug: 'mobile-app', label: 'Mobile app' },
+    { slug: 'web-app', label: 'Web app' },
+    { slug: 'api', label: 'API server' },
+    { slug: 'cli', label: 'Command-line tool' },
+    { slug: 'schema', label: 'Database & schema' },
+    { slug: 'infra', label: 'Infrastructure' },
+    { slug: 'docs', label: 'Docs' },
+];
+export function isValidRoleSlug(value) {
+    return /^[a-z0-9][a-z0-9-]{0,39}$/.test(value);
+}
+export function suffixedRoleSlug(base, number) {
+    const suffix = `-${number}`;
+    return `${base.slice(0, 40 - suffix.length)}${suffix}`;
+}

package/dist/runtime-control.js

@@ -0,0 +1,248 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { configDir } from './config.js';
+const CURRENT_PACKAGE_PATH = fileURLToPath(new URL('../package.json', import.meta.url));
+const CURRENT_ENTRY_PATH = fileURLToPath(new URL('./index.js', import.meta.url));
+export const LOCAL_RUNTIME_PORT = Number(process.env.CTRL_SPC_LOCAL_PORT) || 4572;
+export const NPM_RUNTIME_PORT = Number(process.env.CTRL_SPC_NPM_PORT) || 4571;
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function readManifest(path) {
+    if (!path || !existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+let cachedGlobalPackagePath;
+function globalPackagePath() {
+    if (cachedGlobalPackagePath !== undefined)
+        return cachedGlobalPackagePath;
+    try {
+        const root = execFileSync('npm', ['root', '-g'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        cachedGlobalPackagePath = root ? join(root, '@ctrl-spc', 'cli', 'package.json') : null;
+    }
+    catch {
+        cachedGlobalPackagePath = null;
+    }
+    return cachedGlobalPackagePath;
+}
+function entryForPackage(packagePath) {
+    return packagePath ? join(dirname(packagePath), 'dist', 'index.js') : null;
+}
+export function currentCompanionKind() {
+    const override = process.env.CTRL_SPC_COMPANION_KIND;
+    if (override === 'local' || override === 'npm')
+        return override;
+    const installedEntry = entryForPackage(globalPackagePath());
+    const currentEntry = safeRealpath(CURRENT_ENTRY_PATH);
+    const installedRealpath = installedEntry ? safeRealpath(installedEntry) : null;
+    return currentEntry && installedRealpath && currentEntry === installedRealpath ? 'npm' : 'local';
+}
+function supportsCompanionControl(manifest) {
+    return (manifest?.ctrlSpc?.companionControlVersion ?? 0) >= 1;
+}
+export function runtimeProfiles() {
+    const installedPackagePath = globalPackagePath();
+    const installedEntry = entryForPackage(installedPackagePath);
+    const installedManifest = readManifest(installedPackagePath);
+    const currentEntry = safeRealpath(process.env.CTRL_SPC_LOCAL_ENTRY || CURRENT_ENTRY_PATH);
+    const currentPackage = process.env.CTRL_SPC_LOCAL_ENTRY
+        ? resolve(dirname(process.env.CTRL_SPC_LOCAL_ENTRY), '..', 'package.json')
+        : CURRENT_PACKAGE_PATH;
+    const currentManifest = readManifest(currentPackage);
+    const installedRealpath = installedEntry ? safeRealpath(installedEntry) : null;
+    const localIsInstalled = Boolean(currentEntry && installedRealpath && currentEntry === installedRealpath);
+    const localAvailable = Boolean(currentEntry && !localIsInstalled && supportsCompanionControl(currentManifest));
+    const npmAvailable = Boolean(installedRealpath && existsSync(installedRealpath) && supportsCompanionControl(installedManifest));
+    return [
+        {
+            kind: 'local',
+            label: 'Local development',
+            description: 'Runs the build from this repository on port ' + LOCAL_RUNTIME_PORT + '.',
+            port: LOCAL_RUNTIME_PORT,
+            entryPath: currentEntry,
+            packagePath: currentPackage,
+            version: currentManifest?.version ?? null,
+            available: localAvailable,
+            ...(!localAvailable ? {
+                unavailableReason: localIsInstalled
+                    ? 'Launch the connection manager from the source repository to control a local build.'
+                    : 'Build the local CLI before starting this connection.',
+            } : {}),
+        },
+        {
+            kind: 'npm',
+            label: 'Installed package',
+            description: 'Runs the globally installed npm package on port ' + NPM_RUNTIME_PORT + '.',
+            port: NPM_RUNTIME_PORT,
+            entryPath: installedRealpath,
+            packagePath: installedPackagePath,
+            version: installedManifest?.version ?? null,
+            available: npmAvailable,
+            ...(!npmAvailable ? {
+                unavailableReason: installedManifest
+                    ? 'Update the installed npm package to a version that includes connection controls.'
+                    : 'The @ctrl-spc/cli npm package is not installed globally.',
+            } : {}),
+        },
+    ];
+}
+export async function probeBroker(port, fetcher = fetch) {
+    try {
+        const response = await fetcher(`http://127.0.0.1:${port}/health`, {
+            signal: AbortSignal.timeout(750),
+        });
+        if (!response.ok)
+            return null;
+        const health = await response.json();
+        return health.status === 'ok' ? health : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runtimeStatuses() {
+    return Promise.all(runtimeProfiles().map(async (profile) => {
+        const health = await probeBroker(profile.port);
+        const ownsPort = health?.runtime?.kind === profile.kind;
+        if (health && !ownsPort) {
+            return { ...profile, running: true, ownsPort: false, health, state: 'conflict' };
+        }
+        if (ownsPort) {
+            return { ...profile, running: true, ownsPort: true, health, state: 'ready' };
+        }
+        if (!profile.available) {
+            return { ...profile, running: false, ownsPort: false, health: null, state: 'unavailable' };
+        }
+        return { ...profile, running: false, ownsPort: false, health: null, state: 'off' };
+    }));
+}
+function runtimeDir() {
+    return join(configDir(), 'runtime');
+}
+function pidPath(kind) {
+    return join(runtimeDir(), `${kind}.pid`);
+}
+function logPath(kind) {
+    return join(runtimeDir(), `${kind}.log`);
+}
+function writePrivateFile(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+function readPid(kind) {
+    try {
+        const value = Number(readFileSync(pidPath(kind), 'utf8').trim());
+        return Number.isInteger(value) && value > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitFor(check, timeoutMs, intervalMs = 150) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await check())
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    return check();
+}
+export async function stopRuntime(kind) {
+    const profile = runtimeProfiles().find((candidate) => candidate.kind === kind);
+    const health = await probeBroker(profile.port);
+    const healthPid = health?.runtime?.kind === kind ? health.process_id : undefined;
+    const pid = healthPid ?? readPid(kind);
+    if (!pid || !processExists(pid)) {
+        rmSync(pidPath(kind), { force: true });
+        if (health) {
+            throw new Error(`${profile.label} cannot be stopped safely because port ${profile.port} belongs to an unlabeled process.`);
+        }
+        return;
+    }
+    process.kill(pid, 'SIGTERM');
+    const stopped = await waitFor(() => Promise.resolve(!processExists(pid)), 4_000);
+    if (!stopped) {
+        process.kill(pid, 'SIGKILL');
+        await waitFor(() => Promise.resolve(!processExists(pid)), 1_000);
+    }
+    rmSync(pidPath(kind), { force: true });
+}
+export async function startRuntime(kind) {
+    const profiles = runtimeProfiles();
+    const profile = profiles.find((candidate) => candidate.kind === kind);
+    if (!profile.available || !profile.entryPath) {
+        throw new Error(profile.unavailableReason ?? `${profile.label} is unavailable.`);
+    }
+    const other = profiles.find((candidate) => candidate.kind !== kind);
+    const otherHealth = await probeBroker(other.port);
+    if (otherHealth?.runtime?.kind === other.kind) {
+        await stopRuntime(other.kind);
+    }
+    else if (otherHealth) {
+        throw new Error(`${other.label} is using port ${other.port}, but this older process cannot identify itself. ` +
+            'Stop it from its terminal before switching connections.');
+    }
+    const currentHealth = await probeBroker(profile.port);
+    if (currentHealth?.runtime?.kind === kind)
+        return;
+    if (currentHealth) {
+        throw new Error(`Port ${profile.port} is already used by an unlabeled process. Turn it off before continuing.`);
+    }
+    mkdirSync(runtimeDir(), { recursive: true });
+    const logFd = openSync(logPath(kind), 'a', 0o600);
+    let child;
+    try {
+        child = spawn(process.execPath, [profile.entryPath, '__broker'], {
+            detached: true,
+            env: {
+                ...process.env,
+                CTRL_SPC_PORT: String(profile.port),
+                CTRL_SPC_RUNTIME_KIND: profile.kind,
+                CTRL_SPC_RUNTIME_LABEL: profile.label,
+            },
+            stdio: ['ignore', logFd, logFd],
+        });
+        child.unref();
+    }
+    finally {
+        closeSync(logFd);
+    }
+    if (!child.pid)
+        throw new Error(`${profile.label} did not start.`);
+    writePrivateFile(pidPath(kind), String(child.pid));
+    const ready = await waitFor(async () => {
+        const health = await probeBroker(profile.port);
+        return health?.runtime?.kind === kind;
+    }, 30_000, 250);
+    if (!ready) {
+        rmSync(pidPath(kind), { force: true });
+        const log = existsSync(logPath(kind)) ? readFileSync(logPath(kind), 'utf8').trim().split('\n').slice(-4).join('\n') : '';
+        throw new Error(`${profile.label} did not become ready.${log ? `\n${log}` : ''}`);
+    }
+}

package/dist/supabase.js

@@ -41,3 +41,14 @@ export async function getClient() {
     }
     return client;
 }
+export async function fetchServerCapabilities(client) {
+    try {
+        const { data, error } = await client.rpc('get_ctrl_spc_capabilities');
+        if (!error && data && typeof data === 'object' && !Array.isArray(data)) {
+            return data;
+        }
+    }
+    catch { }
+    console.warn('Notice: this server does not advertise CTRL+SPC capabilities.');
+    return {};
+}

package/dist/topology.js

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { normalizeRemoteUrl } from './git.js';
+import { isValidRoleSlug, ROLE_SUGGESTIONS } from './roles.js';
 /** Directories that are both expensive and extremely unlikely to contain a
  * user-owned repository that should be auto-discovered. An explicitly passed
  * --repo path is still inspected even when one of its ancestors has this name. */
@@ -436,20 +437,21 @@ export function componentTargetId(remoteKey, relativePath) {
     const normalized = toPosix(relativePath).replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
     return `component:${normalizeRemoteUrl(remoteKey)}#${normalized}`;
 }
-export function buildTopologyTargets(discovery) {
+export function buildTopologyTargets(discovery, repositoryKey = (repository) => (repository.origin.status === 'normalized' ? repository.origin.url : null)) {
     const targets = [];
     for (const repository of discovery.repositories) {
-        if (repository.origin.status !== 'normalized')
+        const key = repositoryKey(repository);
+        if (!key)
             continue;
         targets.push({
-            id: repositoryTargetId(repository.origin.url),
+            id: repositoryTargetId(key),
             repositoryRoot: repository.rootPath,
             componentPath: null,
             label: basename(repository.rootPath),
         });
         for (const component of repository.componentCandidates) {
             targets.push({
-                id: componentTargetId(repository.origin.url, component.relativePath),
+                id: componentTargetId(key, component.relativePath),
                 repositoryRoot: repository.rootPath,
                 componentPath: component.relativePath,
                 label: component.label,
@@ -532,6 +534,9 @@ export function planExplicitGrouping(availableTargets, selection) {
     for (const id of Object.keys(targetConfiguration)) {
         if (!selected.has(id))
             throw new Error(`Configuration references an unselected topology target: ${id}`);
+        const role = targetConfiguration[id]?.role;
+        if (role && !isValidRoleSlug(role.slug))
+            throw new Error(`Invalid role slug for topology target ${id}: ${role.slug}`);
     }
     return { mode: 'custom', targetIds, groups, targetConfiguration };
 }
@@ -553,9 +558,22 @@ function parseManifestTargets(values, label) {
         if (config.purpose !== undefined && typeof config.purpose !== 'string') {
             throw new Error(`Grouping manifest target ${config.id} purpose must be a string.`);
         }
+        if (config.role !== undefined && (typeof config.role !== 'string' || !config.role.trim())) {
+            throw new Error(`Grouping manifest target ${config.id} role must be a string.`);
+        }
+        const [roleSlug, ...roleLabelParts] = typeof config.role === 'string' ? config.role.split(':') : [];
+        if (roleSlug && !isValidRoleSlug(roleSlug)) {
+            throw new Error(`Grouping manifest target ${config.id} role has an invalid slug.`);
+        }
+        const catalogLabel = ROLE_SUGGESTIONS.find(role => role.slug === roleSlug)?.label;
         targetConfiguration[config.id] = {
             ...(config.required === undefined ? {} : { required: config.required }),
             ...(config.purpose === undefined ? {} : { purpose: config.purpose }),
+            ...(roleSlug ? { role: {
+                    slug: roleSlug,
+                    label: roleLabelParts.join(':').trim() || catalogLabel,
+                    source: 'user',
+                } } : {}),
         };
         return config.id;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cli",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "CTRL+SPC CLI — per-machine agent for browser login, project linking, presence, and the local MCP server.",
   "engines": {
     "node": ">=22"
@@ -16,13 +16,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "ctrlSpc": {
+    "companionControlVersion": 1
+  },
   "scripts": {
     "build": "tsc",
+    "app": "npm run build && node dist/index.js open",
     "test": "vitest run",
     "test:e2e-contract": "vitest run e2e",
     "typecheck:e2e-contract": "tsc -p e2e/tsconfig.json",
     "run:e2e-copied-work": "node --experimental-strip-types e2e/run-copied-work-item.ts",
     "run:e2e-hosted-topology": "npm run build && node --experimental-strip-types e2e/run-hosted-topology-management.ts",
+    "run:e2e-role-routing": "node --experimental-strip-types e2e/run-role-routing-matrix.ts --apply",
     "setup:e2e-multirepo": "node --experimental-strip-types e2e/setup-multirepo-matrix.ts",
     "verify:e2e-multirepo": "npm run build && node --experimental-strip-types e2e/run-multirepo-matrix.ts"
   },