@wardby/cli 0.6.0 → 0.8.0

package/dist/providers/storage/index.d.ts

@@ -0,0 +1,15 @@
+import type { BlobStore } from "./types.js";
+export type BlobStoreConfig = {
+    kind: "local";
+    localDir: string;
+} | {
+    kind: "gcs";
+    bucket: string;
+} | {
+    kind: "s3";
+    bucket: string;
+    region: string;
+    endpoint?: string;
+};
+/** Build the configured blob store. Cloud adapters take credentials from the environment's default chain. */
+export declare function createBlobStore(config: BlobStoreConfig): BlobStore;

package/dist/providers/storage/index.js

@@ -0,0 +1,14 @@
+import { GcsBlobStore } from "./gcs.js";
+import { LocalBlobStore } from "./local.js";
+import { S3BlobStore } from "./s3.js";
+/** Build the configured blob store. Cloud adapters take credentials from the environment's default chain. */
+export function createBlobStore(config) {
+    switch (config.kind) {
+        case "local":
+            return new LocalBlobStore(config.localDir);
+        case "gcs":
+            return GcsBlobStore.forBucket(config.bucket);
+        case "s3":
+            return S3BlobStore.forBucket(config);
+    }
+}

package/dist/providers/storage/local.d.ts

@@ -0,0 +1,24 @@
+import { type BlobInfo, type BlobStore } from "./types.js";
+/** Filesystem blob store rooted at one directory. Writes go to a temp file in the target directory, then rename (atomic). */
+export declare class LocalBlobStore implements BlobStore {
+    private readonly root;
+    constructor(root: string);
+    private pathFor;
+    private tempPathFor;
+    put(key: string, body: Buffer): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    signedUrl(key: string, _opts: {
+        expiresSec: number;
+        method: "GET" | "PUT";
+    }): Promise<string>;
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    head(key: string): Promise<BlobInfo | null>;
+}

package/dist/providers/storage/local.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createByteMeter } from "./meter.js";
+import { assertValidBlobKey, BlobStoreError } from "./types.js";
+function isNotFound(error) {
+    return error?.code === "ENOENT";
+}
+/** Filesystem blob store rooted at one directory. Writes go to a temp file in the target directory, then rename (atomic). */
+export class LocalBlobStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    pathFor(key) {
+        assertValidBlobKey(key);
+        return join(this.root, key);
+    }
+    tempPathFor(path) {
+        return join(dirname(path), `.tmp-${randomUUID()}`);
+    }
+    async put(key, body) {
+        const path = this.pathFor(key);
+        await mkdir(dirname(path), { recursive: true });
+        const temp = this.tempPathFor(path);
+        try {
+            await writeFile(temp, body);
+            await rename(temp, path);
+        }
+        catch (error) {
+            await rm(temp, { force: true });
+            throw error;
+        }
+    }
+    async get(key) {
+        try {
+            return await readFile(this.pathFor(key));
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new BlobStoreError("not_found", "not_found", { cause: error });
+            throw error;
+        }
+    }
+    async delete(key) {
+        await rm(this.pathFor(key), { force: true });
+    }
+    async signedUrl(key, _opts) {
+        assertValidBlobKey(key);
+        throw new BlobStoreError("not_supported", "not_supported: the local blob store has no signed URLs");
+    }
+    async putStream(key, body, opts) {
+        const path = this.pathFor(key);
+        await mkdir(dirname(path), { recursive: true });
+        const temp = this.tempPathFor(path);
+        const meter = createByteMeter(opts?.maxBytes);
+        try {
+            await pipeline(body, meter.stream, createWriteStream(temp));
+            await rename(temp, path);
+        }
+        catch (error) {
+            await rm(temp, { force: true });
+            throw error;
+        }
+        return { sizeBytes: meter.size(), sha256: meter.digest() };
+    }
+    async getStream(key) {
+        const path = this.pathFor(key);
+        try {
+            await stat(path);
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new BlobStoreError("not_found", "not_found", { cause: error });
+            throw error;
+        }
+        return createReadStream(path);
+    }
+    async head(key) {
+        try {
+            const info = await stat(this.pathFor(key));
+            return { sizeBytes: info.size, updatedAt: info.mtime };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+}

package/dist/providers/storage/meter.d.ts

@@ -0,0 +1,14 @@
+import { Transform } from "node:stream";
+import { BlobStoreError } from "./types.js";
+export interface ByteMeter {
+    stream: Transform;
+    /** Bytes seen so far. */
+    size(): number;
+    /** The blob_too_large error, once the limit tripped. */
+    limitError(): BlobStoreError | undefined;
+    /** Finish the hash; call once, after the body has ended. */
+    digest(): string;
+}
+/** A passthrough that counts bytes (normalizing string chunks), hashes them, and fails with blob_too_large past `maxBytes`. */
+export declare function createByteMeter(maxBytes: number | undefined): ByteMeter;
+export declare function collectStream(stream: NodeJS.ReadableStream): Promise<Buffer>;

package/dist/providers/storage/meter.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { Transform } from "node:stream";
+import { BlobStoreError } from "./types.js";
+/** A passthrough that counts bytes (normalizing string chunks), hashes them, and fails with blob_too_large past `maxBytes`. */
+export function createByteMeter(maxBytes) {
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    let tooLarge;
+    const stream = new Transform({
+        transform(chunk, encoding, callback) {
+            // Only a string is converted; a Buffer (or any byte view) passes through without a copy.
+            const bytes = typeof chunk === "string"
+                ? Buffer.from(chunk, encoding)
+                : Buffer.isBuffer(chunk)
+                    ? chunk
+                    : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+            sizeBytes += bytes.length;
+            if (maxBytes !== undefined && sizeBytes > maxBytes) {
+                tooLarge = new BlobStoreError("blob_too_large", `blob_too_large: more than ${maxBytes} bytes`);
+                callback(tooLarge);
+                return;
+            }
+            hash.update(bytes);
+            callback(null, bytes);
+        },
+    });
+    return { stream, size: () => sizeBytes, limitError: () => tooLarge, digest: () => hash.digest("hex") };
+}
+export async function collectStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks);
+}

