@pierre/storage 0.1.1 → 0.1.3

package/README.md

@@ -2,6 +2,14 @@
 
 Pierre Git Storage SDK for TypeScript/JavaScript applications.
 
+## End-to-End Smoke Test
+
+- `node packages/git-storage-sdk/tests/full-workflow.js -e production -s pierre -k /home/ian/pierre-prod-key.pem`  
+  Drives
+  the Pierre workflow via the SDK: creates a repository, writes commits, fetches branch and diff
+  data, and confirms storage APIs. Swap in your own private key path when running outside this
+  workstation and adjust `-e`/`-s` for non-production environments.
+
 ## Installation
 
 ```bash
@@ -125,7 +133,7 @@ console.log(commitDiff.files);
 const fs = await import('node:fs/promises');
 const result = await repo
   .createCommit({
-    targetRef: 'refs/heads/main',
+    targetBranch: 'main',
     commitMessage: 'Update docs',
     author: { name: 'Docs Bot', email: 'docs@example.com' },
   })
@@ -154,37 +162,44 @@ The builder exposes:
 type CommitResult = {
   commitSha: string;
   treeSha: string;
-  targetRef: string;
+  targetBranch: string;
   packBytes: number;
   blobCount: number;
   refUpdate: {
-    ref: string;
+    branch: string;
     oldSha: string; // All zeroes when the ref is created
     newSha: string;
   };
 };
 ```
 
-If the backend reports a failure (for example, the branch advanced past `baseRef`) the builder
-throws a `RefUpdateError` containing the status, reason, and ref details.
+If the backend reports a failure (for example, the branch advanced past `expectedHeadSha`) the
+builder throws a `RefUpdateError` containing the status, reason, and ref details.
 
 **Options**
 
-- `targetRef` (required): Fully qualified ref that will receive the commit (for example
-  `refs/heads/main`).
-- `baseRef` (optional): Branch or commit that must match the remote tip; omit to fast-forward
+- `targetBranch` (required): Branch name (for example `main`) that will receive the commit.
+- `expectedHeadSha` (optional): Commit SHA that must match the remote tip; omit to fast-forward
   unconditionally.
+- `baseBranch` (optional): Mirrors the `base_branch` metadata and names an existing branch whose tip
+  should seed `targetBranch` if it does not exist. Leave `expectedHeadSha` empty when creating a new
+  branch from `baseBranch`; when both are provided and the branch already exists, `expectedHeadSha`
+  continues to enforce the fast-forward guard.
 - `commitMessage` (required): The commit message.
 - `author` (required): Include `name` and `email` for the commit author.
 - `committer` (optional): Include `name` and `email`. If omitted, the author identity is reused.
 - `signal` (optional): Abort an in-flight upload with `AbortController`.
+- `targetRef` (deprecated, optional): Fully qualified ref (for example `refs/heads/main`). Prefer
+  `targetBranch`, which now accepts plain branch names.
 
 > Files are chunked into 4 MiB segments under the hood, so you can stream large assets without
 > buffering them entirely in memory. File paths are normalized relative to the repository root.
 
-> The `targetRef` must already exist on the remote repository. To seed an empty repository, point to
-> the default branch and omit `baseRef`; the service will create the first commit only when no refs
-> are present.
+> The `targetBranch` must already exist on the remote repository unless you provide `baseBranch` (or
+> the repository has no refs). To seed an empty repository, point to the default branch and omit
+> `expectedHeadSha`. To create a missing branch within an existing repository, set `baseBranch` to
+> the source branch and omit `expectedHeadSha` so the service clones that tip before applying your
+> changes.
 
 ### Streaming Large Files
 
@@ -196,8 +211,8 @@ import { createReadStream } from 'node:fs';
 
 await repo
   .createCommit({
-    targetRef: 'refs/heads/assets',
-    baseRef: 'refs/heads/main',
+    targetBranch: 'assets',
+    expectedHeadSha: 'abc123def4567890abc123def4567890abc12345',
     commitMessage: 'Upload latest design bundle',
     author: { name: 'Assets Uploader', email: 'assets@example.com' },
   })
@@ -417,7 +432,7 @@ interface FilteredFile {
 }
 
 interface RefUpdate {
-  ref: string;
+  branch: string;
   oldSha: string;
   newSha: string;
 }
