@mesh-tech/mesh-cli 0.20.2 → 0.20.4

package/dist/src/commands/registry.d.ts

@@ -1,306 +1,73 @@
-/**
- * mesh registry — Manage npm registry authentication for @mesh-tech packages.
- *
- * Handles CodeArtifact token refresh and project .npmrc setup so that
- * `pnpm install` can resolve @mesh-tech/* packages from the private registry.
- *
- * The registry is ONE global identity (`utils/registry-identity.ts`), so the
- * read path needs no platform context: `mesh registry login` resolves the
- * registry, signs in to its issuer if there is no cached session, asks the
- * Zitadel-gated `registry-auth` broker for a token, and writes `~/.npmrc` —
- * one command, one browser round-trip, no AWS anything on the machine.
- *
- * Credential resolution, in order:
- *   0. The registry-auth BROKER, authenticated with the registry session.
- *      This is the path a brand-new developer takes.
- *   1. Existing AWS credentials in environment (CI/CD) → use directly
- *   2. Zitadel JWT from `mesh login <context>` → AssumeRoleWithWebIdentity
- *   3. AWS SSO / current profile → use directly
- *
- * Paths 1–3 all shell out to the AWS CLI, so they require it to be installed
- * and credentialed. Path 0 requires only a Mesh account, which is the whole
- * point (design: registry-access-without-aws-sso).
- *
- * Usage:
- *   mesh registry login                 — broker first (signs in if needed), then the AWS paths
- *   mesh registry login --device        — same, device-code sign-in (headless / SSH)
- *   mesh registry login --ci            — CI mode: AWS chain only, skip .npmrc creation
- *   mesh registry login --no-broker     — skip the broker, force the AWS paths
- *   mesh registry login --profile p     — a deployer's AWS profile (skips the broker)
- *   mesh registry logout                — forget the registry session
- *   mesh registry status                — show current auth state
- */
 import { Command } from "commander";
 import { MeshCliError } from "../utils/errors.js";
 import type { RegistryTokenState } from "../utils/auth-preflight.js";
 import { type RegistryBrokerFailure, type RegistryGrant } from "../utils/registry-broker.js";
 import { readRegistrySession } from "../utils/registry-identity.js";
-/**
- * Run `aws codeartifact login` to set the auth token in ~/.npmrc.
- */
 export declare function codeartifactLogin(env?: Record<string, string>): boolean;
-/**
- * Resolve the publisher role ARN to assume for `--publish`.
- *
- * Precedence: explicit --role-arn flag wins, then the registry's SSM export
- * (publisherRoleArn, Task 2 of MESH-2168). Throws an actionable error if
- * neither is available — there's no safe default to fall back to since
- * publishing is an opt-in privileged path (DEFAULT_REGISTRY_ROLE stays null).
- */
 export declare function resolvePublisherRoleArn({ roleArnFlag, ssmArn, }: {
     roleArnFlag?: string;
     ssmArn?: string;
 }): string;
-/**
- * Resolve AWS credentials for registry access.
- *
- * Returns env var overrides (or empty object if current env is fine).
- */
 export declare function resolveCredentials(context?: string, roleArn?: string): Record<string, string>;
-/**
- * Write a broker-issued grant into ~/.npmrc: the scoped registry line and the
- * endpoint's auth token, in exactly the shape `aws codeartifact login
- * --namespace @mesh-tech` would have written.
- *
- * Byte-compatibility with the AWS CLI's output is the requirement, not a nicety:
- * `mesh registry status`, the `mesh start` preflight and the dev doctor all
- * parse ~/.npmrc for that pair, and a machine that gets its token from the
- * broker has to look identical to one that got it from AWS.
- */
 export declare function applyGrantToUserNpmrc(grant: RegistryGrant, npmrcPath?: string): {
     path: string;
 };
-/**
- * Human-facing explanation of a failed broker attempt, plus whether the AWS
- * fallback chain is worth running.
- *
- * `not-authorized` is the one case we do NOT fall through on: the caller has a
- * working Mesh account that simply lacks the grant, and quietly trying AWS next
- * would either succeed (masking a missing grant with an AWS account we're
- * trying to stop requiring) or fail with an unrelated AWS error that buries the
- * real answer. Its text ends by naming the re-run — the bare command, which
- * re-mints the session so a role granted after the sign-in reaches the broker;
- * a sign-out is the fallback for a session the issuer will not re-mint.
- *
- * @example
- * describeBrokerFailure({ kind: "unavailable", detail: "ECONNREFUSED" }).fatal; // → false
- */
 export declare function describeBrokerFailure(failure: RegistryBrokerFailure): {
     message: string;
     hint?: string;
     fatal: boolean;
 };