package/dist/providers/storage/s3.d.ts

@@ -0,0 +1,41 @@
+import { type BlobInfo, type BlobStore } from "./types.js";
+/** The slice of S3Client the adapter uses (the real client satisfies it; tests supply an in-memory fake). */
+export interface S3ClientLike {
+    send(command: object): Promise<unknown>;
+    readonly config: unknown;
+}
+/**
+ * S3-compatible blob store (AWS S3, MinIO via `endpoint`). Credentials come from the default AWS credential
+ * chain (Pod Identity on EKS). Streamed uploads use multipart for large bodies; S3 only exposes an object once the
+ * upload completes, so an aborted upload never replaces the previous object.
+ */
+export declare class S3BlobStore implements BlobStore {
+    private readonly client;
+    private readonly bucket;
+    constructor(client: S3ClientLike, bucket: string);
+    /** Build a store using the default credential chain. A custom `endpoint` (MinIO) switches to path-style addressing. */
+    static forBucket(settings: {
+        bucket: string;
+        region: string;
+        endpoint?: string;
+    }): S3BlobStore;
+    private keyed;
+    put(key: string, body: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    signedUrl(key: string, opts: {
+        expiresSec: number;
+        method: "GET" | "PUT";
+    }): Promise<string>;
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    head(key: string): Promise<BlobInfo | null>;
+}

package/dist/providers/storage/s3.js

@@ -0,0 +1,107 @@
+import { pipeline } from "node:stream/promises";
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { collectStream, createByteMeter } from "./meter.js";
+import { assertValidBlobKey, BlobStoreError } from "./types.js";
+function statusOf(error) {
+    return error?.$metadata?.httpStatusCode;
+}
+/** A missing key only: NoSuchBucket and other 404-class failures must surface, not look like an empty store. */
+function isNotFound(error) {
+    const name = error?.name;
+    if (name === "NoSuchKey")
+        return true;
+    // HeadObject has no body, so a missing key arrives as a bare NotFound.
+    return name === "NotFound" && statusOf(error) === 404;
+}
+/**
+ * S3-compatible blob store (AWS S3, MinIO via `endpoint`). Credentials come from the default AWS credential
+ * chain (Pod Identity on EKS). Streamed uploads use multipart for large bodies; S3 only exposes an object once the
+ * upload completes, so an aborted upload never replaces the previous object.
+ */
+export class S3BlobStore {
+    client;
+    bucket;
+    constructor(client, bucket) {
+        this.client = client;
+        this.bucket = bucket;
+    }
+    /** Build a store using the default credential chain. A custom `endpoint` (MinIO) switches to path-style addressing. */
+    static forBucket(settings) {
+        const client = new S3Client({
+            region: settings.region,
+            // Default CRC32 checksums break presigned PUTs (empty-body checksum in the URL) and many S3-compatible endpoints.
+            requestChecksumCalculation: "WHEN_REQUIRED",
+            responseChecksumValidation: "WHEN_REQUIRED",
+            ...(settings.endpoint ? { endpoint: settings.endpoint, forcePathStyle: true } : {}),
+        });
+        return new S3BlobStore(client, settings.bucket);
+    }
+    keyed(key) {
+        assertValidBlobKey(key);
+        return { Bucket: this.bucket, Key: key };
+    }
+    async put(key, body, opts) {
+        await this.client.send(new PutObjectCommand({
+            ...this.keyed(key),
+            Body: body,
+            ContentType: opts?.contentType,
+        }));
+    }
+    async get(key) {
+        return collectStream(await this.getStream(key));
+    }
+    async delete(key) {
+        await this.client.send(new DeleteObjectCommand(this.keyed(key)));
+    }
+    async signedUrl(key, opts) {
+        const params = this.keyed(key);
+        const command = opts.method === "GET" ? new GetObjectCommand(params) : new PutObjectCommand(params);
+        return getSignedUrl(this.client, command, { expiresIn: opts.expiresSec });
+    }
+    async putStream(key, body, opts) {
+        const target = this.keyed(key);
+        const meter = createByteMeter(opts?.maxBytes);
+        const upload = new Upload({
+            client: this.client,
+            params: { ...target, Body: meter.stream, ContentType: opts?.contentType },
+            leavePartsOnError: false,
+        });
+        const uploading = upload.done();
+        uploading.catch(() => undefined); // observed below; avoids an unhandled rejection if the pipeline fails first
+        try {
+            await Promise.all([pipeline(body, meter.stream), uploading]);
+        }
+        catch (error) {
+            // Abort any in-flight multipart upload so no parts (and no object) are left behind; the previous object, if any,
+            // is untouched because S3 publishes an object only when the upload completes.
+            await upload.abort().catch(() => undefined);
+            await uploading.catch(() => undefined);
+            throw meter.limitError() ?? error;
+        }
+        return { sizeBytes: meter.size(), sha256: meter.digest() };
+    }
+    async getStream(key) {
+        try {
+            const result = (await this.client.send(new GetObjectCommand(this.keyed(key))));
+            return result.Body;
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new BlobStoreError("not_found", "not_found", { cause: error });
+            throw error;
+        }
+    }
+    async head(key) {
+        try {
+            const result = (await this.client.send(new HeadObjectCommand(this.keyed(key))));
+            return { sizeBytes: Number(result.ContentLength ?? 0), updatedAt: result.LastModified ?? new Date(0) };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+}

package/dist/providers/storage/types.d.ts

@@ -1,9 +1,26 @@
 /**
- * Storage seam — object/blob storage (email attachments, run artifacts).
+ * Storage seam — object/blob storage (run dependency snapshots today).
  *
- * Default adapter: LocalBlobStore (filesystem).
- * Native adapter:  S3BlobStore (S3 or S3-compatible object storage).
+ * Adapters: LocalBlobStore (filesystem), plus cloud object stores (GCS, S3).
+ * Failures carry a stable `code` (see BlobStoreError).
  */
+export interface BlobInfo {
+    sizeBytes: number;
+    /**
+     * Present only when an adapter records it atomically with the content. Absence means "unknown", never
+     * "verified": callers keep the authoritative digest themselves.
+     */
+    sha256?: string;
+    updatedAt: Date;
+}
+export type BlobStoreErrorCode = "not_found" | "not_supported" | "invalid_key" | "blob_too_large";
+/** An error with a stable machine-readable `code`; the message is the code unless more detail helps. */
+export declare class BlobStoreError extends Error {
+    readonly code: BlobStoreErrorCode;
+    constructor(code: BlobStoreErrorCode, message?: string, options?: {
+        cause?: unknown;
+    });
+}
 export interface BlobStore {
     put(key: string, body: Buffer, opts?: {
         contentType?: string;
@@ -15,4 +32,21 @@ export interface BlobStore {
         expiresSec: number;
         method: "GET" | "PUT";
     }): Promise<string>;
+    /**
+     * Stream a body into the store, computing sha256 and the byte count on the way. Aborts and removes the
+     * partial object (blob_too_large) when the body would exceed `maxBytes`.
+     */
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    /** Rejects with code `not_found` when the key does not exist. */
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    /** Null when the key does not exist. */
+    head(key: string): Promise<BlobInfo | null>;
 }
+/** Throws invalid_key unless the key matches the allowed pattern and has no empty, `.` or `..` segment (so no `//` or trailing `/`). */
+export declare function assertValidBlobKey(key: string): void;

package/dist/providers/storage/types.js

@@ -1,7 +1,24 @@
 /**
- * Storage seam — object/blob storage (email attachments, run artifacts).
+ * Storage seam — object/blob storage (run dependency snapshots today).
  *
- * Default adapter: LocalBlobStore (filesystem).
- * Native adapter:  S3BlobStore (S3 or S3-compatible object storage).
+ * Adapters: LocalBlobStore (filesystem), plus cloud object stores (GCS, S3).
+ * Failures carry a stable `code` (see BlobStoreError).
  */
-export {};
+/** An error with a stable machine-readable `code`; the message is the code unless more detail helps. */
+export class BlobStoreError extends Error {
+    code;
+    constructor(code, message = code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "BlobStoreError";
+    }
+}
+const KEY_PATTERN = /^[a-z0-9][a-z0-9/_.-]{0,500}$/;
+/** Throws invalid_key unless the key matches the allowed pattern and has no empty, `.` or `..` segment (so no `//` or trailing `/`). */
+export function assertValidBlobKey(key) {
+    if (typeof key !== "string" ||
+        !KEY_PATTERN.test(key) ||
+        key.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new BlobStoreError("invalid_key");
+    }
+}

package/dist/providers/vcs/git.d.ts

@@ -1,12 +1,16 @@
-import { type RepositoryFileInput } from "./github.js";
-import type { GitRemote } from "./remote.js";
-import type { ContinuationFinishedDetails, ContinuationOutcome, FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
+import type { RepositoryFileInput } from "./types.js";
+import { type GitRemote } from "./remote.js";
+import type { ContinuationFinishedDetails, ContinuationOutcome, ContinuationTarget, DescriptionWriteOutcome, FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
 export declare const DEFAULT_MAX_CHANGED_FILES = 1000;
 export declare const DEFAULT_MAX_DIFF_BYTES: number;
 export interface GitCommandOptions {
     cwd?: string;
     authToken?: string;
+    /** The username git sends with the token (default: git-askpass.sh's GitHub default). Not secret. */
+    authUsername?: string;
     maxOutputBytes?: number;
+    /** Non-zero exit codes that still resolve with the output (`merge-tree` exits 1 on conflicts). */
+    acceptExitCodes?: readonly number[];
 }
 export interface GitCommandResult {
     stdout: string;
@@ -66,21 +70,50 @@ export declare class GitVcsProvider implements VcsProvider {
     prepareWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace>;
     recoverWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace | null>;
     finalizeChanges(workspace: PreparedWorkspace, details?: FinalizeChangesDetails): Promise<FinalizeChangesResult>;
+    /** The two-parent merge commit (baseCommit, the target) of the staged tree, as the Wardby identity. */
+    private commitMerge;
+    /** Re-derive a continuation's PR description without a push, delegated to the remote; never throws. */
+    refreshPullRequestDescription(workspace: ContinuationTarget, details: FinalizeChangesDetails): Promise<DescriptionWriteOutcome | undefined>;
     cleanup(workspace: PreparedWorkspace): Promise<void>;
     /**
      * Best-effort "wardby is working on this PR" signal (see VcsProvider),
      * delegated to the remote; a remote without one is a no-op. Wrapped so
      * this can NEVER throw or otherwise affect the real coding run.
      */
+    /** Delegated to the remote; never throws (undefined on any failure). */
+    continuationPullRequestDraft(workspace: PreparedWorkspace): Promise<boolean | undefined>;
     notifyContinuationStarted(workspace: PreparedWorkspace, details?: {
         agentName?: string;
     }): Promise<void>;
     /** Companion to notifyContinuationStarted, delegated to the remote under the same never-throw contract. */
-    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    notifyContinuationFinished(workspace: ContinuationTarget, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
     readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
     private validateInput;
     private expectedPaths;
     private validatePrepared;
+    /**
+     * Fetches a continuation's target branch from the same `origin` the clone
+     * came from (never another URL, so never a fork) and deepens the depth-1
+     * clone step by step until the head and the target share a merge base.
+     * Returns true once they do; throws vcs_target_merge_failed when the fetch
+     * fails or no merge base turns up within MERGE_BASE_DEEPEN_STEPS.
+     */
+    private fetchMergeTarget;
+    /**
+     * Merges the fetched target into baseCommit without touching the index or
+     * the working tree (`merge-tree --write-tree`: no MERGE_HEAD, no hooks, no
+     * merge drivers -- none are configured), and records the result as the merge
+     * state. Null when the target is already part of the branch (nothing to merge).
+     */
+    private mergeTargetBranch;
+    /** The recorded merge state (see MERGE_STATE_REF), validated, or undefined when the workspace merged nothing. */
+    private readMergeState;
+    /**
+     * Refuses to finalize while a file the merge left conflicted still holds a
+     * conflict marker pair. Only those files are read: elsewhere a line of
+     * `<<<<<<<` may be legitimate content (a fixture, a doc about merging).
+     */
+    private assertConflictsResolved;
     private inspectWorkspace;
     private assertRemote;
     /**
@@ -96,6 +129,8 @@ export declare class GitVcsProvider implements VcsProvider {
      * problem).
      */
     private assertSafeLocalConfig;
+    /** The git credentials for a remote's access token; none when the remote needs no token. */
+    private gitAuth;
     private pushOnce;
     private remoteHead;
     private revParse;