@lanes-sh/link 0.2.2 → 0.3.0

package/src/connectivity/manifest/requirements.ts

@@ -55,6 +55,15 @@ export interface SetupNeeds {
    * `connect` will never ask for.
    */
   readonly brokered: boolean;
+  /**
+   * What `--auth pasted_token` would ask for, where the provider offers it.
+   *
+   * Separate from `requirements` because it is an alternative rather than a
+   * prerequisite: nothing needs it unless the browser route is closed to you.
+   * Reported only when it is *not* the chosen route, since when it is chosen it
+   * is a requirement above and naming it twice would read as two values.
+   */
+  readonly pastedCredential: string | undefined;
 }
 
 /**
@@ -64,8 +73,23 @@ export interface SetupNeeds {
  * command someone is told to paste and a command the CLI suggests should not be
  * two different sentences.
  */
-function storeCommand(ref: string, placeholder: string, profile: string): string {
-  return `printf %s "${placeholder}" | lanes link secrets set ${ref} --profile ${profile}`;
+function storeCommand(ref: string, placeholder: string, where: Selection): string {
+  return (
+    `printf %s "${placeholder}" | lanes link secrets set ${ref}` +
+    ` --profile ${where.profile} --target ${where.target}`
+  );
+}
+
+/**
+ * Which store a suggested command should write into.
+ *
+ * One object rather than two positional strings, because the pair travels
+ * together everywhere and a caller that transposed them would produce a command
+ * that runs, writes a credential, and puts it somewhere nobody looks.
+ */
+export interface Selection {
+  readonly profile: string;
+  readonly target: string;
 }
 
 /** How the value is spelled, for a ref that several prompts combine into. */
@@ -80,15 +104,79 @@ function placeholderFor(prompts: readonly SetupPrompt[]): string {
   return '<value>';
 }
 
+/**
+ * What the key route needs, which is the key and nothing else.
+ *
+ * Never `needsId`, and that is the substantive difference from the block below:
+ * the key is shared across every connection of a vendor, so its ref does not
+ * derive from a connection id and nothing has to be named before it can be
+ * stored. The subject does derive per connection — but it is not a requirement
+ * because it cannot be placed ahead of time: it lives inside the pointer that
+ * `connect` itself writes, and there is no `secrets set` that would put it
+ * there.
+ */
+function assertionRequirements(
+  assertion: NonNullable<Extract<ProviderManifest['auth'], { kind: 'oauth' }>['assertion']>,
+  where: Selection,
+): SetupNeeds {
+  const shared = assertion.setup.prompts.filter((prompt) => prompt.scope === 'shared');
+
+  return {
+    requirements: shared.map((prompt) => ({
+      ref: assertion.key_ref,
+      label: prompt.label,
+      secret: prompt.secret,
+      scope: 'shared' as const,
+      prompts: [prompt.key],
+      command: storeCommand(assertion.key_ref, '<value>', where),
+    })),
+    needsId: false,
+    brokered: false,
+    pastedCredential: undefined,
+  };
+}
+
+/**
+ * Whether the manifest describes an OAuth client of the operator's own.
+ *
+ * `defineProvider` permits a broker, or a shipped client id, with no client
+ * prompts — a provider with no bring-your-own path is a legal thing to be. Every
+ * surface that offers that path has to ask this first, or it offers a route with
+ * nothing behind it: the chooser, the client resolver, and the setup plan.
+ *
+ * Here rather than in any of the three because it was already written twice in
+ * two different components under two different names, and this change would
+ * have made it three.
+ */
+export function hasOwnClientPath(manifest: ProviderManifest): boolean {
+  return (manifest.setup?.prompts ?? []).some((prompt) => prompt.scope === 'shared');
+}
+
 export function setupRequirements(
   manifest: ProviderManifest,
   connectionId: string | undefined,
-  profile: string,
+  where: Selection,
   options: {
     /** `oauth_apps` entries this profile declares — the clients that are its own. */
     readonly ownClients?: readonly string[];
+    /**
+     * Which way in, for a provider offering two.
+     *
+     * Defaults to the browser flow, which is every provider's only route until
+     * one declares `auth.assertion` — so an omitted value reports exactly what
+     * it always reported. Passed by `connect` once the operator has chosen,
+     * because the two methods need different things and reporting the union
+     * would tell someone to store a client they are not going to use.
+     */
+    readonly method?: 'oauth' | 'assertion' | 'pasted';
   } = {},
 ): SetupNeeds {
+  const assertion = manifest.auth.kind === 'oauth' ? manifest.auth.assertion : undefined;
+
+  if (options.method === 'assertion' && assertion) {
+    return assertionRequirements(assertion, where);
+  }
+
   const prompts = manifest.setup?.prompts ?? [];
 
   // A shared prompt exists to collect a client the operator registers. When a
@@ -101,7 +189,20 @@ export function setupRequirements(
     !(manifest.auth.app !== undefined && (options.ownClients ?? []).includes(manifest.auth.app));
 
   const shared = brokered ? [] : prompts.filter((prompt) => prompt.scope === 'shared');
-  const perConnection = prompts.filter((prompt) => prompt.scope === 'connection');
+
+  // An OAuth provider's per-connection prompt belongs to one route, not to the
+  // provider — it is what `--auth pasted_token` asks for, and nothing the
+  // browser route ever needs. Reporting it either way would put a
+  // mandatory-looking field in front of somebody whose whole path is a browser
+  // round trip, which is the same mistake `brokered` avoids one line above.
+  //
+  // No OAuth manifest had one of these until Slack kept its pasted token as the
+  // way past a workspace that has not approved the Lanes app.
+  const connectionPrompts = prompts.filter((prompt) => prompt.scope === 'connection');
+  const routed = manifest.auth.kind !== 'oauth' || options.method === 'pasted';
+
+  const pasted = routed ? [] : connectionPrompts;
+  const perConnection = routed ? connectionPrompts : [];
 
   const requirements: SetupRequirement[] = [];
 
@@ -115,7 +216,7 @@ export function setupRequirements(
       secret: prompt.secret,
       scope: 'shared',
       prompts: [prompt.key],
-      command: storeCommand(prompt.credential_ref, '<value>', profile),
+      command: storeCommand(prompt.credential_ref, '<value>', where),
     });
   }
 
@@ -133,7 +234,7 @@ export function setupRequirements(
         secret: perConnection.some((prompt) => prompt.secret),
         scope: 'connection',
         prompts: perConnection.map((prompt) => prompt.key),
-        command: storeCommand(ref, placeholderFor(perConnection), profile),
+        command: storeCommand(ref, placeholderFor(perConnection), where),
       });
     }
   }
