@loompad/cli 0.1.0 → 1.1.1

package/dist/daemon/team.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Team Link — a member's daemon on a Loom Team Hub (docs/teams-architecture.md).
+ *
+ * Phase 1, "see each other". What it does, and the decision each part serves:
+ *   - signs in (D4: a GitHub login), holds this device's keys, and the team
+ *     keys it has been given (D5 via invite links, D6 via sealed envelopes)
+ *   - shares projects opt-in, or by git remote matching a team repo (D8)
+ *   - heartbeats every live session in shared projects: agent, state, branch,
+ *     file globs in the clear; goal/task titles sealed (D2, D24 — intent, never
+ *     prompts or transcripts)
+ *   - publishes goal lifecycle to the team feed, and PR/check activity by
+ *     polling `gh` when the team has no GitHub App (D7)
+ *   - keeps a decrypted live view (members, presence, feed) for the UI
+ *
+ * State lives in ~/.loom/team.json (0600): hub session, device keys, team keys.
+ * The hub never holds a readable team key.
+ */
+import { type InviteFragment } from "../core/team-crypto.js";
+import { type FeedIn, type HubClient, type PresenceIn } from "../core/team-hub.js";
+import type { ProjectRuntime } from "./runtime.js";
+import { Deploys } from "./deploys.js";
+import { Landing, type Exec } from "./landing.js";
+import { TeamBrain } from "./team-brain.js";
+import { TeamCoordinator } from "./team-coordinator.js";
+import { Runner, type JobPayload, type RunnerConfig } from "./runner.js";
+/**
+ * The project's GitHub repo ("owner/name"): `git config loom.repo` when set (a
+ * mirror, or a remote that isn't github.com), else its origin remote.
+ */
+export declare function repoOf(dir: string): Promise<string | null>;
+export interface TeamLinkHost {
+    /** Open project runtimes (only these can be shared/heartbeated). */
+    runtimes(): ProjectRuntime[];
+    /** Fan a team frame out to connected UIs. */
+    broadcast(frame: Record<string, unknown>): void;
+    /** Tests inject a hub; production builds an HttpHubClient from state. */
+    hubFactory?: (url: string, token: string) => HubClient;
+    /** Where team.json lives; defaults to ~/.loom/team.json. Tests run two members in one process. */
+    statePath?: string;
+    /** Tests swap `gh` for one-link onboarding's repo-access grant. */
+    gh?: (args: string[]) => Promise<string>;
+    /** Tests swap `gh` (and friends) for the landing flow (Phase 4). */
+    landingExec?: Exec;
+    landingRerunSettleMs?: number;
+    /** Tests: how long a landing turn waits for checks to show up on a fresh push (Phase 6). */
+    landingTrainSettleMs?: number;
+    /** Phase 5: open a directory as a project (a runner's per-goal clone), and close it again. */
+    openProject?(dir: string, name: string): Promise<ProjectRuntime>;
+    closeProject?(rt: ProjectRuntime): Promise<void>;
+    /** Tests: where a runner clones a repo from, and which agent kinds it offers. */
+    runnerCloneUrl?(repo: string): string;
+    runnerKinds?(): Promise<string[]>;
+    /** Tests: the runner's config instead of ~/.loom/runner.json. */
+    runnerConfig?(): RunnerConfig;
+    runnerAwayMs?: number;
+    /** `loom runner exec` inside a container: run this one job, then call done. */
+    runnerExec?: {
+        teamId: string;
+        jobId: string;
+        done(ok: boolean): void;
+    };
+}
+export declare class TeamLink {
+    private host;
+    private file;
+    private state;
+    private hubClient;
+    private views;
+    private unsubs;
+    private timers;
+    private live;
+    private logSubs;
+    private coordinators;
+    private brains;
+    private landings;
+    private deploys;
+    /** Phase 5: this daemon as a runner, when it's configured as one. */
+    runner: Runner | null;
+    /** Return jobs we asked for → the project whose goal comes home (D76). */
+    private pendingReturns;
+    private started;
+    constructor(host: TeamLinkHost);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private hub;
+    private makeClient;
+    /** Refresh tokens rotate: the one in team.json must always be the newest, or the next start signs us out. */
+    private persistHostedSession;
+    /** Swap the hub client, closing a hosted one we replace (its refresh timer would race the new one's). */
+    private setHubClient;
+    /**
+     * Sign in to a hub. Hosted (no URL, "hosted", or `supabase:<url>`): GitHub
+     * OAuth in the browser, or a refresh token from a CLI that already did it.
+     * Self-hosted: as a GitHub login (defaults to the local `gh` user).
+     */
+    signIn(url: string, opts?: {
+        github?: string;
+        secret?: string;
+        token?: string;
+    }): Promise<void>;
+    /** The hosted hub (D65): a Supabase session from GitHub OAuth, kept as its refresh token. */
+    private signInHosted;
+    private ensureDevice;
+    private device;
+    /** (Re)attach to the hub: every team we know, live subscriptions, and shared projects. */
+    connect(): Promise<void>;
+    /** Open any key envelopes sealed to this device we don't have yet (D6). */
+    private pullKeys;
+    private currentKey;
+    private attach;
+    private onHubEvent;
+    createTeam(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * An invite link: the token and the current team key ride the #fragment
+     * (D5) — never sent to any server, the join page included. `extra` makes it
+     * a one-link onboarding (daemon/onboard.ts): the repo to clone, the crews to
+     * set up, and whether joining grants push access to the repo.
+     */
+    invite(teamId?: string, extra?: {
+        repo?: string;
+        project?: string;
+        crews?: InviteFragment["crews"];
+        grant?: boolean;
+    }): Promise<{
+        link: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Is what a link asks for (the repo to clone, the crews to set up) what its
+     * inviter signed? Checked once we're on the team and can see the inviter's
+     * registered devices: anyone holding the link holds the team key, so only the
+     * device signature can't be forged. "unsigned" is a link from an older Loom —
+     * or one with the signature stripped, so it gets no more trust than a bad one.
+     */
+    verifyInvite(inv: InviteFragment, teamId: string): "ok" | "unsigned" | "bad";
+    /** Signed in to this hub already? (A link names its hub.) */
+    signedInTo(hub: string): boolean;
+    /** This daemon's GitHub login on its hub. */
+    github(): string | null;
+    /** The teams this daemon is in, with the repos each shares. */
+    teams(): Array<{
+        id: string;
+        name: string;
+        repos: string[];
+    }>;
+    join(link: string, opts?: {
+        github?: string;
+        secret?: string;
+        token?: string;
+    }): Promise<{
+        id: string;
+        name: string;
+        alreadyMember?: boolean;
+    }>;
+    /**
+     * Remove a member, then rotate the key forward (D6): a new key, sealed to
+     * every remaining device. The removed member keeps what they already saw —
+     * nothing new is readable to them.
+     */
+    removeMember(userId: string, teamId?: string): Promise<{
+        keyVersion: number;
+    }>;
+    /** When this daemon last rotated each team's key. */
+    private rotatedAt;
+    rotate(teamId?: string): Promise<{
+        keyVersion: number;
+    }>;
+    leave(teamId?: string): Promise<void>;
+    /**
+     * Someone redeemed an invite that promised repo access: add them as a
+     * collaborator with push, through this machine's `gh` (it's your repo, and
+     * your invite). GitHub sends them an invitation their Loom accepts.
+     */
+    private grantJoiner;
+    private defaultTeam;
+    /** Share a project's repo with a team (D8: explicit opt-in). */
+    share(rt: ProjectRuntime, teamId?: string): Promise<{
+        repo: string;
+        teamId: string;
+    }>;
+    unshare(rt: ProjectRuntime): void;
+    /** Which team a project publishes to: its explicit share, else a team whose repo matches its remote (D8). */
+    private teamFor;
+    /** Whether the last call to the hub got through, and the error when it didn't. */
+    private hubOk;
+    private connected;
+    private noteHub;
+    /** The heartbeat timer: reconnect when the hub was down at start, then beat. */
+    private tick;
+    /** One heartbeat for every live session in every shared project; returns how many the hub took. */
+    beat(): Promise<number>;
+    private clearAllPresence;
+    private watchRuntimes;
+    /**
+     * Called by the daemon before it drops a runtime (config hot-reload, project
+     * removal, a runner's finished clone). Without it the closed runtime stayed
+     * pinned here — its landing loop ticking against a closed log — and the
+     * reopened one never got a coordinator, team brain or feed of its own.
+     */
+    detachRuntime(projectId: string): void;
+    /** Called by the daemon when it opens a runtime. */
+    attachRuntime(rt: ProjectRuntime): void;
+    runnerConfig(): RunnerConfig;
+    /** Turn this daemon into a runner (or restart it with new settings). */
+    startRunner(patch?: Partial<RunnerConfig>): Promise<Record<string, unknown>>;
+    stopRunner(): Promise<void>;
+    private onJob;
+    /** A one-time link that makes another machine one of your runners (D74). Send it like a password. */
+    pairRunnerLink(): string;
+    /**
+     * On the runner box: take the pairing link's team keys, sign in as the same
+     * member (self-hosted: --secret; hosted: a refresh token from the paste-URL
+     * flow), register this device, and seal the keys to it.
+     */
+    joinAsRunner(link: string, opts?: {
+        github?: string;
+        secret?: string;
+        token?: string;
+        shared?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Revoke a runner: remove the device, then rotate every team's key (D74, D6). */
+    revokeRunner(deviceId: string): Promise<void>;
+    /** Runners that can take this project's goals, and the jobs in flight (decrypted). */
+    runnersView(rt: ProjectRuntime): Promise<{
+        runners: Array<Record<string, unknown>>;
+        jobs: Array<Record<string, unknown>>;
+    }>;
+    private jobShare;
+    /** Pick a runner: the one named, else my first online one. */
+    private pickRunner;
+    /** Start a new goal on a runner (D69, D73). */
+    startCrewOnRunner(rt: ProjectRuntime, id: string, text: string, runner?: string): Promise<{
+        jobId: string;
+    }>;
+    controlRunnerCrew(rt: ProjectRuntime, jobId: string, action: NonNullable<JobPayload["crewAction"]>["action"], text?: string, to?: string): Promise<{
+        jobId: string;
+    }>;
+    requestCrew(rt: ProjectRuntime, input: {
+        owner: string;
+        crew: string;
+        teammate: string;
+        text: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    answerCrewRequest(rt: ProjectRuntime, requestId: string, accept: boolean): Promise<{
+        delivery: string;
+    }>;
+    startOnRunner(rt: ProjectRuntime, g: {
+        goal: string;
+        orchestrator?: string;
+        workers?: string[];
+        plan?: boolean;
+        runner?: string;
+    }): Promise<{
+        jobId: string;
+    }>;
+    /** Move a running goal to a runner at a safe point (D75). */
+    continueOnRunner(rt: ProjectRuntime, runId: string, opts?: {
+        runner?: string;
+        graceMs?: number;
+    }): Promise<{
+        jobId: string;
+    }>;
+    /** The runner job currently holding a goal. */
+    private holderJob;
+    /** Bring a goal home from the runner (D76): the runner moves it out, this daemon imports it. */
+    bringBack(rt: ProjectRuntime, runId: string): Promise<{
+        jobId: string;
+    }>;
+    /** Land a goal that lives on a runner (the owner's click, carried as a job). */
+    landOnRunner(rt: ProjectRuntime, runId: string): Promise<{
+        jobId: string;
+    }>;
+    /** Phase 5 (D72): the project's deploy watch and release notes. */
+    deploysFor(rt: ProjectRuntime): Deploys;
+    /** One deploy poll per shared repo (the feed dedupes across members). */
+    pollDeploys(): Promise<number>;
+    /** Phase 4: the project's goal PRs — checks, fixes, review, landing, adopt. */
+    landingFor(rt: ProjectRuntime): Landing;
+    /** Phase 2: the project's team coordinator, created once and handed to its orchestra. */
+    coordinatorFor(rt: ProjectRuntime): TeamCoordinator;
+    /** Phase 3: the project's share of the team brain, created once and handed to its runtime. */
+    brainFor(rt: ProjectRuntime): TeamBrain;
+    /** Sync every open project's team brain (backfill, publish, canon). */
+    syncBrains(): Promise<void>;
+    private onProjectEvent;
+    pollGitHub(): Promise<number>;
+    /** Where a repo webhook posts for this team: the self-hosted hub's route, or the hosted hub's Edge Function. */
+    webhookUrl(teamId: string): string;
+    /**
+     * The team's webhook: its payload URL and secret (owners only; created on
+     * first ask, replaced with `rotate`), and with `install` a repo webhook made
+     * through `gh` for the events Loom maps. The repo defaults to the project's
+     * shared repo, or the team's only one.
+     */
+    webhook(opts?: {
+        teamId?: string;
+        repo?: string;
+        install?: boolean;
+        rotate?: boolean;
+        rt?: ProjectRuntime;
+    }): Promise<{
+        teamId: string;
+        url: string;
+        secret: string;
+        repo: string | null;
+        events: string[];
+        installed?: {
+            id: number | null;
+            repo: string;
+        };
+        warning?: string;
+    }>;
+    status(): Record<string, unknown>;
+    private decryptPresence;
+    /** A lease for the UI: who, which goal/task (decrypted), what it covers, and its state. */
+    private decryptLease;
+    private decryptFeed;
+    private decryptEvent;
+}
+/**
+ * The live sessions in one project, as presence: busy roster agents and every
+ * orchestra task that is running or queued. Titles go in `intent` (sealed);
+ * everything in `presence` is plain metadata (D2, D24).
+ */
+export declare function sessionsOf(rt: ProjectRuntime, repo: string): Array<{
+    presence: Omit<PresenceIn, "deviceId">;
+    intent: Record<string, unknown>;
+}>;
+/**
+ * PR and check facts from one `gh pr list` row, as idempotent feed events. The
+ * mapping lives in core/github-events.ts, shared with the webhook receivers so
+ * polling and webhooks produce the same dedupe keys (D84).
+ */
+export declare function githubFeedEvents(repo: string, pr: Record<string, unknown>): FeedIn[];