@geekmidas/cli 10.0.0-alpha.9 → 10.0.0-alpha.91

package/dist/sandbox-M8UnLhXE.d.mts

@@ -0,0 +1,126 @@
+//#region src/sandbox/sandbox.d.ts
+/**
+ * Where a deploy runs the project's own code.
+ *
+ * A deploy holds credentials — Dokploy's token, a registry login, an AWS key —
+ * and loading `gkm.config.ts`, sniffing an app's environment and building it
+ * all execute code from the repository being deployed. On a developer's own
+ * laptop that is the developer's code. On a CI job for a fork, or a shared
+ * build runner, it is not, and that code should not be able to read the
+ * credentials used to deploy it, hang the deploy, or reach outside the
+ * checkout.
+ *
+ * So every step that runs project code goes through a `Sandbox`: one call,
+ * with an argument array rather than a shell line, the complete environment
+ * the step needs rather than the host's, a timeout it cannot outlive, secrets
+ * as files rather than variables, and a working directory inside the project.
+ * The steps that need credentials — provisioning, pushing, releasing — are
+ * the deploy's own code and never run in one.
+ *
+ * `LocalSandbox` is the default: a child process on this machine with an
+ * allowlisted environment. A host that builds repositories it does not trust
+ * passes its own — a container per build, a VM — through `deploy()`'s
+ * `sandbox`.
+ */
+/** Where a command's output goes. */
+type SandboxOutput = 'capture' | 'inherit' | 'stderr' | 'ignore';
+interface SandboxExecOptions {
+  /**
+   * Where the command runs: the project root or a directory below it, as an
+   * absolute path or relative to the root. Anywhere else is refused with
+   * {@link SandboxCwdEscape}.
+   */
+  cwd: string;
+  /**
+   * The command's whole environment. Nothing of the host's is added to it:
+   * start from {@link Sandbox.env} and add what the step needs.
+   */
+  env: Readonly<Record<string, string>>;
+  /**
+   * How long the command may run before it is killed. Required: a step that
+   * waits forever — a sniffed entry that opens a server, a build stuck on a
+   * prompt — would otherwise hold the deploy, and its lock, forever.
+   */
+  timeoutMs: number;
+  /**
+   * Files the command can read, by name. Mounted in a directory of their own
+   * — named by `GKM_SECRETS_DIR` in the command's environment — and removed
+   * when it exits. Never set as variables, which every child inherits, a
+   * crash report prints and `/proc/<pid>/environ` shows.
+   */
+  secrets?: Readonly<Record<string, string>>;
+  /**
+   * `capture` (the default) returns stdout and stderr in the result;
+   * `inherit` gives the command the host's terminal; `stderr` sends both
+   * streams to the host's stderr; `ignore` discards them.
+   */
+  output?: SandboxOutput;
+  /** Kills the command when aborted; `exec` rejects with the signal's reason. */
+  signal?: AbortSignal;
+}
+/** How a command ended. A non-zero exit is a result, not an error. */
+interface SandboxResult {
+  exitCode: number | null;
+  signal: string | null;
+  /** What it wrote to stdout, when its output was captured. */
+  stdout: string;
+  /** What it wrote to stderr, when its output was captured. */
+  stderr: string;
+}
+/**
+ * Runs a command against the project, and nothing else of the host's.
+ *
+ * `exec` resolves with the result however the command exited. It rejects
+ * with {@link CommandTimedOut} once the timeout passes — after the command is
+ * gone — with {@link SandboxCwdEscape} for a directory outside the project,
+ * with the signal's reason when aborted, and with the spawn error when the
+ * program cannot be started.
+ */
+interface Sandbox {
+  /** The project: the directory every command runs at or below. */
+  readonly root: string;
+  /**
+   * Whether the code it runs is kept from the host: its files, its
+   * processes, its memory.
+   *
+   * An isolating sandbox shares nothing but what crosses `exec`, so a config
+   * reaches the deploy as data — a live object in it (a custom state store,
+   * an inline target) cannot cross, and is refused with
+   * `ConfigObjectNotSerializable`. A non-isolating one, like
+   * {@link LocalSandbox}, runs on the host as the host's user; a project
+   * whose config holds live objects is then loaded in-process as before,
+   * because a project trusted to run there is trusted to do that.
+   */
+  readonly isolating: boolean;
+  /**
+   * The environment a command starts from: what any program needs to run
+   * here — `PATH`, `HOME`, the locale — and no credential.
+   */
+  readonly env: Readonly<Record<string, string>>;
+  exec(command: string, args: readonly string[], options: SandboxExecOptions): Promise<SandboxResult>;
+}
+/** The variable naming the directory a command's secrets are mounted in. */
+declare const SECRETS_DIR_ENV = "GKM_SECRETS_DIR";
+/** A command was asked to run outside the project. */
+declare class SandboxCwdEscape extends Error {
+  readonly cwd: string;
+  readonly root: string;
+  constructor(cwd: string, root: string);
+}
+/**
+ * `cwd` as an absolute directory inside `root`, or {@link SandboxCwdEscape}.
+ *
+ * Symlinks are resolved on both sides first, so a link inside the project
+ * that points out of it is an escape, and a project reached through a link
+ * (`/tmp` on macOS) is still itself. For a sandbox of a host's own to call
+ * before it runs anything.
+ */
+declare function confineCwd(root: string, cwd: string): string;
+/** A secret's file name: one path segment, so it cannot be written elsewhere. */
+declare class SecretNameInvalid extends Error {
+  readonly secretName: string;
+  constructor(secretName: string);
+}
+//#endregion
+export { SandboxOutput as a, confineCwd as c, SandboxExecOptions as i, Sandbox as n, SandboxResult as o, SandboxCwdEscape as r, SecretNameInvalid as s, SECRETS_DIR_ENV as t };
+//# sourceMappingURL=sandbox-M8UnLhXE.d.mts.map

package/dist/sandbox-M8UnLhXE.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-M8UnLhXE.d.mts","names":[],"sources":["../src/sandbox/sandbox.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;KA6BY;UAEK;;;;;;EAMhB;;;;;EAKA,KAAK,SAAS;;;;;;EAMd;;;;;;;EAOA,UAAU,SAAS;;;;;;EAMnB,SAAS;;EAET,SAAS;;;UAIO;EAChB;EACA;;EAEA;;EAEA;;;;;;;;;;;UAYgB;;WAEP;;;;;;;;;;;;;WAaA;;;;;WAKA,KAAK,SAAS;EACvB,KACC,iBACA,yBACA,SAAS,qBACP,QAAQ;;;cAIC;;cAGA,yBAAyB;WAE3B;WACA;EAFV,YACU,aACA;;;;;;;;;;iBAwBK,WAAW,cAAc;;cAU5B,0BAA0B;WACjB;EAArB,YAAqB"}