@pierre/storage 1.0.3 → 1.2.0

package/README.md

@@ -72,6 +72,22 @@ if (foundRepo) {
 }
 ```
 
+### Hydrating a Repository Without a Request
+
+If you already know the repo metadata, you can construct a `Repo` directly:
+
+```typescript
+const repo = store.repo({
+  id: 'repo-id',
+  defaultBranch: 'main',
+  createdAt: '2024-06-15T12:00:00Z',
+});
+
+// No HTTP request is made by repo()
+const url = await repo.getRemoteURL();
+console.log(url);
+```
+
 ### Grep
 
 ```typescript
@@ -166,6 +182,13 @@ const files = await repo.listFiles({
 });
 console.log(files.paths); // Array of file paths
 
+// List files with mode/size and last commit metadata
+const metadata = await repo.listFilesWithMetadata({
+  ref: 'main',
+});
+console.log(metadata.files[0].lastCommitSha);
+console.log(metadata.commits[metadata.files[0].lastCommitSha].author);
+
 // List branches
 const branches = await repo.listBranches({
   limit: 10,
@@ -363,6 +386,7 @@ class GitStorage {
   constructor(options: GitStorageOptions);
   async createRepo(options?: CreateRepoOptions): Promise<Repo>;
   async findOne(options: FindOneOptions): Promise<Repo | null>;
+  repo(options: RepoOptions): Repo;
   getConfig(): GitStorageOptions;
 }
 ```
@@ -400,6 +424,12 @@ interface FindOneOptions {
   id: string; // Repository ID to find
 }
 
+interface RepoOptions {
+  id: string; // Repository ID
+  defaultBranch?: string; // Defaults to "main"
+  createdAt?: string; // Defaults to ""
+}
+
 interface Repo {
   id: string;
   getRemoteURL(options?: GetRemoteURLOptions): Promise<string>;
@@ -408,6 +438,9 @@ interface Repo {
   getFileStream(options: GetFileOptions): Promise<Response>;
   getArchiveStream(options?: ArchiveOptions): Promise<Response>;
   listFiles(options?: ListFilesOptions): Promise<ListFilesResult>;
+  listFilesWithMetadata(
+    options?: ListFilesWithMetadataOptions
+  ): Promise<ListFilesWithMetadataResult>;
   listBranches(options?: ListBranchesOptions): Promise<ListBranchesResult>;
   listCommits(options?: ListCommitsOptions): Promise<ListCommitsResult>;
   getNote(options: GetNoteOptions): Promise<GetNoteResult>;
@@ -444,6 +477,7 @@ interface ArchiveOptions {
 
 interface ListFilesOptions {
   ref?: string; // Branch, tag, or commit SHA
+  ephemeral?: boolean; // Resolve ref in ephemeral namespace
   ttl?: number;
 }
 
@@ -457,6 +491,32 @@ interface ListFilesResult {
   ref: string;
 }
 
+interface ListFilesWithMetadataOptions {
+  ref?: string; // Branch, tag, or commit SHA
+  ephemeral?: boolean; // Resolve ref in ephemeral namespace
+  ttl?: number;
+}
+
+interface FileWithMetadata {
+  path: string;
+  mode: string;
+  size: number;
+  lastCommitSha: string;
+}
+
+interface CommitMetadata {
+  author: string;
+  date: Date;
+  rawDate: string;
+  message: string;
+}
+
+interface ListFilesWithMetadataResult {
+  files: FileWithMetadata[];
+  commits: Record<string, CommitMetadata>;
+  ref: string;
+}
+
 interface GetNoteOptions {
   sha: string; // Commit SHA to look up notes for
   ttl?: number;

package/dist/index.cjs

@@ -51,6 +51,22 @@ var listFilesResponseSchema = zod.z.object({
   paths: zod.z.array(zod.z.string()),
   ref: zod.z.string()
 });
+var fileWithMetadataRawSchema = zod.z.object({
+  path: zod.z.string(),
+  mode: zod.z.string(),
+  size: zod.z.number(),
+  last_commit_sha: zod.z.string()
+});
+var commitMetadataRawSchema = zod.z.object({
+  author: zod.z.string(),
+  date: zod.z.string(),
+  message: zod.z.string()
+});
+var listFilesWithMetadataResponseSchema = zod.z.object({
+  files: zod.z.array(fileWithMetadataRawSchema),
+  commits: zod.z.record(commitMetadataRawSchema),
+  ref: zod.z.string()
+});
 var branchInfoSchema = zod.z.object({
   cursor: zod.z.string(),
   name: zod.z.string(),
@@ -514,7 +530,7 @@ function concatChunks(a, b) {
 
 // package.json
 var package_default = {
-  version: "1.0.3"};
+  version: "1.2.0"};
 
 // src/version.ts
 var PACKAGE_NAME = "code-storage-sdk";
@@ -1567,6 +1583,33 @@ function transformListCommitsResult(raw) {
     hasMore: raw.has_more
   };
 }
+function transformFileWithMetadata(raw) {
+  return {
+    path: raw.path,
+    mode: raw.mode,
+    size: raw.size,
+    lastCommitSha: raw.last_commit_sha
+  };
+}
+function transformCommitMetadata(raw) {
+  return {
+    author: raw.author,
+    date: new Date(raw.date),
+    rawDate: raw.date,
+    message: raw.message
+  };
+}
+function transformListFilesWithMetadataResult(raw) {
+  const commits = {};
+  for (const [sha, commit] of Object.entries(raw.commits)) {
+    commits[sha] = transformCommitMetadata(commit);
+  }
+  return {
+    files: raw.files.map(transformFileWithMetadata),
+    commits,
+    ref: raw.ref
+  };
+}
 function normalizeDiffState(rawState) {
   if (!rawState) {
     return "unknown";
@@ -1851,6 +1894,29 @@ var RepoImpl = class {
     const raw = listFilesResponseSchema.parse(await response.json());
     return { paths: raw.paths, ref: raw.ref };
   }
+  async listFilesWithMetadata(options) {
+    const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
+    const jwt = await this.generateJWT(this.id, {
+      permissions: ["git:read"],
+      ttl
+    });
+    const params = {};
+    if (options?.ref) {
+      params.ref = options.ref;
+    }
+    if (typeof options?.ephemeral === "boolean") {
+      params.ephemeral = String(options.ephemeral);
+    }
+    const response = await this.api.get(
+      {
+        path: "repos/files/metadata",
+        params: Object.keys(params).length ? params : void 0
+      },
+      jwt
+    );
+    const raw = listFilesWithMetadataResponseSchema.parse(await response.json());
+    return transformListFilesWithMetadataResult(raw);
+  }
   async listBranches(options) {
     const ttl = resolveInvocationTtlSeconds(options, DEFAULT_TOKEN_TTL_SECONDS);
     const jwt = await this.generateJWT(this.id, {
@@ -2418,13 +2484,11 @@ var GitStorage = class _GitStorage {
     if (resp.status === 409) {
       throw new Error("Repository already exists");
     }
-    return new RepoImpl(
-      repoId,
-      resolvedDefaultBranch ?? "main",
-      (/* @__PURE__ */ new Date()).toISOString(),
-      this.options,
-      this.generateJWT.bind(this)
-    );
+    return this.repo({
+      id: repoId,
+      defaultBranch: resolvedDefaultBranch ?? "main",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
   }
   /**
    * List repositories for the authenticated organization
@@ -2470,10 +2534,23 @@ var GitStorage = class _GitStorage {
     const body = await resp.json();
     const defaultBranch = body.default_branch ?? "main";
     const createdAt = body.created_at ?? "";
+    return this.repo({
+      id: options.id,
+      defaultBranch,
+      createdAt
+    });
+  }
+  /**
+   * Create a Repo handle from known metadata without making an HTTP request.
+   */
+  repo(options) {
+    if (!options || typeof options.id !== "string" || options.id.trim() === "") {
+      throw new Error("repo requires a non-empty repository id.");
+    }
     return new RepoImpl(
       options.id,
-      defaultBranch,
-      createdAt,
+      options.defaultBranch ?? "main",
+      options.createdAt ?? "",
       this.options,
       this.generateJWT.bind(this)
     );