@geekmidas/cli 10.0.0-alpha.6 → 10.0.0-alpha.61

package/dist/deploy/public.d.cts

@@ -0,0 +1,459 @@
+import { B as StateVersionConflict, z as StateLocked } from "../types-efNLu9xu.cjs";
+import { ConstructManifest } from "@geekmidas/manifest";
+//#region src/deploy/identity.d.ts
+/**
+ * Who a deploy is, on a target it shares with other workspaces.
+ *
+ * A Dokploy server is one flat namespace of projects, images and Docker
+ * service names. Deploys used to identify everything they made by the
+ * workspace name alone, so two workspaces called `shop` — or `Shop` and
+ * `shop` — deploying to one server landed in the same project, pushed over
+ * each other's images and redeployed each other's applications. A
+ * `DeployIdentity` is what a deploy names and claims its resources by instead.
+ */
+interface DeployIdentity {
+  /**
+   * Whose deploy this is — an organisation, a team, a repository. Two
+   * workspaces with the same name are told apart by it. Defaults to the
+   * kebab-cased workspace name; set `deploy.namespace` to choose one.
+   */
+  readonly namespace: string;
+  /** The workspace name as the target spells it: lowercase, `[a-z0-9-]`. */
+  readonly project: string;
+  readonly stage: string;
+  /**
+   * `<namespace>/<project>`: what a Dokploy project is claimed by.
+   *
+   * The stage is not part of it because one Dokploy project holds every stage
+   * of a workspace, each as an environment — the key has to be the same from
+   * every stage that deploys into it.
+   */
+  readonly key: string;
+  /**
+   * The prefix every name on the target carries: the project alone in the
+   * default namespace, `<namespace>-<project>` in any other.
+   *
+   * The default adds nothing so that a workspace that never set a namespace
+   * keeps the names it was already deployed under — a Postgres is found by
+   * its name, and a new name would be a new, empty database.
+   */
+  readonly scope: string;
+}
+/** What an identity is derived from: a workspace's name and namespace. */
+interface IdentitySource {
+  name: string;
+  deploy?: {
+    namespace?: string;
+  };
+}
+export declare function deployIdentity(workspace: IdentitySource, stage: string): DeployIdentity;
+//#endregion
+//#region src/home.d.ts
+/**
+ * Where the CLI keeps what belongs to a person rather than a project: stage
+ * keys and stored provider credentials.
+ *
+ * `GKM_HOME` names it, so a CI job, a shared build runner or a test can give
+ * every run its own instead of reaching into whoever's home directory the
+ * process happens to have. Unset, it is `~/.gkm`, where it has always been.
+ */
+/** The environment variable that moves the CLI's home. */
+export declare const GKM_HOME_ENV = "GKM_HOME";
+/** The CLI's home: `GKM_HOME` if set, else `~/.gkm`. */
+export declare function gkmHome(env?: NodeJS.ProcessEnv): string;
+//#endregion
+//#region src/deploy/credentials.d.ts
+/**
+ * How a deploy gets the credentials it acts with.
+ *
+ * `deploy()` never prompts and never reads a terminal: it asks a
+ * `CredentialProvider` and, when the provider has nothing, stops with
+ * `MissingCredential` naming what it needed and how to supply it. Whether to
+ * ask a person, read a vault or fail is the caller's decision — `gkm deploy`
+ * prompts at a terminal and stores what was typed; a CI job sets the
+ * environment; a host passes its own provider.
+ */
+/** What each kind of credential is asked for with, and what it is. */
+interface CredentialKinds {
+  /** The Dokploy API a stage deploys through. */
+  dokploy: {
+    /** `deploy.dokploy.endpoint`, when the config names one. */
+    request: {
+      endpoint?: string;
+    };
+    value: {
+      endpoint: string;
+      token: string;
+    };
+  };
+  /**
+   * A container registry login, for Dokploy to pull with. Asked for only when
+   * Dokploy has no registry for `deploy.dokploy.registry` and one has to be
+   * created.
+   */
+  registry: {
+    /** `deploy.dokploy.registry`. */
+    request: {
+      url: string;
+    };
+    value: {
+      username: string;
+      password: string;
+    };
+  };
+}
+type CredentialKind = keyof CredentialKinds;
+/** What a deploy asks a provider for. */
+type CredentialRequest<K extends CredentialKind = CredentialKind> = { [P in K]: {
+  kind: P;
+} & CredentialKinds[P]['request']; }[K];
+/** What a provider answers with. */
+type Credential<K extends CredentialKind> = CredentialKinds[K]['value'];
+interface CredentialProvider {
+  /**
+   * The credential `request` asks for, or `undefined` when this provider has
+   * none — the deploy then raises {@link MissingCredential}.
+   */
+  get<K extends CredentialKind>(request: CredentialRequest<K>, options?: {
+    signal?: AbortSignal;
+  }): Promise<Credential<K> | undefined>;
+}
+/** A deploy needed a credential, and its provider had none. */
+export declare class MissingCredential extends Error {
+  readonly kind: CredentialKind;
+  /** What it was for: the Dokploy endpoint or the registry URL. */
+  readonly target: string | undefined;
+  /** How to supply it. */
+  readonly howToProvide: string;
+  constructor(kind: CredentialKind,
+  /** What it was for: the Dokploy endpoint or the registry URL. */
+  target: string | undefined,
+  /** How to supply it. */
+  howToProvide?: string);
+}
+/** Whatever was asked for, from the first provider that has it. */
+export declare function chainCredentials(...providers: CredentialProvider[]): CredentialProvider;
+interface StoredCredentialsOptions {
+  /** Where to read the variables from. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * The CLI's home, whose `credentials.json` holds stored logins. Defaults
+   * to `GKM_HOME`, else `~/.gkm`.
+   */
+  home?: string;
+}
+/**
+ * Credentials from the environment, then from what `gkm login` stored. What
+ * `deploy()` uses when it is handed no provider.
+ *
+ * - Dokploy: `DOKPLOY_API_TOKEN` / `DOKPLOY_ENDPOINT`, each falling back to
+ *   the stored login, and the endpoint finally to `deploy.dokploy.endpoint`.
+ *   Each half is read on its own: a token is a secret and belongs in the
+ *   environment, an endpoint is configuration and belongs in the config.
+ * - Registry: `DOCKER_REGISTRY_USERNAME` / `DOCKER_REGISTRY_PASSWORD`.
+ */
+export declare function storedCredentials(options?: StoredCredentialsOptions): CredentialProvider;
+//#endregion
+//#region src/deploy/types.d.ts
+/** Result for a single app deployment in workspace mode */
+interface AppDeployResult {
+  /** App name */
+  appName: string;
+  /** App type */
+  type: 'backend' | 'web' | 'mobile';
+  /** Whether deployment succeeded */
+  success: boolean;
+  /** Dokploy application ID */
+  applicationId?: string;
+  /** Docker image reference */
+  imageRef?: string;
+  /** The registry's digest for the image, `sha256:…`, once pushed */
+  digest?: string;
+  /** Deployment URL */
+  url?: string;
+  /** Error message if failed */
+  error?: string;
+}
+/** Result from workspace deployment */
+interface WorkspaceDeployResult {
+  /** Results for each app */
+  apps: AppDeployResult[];
+  /** Dokploy project ID */
+  projectId: string;
+  /** Total number of successful deployments */
+  successCount: number;
+  /** Total number of failed deployments */
+  failedCount: number;
+}
+/**
+ * What a deploy did — or, for a dry run, would do. Plain JSON, so it can be
+ * written out as is (`gkm deploy --json` ends with it).
+ */
+interface DeployResult extends WorkspaceDeployResult {
+  stage: string;
+  /** `<namespace>/<project>`. */
+  identity: string;
+  /** The image tag every app was built with. */
+  tag: string;
+  /** Whether this was a dry run: nothing was created, built or pushed. */
+  dryRun: boolean;
+  /** Dokploy's environment for the stage; empty when a dry run would create it. */
+  environmentId: string;
+  /** Apps left out, and why — a mobile app, another deploy target. */
+  skipped: {
+    app: string;
+    reason: string;
+  }[];
+  /** Each deployed app's public URL. */
+  urls: Record<string, string>;
+  /**
+   * Every resource the run touched, in order: what it applied, or for a dry
+   * run, what it would.
+   */
+  changes: ResourceChange[];
+}
+//#endregion
+//#region src/deploy/events.d.ts
+/**
+ * The stretch of a deploy an event belongs to.
+ *
+ * - `validate`: the config, the stage, the apps, the lock, the stage's secrets
+ *   and what each app reads from its environment
+ * - `plan`: a dry run's lookups — what would be created and what reused
+ * - `provision`: the Dokploy project, environment and registry, and the
+ *   declared constructs
+ * - `release`: each app's image built, pushed and deployed
+ * - `verify`: DNS records and Dokploy's domain validation
+ */
+type DeployPhase = 'validate' | 'plan' | 'provision' | 'release' | 'verify';
+/** An error, as an event carries it. */
+interface DeployEventError {
+  /** The error's class name — `MissingCredential`, `StateLocked`. */
+  name: string;
+  message: string;
+}
+/**
+ * How a resource came to be used:
+ * - `recorded`: the id the stage's state holds still resolves
+ * - `resumed`: a run that died after creating it is picked up
+ * - `found`: it existed and was looked up
+ * - `created`: this run created it
+ */
+type ResourceVia = 'recorded' | 'resumed' | 'found' | 'created';
+/** One resource a deploy touches, planned or applied. */
+interface ResourceChange {
+  /** `<type>:<name>`, unique within the stage — `application:api`. */
+  key: string;
+  /** `project`, `environment`, `registry`, `application`, `domain`, `image`, or a construct's kind. */
+  resourceType: string;
+  /**
+   * For a plan: whether the run would create it, reuse what exists, or
+   * ensure it (look it up, and create it if missing). For an applied change:
+   * what was done.
+   */
+  action: 'create' | 'reuse' | 'ensure' | 'build';
+  /** The target's id, once there is one. */
+  id?: string;
+}
+type DeployEvent = {
+  type: 'deploy.started';
+  stage: string;
+  /** `<namespace>/<project>`. */
+  identity: string;
+  tag: string;
+  /** The apps this run deploys, in order. */
+  apps: string[];
+  dryRun: boolean;
+} | {
+  type: 'phase.started';
+  phase: DeployPhase;
+} | {
+  type: 'phase.finished';
+  phase: DeployPhase;
+} |
+/**
+ * A progress line, exactly as `gkm deploy` prints it — leading newline and
+ * indentation included, so a terminal renderer prints `message` as is.
+ */
+{
+  type: 'log';
+  level: 'info' | 'warn' | 'error';
+  message: string;
+} | {
+  type: 'app.skipped';
+  app: string;
+  reason: string;
+} | ({
+  type: 'resource.planned';
+} & ResourceChange) | ({
+  type: 'resource.applied';
+  via: ResourceVia;
+} & ResourceChange & {
+  id: string;
+}) | {
+  type: 'artifact.built';
+  app: string;
+  imageRef: string;
+  /** The registry's digest, `sha256:…`, once pushed. */
+  digest?: string;
+} | {
+  type: 'app.deployed';
+  app: string;
+  applicationId: string;
+  imageRef: string;
+  url: string;
+} | {
+  type: 'app.failed';
+  app: string;
+  error: DeployEventError;
+} | {
+  type: 'deploy.finished';
+  result: DeployResult;
+} | {
+  type: 'deploy.failed';
+  error: DeployEventError;
+};
+/** Every `type` a deploy event can have. */
+type DeployEventType = DeployEvent['type'];
+//#endregion
+//#region src/deploy/deploy.d.ts
+/**
+ * Where a run's progress lines go, besides its events. `@geekmidas/logger`'s
+ * `Logger` is one.
+ */
+interface DeployLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error?(message: string): void;
+}
+interface DeployInput {
+  /**
+   * The project to deploy: the directory holding `gkm.config.ts`, or any
+   * directory inside it. Never assumed to be `process.cwd()`.
+   */
+  cwd: string;
+  /** The stage to deploy — one of the config's deployed stages. */
+  stage: string;
+  /** The image tag. Defaults to `<stage>-<timestamp>`. */
+  tag?: string;
+  /** Deploy only these apps (in dependency order). Defaults to all. */
+  apps?: string[];
+  /**
+   * Look everything up and report what would happen — as `resource.planned`
+   * events — without taking the lock, writing state, generating secrets,
+   * changing Dokploy or building and pushing images.
+   */
+  dryRun?: boolean;
+  /**
+   * Where credentials come from. Defaults to the environment, then the
+   * logins `gkm login` stored. A credential no provider has stops the run
+   * with `MissingCredential`; nothing prompts.
+   */
+  credentials?: CredentialProvider;
+  /** Receives each progress line as it is written. Defaults to none. */
+  logger?: DeployLogger;
+  /**
+   * Stops the run: in-flight Dokploy requests and docker children are
+   * cancelled, the stage's lock is released, and `result` rejects with the
+   * signal's reason.
+   */
+  signal?: AbortSignal;
+  /**
+   * The CLI's home: stage keys and stored logins. Defaults to `GKM_HOME`,
+   * else `~/.gkm`.
+   */
+  home?: string;
+  /**
+   * Where docker's own output goes: the host's terminal (`inherit`, the
+   * default), its stderr, or nowhere.
+   */
+  childOutput?: 'inherit' | 'stderr' | 'ignore';
+}
+/** A deploy in progress. */
+interface DeployRun extends AsyncIterable<DeployEvent> {
+  /**
+   * What the deploy did, once it is done. Rejects with the error that
+   * stopped it — `MissingCredential`, `StateLocked`, `ProjectNotOwned`, … —
+   * after a `deploy.failed` event carrying the same.
+   */
+  readonly result: Promise<DeployResult>;
+}
+/**
+ * Deploy a project's stage.
+ *
+ * ```ts
+ * import { deploy } from '@geekmidas/cli/deploy';
+ *
+ * const run = deploy({ cwd: '/srv/checkouts/shop', stage: 'production' });
+ * for await (const event of run) {
+ *   if (event.type === 'app.deployed') console.log(event.app, event.url);
+ * }
+ * const result = await run.result;
+ * ```
+ *
+ * The run starts at once; iterating it is optional, and an iteration started
+ * late still sees every event from the first.
+ */
+export declare function deploy(input: DeployInput): DeployRun;
+//#endregion
+//#region src/deploy/index.d.ts
+/** Apps were asked for by name that the workspace does not have. */
+export declare class UnknownDeployApps extends Error {
+  readonly apps: readonly string[];
+  readonly available: readonly string[];
+  constructor(apps: readonly string[], available: readonly string[]);
+}
+/** Every app asked for deploys somewhere other than Dokploy. */
+export declare class NoDeployableApps extends Error {
+  readonly stage: string;
+  constructor(stage: string);
+}
+/** A backend failed, so the run stopped before deploying anything after it. */
+export declare class BackendDeployFailed extends Error {
+  readonly app: string;
+  constructor(app: string, cause: unknown);
+}
+/** An app's environment needs values the stage does not have. */
+export declare class MissingEnvVars extends Error {
+  readonly app: string;
+  readonly missing: readonly string[];
+  readonly stage: string;
+  constructor(app: string, missing: readonly string[], stage: string);
+}
+//#endregion
+//#region src/deploy/ownership.d.ts
+/**
+ * A Dokploy project with the name this deploy would use exists, and nothing
+ * says this workspace created it.
+ */
+export declare class ProjectNotOwned extends Error {
+  readonly projectName: string;
+  readonly projectId: string;
+  readonly identity: string;
+  /** The marker the project carries instead, if it carries one. */
+  readonly ownedBy: string | undefined;
+  constructor(projectName: string, projectId: string, identity: string,
+  /** The marker the project carries instead, if it carries one. */
+  ownedBy: string | undefined);
+}
+//#endregion
+//#region src/deploy/registry.d.ts
+/** There is nowhere to push images to, so Dokploy has nothing to pull. */
+export declare class RegistryNotConfigured extends Error {
+  readonly stage: string;
+  constructor(stage: string);
+}
+/** `deploy.dokploy.registryId` names a registry Dokploy does not have. */
+export declare class RegistryNotFound extends Error {
+  readonly registryId: string;
+  constructor(registryId: string);
+}
+/** More than one Dokploy registry serves the configured registry. */
+export declare class RegistryAmbiguous extends Error {
+  readonly registry: string;
+  readonly registryIds: readonly string[];
+  constructor(registry: string, registryIds: readonly string[]);
+}
+//#endregion
+export { type AppDeployResult, type Credential, type CredentialKind, type CredentialKinds, type CredentialProvider, type CredentialRequest, type DeployEvent, type DeployEventError, type DeployEventType, type DeployIdentity, type DeployInput, type DeployLogger, type DeployPhase, type DeployResult, type DeployRun, type ResourceChange, type ResourceVia, StateLocked, StateVersionConflict, type StoredCredentialsOptions };
+//# sourceMappingURL=public.d.cts.map