@@ -425,7 +440,7 @@ interface RefUpdate {
 interface CommitResult {
   commitSha: string;
   treeSha: string;
-  targetRef: string;
+  targetBranch: string;
   packBytes: number;
   blobCount: number;
   refUpdate: RefUpdate;

package/dist/index.cjs

@@ -157,6 +157,7 @@ var errorEnvelopeSchema = zod.z.object({
 // src/commit.ts
 var MAX_CHUNK_BYTES = 4 * 1024 * 1024;
 var DEFAULT_TTL_SECONDS = 60 * 60;
+var HEADS_REF_PREFIX = "refs/heads/";
 var BufferCtor = globalThis.Buffer;
 var CommitBuilderImpl = class {
   options;
@@ -165,26 +166,18 @@ var CommitBuilderImpl = class {
   operations = [];
   sent = false;
   constructor(deps) {
-    this.options = { ...deps.options };
+    this.options = normalizeCommitOptions(deps.options);
     this.getAuthToken = deps.getAuthToken;
     this.transport = deps.transport;
-    const trimmedTarget = this.options.targetBranch?.trim();
     const trimmedMessage = this.options.commitMessage?.trim();
     const trimmedAuthorName = this.options.author?.name?.trim();
     const trimmedAuthorEmail = this.options.author?.email?.trim();
-    if (!trimmedTarget) {
-      throw new Error("createCommit targetBranch is required");
-    }
-    if (trimmedTarget.startsWith("refs/")) {
-      throw new Error("createCommit targetBranch must not include refs/ prefix");
-    }
     if (!trimmedMessage) {
       throw new Error("createCommit commitMessage is required");
     }
     if (!trimmedAuthorName || !trimmedAuthorEmail) {
       throw new Error("createCommit author name and email are required");
     }
-    this.options.targetBranch = trimmedTarget;
     this.options.commitMessage = trimmedMessage;
     this.options.author = {
       name: trimmedAuthorName,
@@ -193,6 +186,17 @@ var CommitBuilderImpl = class {
     if (typeof this.options.expectedHeadSha === "string") {
       this.options.expectedHeadSha = this.options.expectedHeadSha.trim();
     }
+    if (typeof this.options.baseBranch === "string") {
+      const trimmedBase = this.options.baseBranch.trim();
+      if (trimmedBase === "") {
+        delete this.options.baseBranch;
+      } else {
+        if (trimmedBase.startsWith("refs/")) {
+          throw new Error("createCommit baseBranch must not include refs/ prefix");
+        }
+        this.options.baseBranch = trimmedBase;
+      }
+    }
   }
   addFile(path, source, options) {
     this.ensureNotSent();
@@ -277,6 +281,9 @@ var CommitBuilderImpl = class {
     if (this.options.expectedHeadSha) {
       metadata.expected_head_sha = this.options.expectedHeadSha;
     }
+    if (this.options.baseBranch) {
+      metadata.base_branch = this.options.baseBranch;
+    }
     if (this.options.committer) {
       metadata.committer = {
         name: this.options.committer.name,
@@ -557,6 +564,62 @@ function randomContentId() {
   const random = Math.random().toString(36).slice(2);
   return `cid-${Date.now().toString(36)}-${random}`;
 }
+function normalizeCommitOptions(options) {
+  return {
+    targetBranch: resolveTargetBranch(options),
+    commitMessage: options.commitMessage,
+    expectedHeadSha: options.expectedHeadSha,
+    baseBranch: options.baseBranch,
+    author: options.author,
+    committer: options.committer,
+    signal: options.signal,
+    ttl: options.ttl
+  };
+}
+function resolveTargetBranch(options) {
+  const branchCandidate = typeof options.targetBranch === "string" ? options.targetBranch.trim() : "";
+  if (branchCandidate) {
+    return normalizeBranchName(branchCandidate);
+  }
+  if (hasLegacyTargetRef(options)) {
+    return normalizeLegacyTargetRef(options.targetRef);
+  }
+  throw new Error("createCommit targetBranch is required");
+}
+function normalizeBranchName(value) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error("createCommit targetBranch is required");
+  }
+  if (trimmed.startsWith(HEADS_REF_PREFIX)) {
+    const branch = trimmed.slice(HEADS_REF_PREFIX.length).trim();
+    if (!branch) {
+      throw new Error("createCommit targetBranch is required");
+    }
+    return branch;
+  }
+  if (trimmed.startsWith("refs/")) {
+    throw new Error("createCommit targetBranch must not include refs/ prefix");
+  }
+  return trimmed;
+}
+function normalizeLegacyTargetRef(ref) {
+  const trimmed = ref.trim();
+  if (!trimmed) {
+    throw new Error("createCommit targetRef is required");
+  }
+  if (!trimmed.startsWith(HEADS_REF_PREFIX)) {
+    throw new Error("createCommit targetRef must start with refs/heads/");
+  }
+  const branch = trimmed.slice(HEADS_REF_PREFIX.length).trim();
+  if (!branch) {
+    throw new Error("createCommit targetRef must include a branch name");
+  }
+  return branch;
+}
+function hasLegacyTargetRef(options) {
+  return typeof options.targetRef === "string";
+}
 function createCommitBuilder(deps) {
   return new CommitBuilderImpl(deps);
 }
@@ -1377,9 +1440,13 @@ var RepoImpl = class {
         email: committerEmail
       };
     }
-    const response = await this.api.post({ path: "repos/reset-commits", body: { metadata } }, jwt, {
-      allowedStatus: [...RESTORE_COMMIT_ALLOWED_STATUS]
-    });
+    const response = await this.api.post(
+      { path: "repos/restore-commit", body: { metadata } },
+      jwt,
+      {
+        allowedStatus: [...RESTORE_COMMIT_ALLOWED_STATUS]
+      }
+    );
     const payload = await response.json();
     const parsed = parseRestoreCommitPayload(payload);
     if (parsed && "ack" in parsed) {