-/**
- * A valid Mesh account that lacks the registry role. Its own class so a
- * caller that runs the login in-process (the `mesh init` wizard) can tell
- * "ask for a grant" from every other failure structurally, not by parsing
- * the sentence.
- *
- * @example
- * try {
- *   await runRegistryLogin(undefined, {});
- * } catch (err) {
- *   if (err instanceof RegistryNotAuthorizedError) markStepFailedAndContinue(err);
- *   else throw err;
- * }
- */
 export declare class RegistryNotAuthorizedError extends MeshCliError {
     constructor(message: string);
 }
-/**
- * Whether this run may start a sign-in: always with `--device` (the device
- * code works anywhere the output can be read), otherwise only when there is
- * a terminal to print a code to or open a browser from. Which sign-in runs
- * is the login flow's choice — browser PKCE on a laptop, device code over
- * SSH or in a container. A run with no TTY and no `--device` never starts a
- * device-code poll nobody can complete — it falls to the AWS chain, which
- * is what a CI runner with ambient credentials expects.
- *
- * @example
- * registrySignInAllowed({}, false);             // → false (CI runner, no --device)
- * registrySignInAllowed({ device: true }, false); // → true
- * registrySignInAllowed({}, true);              // → true (a laptop, or an SSH session with a TTY)
- */
 export declare function registrySignInAllowed(opts: Pick<RegistryLoginOptions, "device">, hasTty?: boolean): boolean;
-/**
- * Whether a broker refusal is worth one re-mint of the session before it is
- * reported.
- *
- * `not-authorized` and only `not-authorized`. It is the single refusal a token
- * minted a moment later can answer differently, because Zitadel writes project
- * roles into a token when it issues it and a grant that lands afterwards is
- * absent from every token already held. Every other failure is about the
- * broker or the session itself, which a re-mint does not change — and paying
- * for one there only delays the AWS fallback those failures are meant to reach.
- *
- * Exported so the policy is asserted by a test rather than promised by the one
- * call site that holds it.
- *
- * @example
- * shouldRemintAfter({ kind: "unavailable", detail: "ETIMEDOUT" }); // → false
- */
 export declare function shouldRemintAfter(failure: RegistryBrokerFailure): boolean;
-/** The closing line of the not-authorized text: what to run once the role is granted. */
 export declare const NOT_AUTHORIZED_RERUN = "Once granted, run: mesh registry login   (it re-mints your sign-in; still refused? mesh registry logout && mesh registry login)";
-/** Printed when the read path is given a context it no longer needs. */
 export declare const CONTEXT_IGNORED_NOTICE = "The registry is global \u2014 the context argument is no longer needed (ignored).";
