@sfship/plugin-ship 1.0.0-beta.2

package/lib/core/package.installer.js

@@ -0,0 +1,60 @@
+import { resolveDependencies } from './package.dependencies.js';
+import { deployMetadataStep } from './package.metadata.js';
+import { withSuppressedStdout } from './stdout.js';
+export function describeStep(step) {
+    if (step.kind === 'package-id')
+        return `package-id  ${step.versionId}${step.name ? ` (${step.name})` : ''}`;
+    return `metadata    ${step.repoUrl}/${step.subfolder}`;
+}
+export async function installDependencies(deps, options) {
+    const { alias, wait, dryRun, force, shipDir, log, runCommand } = options;
+    if (deps.length === 0) {
+        log('No dependencies declared in ship.yml.');
+        return;
+    }
+    log('Resolving dependencies...');
+    const steps = await resolveDependencies(deps);
+    if (steps.length === 0) {
+        log('Dependency tree resolved to zero steps.');
+        return;
+    }
+    log(`Resolved ${steps.length} step(s):`);
+    for (const step of steps) {
+        log(`  ${describeStep(step)}`);
+    }
+    if (dryRun) {
+        log('dry-run — skipping install.');
+        return;
+    }
+    let installed = new Set();
+    if (!force) {
+        const listArgs = ['--json', ...(alias !== undefined ? ['--target-org', alias] : [])];
+        const result = (await withSuppressedStdout(() => runCommand('package:installed:list', listArgs)));
+        installed = new Set(result.map((p) => p.SubscriberPackageVersionId));
+        log(`${installed.size} package version(s) already installed in ${alias ?? 'default org'}.`);
+    }
+    for (const step of steps) {
+        if (step.kind === 'package-id') {
+            if (installed.has(step.versionId)) {
+                log(`Already installed: ${step.versionId}${step.name ? ` (${step.name})` : ''} — skipping.`);
+                continue;
+            }
+            log(`Installing ${step.versionId}${step.name ? ` (${step.name})` : ''}...`);
+            const installArgs = ['--package', step.versionId, '--wait', String(wait), '--no-prompt'];
+            if (alias !== undefined)
+                installArgs.push('--target-org', alias);
+            // eslint-disable-next-line no-await-in-loop
+            await runCommand('package:install', installArgs);
+            log(`Installed ${step.versionId}.`);
+        }
+        else {
+            if (installed.has(step.versionId)) {
+                log(`Already installed (${step.versionId}): ${step.repoUrl}/${step.subfolder} — skipping.`);
+                continue;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await deployMetadataStep(step, alias ?? '', shipDir, log, runCommand);
+        }
+    }
+}
+//# sourceMappingURL=package.installer.js.map

package/lib/core/package.installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.installer.js","sourceRoot":"","sources":["../../src/core/package.installer.ts"],"names":[],"mappings":"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"}

package/lib/core/package.metadata.d.ts

@@ -0,0 +1,6 @@
+import type { MetadataStep } from './package.dependencies.js';
+/**
+ * Downloads a CCI `unpackaged/pre` or `unpackaged/post` subfolder from GitHub,
+ * injects namespace tokens, and deploys it to the target org via `project:deploy:start`.
+ */
+export declare function deployMetadataStep(step: MetadataStep, targetOrg: string, shipDir: string, log: (msg: string) => void, runCommand: (id: string, argv: string[]) => Promise<unknown>): Promise<void>;

package/lib/core/package.metadata.js

@@ -0,0 +1,33 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { join } from 'node:path';
+import { walkFiles } from './file.js';
+import { replaceTokens, buildTokenMap } from './package.namespace.js';
+import { normalizeRepo, downloadDir } from './service.github.js';
+/**
+ * Downloads a CCI `unpackaged/pre` or `unpackaged/post` subfolder from GitHub,
+ * injects namespace tokens, and deploys it to the target org via `project:deploy:start`.
+ */
+export async function deployMetadataStep(step, targetOrg, shipDir, log, runCommand) {
+    const repo = normalizeRepo(step.repoUrl);
+    const slug = repo.replace('/', '_');
+    const localDir = join(shipDir, 'tmp', 'deps', slug, step.subfolder);
+    log(`Downloading ${step.repoUrl}/${step.subfolder}@${step.tag}...`);
+    await downloadDir(repo, step.tag, step.subfolder, localDir);
+    const files = await walkFiles(localDir);
+    await Promise.all(files.map((f) => replaceTokens(f, buildTokenMap(step.namespace))));
+    log(`Deploying ${step.subfolder}...`);
+    await runCommand('project:deploy:start', ['--metadata-dir', localDir, '--target-org', targetOrg]);
+}
+//# sourceMappingURL=package.metadata.js.map

package/lib/core/package.metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.metadata.js","sourceRoot":"","sources":["../../src/core/package.metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGjE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAkB,EAClB,SAAiB,EACjB,OAAe,EACf,GAA0B,EAC1B,UAA4D;IAE5D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAEpE,GAAG,CAAC,eAAe,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;IACpE,MAAM,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE5D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAErF,GAAG,CAAC,aAAa,IAAI,CAAC,SAAS,KAAK,CAAC,CAAC;IACtC,MAAM,UAAU,CAAC,sBAAsB,EAAE,CAAC,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;AACpG,CAAC"}

package/lib/core/package.namespace.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Replaces `%%%TOKEN%%%` placeholders in a file in-place.
+ * Binary files (containing null bytes) are skipped.
+ */
+export declare function replaceTokens(filePath: string, tokens: Record<string, string>): Promise<void>;
+/**
+ * Builds the CCI namespace token map for use with {@link replaceTokens}.
+ * Pass an empty string for unmanaged packages.
+ */
+export declare function buildTokenMap(namespace: string): Record<string, string>;

package/lib/core/package.namespace.js

@@ -0,0 +1,40 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+/**
+ * Replaces `%%%TOKEN%%%` placeholders in a file in-place.
+ * Binary files (containing null bytes) are skipped.
+ */
+export async function replaceTokens(filePath, tokens) {
+    const buf = await readFile(filePath);
+    if (buf.includes(0))
+        return; // skip binary files
+    let content = buf.toString('utf8');
+    for (const [token, replacement] of Object.entries(tokens)) {
+        content = content.replaceAll(`%%%${token}%%%`, replacement);
+    }
+    await writeFile(filePath, content, 'utf8');
+}
+/**
+ * Builds the CCI namespace token map for use with {@link replaceTokens}.
+ * Pass an empty string for unmanaged packages.
+ */
+export function buildTokenMap(namespace) {
+    return {
+        NAMESPACE: namespace ? `${namespace}__` : '',
+        NAMESPACE_DOT: namespace ? `${namespace}.` : '',
+        NAMESPACE_OR_C: namespace || 'c',
+    };
+}
+//# sourceMappingURL=package.namespace.js.map

package/lib/core/package.namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.namespace.js","sourceRoot":"","sources":["../../src/core/package.namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,MAA8B;IAClF,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,oBAAoB;IACjD,IAAI,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1D,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,KAAK,KAAK,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE;QAC5C,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE;QAC/C,cAAc,EAAE,SAAS,IAAI,GAAG;KACjC,CAAC;AACJ,CAAC"}

package/lib/core/package.version.d.ts

@@ -0,0 +1,42 @@
+export type PackageVersion = {
+    SubscriberPackageVersionId: string;
+    Version?: string;
+    IsReleased: boolean;
+    Branch?: string | null;
+    Name?: string;
+    CreatedDate: string;
+};
+export declare function selectLatest(versions: PackageVersion[], wantReleased: boolean): PackageVersion | null;
+export declare function extractVersionBase(version: string): string | undefined;
+export type PackageVersionCreateResult = {
+    Id?: string;
+    Status?: string;
+    Package2Id?: string;
+    Package2VersionId?: string;
+    SubscriberPackageVersionId?: string;
+    Branch?: string | null;
+    Tag?: string | null;
+    VersionNumber?: string;
+    MajorVersion?: number;
+    MinorVersion?: number;
+    PatchVersion?: number;
+    BuildNumber?: number;
+};
+export declare function formatVersionNumber(result: PackageVersionCreateResult): string | undefined;
+export declare const VERSION_TYPES: readonly ["build", "patch", "minor", "major"];
+export type VersionType = (typeof VERSION_TYPES)[number];
+type Semver = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export declare function parseSemver(s: string): Semver | null;
+export declare function bump(base: Semver, type: VersionType): Semver;
+/**
+ * Computes the next `.NEXT` version string from the latest release tag and the requested bump type.
+ *
+ * A 'build' bump on an existing release secretly bumps minor instead — sf won't allow a new
+ * build version in a series that already has a promoted production release.
+ */
+export declare function resolveNextVersion(tagName: string | null, versionType: VersionType): string;
+export {};

package/lib/core/package.version.js

@@ -0,0 +1,60 @@
+export function selectLatest(versions, wantReleased) {
+    const matching = versions.filter((v) => v.IsReleased === wantReleased);
+    if (matching.length === 0)
+        return null;
+    matching.sort((a, b) => (a.CreatedDate < b.CreatedDate ? 1 : -1));
+    return matching[0];
+}
+export function extractVersionBase(version) {
+    const parts = version.split('.');
+    return parts.length >= 3 ? `${parts[0]}.${parts[1]}.${parts[2]}` : undefined;
+}
+export function formatVersionNumber(result) {
+    if (result.VersionNumber)
+        return result.VersionNumber;
+    if (result.MajorVersion !== undefined) {
+        return `${result.MajorVersion}.${result.MinorVersion ?? 0}.${result.PatchVersion ?? 0}.${result.BuildNumber ?? 0}`;
+    }
+    return undefined;
+}
+export const VERSION_TYPES = ['build', 'patch', 'minor', 'major'];
+export function parseSemver(s) {
+    const match = s.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+    };
+}
+export function bump(base, type) {
+    switch (type) {
+        case 'major':
+            return { major: base.major + 1, minor: 0, patch: 0 };
+        case 'minor':
+            return { major: base.major, minor: base.minor + 1, patch: 0 };
+        case 'patch':
+            return { major: base.major, minor: base.minor, patch: base.patch + 1 };
+        case 'build':
+            return { ...base };
+    }
+}
+/**
+ * Computes the next `.NEXT` version string from the latest release tag and the requested bump type.
+ *
+ * A 'build' bump on an existing release secretly bumps minor instead — sf won't allow a new
+ * build version in a series that already has a promoted production release.
+ */
+export function resolveNextVersion(tagName, versionType) {
+    let base = { major: 0, minor: 0, patch: 0 };
+    if (tagName) {
+        const parsed = parseSemver(tagName);
+        if (parsed)
+            base = parsed;
+    }
+    const effectiveType = versionType === 'build' && tagName !== null ? 'minor' : versionType;
+    const next = bump(base, effectiveType);
+    return `${next.major}.${next.minor}.${next.patch}.NEXT`;
+}
+//# sourceMappingURL=package.version.js.map

