@treeseed/sdk 0.5.3 → 0.6.0

package/dist/operations/services/git-workflow.d.ts

@@ -32,6 +32,15 @@ export declare function createFeatureBranchFromStaging(cwd: any, branchName: any
 export declare function pushBranch(repoDir: any, branchName: any, { setUpstream }?: {
     setUpstream?: boolean | undefined;
 }): void;
+export declare function ensureRemoteBranchFromBase(repoDir: any, branchName: any, { baseBranch }?: {
+    baseBranch?: string | undefined;
+}): {
+    branchName: any;
+    baseBranch: string;
+    createdLocal: boolean;
+    pushed: boolean;
+    existed: boolean;
+};
 export declare function deleteLocalBranch(repoDir: any, branchName: any): void;
 export declare function deleteRemoteBranch(repoDir: any, branchName: any): boolean;
 export declare function mergeCurrentBranchIntoStaging(cwd: any, featureBranch: any): {

package/dist/operations/services/git-workflow.js

@@ -147,6 +147,37 @@ function pushBranch(repoDir, branchName, { setUpstream = false } = {}) {
   const args = setUpstream ? ["push", "-u", "origin", branchName] : ["push", "origin", branchName];
   runGit(args, { cwd: repoDir });
 }
+function ensureRemoteBranchFromBase(repoDir, branchName, { baseBranch = PRODUCTION_BRANCH } = {}) {
+  fetchOrigin(repoDir);
+  if (remoteBranchExists(repoDir, branchName)) {
+    return {
+      branchName,
+      baseBranch,
+      createdLocal: branchExists(repoDir, branchName) ? false : (() => {
+        runGit(["branch", branchName, `origin/${branchName}`], { cwd: repoDir });
+        return true;
+      })(),
+      pushed: false,
+      existed: true
+    };
+  }
+  const baseRef = remoteBranchExists(repoDir, baseBranch) ? `origin/${baseBranch}` : branchExists(repoDir, baseBranch) ? baseBranch : "";
+  if (!baseRef) {
+    throw new Error(`Base branch "${baseBranch}" does not exist locally or on origin.`);
+  }
+  const createdLocal = !branchExists(repoDir, branchName);
+  if (createdLocal) {
+    runGit(["branch", branchName, baseRef], { cwd: repoDir });
+  }
+  pushBranch(repoDir, branchName, { setUpstream: true });
+  return {
+    branchName,
+    baseBranch,
+    createdLocal,
+    pushed: true,
+    existed: false
+  };
+}
 function deleteLocalBranch(repoDir, branchName) {
   if (!branchExists(repoDir, branchName)) {
     return;
@@ -306,6 +337,7 @@ export {
   deleteLocalBranch,
   deleteRemoteBranch,
   ensureLocalBranchTracking,
+  ensureRemoteBranchFromBase,
   fetchOrigin,
   gitWorkflowRoot,
   headCommit,

package/dist/operations/services/github-api.d.ts

@@ -0,0 +1,115 @@
+import { Octokit } from 'octokit';
+export type GitHubApiClient = Octokit;
+export interface GitHubRepositoryMetadataInput {
+    owner: string;
+    name: string;
+    description?: string | null;
+    homepageUrl?: string | null;
+    visibility?: 'private' | 'public' | 'internal';
+    topics?: string[];
+}
+export interface GitHubRepositorySummary {
+    id: number;
+    owner: string;
+    name: string;
+    slug: string;
+    url: string;
+    sshUrl: string;
+    httpsUrl: string;
+    defaultBranch: string;
+    visibility: 'private' | 'public' | 'internal';
+}
+export interface GitHubWorkflowRunSummary {
+    id: number;
+    status: string | null;
+    conclusion: string | null;
+    url: string | null;
+    headSha: string | null;
+    headBranch: string | null;
+}
+export declare function resolveGitHubApiToken(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): string;
+export declare function parseGitHubRepositorySlug(value: string): {
+    owner: string;
+    name: string;
+};
+export declare function createGitHubApiClient({ env, timeoutMs, }?: {
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    timeoutMs?: number;
+}): GitHubApiClient;
+export declare function getGitHubRepository(repository: string | {
+    owner: string;
+    name: string;
+}, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<GitHubRepositorySummary>;
+export declare function maybeGetGitHubRepository(repository: string | {
+    owner: string;
+    name: string;
+}, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<GitHubRepositorySummary | null>;
+export declare function ensureGitHubRepository(input: GitHubRepositoryMetadataInput, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<GitHubRepositorySummary>;
+export declare function listGitHubRepositorySecretNames(repository: string | {
+    owner: string;
+    name: string;
+}, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<Set<string>>;
+export declare function listGitHubRepositoryVariableNames(repository: string | {
+    owner: string;
+    name: string;
+}, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<Set<string>>;
+export declare function upsertGitHubRepositorySecret(repository: string | {
+    owner: string;
+    name: string;
+}, name: string, value: string, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<void>;
+export declare function upsertGitHubRepositoryVariable(repository: string | {
+    owner: string;
+    name: string;
+}, name: string, value: string, { client }?: {
+    client?: GitHubApiClient;
+}): Promise<void>;
+export declare function upsertGitHubRepositoryVariableWithGhCli(repository: string | {
+    owner: string;
+    name: string;
+}, name: string, value: string, { env, }?: {
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}): void;
+export declare function waitForGitHubWorkflowRunCompletion(repository: string | {
+    owner: string;
+    name: string;
+}, { client, workflow, headSha, branch, timeoutSeconds, pollSeconds, }?: {
+    client?: GitHubApiClient;
+    workflow?: string;
+    headSha?: string | null;
+    branch?: string | null;
+    timeoutSeconds?: number;
+    pollSeconds?: number;
+}): Promise<{
+    status: string;
+    repository: string;
+    workflow: string;
+    runId: number;
+    headSha: string | null;
+    conclusion: string | null;
+    url: string | null;
+}>;
+export declare function ensureGitHubBranchFromBase(repository: string | {
+    owner: string;
+    name: string;
+}, branch: string, { baseBranch, client, }?: {
+    baseBranch?: string;
+    client?: GitHubApiClient;
+}): Promise<{
+    branch: string;
+    baseBranch: string;
+    existed: boolean;
+    created: boolean;
+    sha: string;
+}>;

package/dist/operations/services/github-api.js

@@ -0,0 +1,455 @@
+import { Buffer } from "node:buffer";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { Octokit } from "octokit";
+const require2 = createRequire(import.meta.url);
+const sodium = require2("libsodium-wrappers");
+const DEFAULT_GITHUB_API_TIMEOUT_MS = 6e4;
+function normalizeGitHubVisibility(value, fallback = "private") {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  return normalized === "public" || normalized === "internal" || normalized === "private" ? normalized : fallback;
+}
+function configuredEnvValue(env, key) {
+  const value = env?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+function resolveGitHubApiToken(env = process.env) {
+  return configuredEnvValue(env, "GH_TOKEN") || configuredEnvValue(env, "GITHUB_TOKEN");
+}
+function parseGitHubRepositorySlug(value) {
+  const normalized = String(value ?? "").trim().replace(/\.git$/u, "");
+  const [owner, ...rest] = normalized.split("/").filter(Boolean);
+  if (!owner || rest.length === 0) {
+    throw new Error(`Invalid GitHub repository slug "${value}". Expected owner/name.`);
+  }
+  return {
+    owner,
+    name: rest.join("/")
+  };
+}
+function createGitHubSignal(timeoutMs = DEFAULT_GITHUB_API_TIMEOUT_MS) {
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+    return AbortSignal.timeout(timeoutMs);
+  }
+  return void 0;
+}
+function normalizeGitHubApiError(error, context) {
+  if (error && typeof error === "object") {
+    const status = typeof error.status === "number" ? error.status : null;
+    const message = typeof error.message === "string" ? error.message.trim() : "";
+    if (status === 401 || status === 403) {
+      return new Error(`${context}: GitHub authentication failed.`);
+    }
+    if (status === 404) {
+      return new Error(`${context}: GitHub resource was not found.`);
+    }
+    if (status === 422) {
+      return new Error(`${context}: ${message || "GitHub rejected the request."}`);
+    }
+    if (status && message) {
+      return new Error(`${context}: ${message}`);
+    }
+  }
+  if (error instanceof Error && error.message.trim()) {
+    return new Error(`${context}: ${error.message.trim()}`);
+  }
+  return new Error(`${context}: GitHub API request failed.`);
+}
+function isRetriableGitHubApiError(error) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /timed out|timeout|aborted|ECONNRESET|ECONNREFUSED|fetch failed|socket hang up/iu.test(message);
+}
+async function withGitHubApiRetries(operation, retries = 2) {
+  let attempt = 0;
+  let lastError;
+  while (attempt <= retries) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= retries || !isRetriableGitHubApiError(error)) {
+        throw error;
+      }
+      await sleep(1e3 * (attempt + 1));
+      attempt += 1;
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "GitHub API request failed."));
+}
+function normalizeRepositorySummary(repository) {
+  return {
+    id: Number(repository.id ?? 0),
+    owner: String(repository.owner?.login ?? repository.owner?.name ?? ""),
+    name: String(repository.name ?? ""),
+    slug: `${String(repository.owner?.login ?? repository.owner?.name ?? "")}/${String(repository.name ?? "")}`,
+    url: String(repository.html_url ?? repository.url ?? ""),
+    sshUrl: String(repository.ssh_url ?? ""),
+    httpsUrl: String(repository.clone_url ?? ""),
+    defaultBranch: String(repository.default_branch ?? "main"),
+    visibility: normalizeGitHubVisibility(repository.visibility, repository.private ? "private" : "public")
+  };
+}
+function createGitHubApiClient({
+  env = process.env,
+  timeoutMs = DEFAULT_GITHUB_API_TIMEOUT_MS
+} = {}) {
+  const token = resolveGitHubApiToken(env);
+  if (!token) {
+    throw new Error("Configure GH_TOKEN before using Treeseed GitHub automation.");
+  }
+  return new Octokit({
+    auth: token,
+    request: {
+      signal: createGitHubSignal(timeoutMs)
+    }
+  });
+}
+async function getGitHubRepository(repository, { client = createGitHubApiClient() } = {}) {
+  const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  try {
+    const response = await client.rest.repos.get({ owner, repo: name });
+    return normalizeRepositorySummary(response.data);
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to load GitHub repository ${owner}/${name}`);
+  }
+}
+async function maybeGetGitHubRepository(repository, { client = createGitHubApiClient() } = {}) {
+  try {
+    return await getGitHubRepository(repository, { client });
+  } catch (error) {
+    if (/not found/iu.test(error instanceof Error ? error.message : String(error ?? ""))) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function ensureGitHubRepository(input, { client = createGitHubApiClient() } = {}) {
+  const existing = await maybeGetGitHubRepository({ owner: input.owner, name: input.name }, { client });
+  let repository = existing;
+  if (!repository) {
+    try {
+      const viewer = await client.rest.users.getAuthenticated();
+      if (viewer.data.login === input.owner) {
+        const created = await client.rest.repos.createForAuthenticatedUser({
+          name: input.name,
+          description: input.description ?? void 0,
+          homepage: input.homepageUrl ?? void 0,
+          private: (input.visibility ?? "private") !== "public"
+        });
+        repository = normalizeRepositorySummary(created.data);
+      } else {
+        const created = await client.rest.repos.createInOrg({
+          org: input.owner,
+          name: input.name,
+          description: input.description ?? void 0,
+          homepage: input.homepageUrl ?? void 0,
+          visibility: input.visibility ?? "private"
+        });
+        repository = normalizeRepositorySummary(created.data);
+      }
+    } catch (error) {
+      throw normalizeGitHubApiError(error, `Unable to create GitHub repository ${input.owner}/${input.name}`);
+    }
+  }
+  try {
+    const updated = await client.rest.repos.update({
+      owner: input.owner,
+      repo: input.name,
+      name: input.name,
+      description: input.description ?? void 0,
+      homepage: input.homepageUrl ?? void 0,
+      private: (input.visibility ?? repository.visibility ?? "private") === "private",
+      visibility: input.visibility ?? repository.visibility
+    });
+    repository = normalizeRepositorySummary(updated.data);
+    if (Array.isArray(input.topics)) {
+      await client.rest.repos.replaceAllTopics({
+        owner: input.owner,
+        repo: input.name,
+        names: input.topics
+      });
+    }
+    return repository;
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to update GitHub repository ${input.owner}/${input.name}`);
+  }
+}
+async function paginateNames(request) {
+  const items = await request();
+  return new Set(
+    items.map((entry) => typeof entry?.name === "string" ? entry.name.trim() : "").filter(Boolean)
+  );
+}
+async function listGitHubRepositorySecretNames(repository, { client = createGitHubApiClient() } = {}) {
+  const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  try {
+    return await paginateNames(
+      () => client.paginate(client.rest.actions.listRepoSecrets, {
+        owner,
+        repo: name,
+        per_page: 100
+      })
+    );
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to list GitHub secrets for ${owner}/${name}`);
+  }
+}
+async function listGitHubRepositoryVariableNames(repository, { client = createGitHubApiClient() } = {}) {
+  const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  try {
+    return await paginateNames(
+      () => client.paginate(client.rest.actions.listRepoVariables, {
+        owner,
+        repo: name,
+        per_page: 100
+      })
+    );
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to list GitHub variables for ${owner}/${name}`);
+  }
+}
+async function encryptGitHubSecret(secret, key) {
+  await sodium.ready;
+  const messageBytes = Buffer.from(secret);
+  const keyBytes = Buffer.from(key, "base64");
+  return Buffer.from(sodium.crypto_box_seal(messageBytes, keyBytes)).toString("base64");
+}
+async function upsertGitHubRepositorySecret(repository, name, value, { client = createGitHubApiClient() } = {}) {
+  const { owner, name: repo } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  try {
+    const key = await client.rest.actions.getRepoPublicKey({
+      owner,
+      repo
+    });
+    const encryptedValue = await encryptGitHubSecret(value, key.data.key);
+    await withGitHubApiRetries(() => client.rest.actions.createOrUpdateRepoSecret({
+      owner,
+      repo,
+      secret_name: name,
+      encrypted_value: encryptedValue,
+      key_id: key.data.key_id
+    }));
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to upsert GitHub secret ${name} for ${owner}/${repo}`);
+  }
+}
+async function upsertGitHubRepositoryVariable(repository, name, value, { client = createGitHubApiClient() } = {}) {
+  const { owner, name: repo } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  try {
+    const createOrUpdateRepoVariable = client.rest.actions.createOrUpdateRepoVariable;
+    if (typeof createOrUpdateRepoVariable === "function") {
+      await withGitHubApiRetries(() => createOrUpdateRepoVariable({
+        owner,
+        repo,
+        name,
+        value
+      }));
+      return;
+    }
+    await withGitHubApiRetries(async () => {
+      try {
+        await client.request("POST /repos/{owner}/{repo}/actions/variables", {
+          owner,
+          repo,
+          name,
+          value
+        });
+        return;
+      } catch (error) {
+        const status = typeof error?.status === "number" ? Number(error.status) : null;
+        const message = error instanceof Error ? error.message : String(error ?? "");
+        if (status !== 409 && status !== 422 && !/already exists/iu.test(message)) {
+          throw error;
+        }
+      }
+      await client.request("PATCH /repos/{owner}/{repo}/actions/variables/{name}", {
+        owner,
+        repo,
+        name,
+        value
+      });
+    });
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to upsert GitHub variable ${name} for ${owner}/${repo}`);
+  }
+}
+function upsertGitHubRepositoryVariableWithGhCli(repository, name, value, {
+  env = process.env
+} = {}) {
+  const token = resolveGitHubApiToken(env);
+  if (!token) {
+    throw new Error("Configure GH_TOKEN before using Treeseed GitHub automation.");
+  }
+  const { owner, name: repo } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  const ghEnv = {
+    ...process.env,
+    ...env,
+    GH_TOKEN: token,
+    GITHUB_TOKEN: token
+  };
+  const create = spawnSync(
+    "gh",
+    [
+      "api",
+      `repos/${owner}/${repo}/actions/variables`,
+      "--method",
+      "POST",
+      "-f",
+      `name=${name}`,
+      "-f",
+      `value=${value}`
+    ],
+    { encoding: "utf8", env: ghEnv }
+  );
+  if (create.status === 0) {
+    return;
+  }
+  const combinedCreateOutput = `${create.stdout ?? ""}
+${create.stderr ?? ""}`.trim();
+  if (!/already exists|HTTP 409|HTTP 422/iu.test(combinedCreateOutput)) {
+    throw new Error(combinedCreateOutput || `gh api exited with status ${create.status ?? 1}`);
+  }
+  const update = spawnSync(
+    "gh",
+    [
+      "api",
+      `repos/${owner}/${repo}/actions/variables/${name}`,
+      "--method",
+      "PATCH",
+      "-f",
+      `name=${name}`,
+      "-f",
+      `value=${value}`
+    ],
+    { encoding: "utf8", env: ghEnv }
+  );
+  if (update.status === 0) {
+    return;
+  }
+  const combinedUpdateOutput = `${update.stdout ?? ""}
+${update.stderr ?? ""}`.trim();
+  throw new Error(combinedUpdateOutput || `gh api exited with status ${update.status ?? 1}`);
+}
+function normalizeWorkflowRun(run) {
+  return {
+    id: Number(run.id ?? 0),
+    status: typeof run.status === "string" ? run.status : null,
+    conclusion: typeof run.conclusion === "string" ? run.conclusion : null,
+    url: typeof run.html_url === "string" ? run.html_url : null,
+    headSha: typeof run.head_sha === "string" ? run.head_sha : null,
+    headBranch: typeof run.head_branch === "string" ? run.head_branch : null
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForGitHubWorkflowRunCompletion(repository, {
+  client = createGitHubApiClient(),
+  workflow = "publish.yml",
+  headSha,
+  branch,
+  timeoutSeconds = 600,
+  pollSeconds = 5
+} = {}) {
+  const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutSeconds * 1e3) {
+    try {
+      const listed = await client.rest.actions.listWorkflowRuns({
+        owner,
+        repo: name,
+        workflow_id: workflow,
+        per_page: 20
+      });
+      const match = listed.data.workflow_runs.map((run) => normalizeWorkflowRun(run)).find((run) => (!headSha || run.headSha === headSha) && (!branch || run.headBranch === branch));
+      if (!match?.id) {
+        await sleep(pollSeconds * 1e3);
+        continue;
+      }
+      for (; ; ) {
+        const current = await client.rest.actions.getWorkflowRun({
+          owner,
+          repo: name,
+          run_id: match.id
+        });
+        const normalized = normalizeWorkflowRun(current.data);
+        if (normalized.status === "completed") {
+          return {
+            status: "completed",
+            repository: `${owner}/${name}`,
+            workflow,
+            runId: normalized.id,
+            headSha: normalized.headSha,
+            conclusion: normalized.conclusion,
+            url: normalized.url
+          };
+        }
+        await sleep(pollSeconds * 1e3);
+      }
+    } catch (error) {
+      throw normalizeGitHubApiError(error, `Unable to monitor GitHub workflow ${workflow} in ${owner}/${name}`);
+    }
+  }
+  throw new Error(`Timed out waiting for GitHub workflow ${workflow} in ${owner}/${name}.`);
+}
+async function ensureGitHubBranchFromBase(repository, branch, {
+  baseBranch = "main",
+  client = createGitHubApiClient()
+} = {}) {
+  const { owner, name } = typeof repository === "string" ? parseGitHubRepositorySlug(repository) : repository;
+  try {
+    const existing = await client.rest.repos.getBranch({
+      owner,
+      repo: name,
+      branch
+    });
+    return {
+      branch,
+      baseBranch,
+      existed: true,
+      created: false,
+      sha: existing.data.commit.sha
+    };
+  } catch (error) {
+    if (!/not found/iu.test(error instanceof Error ? error.message : String(error ?? ""))) {
+      throw normalizeGitHubApiError(error, `Unable to resolve GitHub branch ${branch} in ${owner}/${name}`);
+    }
+  }
+  try {
+    const base = await client.rest.repos.getBranch({
+      owner,
+      repo: name,
+      branch: baseBranch
+    });
+    await client.rest.git.createRef({
+      owner,
+      repo: name,
+      ref: `refs/heads/${branch}`,
+      sha: base.data.commit.sha
+    });
+    return {
+      branch,
+      baseBranch,
+      existed: false,
+      created: true,
+      sha: base.data.commit.sha
+    };
+  } catch (error) {
+    throw normalizeGitHubApiError(error, `Unable to create GitHub branch ${branch} from ${baseBranch} in ${owner}/${name}`);
+  }
+}
+export {
+  createGitHubApiClient,
+  ensureGitHubBranchFromBase,
+  ensureGitHubRepository,
+  getGitHubRepository,
+  listGitHubRepositorySecretNames,
+  listGitHubRepositoryVariableNames,
+  maybeGetGitHubRepository,
+  parseGitHubRepositorySlug,
+  resolveGitHubApiToken,
+  upsertGitHubRepositorySecret,
+  upsertGitHubRepositoryVariable,
+  upsertGitHubRepositoryVariableWithGhCli,
+  waitForGitHubWorkflowRunCompletion
+};