p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/src/setup/github-target-repository-provider-live.ts

@@ -0,0 +1,323 @@
+import { GitHubApiError, GitHubClient } from "../github/client.js";
+import type {
+  AuthenticatedGitHubUser,
+  CreateUserRepositoryResult,
+  GitHubRepositoryMetadata,
+  GitHubTokenCapabilitySummary,
+  GitRefResult,
+  GitTreeEntryInput,
+} from "./github-remote-provider.js";
+import {
+  assessPackagedProvisioningTokenCapabilities,
+  classicPatHasRepoScope,
+  classicPatHasWorkflowScope,
+  resolveGitHubTokenType,
+} from "./github-workflow-permissions.js";
+import type {
+  BootstrapCommitFile,
+  CreateTargetRepositoryInput,
+  GitHubTargetRepositoryProvider,
+} from "./github-target-repository-provider.js";
+import { isGitHubNotFoundError } from "./github-target-repository-provider.js";
+import type { RemoteAccessStatus } from "./remote-actions.js";
+
+function preserveGitHubSetupError(error: unknown): Error {
+  if (error instanceof GitHubApiError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(String(error));
+}
+
+function mapRepositoryToMetadata(
+  owner: string,
+  repo: string,
+  repository: import("../github/client.js").GitHubRepository,
+): GitHubRepositoryMetadata {
+  if (repository.id === undefined) {
+    throw new Error(`GitHub repository ${owner}/${repo} returned no repository ID.`);
+  }
+  return {
+    repositoryId: repository.id,
+    owner,
+    repo,
+    description: repository.description ?? null,
+    private: repository.private ?? false,
+    visibility: repository.visibility ?? (repository.private ? "private" : "public"),
+    isTemplate: repository.is_template ?? false,
+    defaultBranch: repository.default_branch ?? "main",
+    permissions: {
+      admin: repository.permissions?.admin ?? false,
+      maintain: repository.permissions?.maintain ?? false,
+      push: repository.permissions?.push ?? false,
+    },
+  };
+}
+
+export class LiveGitHubTargetRepositoryProvider
+  implements GitHubTargetRepositoryProvider
+{
+  constructor(private readonly client: GitHubClient) {}
+
+  async resolveAuthenticatedUser(): Promise<AuthenticatedGitHubUser> {
+    const user = await this.client.getAuthenticatedUser();
+    return { id: user.id, login: user.login };
+  }
+
+  async inspectTokenCapabilities(): Promise<GitHubTokenCapabilitySummary> {
+    const inspected = await this.client.inspectAuthenticatedUser();
+    const tokenType = resolveGitHubTokenType(
+      inspected.tokenType,
+      inspected.oauthScopes,
+    );
+    const metadata = {
+      login: inspected.login,
+      tokenType,
+      oauthScopes: inspected.oauthScopes,
+      hasWorkflowScope: classicPatHasWorkflowScope(inspected.oauthScopes),
+      hasRepoScope: classicPatHasRepoScope(inspected.oauthScopes),
+    };
+    const scopeAmbiguous =
+      tokenType === "classic" && metadata.oauthScopes.length === 0;
+    const assessment = assessPackagedProvisioningTokenCapabilities(metadata);
+    if (!assessment.ok) {
+      return {
+        login: inspected.login,
+        tokenType,
+        hasRepoScope: false,
+        hasWorkflowScope: false,
+        scopeAmbiguous,
+      };
+    }
+    return {
+      login: inspected.login,
+      tokenType,
+      hasRepoScope: metadata.hasRepoScope,
+      hasWorkflowScope: metadata.hasWorkflowScope,
+      scopeAmbiguous,
+    };
+  }
+
+  async checkRepositoryAvailability(
+    owner: string,
+    name: string,
+  ): Promise<"available" | "repository_already_exists" | "forbidden"> {
+    try {
+      const metadata = await this.getRepositoryMetadata(owner, name);
+      return metadata ? "repository_already_exists" : "available";
+    } catch (error) {
+      if (error instanceof GitHubApiError && error.status === 403) {
+        return "forbidden";
+      }
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async createPersonalRepository(
+    input: CreateTargetRepositoryInput,
+  ): Promise<CreateUserRepositoryResult> {
+    try {
+      const created = await this.client.createUserRepository({
+        name: input.name,
+        description: input.description ?? "",
+        private: input.visibility === "private",
+        autoInit: true,
+      });
+      return {
+        repositoryId: created.id,
+        fullName: created.full_name,
+        defaultBranch: created.default_branch,
+      };
+    } catch (error) {
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async getRepositoryMetadata(
+    owner: string,
+    repo: string,
+  ): Promise<GitHubRepositoryMetadata | null> {
+    try {
+      const repository = await this.client.getRepository(owner, repo);
+      return mapRepositoryToMetadata(owner, repo, repository);
+    } catch (error) {
+      if (isGitHubNotFoundError(error)) {
+        return null;
+      }
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async getRepositoryDefaultBranchHead(
+    owner: string,
+    repo: string,
+    branch: string,
+  ): Promise<string> {
+    const ref = await this.client.getBranchRef(owner, repo, branch);
+    return ref.object.sha;
+  }
+
+  async getGitRef(owner: string, repo: string, ref: string): Promise<GitRefResult> {
+    try {
+      const gitRef = await this.client.getGitRef(owner, repo, ref);
+      return {
+        ref: gitRef.ref,
+        object: { sha: gitRef.object.sha },
+      };
+    } catch (error) {
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async createGitRef(
+    owner: string,
+    repo: string,
+    branch: string,
+    sha: string,
+  ): Promise<GitRefResult> {
+    try {
+      const created = await this.client.createGitRef(owner, repo, branch, sha);
+      return {
+        ref: created.ref,
+        object: { sha: created.object.sha },
+      };
+    } catch (error) {
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async writeBootstrapCommit(input: {
+    owner: string;
+    repo: string;
+    branch: string;
+    parentSha: string;
+    files: BootstrapCommitFile[];
+    message: string;
+  }): Promise<{ commitSha: string }> {
+    try {
+      const parentCommit = await this.client.getGitCommit(
+        input.owner,
+        input.repo,
+        input.parentSha,
+      );
+      const treeEntries: GitTreeEntryInput[] = [];
+      for (const file of input.files) {
+        const blob = await this.client.createGitBlob({
+          owner: input.owner,
+          repo: input.repo,
+          content: Buffer.from(file.content, "utf8"),
+        });
+        treeEntries.push({
+          path: file.path,
+          mode: "100644",
+          type: "blob",
+          sha: blob.sha,
+        });
+      }
+      const tree = await this.client.createGitTree({
+        owner: input.owner,
+        repo: input.repo,
+        baseTree: parentCommit.tree.sha,
+        tree: treeEntries,
+      });
+      const commit = await this.client.createGitCommit({
+        owner: input.owner,
+        repo: input.repo,
+        message: input.message,
+        tree: tree.sha,
+        parents: [input.parentSha],
+      });
+      const currentRef = await this.client.getGitRef(
+        input.owner,
+        input.repo,
+        `heads/${input.branch}`,
+      );
+      if (currentRef.object.sha !== input.parentSha) {
+        throw new Error(
+          `Bootstrap ref update rejected: expected parent ${input.parentSha}, found ${currentRef.object.sha}.`,
+        );
+      }
+      await this.client.updateGitRef({
+        owner: input.owner,
+        repo: input.repo,
+        ref: `heads/${input.branch}`,
+        sha: commit.sha,
+      });
+      return { commitSha: commit.sha };
+    } catch (error) {
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async verifyRepositoryAccess(
+    owner: string,
+    repo: string,
+  ): Promise<RemoteAccessStatus> {
+    const metadata = await this.getRepositoryMetadata(owner, repo);
+    if (!metadata) {
+      return "unknown";
+    }
+    if (!metadata.permissions.push) {
+      return "denied";
+    }
+    return "available";
+  }
+
+  async ensureDefaultBranch(
+    owner: string,
+    repo: string,
+    branchName: string,
+  ): Promise<{ defaultBranch: string; corrected: boolean }> {
+    const metadata = await this.getRepositoryMetadata(owner, repo);
+    if (!metadata) {
+      throw new Error(`Repository ${owner}/${repo} was not found.`);
+    }
+    if (metadata.defaultBranch === branchName) {
+      return { defaultBranch: metadata.defaultBranch, corrected: false };
+    }
+    await this.client.updateUserRepository({
+      owner,
+      repo,
+      default_branch: branchName,
+    });
+    const updated = await this.getRepositoryMetadata(owner, repo);
+    return {
+      defaultBranch: updated?.defaultBranch ?? branchName,
+      corrected: true,
+    };
+  }
+
+  async verifyBranchExists(
+    owner: string,
+    repo: string,
+    branch: string,
+  ): Promise<boolean> {
+    try {
+      await this.getGitRef(owner, repo, branch);
+      return true;
+    } catch (error) {
+      if (isGitHubNotFoundError(error)) {
+        return false;
+      }
+      throw preserveGitHubSetupError(error);
+    }
+  }
+
+  async readRepositoryFileContent(
+    owner: string,
+    repo: string,
+    path: string,
+    ref: string,
+  ): Promise<string | null> {
+    const content = await this.client.getRepositoryContent(owner, repo, path, ref);
+    return content ? this.client.decodeRepositoryContent(content) : null;
+  }
+}
+
+export function createLiveGitHubTargetRepositoryProvider(
+  token: string,
+): LiveGitHubTargetRepositoryProvider {
+  return new LiveGitHubTargetRepositoryProvider(new GitHubClient({ token }));
+}

package/workspace-snapshot/files/src/setup/github-target-repository-provider-mock.ts

@@ -0,0 +1,284 @@
+import { createHash } from "node:crypto";
+import { GitHubApiError } from "../github/client.js";
+import type {
+  AuthenticatedGitHubUser,
+  CreateUserRepositoryResult,
+  GitHubRepositoryMetadata,
+  GitHubTokenCapabilitySummary,
+  GitRefResult,
+} from "./github-remote-provider.js";
+import {
+  createMockGitRepositoryStore,
+  type MockGitRepositoryStore,
+} from "./mock-git-repository-store.js";
+import type {
+  BootstrapCommitFile,
+  CreateTargetRepositoryInput,
+  GitHubTargetRepositoryProvider,
+} from "./github-target-repository-provider.js";
+import type { RemoteAccessStatus } from "./remote-actions.js";
+
+export function deterministicTargetMockRepositoryId(fullName: string): number {
+  const hash = createHash("sha256").update(fullName).digest();
+  return hash.readUInt32BE(0);
+}
+
+interface MockRepositoryRecord {
+  owner: string;
+  repo: string;
+  repositoryId: number;
+  description: string;
+  private: boolean;
+  defaultBranch: string;
+  store: MockGitRepositoryStore;
+  branchHeads: Map<string, string>;
+}
+
+export interface MockTargetRepositoryProviderState {
+  authenticatedLogin?: string;
+  createdRepositoryDefaultBranch?: string;
+  forbidCreate?: boolean;
+}
+
+export class MockGitHubTargetRepositoryProvider
+  implements GitHubTargetRepositoryProvider
+{
+  readonly calls: Array<{ method: string; args: unknown[] }> = [];
+  private readonly repositories = new Map<string, MockRepositoryRecord>();
+  private state: MockTargetRepositoryProviderState;
+
+  constructor(state: MockTargetRepositoryProviderState = {}) {
+    this.state = state;
+  }
+
+  setState(state: MockTargetRepositoryProviderState): void {
+    this.state = state;
+  }
+
+  private repoKey(owner: string, repo: string): string {
+    return `${owner}/${repo}`;
+  }
+
+  private requireRepo(owner: string, repo: string): MockRepositoryRecord {
+    const record = this.repositories.get(this.repoKey(owner, repo));
+    if (!record) {
+      throw new GitHubApiError(404, `Repository ${owner}/${repo} not found.`);
+    }
+    return record;
+  }
+
+  async resolveAuthenticatedUser(): Promise<AuthenticatedGitHubUser> {
+    this.calls.push({ method: "resolveAuthenticatedUser", args: [] });
+    const login = this.state.authenticatedLogin ?? "test-user";
+    return { id: 1, login };
+  }
+
+  async inspectTokenCapabilities(): Promise<GitHubTokenCapabilitySummary> {
+    this.calls.push({ method: "inspectTokenCapabilities", args: [] });
+    const login = this.state.authenticatedLogin ?? "test-user";
+    return {
+      login,
+      tokenType: "classic",
+      hasRepoScope: true,
+      hasWorkflowScope: true,
+      scopeAmbiguous: false,
+    };
+  }
+
+  async checkRepositoryAvailability(
+    owner: string,
+    name: string,
+  ): Promise<"available" | "repository_already_exists" | "forbidden"> {
+    this.calls.push({ method: "checkRepositoryAvailability", args: [owner, name] });
+    return this.repositories.has(this.repoKey(owner, name))
+      ? "repository_already_exists"
+      : "available";
+  }
+
+  async createPersonalRepository(
+    input: CreateTargetRepositoryInput,
+  ): Promise<CreateUserRepositoryResult> {
+    this.calls.push({ method: "createPersonalRepository", args: [input] });
+    if (this.state.forbidCreate) {
+      throw new GitHubApiError(403, "Repository creation forbidden.");
+    }
+    const key = this.repoKey(input.owner, input.name);
+    if (this.repositories.has(key)) {
+      throw new GitHubApiError(422, "Repository already exists.");
+    }
+    const store = await createMockGitRepositoryStore();
+    const defaultBranch = this.state.createdRepositoryDefaultBranch ?? "main";
+    const headSha = store.getHeadSha();
+    const repositoryId = deterministicTargetMockRepositoryId(key);
+    this.repositories.set(key, {
+      owner: input.owner,
+      repo: input.name,
+      repositoryId,
+      description: input.description ?? "",
+      private: input.visibility === "private",
+      defaultBranch,
+      store,
+      branchHeads: new Map([[defaultBranch, headSha]]),
+    });
+    return {
+      repositoryId,
+      fullName: key,
+      defaultBranch,
+    };
+  }
+
+  async getRepositoryMetadata(
+    owner: string,
+    repo: string,
+  ): Promise<GitHubRepositoryMetadata | null> {
+    this.calls.push({ method: "getRepositoryMetadata", args: [owner, repo] });
+    const record = this.repositories.get(this.repoKey(owner, repo));
+    if (!record) {
+      return null;
+    }
+    return {
+      repositoryId: record.repositoryId,
+      owner: record.owner,
+      repo: record.repo,
+      description: record.description,
+      private: record.private,
+      visibility: record.private ? "private" : "public",
+      isTemplate: false,
+      defaultBranch: record.defaultBranch,
+      permissions: { admin: true, maintain: true, push: true },
+    };
+  }
+
+  async getRepositoryDefaultBranchHead(
+    owner: string,
+    repo: string,
+    branch: string,
+  ): Promise<string> {
+    this.calls.push({
+      method: "getRepositoryDefaultBranchHead",
+      args: [owner, repo, branch],
+    });
+    const record = this.requireRepo(owner, repo);
+    const head = record.branchHeads.get(branch);
+    if (!head) {
+      throw new GitHubApiError(404, `Branch ${branch} not found.`);
+    }
+    return head;
+  }
+
+  async getGitRef(owner: string, repo: string, ref: string): Promise<GitRefResult> {
+    this.calls.push({ method: "getGitRef", args: [owner, repo, ref] });
+    const record = this.requireRepo(owner, repo);
+    const head = record.branchHeads.get(ref);
+    if (!head) {
+      throw new GitHubApiError(404, `Branch ${ref} not found.`);
+    }
+    return {
+      ref: `refs/heads/${ref}`,
+      object: { sha: head },
+    };
+  }
+
+  async createGitRef(
+    owner: string,
+    repo: string,
+    branch: string,
+    sha: string,
+  ): Promise<GitRefResult> {
+    this.calls.push({ method: "createGitRef", args: [owner, repo, branch, sha] });
+    const record = this.requireRepo(owner, repo);
+    if (record.branchHeads.has(branch)) {
+      throw new GitHubApiError(422, `Branch ${branch} already exists.`);
+    }
+    record.branchHeads.set(branch, sha);
+    return {
+      ref: `refs/heads/${branch}`,
+      object: { sha },
+    };
+  }
+
+  async writeBootstrapCommit(input: {
+    owner: string;
+    repo: string;
+    branch: string;
+    parentSha: string;
+    files: BootstrapCommitFile[];
+    message: string;
+  }): Promise<{ commitSha: string }> {
+    this.calls.push({ method: "writeBootstrapCommit", args: [input] });
+    const record = this.requireRepo(input.owner, input.repo);
+    const currentHead = record.branchHeads.get(input.branch);
+    if (!currentHead || currentHead !== input.parentSha) {
+      throw new Error(
+        `Bootstrap ref update rejected: expected parent ${input.parentSha}, found ${currentHead ?? "missing"}.`,
+      );
+    }
+    const treeEntries = input.files.map((file) => {
+      const sha = record.store.createBlob(Buffer.from(file.content, "utf8"));
+      return { path: file.path, mode: "100644", sha };
+    });
+    const parentCommit = record.store.getCommit(input.parentSha);
+    if (!parentCommit) {
+      throw new Error(`Parent commit ${input.parentSha} not found.`);
+    }
+    const treeSha = record.store.createTreeWithBase(treeEntries, parentCommit.treeSha);
+    const commitSha = record.store.createCommitRecord({
+      message: input.message,
+      treeSha,
+      parents: [input.parentSha],
+    });
+    record.store.updateRef(commitSha, input.parentSha);
+    record.branchHeads.set(input.branch, commitSha);
+    return { commitSha };
+  }
+
+  async verifyRepositoryAccess(
+    owner: string,
+    repo: string,
+  ): Promise<RemoteAccessStatus> {
+    this.calls.push({ method: "verifyRepositoryAccess", args: [owner, repo] });
+    const metadata = await this.getRepositoryMetadata(owner, repo);
+    return metadata ? "available" : "unknown";
+  }
+
+  async ensureDefaultBranch(
+    owner: string,
+    repo: string,
+    branchName: string,
+  ): Promise<{ defaultBranch: string; corrected: boolean }> {
+    this.calls.push({ method: "ensureDefaultBranch", args: [owner, repo, branchName] });
+    const record = this.requireRepo(owner, repo);
+    const corrected = record.defaultBranch !== branchName;
+    record.defaultBranch = branchName;
+    return { defaultBranch: branchName, corrected };
+  }
+
+  async verifyBranchExists(
+    owner: string,
+    repo: string,
+    branch: string,
+  ): Promise<boolean> {
+    this.calls.push({ method: "verifyBranchExists", args: [owner, repo, branch] });
+    const record = this.repositories.get(this.repoKey(owner, repo));
+    return Boolean(record?.branchHeads.has(branch));
+  }
+
+  async readRepositoryFileContent(
+    owner: string,
+    repo: string,
+    path: string,
+    ref: string,
+  ): Promise<string | null> {
+    this.calls.push({
+      method: "readRepositoryFileContent",
+      args: [owner, repo, path, ref],
+    });
+    const record = this.requireRepo(owner, repo);
+    const headSha = record.branchHeads.get(ref);
+    if (!headSha) {
+      return null;
+    }
+    const content = record.store.readFileAtCommit(headSha, path);
+    return content ? content.toString("utf8") : null;
+  }
+}

package/workspace-snapshot/files/src/setup/github-target-repository-provider.ts

@@ -0,0 +1,86 @@
+import { GitHubApiError } from "../github/client.js";
+import type {
+  AuthenticatedGitHubUser,
+  CreateUserRepositoryInput,
+  CreateUserRepositoryResult,
+  GitHubRepositoryMetadata,
+  GitHubTokenCapabilitySummary,
+  GitRefResult,
+} from "./github-remote-provider.js";
+import type { RemoteAccessStatus } from "./remote-actions.js";
+
+export interface CreateTargetRepositoryInput {
+  owner: string;
+  name: string;
+  description?: string;
+  visibility: "private" | "public";
+}
+
+export interface BootstrapCommitFile {
+  path: string;
+  content: string;
+}
+
+export interface GitHubTargetRepositoryProvider {
+  resolveAuthenticatedUser(): Promise<AuthenticatedGitHubUser>;
+  inspectTokenCapabilities(): Promise<GitHubTokenCapabilitySummary>;
+  checkRepositoryAvailability(
+    owner: string,
+    name: string,
+  ): Promise<"available" | "repository_already_exists" | "forbidden">;
+  createPersonalRepository(
+    input: CreateTargetRepositoryInput,
+  ): Promise<CreateUserRepositoryResult>;
+  getRepositoryMetadata(
+    owner: string,
+    repo: string,
+  ): Promise<GitHubRepositoryMetadata | null>;
+  getRepositoryDefaultBranchHead(
+    owner: string,
+    repo: string,
+    branch: string,
+  ): Promise<string>;
+  getGitRef(owner: string, repo: string, ref: string): Promise<GitRefResult>;
+  createGitRef(
+    owner: string,
+    repo: string,
+    branch: string,
+    sha: string,
+  ): Promise<GitRefResult>;
+  writeBootstrapCommit(input: {
+    owner: string;
+    repo: string;
+    branch: string;
+    parentSha: string;
+    files: BootstrapCommitFile[];
+    message: string;
+  }): Promise<{ commitSha: string }>;
+  verifyRepositoryAccess(owner: string, repo: string): Promise<RemoteAccessStatus>;
+  ensureDefaultBranch(
+    owner: string,
+    repo: string,
+    branchName: string,
+  ): Promise<{ defaultBranch: string; corrected: boolean }>;
+  verifyBranchExists(owner: string, repo: string, branch: string): Promise<boolean>;
+  readRepositoryFileContent(
+    owner: string,
+    repo: string,
+    path: string,
+    ref: string,
+  ): Promise<string | null>;
+}
+
+export type { CreateUserRepositoryInput, CreateUserRepositoryResult };
+
+export {
+  LiveGitHubTargetRepositoryProvider,
+  createLiveGitHubTargetRepositoryProvider,
+} from "./github-target-repository-provider-live.js";
+export {
+  MockGitHubTargetRepositoryProvider,
+  deterministicTargetMockRepositoryId,
+} from "./github-target-repository-provider-mock.js";
+
+export function isGitHubNotFoundError(error: unknown): boolean {
+  return error instanceof GitHubApiError && error.status === 404;
+}

package/workspace-snapshot/files/src/setup/github-workflow-permissions.ts

@@ -5,7 +5,8 @@ export const GITHUB_TOKEN_HELP_DISCLOSURE_LABEL = "How do I get a GitHub token?"
 export const GITHUB_TOKEN_GUIDED_HELPER_TEXT =
   "Use a classic GitHub personal access token with repo and workflow access. This lets the harness check your repos, save encrypted setup secrets, and open workflow install PRs later.";
 
-export const GITHUB_TOKEN_INPUT_LABEL = "Paste your GitHub token";
+export const GITHUB_TOKEN_INPUT_LABEL =
+  "Copy an existing GitHub personal access token or create a new one, then paste it here.";
 
 export const GITHUB_TOKEN_VERIFY_HELP_HINT = `Open "${GITHUB_TOKEN_HELP_DISCLOSURE_LABEL}" and create a classic token with repo and workflow selected.`;