@lanes-sh/link 0.3.0 → 0.3.2

package/src/profile/schema.ts

@@ -366,7 +366,7 @@ export const configSchema = z.object({
        *
        * A deployment only, and this cannot widen that: a loopback endpoint
        * refuses every cross-origin request and must keep doing so. Why the
-       * default is a wildcard is `src/server/cors.ts` and ADR-040.
+       * default is a wildcard is `src/server/cors.ts` and ADR-039.
        */
       allowed_origins: z.array(browserOrigin).optional(),
     })
@@ -406,10 +406,45 @@ export type AuthorizationConfig = z.infer<typeof authorizationSchema>;
 export { authorizationSchema, identitySchema };
 export type { IdentityEntry } from './identity.ts';
 
+/**
+ * Where a deployment lives — an index, not configuration.
+ *
+ * **Nothing resolves from this.** A target is still declared by the profile,
+ * and a command still acts on what the profile says. This exists because the
+ * profile file was the *only* record that a deployment existed, so rewriting
+ * one erased the sole pointer to a live service, a bucket holding every byte
+ * the endpoint remembered, and a credential store — none of which had gone
+ * anywhere. There was no command that could find them again.
+ *
+ * It lives in `lanes-link.yaml`, outside any profile, for exactly that reason:
+ * a record kept inside the thing it describes cannot survive the thing being
+ * lost. `lanes link sync targets` reads it, and reads it *only* to know where
+ * to look (ADR-044).
+ *
+ * Written by `deploy`, after an upload has succeeded — so it never names a
+ * workspace nothing was ever put in.
+ */
+export const deploymentRecordSchema = z.object({
+  target: identifier,
+  /** Where the deployed endpoint reads its config: `gs://bucket[/prefix]`. */
+  workspace: z.string().min(1),
+  /**
+   * Whose bearer token opens this endpoint (ADR-009).
+   *
+   * Recorded rather than inferred. One endpoint serves every profile in the
+   * bucket under one token, and which profile's token that is decides who gets
+   * in — the one question about a deployment that must not be guessed at.
+   */
+  primary: identifier.optional(),
+  last_deploy: z.string().optional(),
+});
+
 /** The workspace file: `lanes-link.yaml`, alongside a `profiles/` directory. */
 export const workspaceSchema = z.object({
   contract: z.number().int().positive(),
   default_profile: identifier.optional(),
+  deployments: z.array(deploymentRecordSchema).default([]),
 });
 
 export type WorkspaceConfig = z.infer<typeof workspaceSchema>;
+export type DeploymentRecord = z.infer<typeof deploymentRecordSchema>;

package/src/profile/targets.ts

@@ -110,3 +110,56 @@ export function undeclaredTarget(target: string, config: Config, profile?: strin
 
   return new ConfigError(`Target "${target}" is not declared by ${whose} (have: ${have})`);
 }
+
+/**
+ * The refusal for a target-scoped command that named no target.
+ *
+ * The twin of `noTargetNamed`, for the commands whose subject is the target
+ * rather than one profile's view of it (ADR-043). It lists the target names the
+ * *workspace* declares and who declares each, because the question those
+ * commands are asking is "which endpoint", and a target only one profile knows
+ * about is the answer to a different question than one they all share.
+ *
+ * Naming the profiles is not decoration. A target declared by one profile and
+ * not its sibling is precisely the state that reads as a deployment having
+ * disappeared, and it is invisible from inside either profile alone.
+ */
+export function noTargetInWorkspace(
+  declared: ReadonlyMap<string, readonly string[]>,
+  workspaceRoot: string,
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): ConfigError {
+  if (declared.size === 0) {
+    return new ConfigError(
+      `--target is required, and no profile in ${workspaceRoot} declares one.\n` +
+        '  Create a profile with: lanes link profile add <name> --target local',
+    );
+  }
+
+  const total = new Set(
+    [...declared.values()].flatMap((profiles) => profiles as readonly string[]),
+  ).size;
+
+  const rows = [...declared.entries()]
+    .map(([name, profiles]) => {
+      // "every profile" rather than the list once it is all of them: the list is
+      // there to show a gap, and a complete one shows none.
+      const whose = profiles.length === total ? 'every profile' : profiles.join(', ');
+      return `    ${name}    ${whose}`;
+    })
+    .join('\n');
+
+  const first = [...declared.keys()][0]!;
+  const stale = env[LEGACY_TARGET_ENV];
+
+  return new ConfigError(
+    '--target is required. This command acts on a target, and every profile\n' +
+      'that declares it.\n\n' +
+      `  Targets in ${workspaceRoot}\n${rows}\n` +
+      `\n  e.g. lanes link status --target ${first}` +
+      (stale
+        ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
+          '  Unset it, or pass --target.'
+        : ''),
+  );
+}

