@sealant/sdk 0.17.0 → 0.18.1

package/README.md

@@ -124,6 +124,31 @@ const workspace = await sealant.workspaces.create({
 rootless daemon at launch. The workspace receives `DOCKER_HOST`; Sealant never mounts the host
 Docker socket. GitHub credentials provide both `GH_TOKEN` and `GITHUB_TOKEN` to the workspace.
 
+## Dotfiles and shell
+
+Bring your own environment: a login shell and dotfiles applied before the workspace accepts work.
+
+```ts
+const workspace = await sealant.workspaces.create({
+  repository: "github.com/acme/billing-service",
+  harness: codex(),
+  shell: "zsh",
+  dotfiles: {
+    // A repo the platform clones and applies (chezmoi/stow layouts detected, else copied):
+    repository: { url: "github.com/acme/dotfiles" },
+    // And/or caller-resolved archives — a checkout cloned host-side with your own ssh identity,
+    // or a scanned selection of home files, sent as gzipped tars (max 4, ~4MB decoded each):
+    archives: [{ data: tarGzBase64, manager: "copy", bootstrap: false }],
+  },
+});
+```
+
+`shell` installs the shell package and switches the login shell, so `.zshrc`/`.fishrc` actually take
+effect. The `repository` applies first, then each archive in order, so local selections override
+repo files. A failing apply fails the launch loudly rather than handing the agent a half-prepared
+home. Managed OS families only — with `baseImage`, `dotfiles` and non-bash `shell` are rejected
+client-side with the platform's reasoning.
+
 ## Custom base images
 
 Instead of a managed OS family, a workspace image can be built from any image reference you already

package/dist/internal/blueprint.js

@@ -41,6 +41,17 @@ export const buildCreateWorkspaceRequest = (options, config) => {
     if (options.os !== undefined && options.baseImage !== undefined) {
         throw new SealantError("workspaces.create accepts either `os` (a managed OS family) or `baseImage` (a custom base image reference), not both.", { code: "invalid_create_options" });
     }
+    if (options.baseImage !== undefined && options.dotfiles !== undefined) {
+        throw new SealantError("`dotfiles` is not supported with `baseImage`: custom bases guarantee only a POSIX shell, so the dotfiles managers are not provisioned.", { code: "invalid_create_options" });
+    }
+    if (options.baseImage !== undefined && options.shell !== undefined && options.shell !== "bash") {
+        throw new SealantError("`shell` is not supported with `baseImage`: custom bases run /bin/sh and the login shell cannot be switched.", { code: "invalid_create_options" });
+    }
+    if (options.dotfiles !== undefined &&
+        options.dotfiles.repository === undefined &&
+        (options.dotfiles.archives === undefined || options.dotfiles.archives.length === 0)) {
+        throw new SealantError("`dotfiles` requires a `repository`, at least one entry in `archives`, or both.", { code: "invalid_create_options" });
+    }
     const sourceName = options.repository ?? options.source?.path ?? "workspace";
     const tail = sourceName
         .split("/")
@@ -72,6 +83,8 @@ export const buildCreateWorkspaceRequest = (options, config) => {
             ...(toolingPackages.length === 0 ? {} : { packages: toolingPackages }),
             ...(dockerService ? { services: { docker: { enabled: true } } } : {}),
         };
+    const dotfilesRepository = options.dotfiles?.repository;
+    const dotfilesArchives = options.dotfiles?.archives ?? [];
     const spec = {
         version: "1",
         sources: {
@@ -84,6 +97,21 @@ export const buildCreateWorkspaceRequest = (options, config) => {
                     ...(options.ref === undefined ? {} : { ref: options.ref }),
                 }
                 : { kind: "mount", hostPath: options.source?.path },
+            ...(dotfilesRepository === undefined
+                ? {}
+                : {
+                    inputs: [
+                        {
+                            id: "dotfiles",
+                            kind: "git",
+                            purpose: "dotfiles",
+                            provider: "generic",
+                            url: toGitUrl(dotfilesRepository.url),
+                            // Omitted ref = the remote's default branch — never assumed to be `main`.
+                            ...(dotfilesRepository.ref === undefined ? {} : { ref: dotfilesRepository.ref }),
+                        },
+                    ],
+                }),
             ...(mounts.length === 0
                 ? {}
                 : {
@@ -96,7 +124,35 @@ export const buildCreateWorkspaceRequest = (options, config) => {
                 }),
         },
         harness: { id: options.harness.id },
-        customization: { enableSealantd: true },
+        customization: {
+            enableSealantd: true,
+            ...(options.shell === undefined ? {} : { defaultShell: options.shell }),
+            // The repository path's knobs live at customization level; archives carry their own.
+            ...(dotfilesRepository?.manager === undefined
+                ? {}
+                : { dotfilesManager: dotfilesRepository.manager }),
+            ...(dotfilesRepository?.bootstrap === undefined
+                ? {}
+                : { dotfilesBootstrap: dotfilesRepository.bootstrap }),
+            ...(dotfilesRepository?.bootstrapCommand === undefined
+                ? {}
+                : { dotfilesBootstrapCommand: dotfilesRepository.bootstrapCommand }),
+        },
+        ...(dotfilesArchives.length === 0
+            ? {}
+            : {
+                runtime: {
+                    dotfilesArchives: dotfilesArchives.map((archive) => ({
+                        data: archive.data,
+                        ...(archive.manager === undefined ? {} : { manager: archive.manager }),
+                        ...(archive.target === undefined ? {} : { target: archive.target }),
+                        ...(archive.bootstrap === undefined ? {} : { bootstrap: archive.bootstrap }),
+                        ...(archive.bootstrapCommand === undefined
+                            ? {}
+                            : { bootstrapCommand: archive.bootstrapCommand }),
+                    })),
+                },
+            }),
         target: {
             os: options.baseImage !== undefined
                 ? { family: "custom", mode: "require", baseImage: options.baseImage }

package/dist/types.d.ts

@@ -123,6 +123,53 @@ export interface WorkspaceExtraMount {
     /** Defaults to `true`. Pass `false` deliberately — writes to extra mounts are unrecorded. */
     readonly readOnly?: boolean;
 }
+/** How a dotfiles tree is applied inside the workspace. */
+export type WorkspaceDotfilesManager = "auto" | "chezmoi" | "stow" | "copy";
+/**
+ * A dotfiles repository the platform clones and applies before the workspace accepts work. Public
+ * or GitHub-App-reachable repos work as-is; for a repo only the caller's own ssh identity can
+ * reach, resolve it host-side and send the checkout as an archive instead (see
+ * `WorkspaceDotfilesArchive`).
+ */
+export interface WorkspaceDotfilesRepository {
+    /** Clone URL (or `"github.com/acme/dotfiles"` shorthand). */
+    readonly url: string;
+    /** Git ref. Omitted = the remote's default branch — never assumed to be `main`. */
+    readonly ref?: string;
+    /** Defaults to `"auto"`: chezmoi/stow layouts are detected, everything else is copied. */
+    readonly manager?: WorkspaceDotfilesManager;
+    /** Run the repo's bootstrap command after applying (skipped when absent). Defaults to true. */
+    readonly bootstrap?: boolean;
+    /** Bootstrap command, relative to the checkout. Defaults to `./install.sh`. */
+    readonly bootstrapCommand?: string;
+}
+/**
+ * A caller-resolved dotfiles tree: a gzipped tar the daemon extracts and applies at boot through
+ * the same manager dispatch as a cloned repo. This is the shape for dotfiles resolved host-side —
+ * a checkout cloned with the caller's own ssh identity, or a scanned selection of home files —
+ * so no URL or credential ever has to reach the workspace. Max 4 archives, ~4MB decoded each.
+ */
+export interface WorkspaceDotfilesArchive {
+    /** base64 of a `.tar.gz` whose contents apply relative to the target. */
+    readonly data: string;
+    /** Defaults to `"auto"`. Scanned home files usually want `"copy"`. */
+    readonly manager?: WorkspaceDotfilesManager;
+    /** Where the tree lands: `"home"` (default) or `"config"` (`$HOME/.config`, copy manager only). */
+    readonly target?: "home" | "config";
+    /** Run `./install.sh` (or `bootstrapCommand`) after applying when present. Defaults to true. */
+    readonly bootstrap?: boolean;
+    readonly bootstrapCommand?: string;
+}
+/**
+ * Dotfiles for the workspace: a repository the platform clones, caller-resolved archives, or both
+ * (the repository applies first, archives after — in order — so local selections override repo
+ * files). Applied before the workspace reports ready; a failing apply fails the launch loudly.
+ * Not supported with `baseImage` (custom bases guarantee only a POSIX shell).
+ */
+export interface WorkspaceDotfilesOptions {
+    readonly repository?: WorkspaceDotfilesRepository;
+    readonly archives?: readonly WorkspaceDotfilesArchive[];
+}
 /** Runtime-managed services attached only to this workspace. */
 export interface WorkspaceServicesOptions {
     /**
@@ -160,6 +207,14 @@ export interface CreateOptions {
     readonly baseImage?: string;
     /** Extra OS packages to install in the workspace. */
     readonly packages?: readonly string[];
+    /**
+     * Login shell for the workspace user (`"bash"` default). The shell package is installed and the
+     * login shell switched, so dotfiles like `.zshrc` actually take effect. Managed OS families
+     * only — custom bases guarantee just a POSIX shell.
+     */
+    readonly shell?: "bash" | "zsh" | "fish";
+    /** Dotfiles applied before the workspace accepts work (see `WorkspaceDotfilesOptions`). */
+    readonly dotfiles?: WorkspaceDotfilesOptions;
     /** Runtime-managed services that need more than installing an OS package. */
     readonly services?: WorkspaceServicesOptions;
     /** When true (default), resolve only once the workspace runtime is live. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sealant/api-contracts": "^0.17.0"
+    "@sealant/api-contracts": "^0.18.1"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0-beta.85",