package/lib/core/package.version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.version.js","sourceRoot":"","sources":["../../src/core/package.version.ts"],"names":[],"mappings":"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"}

package/lib/core/project.init.d.ts

@@ -0,0 +1,11 @@
+export type InitOptions = {
+    packageName: string;
+    namespace?: string;
+    packageType: 'Managed' | 'Unlocked';
+    repoUrl?: string;
+};
+export type InitResult = {
+    created: string[];
+    skipped: string[];
+};
+export declare function initProject(options: InitOptions, projectDir: string): InitResult;

package/lib/core/project.init.js

@@ -0,0 +1,121 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fileExists, ensureDir, readText, writeText, writeJson, appendText, removeFile } from './file.js';
+const templateDir = join(fileURLToPath(import.meta.url), '..', 'templates');
+function writeIfAbsent(absPath, relPath, content, result) {
+    if (fileExists(absPath)) {
+        result.skipped.push(relPath);
+        return;
+    }
+    writeText(absPath, content);
+    result.created.push(relPath);
+}
+function buildShipYml({ packageName, namespace, packageType, repoUrl }) {
+    const lines = ['project:', '  package:', `    name: ${packageName}`];
+    if (namespace)
+        lines.push(`    namespace: ${namespace}`);
+    lines.push(`    type: ${packageType}`);
+    lines.push('  git:', '    defaultBranch: main');
+    if (repoUrl)
+        lines.push(`    repoUrl: ${repoUrl}`);
+    return lines.join('\n') + '\n';
+}
+function patchSfdxProjectJson(projectDir, { packageName, namespace, packageType }) {
+    const filePath = join(projectDir, 'sfdx-project.json');
+    if (!fileExists(filePath))
+        return;
+    const raw = JSON.parse(readText(filePath));
+    const defaultDir = raw.packageDirectories.find((d) => d.default) ?? raw.packageDirectories[0];
+    if (defaultDir) {
+        defaultDir.package = packageName;
+        defaultDir.versionName = 'ver 0.1';
+        defaultDir.versionNumber = '0.0.0.NEXT';
+        if (packageType === 'Managed') {
+            defaultDir.ancestorVersion = 'HIGHEST';
+        }
+    }
+    if (namespace) {
+        raw.namespace = namespace;
+    }
+    writeJson(filePath, raw);
+}
+function appendToGitignore(projectDir) {
+    const filePath = join(projectDir, '.gitignore');
+    const entry = '\n# sf-ship\n.ship/tmp/\n';
+    const existing = fileExists(filePath) ? readText(filePath) : '';
+    if (!existing.includes('.ship/tmp/')) {
+        appendText(filePath, entry);
+    }
+}
+function appendToForceignore(projectDir) {
+    const filePath = join(projectDir, '.forceignore');
+    const entry = [
+        '',
+        '# sf-ship',
+        '**/*.profile-meta.xml',
+        '**/*.appMenu-meta.xml',
+        '**/sfdcInternalInt__*.permissionset-meta.xml',
+        '',
+    ].join('\n');
+    const existing = fileExists(filePath) ? readText(filePath) : '';
+    if (!existing.includes('# sf-ship')) {
+        appendText(filePath, entry);
+    }
+}
+const commonSettings = {
+    lightningExperienceSettings: { enableS1DesktopEnabled: true },
+    securitySettings: {
+        enableAdminLoginAsAnyUser: true,
+        sessionSettings: { forceRelogin: false },
+    },
+};
+function buildOrgDefs(packageName) {
+    const label = (env) => `${packageName}:${env}`;
+    return {
+        dev: {
+            orgName: label('dev'),
+            edition: 'Developer',
+            hasSampleData: true,
+            settings: {
+                ...commonSettings,
+                userManagementSettings: { permsetsInFieldCreation: true, enableEnhancedPermsetMgmt: true },
+            },
+        },
+        feature: { orgName: label('feature'), edition: 'Developer', settings: commonSettings },
+        beta: { orgName: label('beta'), edition: 'Developer', settings: commonSettings },
+        qa: { orgName: label('qa'), edition: 'Enterprise', hasSampleData: true, settings: commonSettings },
+        regression: { orgName: label('regression'), edition: 'Enterprise', settings: commonSettings },
+        release: { orgName: label('release'), edition: 'Enterprise', settings: commonSettings },
+    };
+}
+export function initProject(options, projectDir) {
+    const result = { created: [], skipped: [] };
+    const orgsDir = join(projectDir, '.ship', 'orgs');
+    ensureDir(orgsDir);
+    patchSfdxProjectJson(projectDir, options);
+    appendToGitignore(projectDir);
+    appendToForceignore(projectDir);
+    writeIfAbsent(join(projectDir, 'README.md'), 'README.md', readText(join(templateDir, 'README.md')), result);
+    const legacyConfigDir = join(projectDir, 'config');
+    if (fileExists(legacyConfigDir))
+        removeFile(legacyConfigDir);
+    writeIfAbsent(join(projectDir, 'ship.yml'), 'ship.yml', buildShipYml(options), result);
+    for (const [name, def] of Object.entries(buildOrgDefs(options.packageName))) {
+        writeIfAbsent(join(orgsDir, `${name}.json`), `.ship/orgs/${name}.json`, JSON.stringify(def, null, 4) + '\n', result);
+    }
+    return result;
+}
+//# sourceMappingURL=project.init.js.map