package/src/profile/workspace.ts

@@ -247,3 +247,76 @@ export function workspacePath(workspaceRoot: string, path: string): string {
   }
   return isAbsolute(path) ? path : resolve(workspaceRoot, path);
 }
+
+/**
+ * One profile, loaded, for the commands whose subject is the whole workspace.
+ *
+ * `profilePath` rather than a bare name because a caller reporting on several
+ * profiles at once has nowhere to recompute it from without knowing whether the
+ * root is a bucket.
+ */
+export interface LoadedProfile {
+  readonly profile: string;
+  readonly profilePath: string;
+  readonly config: Config;
+}
+
+/**
+ * Every profile in the workspace, and the ones that would not open.
+ *
+ * **Skipping rather than failing** is the same rule `openReconciled` follows for
+ * a deployed endpoint: a workspace holding one broken profile still has a true
+ * answer to give about the others, and a listing that dies on the first bad file
+ * is one that stops working exactly when it is needed. What it must not do is
+ * skip *silently* — `unreadable` is the half a caller has to print, and the
+ * reason it carries the message rather than the error is that a caller rendering
+ * a table has no use for a stack.
+ */
+export interface WorkspaceProfiles {
+  readonly workspaceRoot: string;
+  readonly loaded: readonly LoadedProfile[];
+  readonly unreadable: readonly { readonly profile: string; readonly reason: string }[];
+}
+
+export async function loadWorkspaceProfiles(workspaceRoot: string): Promise<WorkspaceProfiles> {
+  const loaded: LoadedProfile[] = [];
+  const unreadable: { profile: string; reason: string }[] = [];
+
+  for (const profile of await listProfiles(workspaceRoot)) {
+    try {
+      const { config } = await loadProfileConfig(workspaceRoot, profile);
+      loaded.push({ profile, profilePath: profilePath(workspaceRoot, profile), config });
+    } catch (error) {
+      // First line only: a `ConfigError` from the loader carries every schema
+      // issue on its own line, and a row in a table has room for none of them.
+      const message = error instanceof Error ? error.message : String(error);
+      unreadable.push({ profile, reason: message.split('\n')[0] ?? 'could not be read' });
+    }
+  }
+
+  return { workspaceRoot, loaded, unreadable };
+}
+
+/**
+ * Which profiles declare each target name, across the whole workspace.
+ *
+ * A target is declared per profile and the endpoint serves every profile in the
+ * workspace (ADR-009), so "who has `cloud`" is a question with a list for an
+ * answer rather than a yes or no. The disagreement — one profile declaring it
+ * and its sibling not — is the state that reads as a target having vanished.
+ */
+export function targetsByName(
+  workspace: WorkspaceProfiles,
+): ReadonlyMap<string, readonly string[]> {
+  const byName = new Map<string, string[]>();
+
+  for (const { profile, config } of workspace.loaded) {
+    for (const target of Object.keys(config.targets)) {
+      const profiles = byName.get(target);
+      if (profiles) profiles.push(profile);
+      else byName.set(target, [profile]);
+    }
+  }
+
+  return byName;
+}

package/src/providers/google/shared/setup.ts

