@pierre/storage 0.7.0 → 0.9.0

package/README.md

@@ -40,6 +40,16 @@ console.log(repo.id); // e.g., '123e4567-e89b-12d3-a456-426614174000'
 // Create a repository with custom ID
 const customRepo = await store.createRepo({ id: 'my-custom-repo' });
 console.log(customRepo.id); // 'my-custom-repo'
+
+// Create a repository by forking an existing repo
+const forkedRepo = await store.createRepo({
+  id: 'my-fork', // optional
+  baseRepo: {
+    id: 'my-template-id',
+    ref: 'main', // optional
+  },
+});
+// If defaultBranch is omitted, the SDK returns "main".
 ```
 
 ### Finding a Repository
@@ -116,6 +126,10 @@ const repo = await store.createRepo();
 // or
 const repo = await store.findOne({ id: 'existing-repo-id' });
 
+// List repositories for the org
+const repos = await store.listRepos({ limit: 20 });
+console.log(repos.repos);
+
 // Get file content (streaming)
 const resp = await repo.getFileStream({
   path: 'README.md',
@@ -145,6 +159,27 @@ const commits = await repo.listCommits({
 });
 console.log(commits.commits);
 
+// Read a git note for a commit
+const note = await repo.getNote({ sha: 'abc123...' });
+console.log(note.note);
+
+// Add a git note
+const noteResult = await repo.createNote({
+  sha: 'abc123...',
+  note: 'Release QA approved',
+  author: { name: 'Release Bot', email: 'release@example.com' },
+});
+console.log(noteResult.newRefSha);
+
+// Append to an existing git note
+await repo.appendNote({
+  sha: 'abc123...',
+  note: 'Follow-up review complete',
+});
+
+// Delete a git note
+await repo.deleteNote({ sha: 'abc123...' });
+
 // Get branch diff
 const branchDiff = await repo.getBranchDiff({
   branch: 'feature-branch',
@@ -312,6 +347,19 @@ interface GitStorageOptions {
 
 interface CreateRepoOptions {
   id?: string; // Optional custom repository ID
+  baseRepo?:
+    | {
+        id: string; // Fork source repo ID
+        ref?: string; // Optional ref to fork from
+        sha?: string; // Optional commit SHA to fork from
+      }
+    | {
+        owner: string; // GitHub owner
+        name: string; // GitHub repository name
+        defaultBranch?: string;
+        provider?: 'github';
+      };
+  defaultBranch?: string; // Optional default branch name (defaults to "main")
 }
 
 interface FindOneOptions {
@@ -327,6 +375,10 @@ interface Repo {
   listFiles(options?: ListFilesOptions): Promise<ListFilesResult>;
   listBranches(options?: ListBranchesOptions): Promise<ListBranchesResult>;
   listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult>;
+  getNote(options: GetNoteOptions): Promise<GetNoteResult>;
+  createNote(options: CreateNoteOptions): Promise<NoteWriteResult>;
+  appendNote(options: AppendNoteOptions): Promise<NoteWriteResult>;
+  deleteNote(options: DeleteNoteOptions): Promise<NoteWriteResult>;
   getBranchDiff(options: GetBranchDiffOptions): Promise<GetBranchDiffResult>;
   getCommitDiff(options: GetCommitDiffOptions): Promise<GetCommitDiffResult>;
 }
@@ -360,6 +412,52 @@ interface ListFilesResult {
   ref: string;
 }
 
+interface GetNoteOptions {
+  sha: string; // Commit SHA to look up notes for
+  ttl?: number;
+}
+
+interface GetNoteResult {
+  sha: string;
+  note: string;
+  refSha: string;
+}
+
+interface CreateNoteOptions {
+  sha: string;
+  note: string;
+  expectedRefSha?: string;
+  author?: { name: string; email: string };
+  ttl?: number;
+}
+
+interface AppendNoteOptions {
+  sha: string;
+  note: string;
+  expectedRefSha?: string;
+  author?: { name: string; email: string };
+  ttl?: number;
+}
+
+interface DeleteNoteOptions {
+  sha: string;
+  expectedRefSha?: string;
+  author?: { name: string; email: string };
+  ttl?: number;
+}
+
+interface NoteWriteResult {
+  sha: string;
+  targetRef: string;
+  baseCommit?: string;
+  newRefSha: string;
+  result: {
+    success: boolean;
+    status: string;
+    message?: string;
+  };
+}
+
 interface ListBranchesOptions {
   cursor?: string;
   limit?: number;

package/dist/index.cjs

@@ -76,6 +76,40 @@ var listCommitsResponseSchema = zod.z.object({
   next_cursor: zod.z.string().nullable().optional(),
   has_more: zod.z.boolean()
 });
+var repoBaseInfoSchema = zod.z.object({
+  provider: zod.z.string(),
+  owner: zod.z.string(),
+  name: zod.z.string()
+});
+var repoInfoSchema = zod.z.object({
+  repo_id: zod.z.string(),
+  url: zod.z.string(),
+  default_branch: zod.z.string(),
+  created_at: zod.z.string(),
+  base_repo: repoBaseInfoSchema.optional().nullable()
+});
+var listReposResponseSchema = zod.z.object({
+  repos: zod.z.array(repoInfoSchema),
+  next_cursor: zod.z.string().nullable().optional(),
+  has_more: zod.z.boolean()
+});
+var noteReadResponseSchema = zod.z.object({
+  sha: zod.z.string(),
+  note: zod.z.string(),
+  ref_sha: zod.z.string()
+});
+var noteResultSchema = zod.z.object({
+  success: zod.z.boolean(),
+  status: zod.z.string(),
+  message: zod.z.string().optional()
+});
+var noteWriteResponseSchema = zod.z.object({
+  sha: zod.z.string(),
+  target_ref: zod.z.string(),
+  base_commit: zod.z.string().optional(),
+  new_ref_sha: zod.z.string(),
+  result: noteResultSchema
+});
 var diffStatsSchema = zod.z.object({
   files: zod.z.number(),
   additions: zod.z.number(),
@@ -472,7 +506,7 @@ function concatChunks(a, b) {
 
 // package.json
 var package_default = {
-  version: "0.7.0"};
+  version: "0.9.0"};
 
 // src/version.ts
 var PACKAGE_NAME = "code-storage-sdk";
@@ -1364,6 +1398,36 @@ var RESTORE_COMMIT_ALLOWED_STATUS = [
   504
   // Gateway Timeout - long-running storage operations
 ];
+var NOTE_WRITE_ALLOWED_STATUS = [
+  400,
+  // Bad Request - validation errors
+  401,
+  // Unauthorized - missing/invalid auth header
+  403,
+  // Forbidden - missing git:write scope
+  404,
+  // Not Found - repo or note lookup failures
+  408,
+  // Request Timeout - client cancelled
+  409,
+  // Conflict - concurrent ref updates
+  412,
+  // Precondition Failed - optimistic concurrency
+  422,
+  // Unprocessable Entity - metadata issues
+  429,
+  // Too Many Requests - upstream throttling
+  499,
+  // Client Closed Request - storage cancellation
+  500,
+  // Internal Server Error - generic failure
+  502,
+  // Bad Gateway - storage/gateway bridge issues
+  503,
+  // Service Unavailable - storage selection failures
+  504
+  // Gateway Timeout - long-running storage operations
+];
 function resolveInvocationTtlSeconds(options, defaultValue = DEFAULT_TOKEN_TTL_SECONDS) {
   if (typeof options?.ttl === "number" && options.ttl > 0) {
     return options.ttl;
@@ -1551,6 +1615,23 @@ function transformCreateBranchResult(raw) {
     commitSha: raw.commit_sha ?? void 0
   };
 }
+function transformListReposResult(raw) {
+  return {
+    repos: raw.repos.map((repo) => ({
+      repoId: repo.repo_id,
+      url: repo.url,
+      defaultBranch: repo.default_branch,
+      createdAt: repo.created_at,
+      baseRepo: repo.base_repo ? {
+        provider: repo.base_repo.provider,
+        owner: repo.base_repo.owner,
+        name: repo.base_repo.name
+      } : void 0
+    })),
+    nextCursor: raw.next_cursor ?? void 0,
+    hasMore: raw.has_more
+  };
+}
 function transformGrepLine(raw) {
   return {
     lineNumber: raw.line_number,
@@ -1564,6 +1645,88 @@ function transformGrepFileMatch(raw) {
     lines: raw.lines.map(transformGrepLine)
   };
 }
+function transformNoteReadResult(raw) {
+  return {
+    sha: raw.sha,
+    note: raw.note,
+    refSha: raw.ref_sha
+  };
+}
+function transformNoteWriteResult(raw) {
+  return {
+    sha: raw.sha,
+    targetRef: raw.target_ref,
+    baseCommit: raw.base_commit,
+    newRefSha: raw.new_ref_sha,
+    result: {
+      success: raw.result.success,
+      status: raw.result.status,
+      message: raw.result.message
+    }
+  };
+}
+function buildNoteWriteBody(sha, note, action, options) {
+  const body = {
+    sha,
+    action,
+    note
+  };
+  const expectedRefSha = options.expectedRefSha?.trim();
+  if (expectedRefSha) {
+    body.expected_ref_sha = expectedRefSha;
+  }
+  if (options.author) {
+    const authorName = options.author.name?.trim();
+    const authorEmail = options.author.email?.trim();
+    if (!authorName || !authorEmail) {
+      throw new Error("note author name and email are required when provided");
+    }
+    body.author = {
+      name: authorName,
+      email: authorEmail
+    };
+  }
+  return body;
+}
+async function parseNoteWriteResponse(response, method) {
+  let jsonBody;
+  const contentType = response.headers.get("content-type") ?? "";
+  try {
+    if (contentType.includes("application/json")) {
+      jsonBody = await response.json();
+    } else {
+      jsonBody = await response.text();
+    }
+  } catch {
+    jsonBody = void 0;
+  }
+  if (jsonBody && typeof jsonBody === "object") {
+    const parsed = noteWriteResponseSchema.safeParse(jsonBody);
+    if (parsed.success) {
+      return transformNoteWriteResult(parsed.data);
+    }
+    const parsedError = errorEnvelopeSchema.safeParse(jsonBody);
+    if (parsedError.success) {
+      throw new ApiError({
+        message: parsedError.data.error,
+        status: response.status,
+        statusText: response.statusText,
+        method,
+        url: response.url,
+        body: jsonBody
+      });
+    }
+  }
+  const fallbackMessage = typeof jsonBody === "string" && jsonBody.trim() !== "" ? jsonBody.trim() : `Request ${method} ${response.url} failed with status ${response.status} ${response.statusText}`;
+  throw new ApiError({
+    message: fallbackMessage,
+    status: response.status,
+    statusText: response.statusText,
+    method,
+    url: response.url,
+    body: jsonBody
+  });
+}
 var RepoImpl = class {
   constructor(id, defaultBranch, options, generateJWT) {
     this.id = id;
@@ -1679,6 +1842,132 @@ var RepoImpl = class {
       next_cursor: raw.next_cursor ?? void 0
     });
   }
+  async getNote(options) {
+    const sha = options?.sha?.trim();
+    if (!sha) {
+      throw new Error("getNote sha is required");
+    }
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ["git:read"],
+      ttl
+    });
+    const response = await this.api.get({ path: "repos/notes", params: { sha } }, jwt);
+    const raw = noteReadResponseSchema.parse(await response.json());
+    return transformNoteReadResult(raw);
+  }
+  async createNote(options) {
+    const sha = options?.sha?.trim();
+    if (!sha) {
+      throw new Error("createNote sha is required");
+    }
+    const note = options?.note?.trim();
+    if (!note) {
+      throw new Error("createNote note is required");
+    }
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ["git:write"],
+      ttl
+    });
+    const body = buildNoteWriteBody(sha, note, "add", {
+      expectedRefSha: options.expectedRefSha,
+      author: options.author
+    });
+    const response = await this.api.post({ path: "repos/notes", body }, jwt, {
+      allowedStatus: [...NOTE_WRITE_ALLOWED_STATUS]
+    });
+    const result = await parseNoteWriteResponse(response, "POST");
+    if (!result.result.success) {
+      throw new RefUpdateError(
+        result.result.message ?? `createNote failed with status ${result.result.status}`,
+        {
+          status: result.result.status,
+          message: result.result.message,
+          refUpdate: toPartialRefUpdate(result.targetRef, result.baseCommit, result.newRefSha)
+        }
+      );
+    }
+    return result;
+  }
+  async appendNote(options) {
+    const sha = options?.sha?.trim();
+    if (!sha) {
+      throw new Error("appendNote sha is required");
+    }
+    const note = options?.note?.trim();
+    if (!note) {
+      throw new Error("appendNote note is required");
+    }
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ["git:write"],
+      ttl
+    });
+    const body = buildNoteWriteBody(sha, note, "append", {
+      expectedRefSha: options.expectedRefSha,
+      author: options.author
+    });
+    const response = await this.api.post({ path: "repos/notes", body }, jwt, {
+      allowedStatus: [...NOTE_WRITE_ALLOWED_STATUS]
+    });
+    const result = await parseNoteWriteResponse(response, "POST");
+    if (!result.result.success) {
+      throw new RefUpdateError(
+        result.result.message ?? `appendNote failed with status ${result.result.status}`,
+        {
+          status: result.result.status,
+          message: result.result.message,
+          refUpdate: toPartialRefUpdate(result.targetRef, result.baseCommit, result.newRefSha)
+        }
+      );
+    }
+    return result;
+  }
+  async deleteNote(options) {
+    const sha = options?.sha?.trim();
+    if (!sha) {
+      throw new Error("deleteNote sha is required");
+    }
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ["git:write"],
+      ttl
+    });
+    const body = {
+      sha
+    };
+    const expectedRefSha = options.expectedRefSha?.trim();
+    if (expectedRefSha) {
+      body.expected_ref_sha = expectedRefSha;
+    }
+    if (options.author) {
+      const authorName = options.author.name?.trim();
+      const authorEmail = options.author.email?.trim();
+      if (!authorName || !authorEmail) {
+        throw new Error("deleteNote author name and email are required when provided");
+      }
+      body.author = {
+        name: authorName,
+        email: authorEmail
+      };
+    }
+    const response = await this.api.delete({ path: "repos/notes", body }, jwt, {
+      allowedStatus: [...NOTE_WRITE_ALLOWED_STATUS]
+    });
+    const result = await parseNoteWriteResponse(response, "DELETE");
+    if (!result.result.success) {
+      throw new RefUpdateError(
+        result.result.message ?? `deleteNote failed with status ${result.result.status}`,
+        {
+          status: result.result.status,
+          message: result.result.message,
+          refUpdate: toPartialRefUpdate(result.targetRef, result.baseCommit, result.newRefSha)
+        }
+      );
+    }
+    return result;
+  }
   async getBranchDiff(options) {
     const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
     const jwt = await this.generateJWT(this.id, {
@@ -1984,23 +2273,83 @@ var GitStorage = class _GitStorage {
       permissions: ["repo:write"],
       ttl
     });
-    const baseRepoOptions = options?.baseRepo ? {
-      provider: "github",
-      ...snakecaseKeys__default.default(options.baseRepo)
-    } : null;
-    const defaultBranch = options?.baseRepo?.defaultBranch ?? options?.defaultBranch ?? "main";
-    const createRepoPath = baseRepoOptions || defaultBranch ? {
+    const baseRepo = options?.baseRepo;
+    const isFork = baseRepo ? "id" in baseRepo : false;
+    let baseRepoOptions = null;
+    let resolvedDefaultBranch;
+    if (baseRepo) {
+      if ("id" in baseRepo) {
+        const baseRepoToken = await this.generateJWT(baseRepo.id, {
+          permissions: ["git:read"],
+          ttl
+        });
+        baseRepoOptions = {
+          provider: "code",
+          name: baseRepo.id,
+          operation: "fork",
+          auth: { token: baseRepoToken },
+          ...baseRepo.ref ? { ref: baseRepo.ref } : {},
+          ...baseRepo.sha ? { sha: baseRepo.sha } : {}
+        };
+      } else {
+        baseRepoOptions = {
+          provider: "github",
+          ...snakecaseKeys__default.default(baseRepo)
+        };
+        resolvedDefaultBranch = baseRepo.defaultBranch;
+      }
+    }
+    if (!resolvedDefaultBranch) {
+      if (options?.defaultBranch) {
+        resolvedDefaultBranch = options.defaultBranch;
+      } else if (!isFork) {
+        resolvedDefaultBranch = "main";
+      }
+    }
+    const createRepoPath = baseRepoOptions || resolvedDefaultBranch ? {
       path: "repos",
       body: {
         ...baseRepoOptions && { base_repo: baseRepoOptions },
-        default_branch: defaultBranch
+        ...resolvedDefaultBranch && { default_branch: resolvedDefaultBranch }
       }
     } : "repos";
     const resp = await this.api.post(createRepoPath, jwt, { allowedStatus: [409] });
     if (resp.status === 409) {
       throw new Error("Repository already exists");
     }
-    return new RepoImpl(repoId, defaultBranch, this.options, this.generateJWT.bind(this));
+    return new RepoImpl(
+      repoId,
+      resolvedDefaultBranch ?? "main",
+      this.options,
+      this.generateJWT.bind(this)
+    );
+  }
+  /**
+   * List repositories for the authenticated organization
+   * @returns Paginated repositories list
+   */
+  async listRepos(options) {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT("org", {
+      permissions: ["org:read"],
+      ttl
+    });
+    let params;
+    if (options?.cursor || typeof options?.limit === "number") {
+      params = {};
+      if (options.cursor) {
+        params.cursor = options.cursor;
+      }
+      if (typeof options.limit === "number") {
+        params.limit = options.limit.toString();
+      }
+    }
+    const response = await this.api.get({ path: "repos", params }, jwt);
+    const raw = listReposResponseSchema.parse(await response.json());
+    return transformListReposResult({
+      ...raw,
+      next_cursor: raw.next_cursor ?? void 0
+    });
   }
   /**
    * Find a repository by ID