@popoverinstall/cli 0.8.1 → 0.9.0

package/dist/repos.d.ts

@@ -0,0 +1,180 @@
+import { type LocalRepo } from "./repo-scan.js";
+/**
+ * `popover repos` — which repositories your teams treat as one product.
+ *
+ * Two agents can see each other when they share a team and share a repo. A team's repo list
+ * is what lets "share a repo" mean `backend`, `app` and `firmware` rather than one clone —
+ * see docs/team-repos.md. This command is the half of that a person drives from a terminal:
+ *
+ *     popover repos                  what this repo is on, and what your teams have listed
+ *     popover repos add [team]       register this repo with a team you administer
+ *     popover repos rm  [team]       remove it
+ *
+ * ## Why there is no repo argument
+ *
+ * Because a name is not a claim. The list stores a possession-derived key, and the server
+ * resolves that key from the caller's *own published sessions*; naming a repository you have
+ * never held produces nothing at all (§2). So possession comes from the working directory,
+ * and the only thing this command sends is a remote it found there.
+ *
+ * ## Why this never touches Postgres
+ *
+ * Every other read the CLI does could in principle go straight to Supabase under the daemon's
+ * token, governed by RLS. Registration cannot: it has to be accompanied by a GitHub ownership
+ * check that needs the admin's OAuth token, which Clerk holds and only the web app can reach.
+ * `register_team_repo` is service-role only and refuses an `authenticated` caller outright, so
+ * there is deliberately no path from here to the table. Hence the three HTTP routes below, and
+ * hence the fact that the failures worth explaining at length are all *its* failures.
+ *
+ * ## Removal is here, but not in the plugin command
+ *
+ * Removing a repo cuts other people's agents out of scope at the next gate evaluation. It is
+ * one line to type and there is no undo but re-adding, so it stays a thing a human typed.
+ * `/popover:repos` reports and adds, and says why it will not remove.
+ */
+/**
+ * A team the caller belongs to.
+ *
+ * `admins` is optional and the CLI treats it as a nicety rather than a guarantee. It is what
+ * turns "you are not an admin" into "ask Ana or Priya", which is the difference between a
+ * refusal somebody can act on and one that just stops them — but a backend that does not send
+ * it must not break the command, so every use of it degrades to naming the team alone.
+ */
+export interface TeamView {
+    id: string;
+    name: string;
+    isAdmin: boolean;
+    admins?: string[];
+}
+/**
+ * A repo the caller has sessions in, and the teams that list it.
+ *
+ * `lastSeen` is null for a repo the caller does not hold — an entry that is on a team's list
+ * but has never been worked in from this account. Rendered as such rather than hidden, because
+ * "Quolabs lists four repos and you have two of them" is the fact somebody is looking for.
+ */
+export interface RepoView {
+    remote: string;
+    lastSeen: string | null;
+    teams: string[];
+}
+export interface ReposView {
+    teams: TeamView[];
+    repos: RepoView[];
+}
+/**
+ * Why the server refused to register a repo.
+ *
+ * Six values, and each one gets its own sentence in `refusal()` below. Collapsing any two of
+ * them into "could not add that repo" would be the whole difference between a person fixing
+ * this in thirty seconds and giving up: they are respectively a permissions problem in
+ * popover, a missing GitHub link, a missing GitHub *scope*, a permissions problem on GitHub,
+ * a repository host we cannot check at all, and an organization that has not approved us.
+ *
+ * An unknown seventh value from a newer backend is relayed verbatim rather than mapped to the
+ * nearest of these, because a wrong explanation is worse than an unexplained refusal.
+ */
+export type AddRefusal = "not_admin" | "github_not_linked" | "github_scope_missing" | "not_repo_admin" | "not_github" | "github_org_restricted";
+export declare function reposCommand(argv: string[]): Promise<number>;
+export interface AddPlan {
+    /** What to POST, and under which remote. */
+    add: Array<{
+        repo: LocalRepo;
+        remote: string;
+    }>;
+    /** Already on this team's list. Not an error; the command says so and exits 0. */
+    already: LocalRepo[];
+    /** Held here, but with no key on the server, so there is nothing to register. */
+    unpublished: LocalRepo[];
+}
+/**
+ * Sort the repos in front of us into the three things that can be true of them.
+ *
+ * The subtle part is *which remote* gets registered for a clone that has several. A fork has
+ * `origin = alice/backend` and `upstream = acme/backend` and publishes a key for each, so the
+ * remote to register is the first one the server confirms a key for — not blindly the primary,
+ * which would produce a refusal ("no key for alice/backend") that is true, unhelpful, and
+ * avoidable with information we already hold.
+ *
+ * When the server confirms none of them the repo is `unpublished`, which is checked here
+ * rather than discovered from a 4xx, because only this side knows whether the cause is a
+ * shallow clone.
+ */
+export declare function planAdd(here: LocalRepo[], team: TeamView, view: ReposView): AddPlan;
+/**
+ * Which teams a typed argument could mean.
+ *
+ * Matched by id, then by exact name, then by prefix — the same widening a person expects from
+ * `popover rename B1`. Case-insensitive, because a team called "Quolabs" is typed `quolabs`.
+ * Returns every match rather than picking one: two teams whose names share a prefix is a real
+ * arrangement, and silently registering a repo with the wrong one is not recoverable by the
+ * person who did it.
+ */
+export declare function resolveTeam(teams: TeamView[], typed: string): TeamView[];
+export interface RefusalContext {
+    team?: TeamView;
+    remote?: string;
+    verb?: "add" | "remove";
+}
+export interface RefusalText {
+    headline: string;
+    hints: string[];
+}
+/**
+ * One actionable sentence per reason, plus what to do about it.
+ *
+ * Written out longhand rather than generated, because the differences between them are the
+ * whole point and a template would flatten exactly the two that are easiest to confuse:
+ * `github_not_linked` and `github_scope_missing`. Most people who sign up for popover sign up
+ * *with GitHub*, which links an account with Clerk's default scopes and no `repo` — so the
+ * second is the common case, and telling that person "you have no GitHub account" sends them
+ * to link a second one and get the same refusal again.
+ */
+export declare function refusal(reason: AddRefusal, ctx?: RefusalContext): RefusalText;
+/**
+ * Turn an API failure into text, mapping an unknown reason to something honest.
+ *
+ * Exported for the tests rather than for other callers: the three branches below all exist to
+ * stop a non-refusal being rendered as a refusal, and each of them is one careless edit away
+ * from telling somebody to go and change permissions they have.
+ */
+export declare function refusalFor(result: ApiFailure, remote: string, team: TeamView, verb?: "add" | "remove", repo?: LocalRepo): RefusalText;
+export interface ApiFailure {
+    ok: false;
+    status: number;
+    /** The `reason` from a 403 body, when there was one. */
+    reason?: string;
+    /** The `error` code from any of our own error bodies. */
+    error?: string;
+    /**
+     * A sentence the server wrote, when it sent one.
+     *
+     * Relayed rather than rewritten for the failures this file cannot phrase better than the
+     * route can — a GitHub outage carries its own detail, and a newer backend may know about
+     * something this build does not. Never used for the six `reason` refusals, whose wording is
+     * the point and lives in `refusal()`.
+     */
+    message?: string;
+    /**
+     * Something answered with a success status and a body that is not what this route returns.
+     *
+     * Its own flag rather than a status, because the status is 200 and reporting "failed (200)"
+     * is a sentence nobody can act on. In practice this is an auth wall that redirects rather
+     * than refusing: `https://popover.to/api/teams/repos` 307s to a sign-in page, `fetch`
+     * follows it, and the HTML that comes back is a perfectly successful response to a request
+     * we did not make. Left unchecked it surfaced as a TypeError about `.map`.
+     */
+    malformed?: true;
+    /**
+     * Whether our API refused this, or something in front of it did.
+     *
+     * The same test `popover fork` makes, for the same reason: a 401 from the route means the
+     * device token is no longer good and the fix is `popover login`, while a 401 from an auth
+     * wall between here and the app — a protected preview deployment, an SSO proxy, a captive
+     * portal — means nothing of the sort, and sending someone to re-authenticate popover over it
+     * wastes their time on the wrong problem. Our routes always answer with a JSON `error`
+     * string; a wall answers with something else.
+     */
+    ours: boolean;
+}
+//# sourceMappingURL=repos.d.ts.map

package/dist/repos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repos.d.ts","sourceRoot":"","sources":["../src/repos.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,SAAS,EAGf,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,mBAAmB,GACnB,sBAAsB,GACtB,gBAAgB,GAChB,YAAY,GACZ,uBAAuB,CAAC;AAe5B,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8ClE;AA2UD,MAAM,WAAW,OAAO;IACtB,4CAA4C;IAC5C,GAAG,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,kFAAkF;IAClF,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,iFAAiF;IACjF,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAqBnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAWxE;AAUD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,GAAE,cAAmB,GAAG,WAAW,CA8EjF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,EACd,IAAI,GAAE,KAAK,GAAG,QAAgB,EAC9B,IAAI,CAAC,EAAE,SAAS,GACf,WAAW,CAmEb;AAQD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB;;;;;;;;;OASG;IACH,IAAI,EAAE,OAAO,CAAC;CACf"}