@@ -40,6 +40,21 @@ export const googleSetup = (
     summary: `${product} signs in with Google. By default it authorises against the OAuth client Lanes operates, so there is nothing to register and no client secret on this machine — the code is exchanged for a token by the Lanes API, which holds that secret. Pass --own-client to register a client of your own instead; the steps below are that path, asked once per profile and then covering every Google account you connect.`,
     docs: 'docs/detailed/setup/google.md',
     docs_url: 'https://console.cloud.google.com/auth',
+    // AUDIENCE leads with Internal, and the ordering is the point rather than a
+    // preference. The seven-day `invalid_grant` everyone hits is a property of
+    // publishing status, and an Internal app has no publishing status to have —
+    // so it also has no expiry, no verification question, no unverified-app
+    // warning, no test-user list, and no scope registration. Steering a
+    // Workspace user to External costs them every one of those, to buy reach
+    // they do not want: Internal admits only their own domain, which is the
+    // whole set of accounts they were going to connect.
+    //
+    // What it cannot be is the only path. "Internal" is Google's word for
+    // "inside my Workspace organisation", not "private to me", and the option
+    // is simply absent on a project with no organisation behind it. So a
+    // personal @gmail.com still needs External and still has to publish, and
+    // the steps say which half applies to whom rather than making everyone read
+    // both.
     steps: [
       ...(options.preview
         ? [
@@ -56,13 +71,13 @@ export const googleSetup = (
       }\n       Without gcloud: APIs & Services → Library, and search for each by name.`,
       'The rest is under Google Auth Platform — https://console.cloud.google.com/auth — in this order:',
       '  BRANDING — app name and a support email. Seen by nobody but you.',
-      '  AUDIENCE — User type: EXTERNAL (even with a Workspace domain: "Internal" admits only that one domain, so a mix of personal and Workspace accounts needs External). Add every account you will connect under "Test users".',
-      '  AUDIENCE, again — PUBLISH the app. This is the setting that decides whether your connections survive the week, and it is not the same thing as verification: a client left in "Testing" has every refresh token it issues expired after exactly seven days, and one set to "In production" does not, review pending or not.',
-      `  DATA ACCESS — where scopes live now. Add:\n       ${scopes.join('\n       ')}\n       Note drive.file is filed under "sensitive" rather than "restricted", so it appears in a different section of that page.`,
+      '  AUDIENCE — User type, and this is the step that decides how much of the rest you do.\n       INTERNAL, if the project sits in a Google Workspace organisation and every account you will connect is on that domain. An Internal app has no publishing status at all — so no seven-day expiry, no verification, no test-user list, no unverified-app warning screen, and no scopes to register. Skip to CLIENTS.\n       EXTERNAL, for a personal @gmail.com, or a mix of personal and Workspace accounts. Internal is not offered without a Workspace organisation, and admits only your own domain. Add every account you will connect under "Test users", then do the two steps below.',
+      '  AUDIENCE, again — EXTERNAL ONLY: PUBLISH the app. This is the setting that decides whether your connections survive the week, and it is not the same thing as verification: a client left in "Testing" has every refresh token it issues expired after exactly seven days, and one set to "In production" does not, review pending or not. Internal apps have no publishing status, which is why they never expire.',
+      `  DATA ACCESS — EXTERNAL ONLY. Where scopes live now. Add:\n       ${scopes.join('\n       ')}\n       Note drive.file is filed under "sensitive" rather than "restricted", so it appears in a different section of that page. An Internal app does not need this: it authorises scopes that were never registered here, so the page can stay empty.`,
       '  CLIENTS — Create OAuth client → type: DESKTOP APP. Google\'s docs say "Web application" with a redirect URI for Claude or Antigravity, because they assume the agent host runs the OAuth. Here the CLI does, on a loopback port — which is also why this stays Desktop even when the server runs on Cloud Run.',
       'Copy the client ID and secret — you are asked for them next.',
-      'What publishing unverified costs, so it is a decision rather than a surprise: everyone you connect sees a "Google hasn\'t verified this app" screen and has to click through Advanced, and the project gains a cap of 100 new users granted these scopes. That cap is for the lifetime of the project and cannot be reset — which does not matter for a client only you use, and matters a great deal for one you intend to hand out.',
-      'Verification itself is the other path and a much longer one — restricted scopes mean a review with a security assessment measured in months. It is worth starting and not worth waiting on: publishing above removes the weekly re-authorisation today.',
+      'EXTERNAL ONLY — what publishing unverified costs, so it is a decision rather than a surprise: everyone you connect sees a "Google hasn\'t verified this app" screen and has to click through Advanced, and the project gains a cap of 100 new users granted these scopes. That cap is for the lifetime of the project and cannot be reset — which does not matter for a client only you use, and matters a great deal for one you intend to hand out. None of this applies to an Internal app.',
+      'EXTERNAL ONLY — verification itself is the other path and a much longer one: restricted scopes mean a review with a security assessment measured in months. It is worth starting and not worth waiting on, since publishing above removes the weekly re-authorisation today. If you have a Workspace domain, Internal skips this question entirely.',
       'If none of that suits — an organisation that forbids publishing, or a client that must stay in Testing — connect with a service account key instead. It does not expire at all: lanes link connect ' + product.toLowerCase().split(' ')[0] + ' --auth service_account',
     ],
     prompts: [

package/src/server/index.ts

@@ -371,7 +371,7 @@ export function serve(options: ServeOptions): RunningServer {
   // Cross-origin access, and its absence, are decided here for the same reason
   // `allowedHostnames` and `dashboard` are: they are all properties of what this
   // is bound to. The two are mutually exclusive and the exclusion is the
-  // decision — see `./cors.ts`, and ADR-040.
+  // decision — see `./cors.ts`, and ADR-039.
   const cors: CorsPolicy | undefined = loopback
     ? undefined
     : { allowedOrigins: primary.config.auth.allowed_origins ?? [ANY_ORIGIN] };