@ctrl-spc/cli 1.1.14 → 1.2.0

package/dist/commands/init.js

@@ -0,0 +1,457 @@
+import { createHash } from 'node:crypto';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { getMachineIdentity } from '../config.js';
+import { normalizeRemoteUrl } from '../git.js';
+import { getClient } from '../supabase.js';
+import { ask, select } from '../prompt.js';
+import { buildTopologyTargets, componentTargetId, discoverRepositoryTopology, planExplicitGrouping, readGroupingManifest, repositoryTargetId, } from '../topology.js';
+import { upsertProjectLink } from './link.js';
+function setGrouping(flags, grouping) {
+    if (flags.grouping) {
+        throw new Error(`Choose exactly one grouping option: --combine, --split, or --manifest <file>.`);
+    }
+    flags.grouping = grouping;
+}
+/**
+ * Parses the legacy single-repo flags plus deterministic multi-repo selection:
+ * repeatable `--repo`, and exactly one of `--combine`, `--split`, or
+ * canonical `--manifest <file>` (`--group` remains a compatibility alias).
+ */
+export function parseInitArgs(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        if (flag === '--combine' || flag === '--split') {
+            setGrouping(flags, flag === '--combine' ? 'combine' : 'split');
+            continue;
+        }
+        if (flag === '--yes') {
+            flags.yes = true;
+            continue;
+        }
+        if (flag !== '--org' && flag !== '--name' && flag !== '--repo' && flag !== '--group' && flag !== '--manifest') {
+            throw new Error(`Unknown argument: ${flag}`);
+        }
+        const value = argv[i + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error(`${flag} requires a value`);
+        if (flag === '--org')
+            flags.org = value;
+        else if (flag === '--name')
+            flags.name = value;
+        else if (flag === '--repo') {
+            const repos = flags.repos ?? [];
+            if (repos.includes(value))
+                throw new Error(`Repository path repeated: ${value}`);
+            repos.push(value);
+            flags.repos = repos;
+        }
+        else {
+            setGrouping(flags, 'custom');
+            flags.groupManifest = value;
+        }
+        i++;
+    }
+    if (flags.name && (flags.grouping === 'split' || flags.grouping === 'custom')) {
+        throw new Error('--name can only be used for a single project; name split/custom groups in their grouping choices.');
+    }
+    return flags;
+}
+function isWithin(parent, child) {
+    const rel = relative(parent, child);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+function commonAncestor(paths) {
+    if (paths.length === 0)
+        return process.cwd();
+    let candidate = resolve(paths[0]);
+    while (!paths.every((path) => isWithin(candidate, resolve(path)))) {
+        const parent = dirname(candidate);
+        if (parent === candidate)
+            return candidate;
+        candidate = parent;
+    }
+    return candidate;
+}
+/** Stable across machines because local checkout paths never participate. */
+export function topologyKeyForScopes(scopes) {
+    const normalized = scopes
+        .map((scope) => ({
+        remote: normalizeRemoteUrl(scope.remote_key),
+        path: scope.scope_path.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, ''),
+    }));
+    const members = normalized
+        .map((scope) => `${scope.remote}\u0000${scope.path}`)
+        .sort();
+    if (members.length === 1 && normalized[0].path === '') {
+        // Reuse the backfilled identity of existing single-repository projects.
+        return `legacy:${normalized[0].remote}`;
+    }
+    const digest = createHash('sha256').update(JSON.stringify(members)).digest('hex');
+    return `topology:v1:${digest}`;
+}
+function mergeDiscoveries(discoveries) {
+    const selectedPaths = discoveries.map((item) => item.selectedPath);
+    const candidates = discoveries.flatMap((item) => item.repositories);
+    const byIdentity = new Map();
+    for (const repository of candidates) {
+        const identity = repository.origin.status === 'normalized'
+            ? `remote:${repository.origin.url}`
+            : `git:${repository.gitCommonDir}`;
+        const group = byIdentity.get(identity) ?? [];
+        group.push(repository);
+        byIdentity.set(identity, group);
+    }
+    const repositories = [...byIdentity.values()].map((group) => {
+        group.sort((a, b) => a.rootPath.localeCompare(b.rootPath));
+        const chosen = group[0];
+        return {
+            ...chosen,
+            containsSelection: group.some((item) => item.containsSelection),
+            alternateWorktreeRoots: [...new Set(group.flatMap((item) => [
+                    ...item.alternateWorktreeRoots,
+                    ...(item.rootPath === chosen.rootPath ? [] : [item.rootPath]),
+                ]))].sort(),
+        };
+    }).sort((a, b) => a.rootPath.localeCompare(b.rootPath));
+    const root = commonAncestor(discoveries.map((item) => item.scanRoot));
+    return {
+        selectedPath: commonAncestor(selectedPaths),
+        scanRoot: root,
+        containingGitRoot: discoveries.length === 1 ? discoveries[0].containingGitRoot : null,
+        repositories,
+    };
+}
+function defaultTargetIds(discovery, mode) {
+    if (mode === 'combine') {
+        return discovery.repositories.flatMap((repository) => repository.origin.status === 'normalized'
+            ? [repositoryTargetId(repository.origin.url)]
+            : []);
+    }
+    return discovery.repositories.flatMap((repository) => {
+        if (repository.origin.status !== 'normalized')
+            return [];
+        const remote = repository.origin.url;
+        return repository.componentCandidates.length > 0
+            ? repository.componentCandidates.map((component) => componentTargetId(remote, component.relativePath))
+            : [repositoryTargetId(remote)];
+    });
+}
+function printDiscovery(discovery) {
+    console.log(`Discovered ${discovery.repositories.length} ${discovery.repositories.length === 1 ? 'repository' : 'repositories'}:`);
+    for (const repository of discovery.repositories) {
+        const remote = repository.origin.status === 'normalized' ? repository.origin.url : 'missing origin';
+        const repositoryId = repository.origin.status === 'normalized' ? repositoryTargetId(repository.origin.url) : 'unavailable';
+        console.log(`  - ${repository.rootPath} (${remote})`);
+        console.log(`    target: ${repositoryId}`);
+        if (repository.origin.status === 'normalized') {
+            for (const component of repository.componentCandidates) {
+                console.log(`    component: ${component.relativePath} (${componentTargetId(repository.origin.url, component.relativePath)})`);
+            }
+        }
+    }
+}
+async function chooseGrouping(discovery, flags) {
+    const hasMultipleRepositories = discovery.repositories.length > 1;
+    const hasComponents = discovery.repositories.some((repository) => repository.componentCandidates.length > 0);
+    const choiceRequired = hasMultipleRepositories || hasComponents;
+    let grouping = flags.grouping;
+    let manifestPath = flags.groupManifest;
+    if (!grouping && choiceRequired) {
+        if (!process.stdin.isTTY) {
+            throw new Error('This workspace has multiple repositories or monorepo components. Choose explicitly with --combine, --split, or --manifest <file>.');
+        }
+        grouping = await select(hasMultipleRepositories
+            ? 'How should these repositories and monorepo components become projects?'
+            : 'How should this monorepo become projects?', [
+            { label: hasMultipleRepositories ? 'Combine repositories (keep monorepos together)' : 'Keep monorepo together', value: 'combine' },
+            { label: hasMultipleRepositories ? 'Separate repositories and detected components' : 'Separate detected components', value: 'split' },
+            { label: 'Use custom groups from a manifest', value: 'custom' },
+        ]);
+        if (grouping === 'custom')
+            manifestPath = await ask('Grouping manifest path', 'ctrl-spc-groups.json');
+    }
+    if (!grouping)
+        return null;
+    if (grouping === 'custom') {
+        if (!manifestPath)
+            throw new Error('Custom grouping requires --manifest <file>.');
+        return readGroupingManifest(manifestPath);
+    }
+    return { mode: grouping, targetIds: defaultTargetIds(discovery, grouping) };
+}
+function projectNameForGroup(group, targets, flags, workspaceRoot) {
+    if (group.name)
+        return group.name;
+    if (flags.name)
+        return flags.name;
+    if (group.targetIds.length === 1)
+        return targets.get(group.targetIds[0]).label;
+    return basename(workspaceRoot);
+}
+function planProjects(discovery, targets, grouping, flags) {
+    const targetsById = new Map(targets.map((target) => [target.id, target]));
+    const repositoriesByRoot = new Map(discovery.repositories.map((repository) => [repository.rootPath, repository]));
+    return grouping.groups.map((group) => {
+        const selectedTargets = group.targetIds.map((id) => targetsById.get(id));
+        const projectRoot = selectedTargets.length === 1 && selectedTargets[0].componentPath
+            ? join(selectedTargets[0].repositoryRoot, selectedTargets[0].componentPath)
+            : commonAncestor(selectedTargets.map((target) => target.repositoryRoot));
+        const componentRepositoryRoots = [...new Set(selectedTargets.filter((target) => target.componentPath !== null).map((target) => target.repositoryRoot))];
+        const sharedContextScopes = componentRepositoryRoots.map((repositoryRoot, position) => {
+            const repository = repositoriesByRoot.get(repositoryRoot);
+            if (repository.origin.status !== 'normalized')
+                throw new Error(`Missing origin for ${repository.rootPath}`);
+            const repositoryTargets = selectedTargets.filter((target) => target.repositoryRoot === repositoryRoot);
+            const required = repositoryTargets.some((target) => grouping.targetConfiguration[target.id]?.required !== false);
+            return {
+                remote_key: repository.origin.url,
+                repository_name: basename(repository.rootPath),
+                scope_path: '',
+                kind: 'shared_context',
+                scope_name: `${basename(repository.rootPath)} shared context`,
+                purpose: 'Shared monorepo root context: inspect root configuration, documentation, and shared packages without treating unselected components as affected.',
+                required,
+                position,
+                local_path: repository.rootPath,
+                verified_remote_key: repository.origin.url,
+            };
+        });
+        const componentOrRepositoryScopes = selectedTargets.map((target, index) => {
+            const repository = repositoriesByRoot.get(target.repositoryRoot);
+            if (repository.origin.status !== 'normalized')
+                throw new Error(`Missing origin for ${repository.rootPath}`);
+            const scopePath = target.componentPath ?? '';
+            const config = grouping.targetConfiguration[target.id] ?? {};
+            return {
+                remote_key: repository.origin.url,
+                repository_name: basename(repository.rootPath),
+                scope_path: scopePath,
+                kind: scopePath ? 'component' : 'repository',
+                scope_name: target.label,
+                purpose: config.purpose?.trim() || (scopePath
+                    ? 'Monorepo component; inspect shared repository root context'
+                    : 'Whole repository'),
+                required: config.required ?? true,
+                position: sharedContextScopes.length + index,
+                local_path: repository.rootPath,
+                verified_remote_key: repository.origin.url,
+            };
+        });
+        const scopes = [...sharedContextScopes, ...componentOrRepositoryScopes];
+        return {
+            name: projectNameForGroup(group, targetsById, flags, projectRoot),
+            topologyKey: topologyKeyForScopes(scopes),
+            legacyRemote: [...scopes.map((scope) => scope.remote_key)].sort()[0],
+            workspaceRoot: projectRoot,
+            scopes,
+        };
+    });
+}
+async function confirmWritePlan(flags) {
+    if (flags.yes)
+        return true;
+    if (!process.stdin.isTTY) {
+        throw new Error('Review complete. Re-run with --yes to apply this repository grouping non-interactively.');
+    }
+    return select('Apply this repository grouping?', [
+        { label: 'Yes, create or update these projects', value: true },
+        { label: 'No, make no changes', value: false },
+    ]);
+}
+/** Discovers the selected workspace, confirms an explicit grouping whenever
+ * more than one repository/component choice exists, then persists every
+ * planned project. A plain single repository keeps the legacy atomic flow. */
+export async function init(argv = []) {
+    let flags;
+    try {
+        flags = parseInitArgs(argv);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error('Usage: ctrl-spc init [--org <org-id>] [--name <project-name>] ' +
+            '[--repo <path> ...] [--combine | --split | --manifest <manifest.json>] [--yes]');
+        process.exitCode = 1;
+        return;
+    }
+    const cwd = process.cwd();
+    let discovery;
+    let groupingSelection;
+    let groupedProjects = [];
+    try {
+        const selectedPaths = (flags.repos?.length ? flags.repos : [cwd]).map((path) => resolve(cwd, path));
+        discovery = mergeDiscoveries(selectedPaths.map((path) => discoverRepositoryTopology(path)));
+        if (discovery.repositories.length === 0) {
+            throw new Error('No Git repositories were discovered. Add an origin remote or pass one or more --repo paths.');
+        }
+        const missingOrigins = discovery.repositories.filter((repository) => repository.origin.status === 'missing_origin');
+        if (missingOrigins.length > 0) {
+            throw new Error(`No git remote "origin" found for: ${missingOrigins.map((repository) => repository.rootPath).join(', ')}. ` +
+                'Add an origin remote before initializing.');
+        }
+        printDiscovery(discovery);
+        groupingSelection = await chooseGrouping(discovery, flags);
+        if (groupingSelection) {
+            const targets = buildTopologyTargets(discovery);
+            const grouping = planExplicitGrouping(targets, groupingSelection);
+            groupedProjects = planProjects(discovery, targets, grouping, flags);
+            console.log(`Grouping: ${grouping.mode === 'split' ? 'separate' : grouping.mode}`);
+            for (const project of groupedProjects) {
+                console.log(`  - ${project.name}:`);
+                for (const scope of project.scopes) {
+                    console.log(`    ${scope.remote_key}${scope.scope_path ? `#${scope.scope_path}` : ''} — ` +
+                        `${scope.kind} — ${scope.required ? 'required' : 'optional'} — ${scope.purpose}`);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+    }
+    const client = await getClient();
+    const { data: userData, error: userError } = await client.auth.getUser();
+    if (userError || !userData.user) {
+        console.error(`Could not resolve the signed-in user: ${userError?.message ?? 'no user returned'}`);
+        process.exitCode = 1;
+        return;
+    }
+    const userId = userData.user.id;
+    let orgId = flags.org;
+    let orgLabel = null;
+    if (!orgId) {
+        const org = await chooseOrg(client);
+        if (!org) {
+            console.error('No organizations found for the signed-in user.');
+            process.exitCode = 1;
+            return;
+        }
+        orgId = org.id;
+        orgLabel = org.name;
+    }
+    if (!groupingSelection) {
+        const repository = discovery.repositories[0];
+        const key = repository.origin.status === 'normalized' ? repository.origin.url : '';
+        const defaultName = basename(repository.rootPath);
+        const name = flags.name ?? (flags.org ? defaultName : await ask('Project name', defaultName));
+        console.log(`Review: ${name} — ${key} — required whole repository`);
+        try {
+            if (!await confirmWritePlan(flags)) {
+                console.log('Cancelled — no projects or repository links were changed.');
+                return;
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        const { data, error } = await client.rpc('init_project', {
+            p_org: orgId,
+            p_git_remote_url: key,
+            p_name: name,
+        });
+        if (error) {
+            console.error(`Failed to register project: ${error.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = data;
+        switch (result.status) {
+            case 'foreign_org':
+                console.error(`The repo ${key} is already registered to the organization "${result.org_name}", which you are not a member of. Ask an owner of "${result.org_name}" to invite you, then run \`ctrl-spc link\`.`);
+                process.exitCode = 1;
+                return;
+            case 'exists':
+                console.log(`Project "${result.project_name}" is already registered (${result.org_name}, ${key}) — linking this machine.`);
+                break;
+            case 'created':
+                console.log(`Created project "${result.project_name}" in "${result.org_name ?? orgLabel}" — ${key}`);
+                break;
+        }
+        await upsertProjectLink(client, userId, result.project_id, repository.rootPath);
+        console.log(`Linked — local path ${repository.rootPath}`);
+        return;
+    }
+    try {
+        if (!await confirmWritePlan(flags)) {
+            console.log('Cancelled — no projects or repository links were changed.');
+            return;
+        }
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+    }
+    const machine = getMachineIdentity();
+    const { data, error } = await client.rpc('configure_project_topology_batch', {
+        p_org: orgId,
+        p_machine: machine.id,
+        p_machine_name: machine.name,
+        p_projects: groupedProjects.map((project) => ({
+            topology_key: project.topologyKey,
+            name: project.name,
+            git_remote_url: project.legacyRemote,
+            workspace_root: project.workspaceRoot,
+            scopes: project.scopes,
+        })),
+    });
+    if (error) {
+        console.error(`Failed to configure project grouping: ${error.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const batch = data;
+    const orderedProjects = [...groupedProjects].sort((left, right) => left.topologyKey.localeCompare(right.topologyKey));
+    const results = Array.isArray(batch?.projects) ? batch.projects : [];
+    const validBatch = batch !== null
+        && Number(batch.project_count) === groupedProjects.length
+        && results.length === groupedProjects.length
+        && results.every((result, index) => {
+            const planned = orderedProjects[index];
+            return (result.status === 'created' || result.status === 'updated')
+                && typeof result.project_id === 'string' && result.project_id.length > 0
+                && result.project_name === planned.name
+                && Number(result.scope_count) === planned.scopes.length
+                && Number.isInteger(Number(result.topology_revision))
+                && Number(result.topology_revision) > 0;
+        })
+        && new Set(results.map((result) => result.project_id)).size === results.length;
+    if (!validBatch) {
+        console.error('Failed to configure project grouping: the server returned a response that does not match the reviewed projects. No local project links were changed.');
+        process.exitCode = 1;
+        return;
+    }
+    const resultByProject = new Map();
+    orderedProjects.forEach((project, index) => resultByProject.set(project, results[index]));
+    for (const project of groupedProjects) {
+        const result = resultByProject.get(project);
+        await upsertProjectLink(client, userId, result.project_id, project.workspaceRoot);
+        const verb = result.status === 'created' ? 'Created' : 'Updated';
+        console.log(`${verb} project "${result.project_name}" in "${orgLabel ?? orgId}" — ` +
+            `${result.scope_count} ${result.scope_count === 1 ? 'scope' : 'scopes'}, topology revision ${result.topology_revision}`);
+        console.log(`Linked — local path ${project.workspaceRoot}`);
+    }
+}
+/** Fetches the user's orgs (RLS-scoped) and resolves which one to use. */
+async function chooseOrg(client) {
+    const { data: orgRows, error } = await client
+        .from('organizations')
+        .select('id, name, is_personal')
+        .order('is_personal', { ascending: false });
+    if (error)
+        throw new Error(`Failed to look up your organizations: ${error.message}`);
+    const orgs = (orgRows ?? []).map((o) => ({
+        id: o.id,
+        name: o.name,
+        isPersonal: o.is_personal,
+    }));
+    if (orgs.length === 0)
+        return null;
+    if (orgs.length === 1)
+        return orgs[0];
+    const defaultIndex = Math.max(orgs.findIndex((o) => o.isPersonal), 0);
+    return select('Which organization should this project belong to?', orgs.map((o) => ({ label: o.isPersonal ? `${o.name} (Personal)` : o.name, value: o })), defaultIndex);
+}

package/dist/commands/link.js

@@ -0,0 +1,152 @@
+import { getMachineIdentity } from '../config.js';
+import { getClient } from '../supabase.js';
+import { select } from '../prompt.js';
+import { observeLocalWorkspace, registerMachineWorkspace, } from './run.js';
+export function parseLinkArgs(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        if (flag !== '--project')
+            throw new Error(`Unknown argument: ${flag}`);
+        const value = argv[i + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error(`${flag} requires a value`);
+        if (flags.project)
+            throw new Error('--project may only be provided once');
+        flags.project = value;
+        i++;
+    }
+    return flags;
+}
+function one(value) {
+    return Array.isArray(value) ? value[0] ?? null : value;
+}
+/** Every project visible through RLS, with its complete normalized remote set. */
+export async function listTopologyProjects(client) {
+    const { data, error } = await client
+        .from('project_repository_scopes')
+        .select('project_id,' +
+        'project:projects!project_repository_scopes_project_id_fkey(' +
+        'id,name,org:organizations!projects_org_id_fkey(name)),' +
+        'scope:repository_scopes!project_repository_scopes_repository_scope_id_fkey(' +
+        'repository:repositories!repository_scopes_repository_id_fkey(remote_key))')
+        .eq('active', true);
+    if (error)
+        throw new Error(`Could not load project repository topology: ${error.message}`);
+    const projects = new Map();
+    for (const raw of (data ?? [])) {
+        const project = one(raw.project);
+        const scope = one(raw.scope);
+        const repository = scope ? one(scope.repository) : null;
+        if (!project || !repository)
+            continue;
+        const existing = projects.get(project.id) ?? {
+            id: project.id,
+            name: project.name,
+            orgName: one(project.org)?.name ?? '',
+            remoteKeys: [],
+        };
+        if (!existing.remoteKeys.includes(repository.remote_key))
+            existing.remoteKeys.push(repository.remote_key);
+        projects.set(project.id, existing);
+    }
+    return [...projects.values()]
+        .map((project) => ({ ...project, remoteKeys: project.remoteKeys.sort() }))
+        .sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
+}
+export async function loadTopologyProject(client, projectId) {
+    const { data, error } = await client
+        .from('projects')
+        .select('id,name,org:organizations!projects_org_id_fkey(name)')
+        .eq('id', projectId)
+        .maybeSingle();
+    if (error)
+        throw new Error(`Could not load project ${projectId}: ${error.message}`);
+    if (!data)
+        return null;
+    const row = data;
+    const all = await listTopologyProjects(client);
+    const topology = all.find((project) => project.id === row.id);
+    return topology ?? {
+        id: row.id,
+        name: row.name,
+        orgName: one(row.org)?.name ?? '',
+        remoteKeys: [],
+    };
+}
+export async function chooseTopologyProject(client, explicitProjectId, observedRemoteKeys, options = { action: 'link' }) {
+    if (explicitProjectId) {
+        const explicit = await loadTopologyProject(client, explicitProjectId);
+        if (!explicit)
+            throw new Error(`No accessible project found for id "${explicitProjectId}".`);
+        return explicit;
+    }
+    const observed = new Set(observedRemoteKeys);
+    const all = await listTopologyProjects(client);
+    let candidates = all.filter((project) => project.remoteKeys.some((remote) => observed.has(remote)));
+    if (candidates.length === 0 && options.allowAllWhenNoMatch)
+        candidates = all;
+    if (candidates.length === 0) {
+        throw new Error(observed.size === 0
+            ? `No Git checkout was found here. Re-run with --project <project-id> to ${options.action} a project explicitly.`
+            : `No project matches the repositories found here. Run ctrl-spc init, or use --project <project-id>.`);
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    if (!process.stdin.isTTY) {
+        throw new Error(`${candidates.length} projects match this workspace. Re-run with --project <project-id>: ` +
+            candidates.map((project) => `${project.name} (${project.id})`).join(', '));
+    }
+    return select(`Which project should CTRL+SPC ${options.action}?`, candidates.map((project) => ({
+        label: `${project.name}${project.orgName ? ` (${project.orgName})` : ''}`,
+        value: project,
+    })));
+}
+/** Legacy compatibility for old clients; current clients use machine_workspaces/checkouts. */
+export async function upsertProjectLink(client, userId, projectId, localPath) {
+    const { error } = await client
+        .from('project_links')
+        .upsert({ user_id: userId, project_id: projectId, local_path: localPath }, { onConflict: 'user_id,project_id' });
+    if (error)
+        throw new Error(`Failed to link project: ${error.message}`);
+}
+/** Reconciles the selected project's full repository topology on this machine. */
+export async function link(argv = [], deps = {}) {
+    let flags;
+    try {
+        flags = parseLinkArgs(argv);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error('Usage: ctrl-spc link [--project <project-id>]');
+        process.exitCode = 1;
+        return;
+    }
+    const cwd = process.cwd();
+    const observe = deps.observeWorkspace ?? observeLocalWorkspace;
+    const observation = observe(cwd);
+    const client = await (deps.getClient ?? getClient)();
+    const { data: userData, error: userError } = await client.auth.getUser();
+    if (userError || !userData.user) {
+        console.error(`Could not resolve the signed-in user: ${userError?.message ?? 'no user returned'}`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const remoteKeys = observation.checkouts
+            .map((checkout) => checkout.remoteKey)
+            .filter((remote) => remote !== null);
+        const project = await chooseTopologyProject(client, flags.project, remoteKeys);
+        const machine = getMachineIdentity();
+        const result = await registerMachineWorkspace(client, userData.user.id, project.id, machine, cwd, { observeWorkspace: () => observation });
+        await upsertProjectLink(client, userData.user.id, project.id, observation.workspaceRoot);
+        console.log(`Linked "${project.name}"${project.orgName ? ` (${project.orgName})` : ''} — ` +
+            `${result.availableRepositories} available` +
+            (result.missingRepositories > 0 ? `, ${result.missingRepositories} missing` : '') +
+            `; workspace ${observation.workspaceRoot}`);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+}