package/lib/core/project.init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.init.js","sourceRoot":"","sources":["../../src/core/project.init.ts"],"names":[],"mappings":"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"}

package/lib/core/service.d.ts

@@ -0,0 +1,45 @@
+/** Metadata stored alongside a credential, describing the account and granted scopes. */
+export type ServiceMeta = {
+    service: string;
+    account: string;
+    alias: string;
+    scopes: string[];
+};
+/**
+ * Retrieves the stored token for a service alias from the OS keychain.
+ *
+ * @param service - The external service name (e.g. `'github.com'`).
+ * @param alias - The account alias (e.g. `'default'`).
+ * @returns The stored token, or `null` if not found.
+ */
+export declare function getToken(service: string, alias: string): string | null;
+/**
+ * Stores a token in the OS keychain and writes a metadata file alongside it.
+ *
+ * @param service - The external service name (e.g. `'github.com'`).
+ * @param account - The account identifier (e.g. GitHub username).
+ * @param alias - The account alias (e.g. `'default'`).
+ * @param token - The credential to store.
+ * @param scopes - The scopes or permissions granted to this credential.
+ */
+export declare function setToken(service: string, account: string, alias: string, token: string, scopes?: string[]): void;
+/**
+ * Reads the metadata for a stored credential by alias.
+ *
+ * @param service - The external service name.
+ * @param alias - The account alias to look up.
+ * @returns The metadata, or `undefined` if no credential is stored for this alias.
+ */
+export declare function getMeta(service: string, alias: string): ServiceMeta | undefined;
+/**
+ * Returns metadata for all stored credentials.
+ */
+export declare function listMetas(): ServiceMeta[];
+/**
+ * Removes a stored credential from the OS keychain and deletes its metadata file.
+ *
+ * @param service - The external service name.
+ * @param account - The account identifier.
+ * @param alias - The account alias.
+ */
+export declare function deleteToken(service: string, account: string, alias: string): void;