-/**
- * Why the broker did not produce a grant — the fact the final AWS-chain error
- * message is built from, so it can only ever cite something that was actually
- * printed.
- */
-export type BrokerOutcome = 
-/** `--profile` — an explicit AWS-identity instruction; the broker was never tried. */
-{
+export type BrokerOutcome = {
     kind: "skipped-profile";
     profile: string;
-}
-/** `--no-broker`, `--ci` or `--publish` — the AWS chain was asked for by name. */
- | {
+} | {
     kind: "skipped-flag";
     flag: string;
-}
-/** The broker was tried and could not answer (discovery failed, 5xx, timeout). */
- | {
+} | {
     kind: "unavailable";
     detail: string;
-}
-/** No registry session and no way to sign in on this run (headless, no `--device`). */
- | {
+} | {
     kind: "no-session";
     detail: string;
 };
-/**
- * Whether this `mesh registry login` invocation may rewrite ~/.npmrc.
- *
- * The self-heal is a **laptop** fix. CI pipelines run the unscoped
- * `aws codeartifact login` DELIBERATELY — a host-scoped token is what lets
- * pnpm pull upstream-cached public packages through CodeArtifact — so in a
- * runner the "hijack" line is load-bearing and deleting it would break the
- * install we were asked not to touch. `--ci` is the one signal that says so.
- *
- * Extracted (and tested) rather than left inline because "this changes no CI
- * behaviour" is a promise about the code, not about the workflow files we
- * happen not to have edited.
- */
 export declare function shouldRepairUserNpmrc(opts: Pick<RegistryLoginOptions, "ci">): boolean;
-/**
- * Repair a hijacked ~/.npmrc: remove an unscoped `registry=<codeartifact>`
- * line if one is present, after taking a timestamped backup.
- *
- * `aws codeartifact login` run WITHOUT `--namespace @mesh-tech` writes that
- * line, and nothing in this CLI used to remove it — so one bare login made
- * CodeArtifact the default registry forever, and every public `npm install`
- * started failing with E401 12 hours later when the token expired. We write
- * the correct (scoped) state; this is the missing repair of the wrong state.
- *
- * Never throws — a repair failure must not fail an otherwise-good login.
- */
 export declare function repairUnscopedRegistry(npmrcPath?: string): {
     removed: string | null;
     backupPath?: string;
     error?: string;
 };
-/**
- * Check that ~/.npmrc is in a working state for @mesh-tech installs: a
- * CodeArtifact token that the registry actually accepts, and no unscoped
- * `registry=` hijacking public npm.
- *
- * A substring match on the file (the old check) reported "valid" for an
- * expired token AND for a hijacked default registry — precisely the state
- * `mesh registry status` exists to catch.
- */
 export interface RegistryTokenCheck {
-    /** Token accepted by the registry AND no unscoped `registry=` hijack. */
     valid: boolean;
-    /** The probe's verdict, so callers can tell "broken" from "unverifiable". */
     state: RegistryTokenState;
     endpoint?: string;
     reason?: string;
     hijackLine?: string;
 }
-/**
- * The `Registry session:` line of `mesh registry status`. Pure; exported for
- * the message test.
- *
- * @example
- * renderRegistrySessionLine(null); // → "No registry session — run: mesh registry login"
- */
 export declare function renderRegistrySessionLine(session: {
     email: string;
     expiresAt: string;
 } | null, now?: number): string;
 export declare function checkExistingToken(): Promise<RegistryTokenCheck>;
-/**
- * `mesh registry status` — returns the process exit code instead of calling
- * `process.exit`, so the "broken" vs "unverifiable" distinction is testable.
- *
- * Exit 1 is for faults the user can act on right now: a missing or expired
- * token, or an unscoped CodeArtifact `registry=` line (locally detectable, and
- * broken regardless of the network). An **unreachable** registry is neither —
- * it warns and exits 0, because the remediation we'd print (`mesh registry
- * login`) cannot work offline either, and the same rule already governs the
- * `mesh init` doctor.
- */
 export declare function runRegistryStatus(opts?: {
-    /** Test seam — defaults to the real ~/.npmrc + live registry probe. */
     check?: () => Promise<RegistryTokenCheck>;
-    /** Test seam — defaults to the cached registry session. */
     session?: ReturnType<typeof readRegistrySession>;
 }): Promise<number>;
 export interface RegistryLoginOptions {
     role?: string;
     ci?: boolean;
     skipNpmrc?: boolean;
-    /** AWS SSO profile (e.g. mesh-dev) — auto-runs `aws sso login` when stale */
     profile?: string;
-    /** Assume the registry's publisher role (from --role or the registry's SSM export) */
     publish?: boolean;
-    /**
-     * Try the Zitadel-gated registry broker before the AWS paths. Default true.
-     * `--no-broker` forces the AWS chain (commander sets this to false).
-     */
     broker?: boolean;
-    /** Sign in with the device-code flow instead of the browser callback (headless / SSH). */
     device?: boolean;
 }
-/**
- * The full registry-auth sequence (CodeArtifact token → ~/.npmrc → project
- * .npmrc). `context` matters only to `--publish` (the publisher role comes
- * from that context's SSM export) and to the explicit AWS chain
- * (`--no-broker` / `--ci`, where a cached platform session can assume a
- * role); on the default read path it is ignored, because the registry is
- * global.
- *
- * Fails by throwing `MeshCliError` rather than exiting, so a caller that runs
- * this in-process (the `mesh init` wizard, the app-tenant doctor's `--fix`)
- * can report the outcome and carry on.
- *
- * @example
- * await runRegistryLogin(undefined, {});          // a laptop: broker, browser if needed
- * await runRegistryLogin(undefined, { ci: true }); // a runner: ambient AWS creds only
- */
 export declare function runRegistryLogin(context: string | undefined, opts: RegistryLoginOptions): Promise<void>;
-/**
- * The error for a failed `aws codeartifact login`, built from WHY the AWS
- * chain was the path taken — so the text can only ever describe something
- * that actually happened on this run.
- *
- * Three shapes:
- *
- * - `--profile`: the profile's AWS identity cannot read the registry. That
- *   flag is for deployers whose account is allowed to; anyone else should drop
- *   it and take the broker path, which needs no AWS at all.
- * - broker unavailable / no session: the broker was tried and printed a
- *   warning; this names that warning and the two ways forward.
- * - an explicit AWS flag (`--no-broker`, `--ci`, `--publish`): the caller asked
- *   for the AWS chain, so the fix is the AWS credentials, not the broker.
- *
- * Pure; exported for the message tests.
- *
- * @example
- * describeAwsChainFailure({ kind: "skipped-profile", profile: "ctdev" }); // "AWS profile 'ctdev' cannot read…"
- */
 export declare function describeAwsChainFailure(outcome: BrokerOutcome): string;
 export declare function registerRegistryCommands(program: Command): void;
-//# sourceMappingURL=registry.d.ts.map