package/dist/deploy/public.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.cts","names":[],"sources":["../../src/deploy/identity.ts","../../src/home.ts","../../src/deploy/credentials.ts","../../src/deploy/types.ts","../../src/deploy/events.ts","../../src/deploy/deploy.ts","../../src/deploy/index.ts","../../src/deploy/ownership.ts","../../src/deploy/registry.ts"],"mappings":";;;;;;;;;;;;;UAaiB;;;;;;WAMP;;WAEA;WACA;;;;;;;;WAQA;;;;;;;;;WASA;;;UA0CO;EAChB;EACA;IAAW;;;wBAGI,eACf,WAAW,gBACX,gBACE;;;;;;;;;;;;qBC5EU;;wBAGG,QAAQ,MAAK,OAAO;;;;;;;;;;;;;;UCFnB;;EAEhB;;IAEC;MAAW;;IACX;MAAS;MAAkB;;;;;;;;EAO5B;;IAEC;MAAW;;IACX;MAAS;MAAkB;;;;KAIjB,uBAAuB;;KAGvB,kBAAkB,UAAU,iBAAiB,qBACvD,KAAK;EAAM,MAAM;IAAM,gBAAgB,iBACvC;;KAGU,WAAW,UAAU,kBAAkB,gBAAgB;UAElD;;;;;EAKhB,IAAI,UAAU,gBACb,SAAS,kBAAkB,IAC3B;IAAY,SAAS;MACnB,QAAQ,WAAW;;;qBAYV,0BAA0B;WAE5B,MAAM;;WAEN;;WAEA;EALV,YACU,MAAM,gBAEN;;EAAA,4BAEA;;EAAA;;;wBAYK,oBACZ,WAAW,uBACZ;UAYc;;EAEhB,MAAM,OAAO;;;;;EAKb;;;;;;;;;;;;wBAae,kBACf,UAAS,2BACP;;;;UCzEc;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIgB;;EAEhB,MAAM;;EAEN;;EAEA;;EAEA;;;;;;UAOgB,qBAAqB;EACrC;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;IAAW;IAAa;;;EAExB,MAAM;;;;;EAKN,SAAS;;;;;;;;;;;;;;;KCtEE;;UAQK;;EAEhB;EACA;;;;;;;;;KAUW;;UAGK;;EAEhB;;EAEA;;;;;;EAMA;;EAEA;;KAGW;EAET;EACA;;EAEA;EACA;;EAEA;EACA;;EAEE;EAAuB,OAAO;;EAC9B;EAAwB,OAAO;;;;;;;EAK/B;EAAa;EAAkC;;EAC/C;EAAqB;EAAa;;EACjC;IAA6B;EAC7B;EAA0B,KAAK;IAAgB;EACjD;;EAGD;EACA;EACA;;EAEA;;EAGA;EACA;EACA;EACA;EACA;;EAEE;EAAoB;EAAa,OAAO;;EACxC;EAAyB,QAAQ;;EACjC;EAAuB,OAAO;;;KAGvB,kBAAkB;;;;;;;UChFb;EAChB,KAAK;EACL,KAAK;EACL,OAAO;;UAGS;;;;;EAKhB;;EAEA;;EAEA;;EAEA;;;;;;EAMA;;;;;;EAMA,cAAc;;EAEd,SAAS;;;;;;EAMT,SAAS;;;;;EAKT;;;;;EAKA;;;UAIgB,kBAAkB,cAAc;;;;;;WAMvC,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;wBA2EV,OAAO,OAAO,cAAc;;;;qBCwX/B,0BAA0B;WAE5B;WACA;EAFV,YACU,yBACA;;;qBAWE,yBAAyB;WAChB;EAArB,YAAqB;;;qBAST,4BAA4B;WAE9B;EADV,YACU,aACT;;;qBAWW,uBAAuB;WAEzB;WACA;WACA;EAHV,YACU,aACA,4BACA;;;;;;;;qBCtiBE,wBAAwB;WAE1B;WACA;WACA;;WAEA;EALV,YACU,qBACA,mBACA,kBAEA;;EAAA;;;;;qBChBE,8BAA8B;WACrB;EAArB,YAAqB;;;qBAUT,yBAAyB;WAChB;EAArB,YAAqB;;;qBAUT,0BAA0B;WAE5B;WACA;EAFV,YACU,kBACA"}