package/lib/core/service.github.d.ts

@@ -0,0 +1,98 @@
+import type { ServiceMeta } from './service.js';
+declare const SERVICE = "github";
+/** Metadata for a stored GitHub credential. */
+export type GithubMeta = ServiceMeta & {
+    service: typeof SERVICE;
+};
+/** Returns the stored GitHub access token for the given alias, or `undefined` if not connected. */
+export declare function getGithubToken(alias?: string): string | undefined;
+/**
+ * Persists a GitHub access token securely for the given alias.
+ * The token is stored in the OS keychain; metadata is written alongside it.
+ */
+export declare function setGithubToken(token: string, username: string, alias?: string, scopes?: string[]): void;
+/** Normalises a GitHub reference to an `owner/repo` slug, accepting full URLs or slugs. */
+export declare function normalizeRepo(github: string): string;
+/** A GitHub release with its associated tag name. */
+export type ReleaseRef = {
+    tagName: string;
+};
+export type GitTagObject = {
+    sha: string;
+};
+export type Release = {
+    html_url: string;
+};
+export type ReleaseListItem = {
+    tag_name: string;
+    prerelease: boolean;
+};
+/** Response from the GitHub device code endpoint. */
+export type DeviceCodeResponse = {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+};
+/** A GitHub user object. */
+export type GithubUser = {
+    login: string;
+};
+/** Fetches the authenticated user and their granted OAuth scopes. */
+export declare function fetchGithubUser(token: string): Promise<{
+    user: GithubUser;
+    scopes: string[];
+}>;
+/**
+ * Fetches a GitHub release for `repo`. Returns `null` if no release exists.
+ * When `tag` is provided, fetches that specific release.
+ * When `prerelease` is true, fetches the latest pre-release; otherwise fetches the latest production release.
+ */
+export declare function fetchRelease(repo: string, tag?: string, prerelease?: boolean): Promise<ReleaseRef | null>;
+/** Fetches raw file content from a GitHub repository at a specific ref. Returns `null` if the file does not exist. */
+export declare function fetchRaw(repo: string, ref: string, filename: string): Promise<string | null>;
+/**
+ * Fetches the annotated git tag object for `tagName` in `repo`.
+ * Returns `null` for lightweight tags (no message) or if the tag does not exist.
+ */
+export declare function fetchGitTag(repo: string, tagName: string): Promise<{
+    message: string;
+} | null>;
+/** Basic metadata for a GitHub repository. */
+export type GithubRepo = {
+    full_name: string;
+    description: string | null;
+    default_branch: string;
+    stargazers_count: number;
+    open_issues_count: number;
+    visibility: string;
+};
+/** Fetches basic repository metadata from the GitHub API using an explicit token. */
+export declare function fetchRepoInfo(repo: string, token: string): Promise<GithubRepo>;
+/**
+ * Returns the package namespace declared in a CCI repo's `cumulusci.yml` at `ref`.
+ * Returns an empty string if the file is missing or declares no namespace.
+ */
+export declare function fetchCciNamespace(repo: string, ref: string): Promise<string>;
+/**
+ * Lists the immediate subdirectories of `path` in a GitHub repo at `ref`.
+ * Returns an empty array if the path does not exist.
+ */
+export declare function fetchSubdirs(repo: string, ref: string, path: string): Promise<string[]>;
+/** Downloads a GitHub repository directory at `ref` into `localDir`, recursing into subdirectories. */
+export declare function downloadDir(repo: string, ref: string, remotePath: string, localDir: string): Promise<void>;
+/** Authenticated GitHub API call. Throws ExpectedError on non-2xx. */
+export declare function gh<T>(token: string, path: string, init?: {
+    method?: string;
+    body?: unknown;
+}): Promise<T>;
+/** Returns the SHA of the first commit on the repo's default branch, or null. */
+export declare function fetchFirstCommitSha(repo: string, token: string): Promise<string | null>;
+/** Resolves a commit SHA from a full 40-char SHA, branch name, or the repo's default branch. */
+export declare function resolveCommitSha(target: string | undefined, token: string, repo: string): Promise<string>;
+/** Initiates the GitHub OAuth device flow and returns the device code response. */
+export declare function requestDeviceCode(): Promise<DeviceCodeResponse>;
+/** Polls the GitHub token endpoint until the user authorizes the device or an error occurs. */
+export declare function pollForToken(deviceCode: string, interval: number): Promise<string>;
+export {};