@@ -142,5 +243,7 @@ export function setupRequirements(
     requirements,
     needsId: perConnection.length > 0 && connectionId === undefined,
     brokered,
+    pastedCredential:
+      pasted.length > 0 ? pasted.map((prompt) => prompt.label).join(', then ') : undefined,
   };
 }

package/src/deployments/adapters/filesystem.ts

@@ -166,7 +166,16 @@ const BY_EXTENSION: Record<string, string> = {
   '.yml': 'application/yaml',
 };
 
-function inferContentType(path: string): string | undefined {
+/**
+ * Exported so `github.ts` answers identically.
+ *
+ * That adapter has nowhere to *store* a content type — a sidecar there would be
+ * a file in the owner's own repository, listed beside their entries — so the
+ * extension is all it has. Sharing the map means a `.md` written locally and
+ * the same `.md` in a repository do not report different types, which is what
+ * `#stores/blobs/conformance.ts` exists to hold.
+ */
+export function inferContentType(path: string): string | undefined {
   const dot = path.lastIndexOf('.');
   return dot === -1 ? undefined : BY_EXTENSION[path.slice(dot).toLowerCase()];
 }

package/src/deployments/adapters/github-api.ts

@@ -0,0 +1,106 @@
+/**
+ * The wire, for the two files above it.
+ *
+ * `github-repo.ts` holds the state — which commit the branch is on, what is in
+ * its tree, which blobs have been read — and `github-commit.ts` holds the one
+ * operation that assembles several files into a single commit. What is left
+ * here is everything neither of them should have to know twice: the host, the
+ * headers, base64, path encoding, and what a failure means.
+ *
+ * `fetch` and no client library, the same argument `gcs.ts` and
+ * `gcp-secret-manager.ts` make: a repository holding live refresh tokens does
+ * not take on a transitive dependency tree to save some URL building.
+ */
+
+/**
+ * Declared here rather than imported, for the reason `gcs.ts` gives: this
+ * component may not import `#auth`, and `typeof globalThis.fetch` under Bun's
+ * types carries a `preconnect` a test double would have to stub.
+ */
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+export const API = 'https://api.github.com';
+
+/** Every request declares the version, as GitHub's own documentation does. */
+const VERSION = '2022-11-28';
+
+export function githubHeaders(token: string, init: RequestInit): Record<string, string> {
+  const headers: Record<string, string> = {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'x-github-api-version': VERSION,
+    ...((init.headers ?? {}) as Record<string, string>),
+  };
+  if (init.body !== undefined) headers['content-type'] = 'application/json';
+  return headers;
+}
+
+/** Percent-encode each segment, leaving the slashes that address a directory. */
+export function encodePath(path: string): string {
+  return path.split('/').map(encodeURIComponent).join('/');
+}
+
+export function base64(data: Uint8Array): string {
+  let binary = '';
+  for (const byte of data) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export class GithubApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'GithubApiError';
+  }
+}
+
+/**
+ * A failure that says what was being attempted and, where GitHub's own message
+ * does not, what to do about it.
+ *
+ * Three are worth naming because they are the three an operator actually hits:
+ * a token that has expired or was never granted this repository, the rate
+ * limit, and a repository whose name is right and whose visibility is not.
+ * GitHub answers the last two of those with a 404 by design — it does not
+ * confirm that a repository you cannot see exists — so the message has to offer
+ * the causes rather than assert one.
+ */
+export async function failure(what: string, response: Response): Promise<GithubApiError> {
+  const body = await response.text().catch(() => '');
+  const detail = body.slice(0, 300);
+
+  if (response.status === 401) {
+    return new GithubApiError(
+      `GitHub refused the token while trying to ${what} (401). It has expired, been revoked, or ` +
+        'was never valid. Generate another and run: lanes link knowledge use github --repo <owner/name>',
+      401,
+    );
+  }
+
+  if (response.status === 403 && response.headers.get('x-ratelimit-remaining') === '0') {
+    const reset = Number(response.headers.get('x-ratelimit-reset') ?? 0);
+    const when = reset > 0 ? new Date(reset * 1000).toISOString() : 'shortly';
+    return new GithubApiError(
+      `GitHub's rate limit is spent, so this could not ${what}. It resets at ${when}. ` +
+        "Keeping memory and skills in a repository makes that limit one of this endpoint's own — " +
+        'ADR-041 says so plainly, and it is the cost of the arrangement rather than a fault.',
+      403,
+    );
+  }
+
+  if (response.status === 403 || response.status === 404) {
+    return new GithubApiError(
+      `GitHub would not let this token ${what} (${response.status}). The usual causes are a token ` +
+        'that was not granted this repository, a fine-grained token still waiting on an ' +
+        `organisation owner's approval, or Contents permission set to read rather than write. ${detail}`,
+      response.status,
+    );
+  }
+
+  return new GithubApiError(
+    `GitHub failed to ${what} (${response.status}). ${detail}`,
+    response.status,
+  );
+}

package/src/deployments/adapters/github-commit.ts

@@ -0,0 +1,103 @@
+import { base64 } from './github-api.ts';
+import type { GithubRepository } from './github-repo.ts';
+
+/**
+ * Many files, and many deletions, as **one** commit.
+ *
+ * `writeFile` is one commit per file, which is right for a single write and
+ * wrong for a migration: two hundred commits each reading "store memory entry"
+ * is not a history anybody opens, and it is two hundred round trips against a
+ * limit this endpoint now shares. This goes through the Git Data API instead —
+ * blobs, a tree, a commit, then move the ref — which is what `git push` does
+ * and produces the same object graph.
+ *
+ * Its own file because it is the one operation that does not fit the
+ * one-request-one-answer shape of everything in `github-repo.ts`, and because
+ * it needs none of that file's private state: it works entirely through the
+ * repository's public surface, so the split costs nothing.
+ *
+ * **The empty repository is the ordinary case here, not an edge one.** Somebody
+ * following the setup steps creates a repository for this and migrates into it
+ * immediately, so there is no parent commit and no base tree, and the ref has
+ * to be created rather than moved.
+ */
+
+export interface CommitFile {
+  readonly path: string;
+  readonly data: Uint8Array;
+}
+
+/** The new commit sha, or null when there was nothing to commit. */
+export async function commitFiles(
+  repository: GithubRepository,
+  files: readonly CommitFile[],
+  deletes: readonly string[],
+  message: string,
+): Promise<string | null> {
+  if (files.length === 0 && deletes.length === 0) return null;
+
+  const branch = await repository.branch();
+  // Forced: a migration is the one place where reading a two-second-old head
+  // could mean committing against a parent that has already moved.
+  const head = await repository.head(true);
+
+  const blobs = await Promise.all(
+    files.map(async (file) => ({
+      path: file.path,
+      sha: (
+        await repository.json<{ sha: string }>(
+          `/repos/${repository.repo}/git/blobs`,
+          {
+            method: 'POST',
+            body: JSON.stringify({ content: base64(file.data), encoding: 'base64' }),
+          },
+          `upload "${file.path}" to ${repository.repo}`,
+        )
+      ).sha,
+    })),
+  );
+
+  const tree = await repository.json<{ sha: string }>(
+    `/repos/${repository.repo}/git/trees`,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        ...(head ? { base_tree: head.commit } : {}),
+        tree: [
+          ...blobs.map((blob) => ({ path: blob.path, mode: '100644', type: 'blob', sha: blob.sha })),
+          // A null sha is how the Git Data API spells "not in this tree".
+          ...deletes.map((path) => ({ path, mode: '100644', type: 'blob', sha: null })),
+        ],
+      }),
+    },
+    `build a tree for ${repository.repo}`,
+  );
+
+  const commit = await repository.json<{ sha: string }>(
+    `/repos/${repository.repo}/git/commits`,
+    {
+      method: 'POST',
+      body: JSON.stringify({ message, tree: tree.sha, parents: head ? [head.commit] : [] }),
+    },
+    `commit to ${repository.repo}`,
+  );
+
+  // Create when the branch has no commits, move when it does. A `PATCH` on a
+  // ref that does not exist answers 422, which reads as a permissions problem
+  // and is not one.
+  await repository.json(
+    head
+      ? `/repos/${repository.repo}/git/refs/heads/${encodeURIComponent(branch)}`
+      : `/repos/${repository.repo}/git/refs`,
+    {
+      method: head ? 'PATCH' : 'POST',
+      body: JSON.stringify(
+        head ? { sha: commit.sha } : { ref: `refs/heads/${branch}`, sha: commit.sha },
+      ),
+    },
+    `move "${branch}" in ${repository.repo}`,
+  );
+
+  repository.invalidate();
+  return commit.sha;
+}