@bakers-build/addon-forge 0.0.0-stage → 0.8.1-next.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-forge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build forge tools: a sandboxed run fetches, pushes its own branches, opens its PR/MR, reads checks and merges through the conductor, which holds the token. Backends implement the ForgeBackend contract (./backend).
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://github.com/bakers-build/bakers-build (bakers-cli/).

package/dist/src/backend.d.ts

@@ -0,0 +1,66 @@
+import type { GitAuth } from './git.js';
+export type { GitAuth };
+export interface ForgePr {
+    /** GitHub PR number, GitLab MR iid. */
+    readonly number: number;
+    readonly url: string;
+    readonly head: string;
+    readonly base: string;
+    readonly title: string;
+    readonly headSha: string;
+}
+export type CheckStatus = 'success' | 'pending' | 'failure' | 'missing';
+export interface ForgeCheck {
+    readonly name: string;
+    readonly status: CheckStatus;
+    /** Required by the base branch's rules (GitHub) or not allowed to fail (GitLab). */
+    readonly required: boolean;
+}
+export interface ForgeMerge {
+    readonly method: 'squash' | 'merge';
+    readonly deleteSource: boolean;
+    readonly subject: string;
+    readonly body: string;
+}
+export interface ForgeBackend {
+    readonly id: string;
+    /** Every credential value; the tools redact them from all output. */
+    secrets(): readonly string[];
+    /** The configured repository URL and the header that authenticates git. */
+    gitAuth(): Promise<GitAuth>;
+    findOpenPr(head: string): Promise<ForgePr | undefined>;
+    createPr(input: {
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+    }): Promise<ForgePr>;
+    updatePr(pr: ForgePr, input: {
+        title: string;
+        body: string;
+    }): Promise<ForgePr>;
+    openPrsWithBase(base: string): Promise<ForgePr[]>;
+    /** Checks on `ref` (a SHA or branch), `required` as `base`'s rules say. */
+    checks(ref: string, base: string): Promise<ForgeCheck[]>;
+    /** A conflict or a not yet computed mergeability is a reason. */
+    mergeBlocker(pr: ForgePr): Promise<string | undefined>;
+    /** Merges with every option sent explicitly; deletes the source when asked. */
+    merge(pr: ForgePr, options: ForgeMerge): Promise<void>;
+    isMerged(pr: ForgePr): Promise<boolean>;
+}
+export type ForgeBackendFactory = (settings: unknown, context: {
+    readonly home: string;
+    readonly fetch?: typeof fetch;
+}) => Promise<ForgeBackend>;
+/** Reject a factory result that is not a `ForgeBackend`. */
+export declare function assertForgeBackend(value: unknown, spec: string): asserts value is ForgeBackend;
+/**
+ * A token from the conductor's own CLI login (`gh`, `glab`), run outside any
+ * sandbox and read again after five minutes so a new login is picked up.
+ * Every value read is pushed to `seen`, for the backend's `secrets()`.
+ */
+export declare function cliToken(cmd: string, args: string[], seen: string[]): () => Promise<string>;
+/** JSON over HTTP for backends: throws status and body text on failure. */
+export declare function requestJson(doFetch: typeof fetch, url: string, init: RequestInit & {
+    allow404?: boolean;
+}): Promise<unknown>;

package/dist/src/backend.js

@@ -0,0 +1,56 @@
+// The forge backend contract. A backend package (`@bakers-build/addon-forge-
+// github`, `@bakers-build/addon-forge-gitlab`) default-exports a
+// `ForgeBackendFactory`; the forge tools know only this shape, never a
+// service's API. Ownership, titles and merge gates stay with the tools.
+import { execFile } from 'node:child_process';
+const METHODS = [
+    'secrets',
+    'gitAuth',
+    'findOpenPr',
+    'createPr',
+    'updatePr',
+    'openPrsWithBase',
+    'checks',
+    'mergeBlocker',
+    'merge',
+    'isMerged',
+];
+/** Reject a factory result that is not a `ForgeBackend`. */
+export function assertForgeBackend(value, spec) {
+    const obj = value;
+    if (typeof obj !== 'object' || obj === null)
+        throw new Error(`forge backend '${spec}' did not return an object`);
+    if (typeof obj.id !== 'string' || obj.id === '')
+        throw new Error(`forge backend '${spec}' is missing string "id"`);
+    for (const m of METHODS)
+        if (typeof obj[m] !== 'function')
+            throw new Error(`forge backend '${spec}' is missing function "${m}"`);
+}
+/**
+ * A token from the conductor's own CLI login (`gh`, `glab`), run outside any
+ * sandbox and read again after five minutes so a new login is picked up.
+ * Every value read is pushed to `seen`, for the backend's `secrets()`.
+ */
+export function cliToken(cmd, args, seen) {
+    let cached;
+    return async () => {
+        if (cached && Date.now() < cached.until)
+            return cached.value;
+        const value = await new Promise((resolve) => execFile(cmd, args, { timeout: 10_000 }, (err, out) => resolve(err ? '' : String(out).trim())));
+        if (!value)
+            throw new Error(`${cmd} gave no token: run '${cmd} auth login' on the conductor's machine`);
+        seen.push(value);
+        cached = { value, until: Date.now() + 300_000 };
+        return value;
+    };
+}
+/** JSON over HTTP for backends: throws status and body text on failure. */
+export async function requestJson(doFetch, url, init) {
+    const res = await doFetch(url, init);
+    if (res.status === 404 && init.allow404)
+        return undefined;
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`${init.method ?? 'GET'} ${new URL(url).pathname} answered ${res.status}: ${text.slice(0, 500)}`);
+    return text ? JSON.parse(text) : undefined;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,13 @@
+import { type ForgeBackend } from './backend.js';
+export declare const FORGE_SPEC = "@bakers-build/addon-forge";
+export declare const FORGE_NEEDS_BACKEND = "addons[@bakers-build/addon-forge].with.backend.use must name a forge backend ('@bakers-build/addon-forge-github' or '@bakers-build/addon-forge-gitlab') in ~/.bakers/machine.config.js or .bakers/project.config.js; see docs/addons/forge";
+export interface MergeRule {
+    readonly method: 'squash' | 'merge';
+    readonly delete_source: boolean;
+}
+/** The machine wins key by key (a machine `backend` replaces the project's). */
+export declare function mergeWith(project: unknown, machine: unknown): unknown;
+/** The rule for merging into `base`: `merge[base]`, else `merge['*']`, else squash and delete. */
+export declare function mergeRule(settings: unknown, base: string): MergeRule;
+/** Resolve, load and construct the configured backend. */
+export declare function loadForgeBackend(settings: unknown, home: string): Promise<ForgeBackend>;

package/dist/src/config.js

@@ -0,0 +1,67 @@
+// The forge entry's `with`: `merge` rules per base branch and exactly one
+// `backend` (`use` names the package, `with` is that package's settings);
+// options.schema.json describes them.
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { resolveModuleEslintStyle } from '@bakers-build/core';
+import { assertForgeBackend, } from './backend.js';
+export const FORGE_SPEC = '@bakers-build/addon-forge';
+export const FORGE_NEEDS_BACKEND = `addons[${FORGE_SPEC}].with.backend.use must name a forge backend ('@bakers-build/addon-forge-github' or '@bakers-build/addon-forge-gitlab') in ~/.bakers/machine.config.js or .bakers/project.config.js; see docs/addons/forge`;
+const DEFAULT_RULE = { method: 'squash', delete_source: true };
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The machine wins key by key (a machine `backend` replaces the project's). */
+export function mergeWith(project, machine) {
+    if (!isObject(machine))
+        return machine === undefined ? project : machine;
+    if (!isObject(project))
+        return machine;
+    return { ...project, ...machine };
+}
+/** The rule for merging into `base`: `merge[base]`, else `merge['*']`, else squash and delete. */
+export function mergeRule(settings, base) {
+    const merge = isObject(settings) && isObject(settings.merge) ? settings.merge : {};
+    return (merge[base] ?? merge['*'] ?? DEFAULT_RULE);
+}
+/** Resolution bases rooted at the running `bakers` host install (see addon-ports' config). */
+function hostInstallBases() {
+    const entry = process.argv[1];
+    if (!entry)
+        return [import.meta.url];
+    let real;
+    try {
+        real = realpathSync(entry);
+    }
+    catch {
+        real = entry;
+    }
+    const entryUrl = pathToFileURL(real);
+    return [entryUrl.href, new URL('../host/dist/src/host.js', entryUrl).href];
+}
+/** Resolve, load and construct the configured backend. */
+export async function loadForgeBackend(settings, home) {
+    const backend = isObject(settings) ? settings.backend : undefined;
+    if (!isObject(backend) ||
+        typeof backend.use !== 'string' ||
+        backend.use === '')
+        throw new Error(FORGE_NEEDS_BACKEND);
+    const spec = backend.use;
+    const resolved = resolveModuleEslintStyle(spec, [
+        pathToFileURL(`${home}/`).href,
+        ...hostInstallBases(),
+        pathToFileURL(`${process.cwd()}/`).href,
+    ]);
+    if (resolved === undefined)
+        throw new Error(`forge cannot resolve backend package '${spec}'`);
+    const factory = (await import(pathToFileURL(resolved).href)).default;
+    if (typeof factory !== 'function')
+        throw new Error(`forge backend '${spec}' has no default export factory`);
+    let made;
+    try {
+        made = await factory(backend.with, { home });
+    }
+    catch (err) {
+        throw new Error(`forge backend '${spec}' rejected its settings: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    assertForgeBackend(made, spec);
+    return made;
+}

package/dist/src/git.d.ts

@@ -0,0 +1,28 @@
+export interface GitAuth {
+    /** The configured repository URL, never the clone's `origin`. */
+    readonly url: string;
+    /** An HTTP header line (`Authorization: …`) git sends to the remote. */
+    readonly header: string;
+}
+export interface PushLease {
+    readonly forceWithLease?: boolean;
+    /** The remote SHA the lease expects; default: refs/remotes/origin/<branch>. */
+    readonly expectedSha?: string;
+}
+/** The SHA of a local branch of the clone, if it exists. */
+export declare function localSha(worktree: string, branch: string): Promise<string | undefined>;
+/**
+ * Fetch `branches` into the clone's `refs/remotes/origin/<name>`, no tags.
+ * Branches the remote lacks are skipped. Changes nothing remote.
+ */
+export declare function fetchBranches(worktree: string, auth: GitAuth, branches: readonly string[]): Promise<{
+    name: string;
+    sha: string;
+}[]>;
+/**
+ * Push the clone's `refs/heads/<branch>` to the remote's branch of the same
+ * name. Without a lease only a fast-forward lands; with one, the remote must
+ * still be at the expected SHA (absent remote-tracking ref: no branch).
+ * Returns the pushed SHA and records it as refs/remotes/origin/<branch>.
+ */
+export declare function pushBranch(worktree: string, auth: GitAuth, branch: string, lease: PushLease): Promise<string>;

package/dist/src/git.js

@@ -0,0 +1,177 @@
+// Network git that trusts nothing in the run's clone. Every fetch and push
+// runs in a throwaway bare repository whose object directory is the clone's
+// own store, with no global, system or repository config, no hooks, and only
+// the remote's protocol allowed. The token reaches git as an environment
+// header, never argv, URL or file. Against the clone itself only `rev-parse`,
+// `for-each-ref` and `update-ref` run, with hooks and fsmonitor disabled.
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const HARDEN = ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false'];
+function baseEnv(home) {
+    return {
+        PATH: process.env.PATH,
+        HOME: home,
+        LANG: 'C',
+        GIT_CONFIG_NOSYSTEM: '1',
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_TERMINAL_PROMPT: '0',
+    };
+}
+function run(args, env, input) {
+    return new Promise((resolve, reject) => {
+        const child = execFile('git', args, { env, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error(`git failed: ${stderr.trim() || err.message}`));
+            else
+                resolve(stdout.trim());
+        });
+        if (input !== undefined)
+            child.stdin?.end(input);
+    });
+}
+/** The clone's common git dir (shared by all its worktrees). */
+async function commonDir(worktree, env) {
+    return run([
+        '-C',
+        worktree,
+        ...HARDEN,
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-common-dir',
+    ], env);
+}
+const inClone = (common, env, ...args) => run([`--git-dir=${common}`, ...HARDEN, ...args], env);
+async function readRef(common, env, ref) {
+    try {
+        return await inClone(common, env, 'rev-parse', '--verify', '-q', `${ref}^{commit}`);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Run `body` with a scratch repository on the clone's object store. */
+async function withScratch(worktree, auth, body) {
+    const home = await mkdtemp(join(tmpdir(), 'bakers-forge-'));
+    try {
+        const env = baseEnv(home);
+        const common = await commonDir(worktree, env);
+        // The conductor's git would read any object store the run lists here.
+        const alternates = await readFile(join(common, 'objects', 'info', 'alternates'), 'utf8').catch(() => '');
+        if (alternates.trim())
+            throw new Error('the clone lists object alternates (objects/info/alternates); forge tools refuse a borrowed object store');
+        const scratch = join(home, 'scratch.git');
+        await run(['init', '--bare', '-q', scratch], env);
+        const scheme = new URL(auth.url).protocol.slice(0, -1);
+        const config = [
+            ['core.hooksPath', '/dev/null'],
+            ['core.fsmonitor', 'false'],
+            ['protocol.allow', 'never'],
+            [`protocol.${scheme}.allow`, 'always'],
+            ['gc.auto', '0'],
+            ['maintenance.auto', 'false'],
+            ['http.extraHeader', auth.header],
+        ];
+        const remoteEnv = {
+            ...env,
+            GIT_DIR: scratch,
+            GIT_OBJECT_DIRECTORY: join(common, 'objects'),
+            GIT_CONFIG_COUNT: String(config.length),
+        };
+        config.forEach(([key, value], i) => {
+            remoteEnv[`GIT_CONFIG_KEY_${i}`] = key;
+            remoteEnv[`GIT_CONFIG_VALUE_${i}`] = value;
+        });
+        return await body({
+            common,
+            env,
+            remote: (args, input) => run(args, remoteEnv, input),
+        });
+    }
+    finally {
+        await rm(home, { recursive: true, force: true });
+    }
+}
+/** The SHA of a local branch of the clone, if it exists. */
+export async function localSha(worktree, branch) {
+    const home = await mkdtemp(join(tmpdir(), 'bakers-forge-'));
+    try {
+        const env = baseEnv(home);
+        return await readRef(await commonDir(worktree, env), env, `refs/heads/${branch}`);
+    }
+    finally {
+        await rm(home, { recursive: true, force: true });
+    }
+}
+/** Remote heads of `branches` as `name → sha`; absent names are left out. */
+function parseLsRemote(out) {
+    const heads = new Map();
+    for (const line of out.split('\n')) {
+        const [sha, ref] = line.split('\t');
+        if (sha && ref?.startsWith('refs/heads/'))
+            heads.set(ref.slice('refs/heads/'.length), sha);
+    }
+    return heads;
+}
+/**
+ * Fetch `branches` into the clone's `refs/remotes/origin/<name>`, no tags.
+ * Branches the remote lacks are skipped. Changes nothing remote.
+ */
+export async function fetchBranches(worktree, auth, branches) {
+    return withScratch(worktree, auth, async ({ common, env, remote }) => {
+        const heads = parseLsRemote(await remote([
+            'ls-remote',
+            '--heads',
+            auth.url,
+            ...branches.map((b) => `refs/heads/${b}`),
+        ]));
+        const wanted = branches.filter((b, i) => heads.has(b) && branches.indexOf(b) === i);
+        if (wanted.length === 0)
+            return [];
+        // The clone's remote-tracking refs seed negotiation, so only new objects travel.
+        const known = await inClone(common, env, 'for-each-ref', '--format=create %(refname) %(objectname)', 'refs/remotes/origin/');
+        // A ref to an object the store lacks only costs negotiation; ignore it.
+        if (known)
+            await remote(['update-ref', '--stdin'], `${known}\n`).catch(() => '');
+        await remote([
+            'fetch',
+            '--no-tags',
+            '--no-write-fetch-head',
+            '-q',
+            auth.url,
+            ...wanted.map((b) => `+refs/heads/${b}:refs/remotes/origin/${b}`),
+        ]);
+        const out = [];
+        for (const name of wanted) {
+            // What the fetch wrote, not ls-remote's answer: the remote may have moved since.
+            const sha = await remote(['rev-parse', `refs/remotes/origin/${name}`]);
+            await inClone(common, env, 'update-ref', `refs/remotes/origin/${name}`, sha);
+            out.push({ name, sha });
+        }
+        return out;
+    });
+}
+/**
+ * Push the clone's `refs/heads/<branch>` to the remote's branch of the same
+ * name. Without a lease only a fast-forward lands; with one, the remote must
+ * still be at the expected SHA (absent remote-tracking ref: no branch).
+ * Returns the pushed SHA and records it as refs/remotes/origin/<branch>.
+ */
+export async function pushBranch(worktree, auth, branch, lease) {
+    return withScratch(worktree, auth, async ({ common, env, remote }) => {
+        const sha = await readRef(common, env, `refs/heads/${branch}`);
+        if (!sha)
+            throw new Error(`no local branch '${branch}' to push`);
+        const args = ['push', '--porcelain', '--no-verify'];
+        if (lease.forceWithLease) {
+            const expected = lease.expectedSha ??
+                (await readRef(common, env, `refs/remotes/origin/${branch}`)) ??
+                '';
+            args.push(`--force-with-lease=refs/heads/${branch}:${expected}`);
+        }
+        await remote([...args, auth.url, `${sha}:refs/heads/${branch}`]);
+        await inClone(common, env, 'update-ref', `refs/remotes/origin/${branch}`, sha);
+        return sha;
+    });
+}

package/dist/src/preset.d.ts

@@ -0,0 +1,5 @@
+import type { Preset } from '@bakers-build/conductor/contract';
+import type { BbPreset } from '@bakers-build/core';
+export declare const scopes: BbPreset['scopes'];
+export { mergeWith } from './config.js';
+export declare const tools: Preset['tools'];

package/dist/src/preset.js

@@ -0,0 +1,13 @@
+// The forge addon: five conductor tools a sandboxed run delivers through,
+// while the token stays with the conductor. Without a forge entry no tool is
+// served and runs deliver as before.
+import { FORGE_TOOL_DEFINITIONS } from './tool-definitions.js';
+// Configurable on either level; the machine entry's with wins.
+export const scopes = ['machine', 'project'];
+// Merge the entry's own settings across scopes; options.schema.json describes them.
+export { mergeWith } from './config.js';
+export const tools = {
+    contract: 1,
+    tools: FORGE_TOOL_DEFINITIONS,
+    handlers: (options) => import('./tools.js').then((m) => m.toolsFor(options)),
+};

package/dist/src/rules.d.ts

@@ -0,0 +1,14 @@
+/** `RULE` of `tests/contract/mr-title.sh`, verbatim (a test keeps them equal). */
+export declare const CONVENTIONAL_TITLE_RULE = "^(feat|fix|chore|docs|refactor|test|ci|build|perf)(\\([a-z0-9._/-]+\\))?!?: [^[:space:]].*$";
+export declare function isConventionalTitle(title: string): boolean;
+export declare const TITLE_REFUSAL = "the title must be a Conventional Commits subject `type(scope)!: subject`, type one of feat, fix, chore, docs, refactor, test, ci, build, perf (e.g. `feat(cli): forge tools`)";
+/** The run's own branch, or `<branch_name>-<suffix>`. */
+export declare function isOwned(branch: string, branchName: string): boolean;
+export declare function ownershipRefusal(branch: string, branchName: string): string;
+/** The ticket branch merges into `base_branch`; a variant into the ticket branch. */
+export declare function derivedBase(branch: string, run: {
+    branchName: string;
+    baseBranch: string;
+}): string;
+/** Remove every secret and any Authorization header value. */
+export declare function redact(text: string, secrets: readonly string[]): string;

package/dist/src/rules.js

@@ -0,0 +1,38 @@
+// The forge tools' pure rules: which branches a run owns, where each merges,
+// which PR/MR titles pass, and what never leaves a tool result.
+/** `RULE` of `tests/contract/mr-title.sh`, verbatim (a test keeps them equal). */
+export const CONVENTIONAL_TITLE_RULE = '^(feat|fix|chore|docs|refactor|test|ci|build|perf)(\\([a-z0-9._/-]+\\))?!?: [^[:space:]].*$';
+const TITLE = new RegExp(CONVENTIONAL_TITLE_RULE.replace('[^[:space:]]', '\\S'));
+export function isConventionalTitle(title) {
+    return TITLE.test(title);
+}
+export const TITLE_REFUSAL = 'the title must be a Conventional Commits subject `type(scope)!: subject`, type one of feat, fix, chore, docs, refactor, test, ci, build, perf (e.g. `feat(cli): forge tools`)';
+/** One ref component: no slash, no `..`, no trailing `.` or `.lock`. */
+const SUFFIX = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+/** The run's own branch, or `<branch_name>-<suffix>`. */
+export function isOwned(branch, branchName) {
+    if (branch === branchName)
+        return true;
+    if (!branch.startsWith(`${branchName}-`))
+        return false;
+    const suffix = branch.slice(branchName.length + 1);
+    return (SUFFIX.test(suffix) &&
+        !suffix.includes('..') &&
+        !suffix.endsWith('.') &&
+        !suffix.endsWith('.lock'));
+}
+export function ownershipRefusal(branch, branchName) {
+    return `branch '${branch}' is not owned by this run: only '${branchName}' and '${branchName}-<suffix>' may be used`;
+}
+/** The ticket branch merges into `base_branch`; a variant into the ticket branch. */
+export function derivedBase(branch, run) {
+    return branch === run.branchName ? run.baseBranch : run.branchName;
+}
+/** Remove every secret and any Authorization header value. */
+export function redact(text, secrets) {
+    let out = text.replace(/(authorization["']?:\s*["']?)(?:\w+\s+)?[^\s"',]+/gi, '$1[redacted]');
+    for (const secret of secrets)
+        if (secret.length >= 4)
+            out = out.split(secret).join('[redacted]');
+    return out;
+}

package/dist/src/tool-definitions.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from '@bakers-build/conductor/contract';
+export declare const FORGE_TOOL_DEFINITIONS: Record<string, ToolDefinition>;

package/dist/src/tool-definitions.js

@@ -0,0 +1,58 @@
+// The forge tools' definitions, apart from their handlers so the preset stays
+// import-light. No tool takes a ticket, a base or a target: those come from
+// the calling run.
+const branch = {
+    type: 'string',
+    description: "an owned branch: the ticket's branch_name (default) or <branch_name>-<suffix>",
+};
+export const FORGE_TOOL_DEFINITIONS = {
+    forge_fetch: {
+        description: "Fetch the ticket's base_branch, its own branch and the named parent branches into refs/remotes/origin/*; read only. Then rebase or merge locally with git.",
+        input: {
+            type: 'object',
+            properties: {
+                branches: {
+                    type: 'string',
+                    description: 'further branches to fetch, space-separated, e.g. those of parent-linked tickets',
+                },
+            },
+        },
+    },
+    forge_push: {
+        description: "Push an owned branch's local head. Fast-forward only, unless force_with_lease: then the remote must still be at expected_sha (default: refs/remotes/origin/<branch>). Bare force does not exist.",
+        input: {
+            type: 'object',
+            properties: {
+                branch,
+                force_with_lease: { type: 'boolean' },
+                expected_sha: { type: 'string', pattern: '^[0-9a-f]{40}$' },
+            },
+        },
+    },
+    forge_pr_upsert: {
+        description: "Create the PR/MR of an owned branch into its base (base_branch, or the ticket branch for a variant), or update the open one's title and body. The title must be a Conventional Commits subject.",
+        input: {
+            type: 'object',
+            properties: {
+                branch,
+                title: { type: 'string' },
+                body: { type: 'string' },
+            },
+            required: ['title'],
+        },
+    },
+    forge_checks: {
+        description: "Status of each check or pipeline job, and whether it is required, on the head of an owned branch's PR/MR, or on any `ref` (branch or SHA); read only, one shot.",
+        input: {
+            type: 'object',
+            properties: {
+                branch,
+                ref: { type: 'string', description: 'any branch or SHA, read only' },
+            },
+        },
+    },
+    forge_merge: {
+        description: "Merge the open PR/MR of an owned branch into its base, once it is conflict free and every required check is green. Human approval is the workflow's merge gate, not this tool's.",
+        input: { type: 'object', properties: { branch } },
+    },
+};

package/dist/src/tools.d.ts

@@ -0,0 +1,13 @@
+import type { ToolHandler } from '@bakers-build/conductor/contract';
+import type { ForgeBackend, ForgeCheck } from './backend.js';
+export declare const FORGE_NEEDS_RUN = "forge tools act only for an agent run: the call carries no ticket branch_name and base_branch (an operator delivers by hand)";
+export interface ForgeToolDeps {
+    backend(): Promise<ForgeBackend>;
+    /** The forge entry's `with` (merge rules). */
+    settings: unknown;
+}
+/** Failure first, then pending, over the required checks. */
+export declare function overall(checks: readonly ForgeCheck[]): ForgeCheck['status'];
+export declare function forgeTools(deps: ForgeToolDeps): Record<string, ToolHandler>;
+/** The live tools for the conductor's effective forge entry `with`. */
+export declare function toolsFor(options: unknown): Record<string, ToolHandler>;

package/dist/src/tools.js

@@ -0,0 +1,182 @@
+// The forge tools. Every call takes the ticket, branch_name and base_branch
+// from the calling run; the token stays with the backend and is redacted
+// from every result and error.
+import { homeBbDir } from '@bakers-build/core';
+import { FORGE_NEEDS_BACKEND, loadForgeBackend, mergeRule } from './config.js';
+import { fetchBranches, pushBranch } from './git.js';
+import { derivedBase, isConventionalTitle, isOwned, ownershipRefusal, redact, TITLE_REFUSAL, } from './rules.js';
+export const FORGE_NEEDS_RUN = 'forge tools act only for an agent run: the call carries no ticket branch_name and base_branch (an operator delivers by hand)';
+function runOf(req) {
+    const t = req.ticket;
+    if (!t?.branchName || !t.baseBranch)
+        throw new Error(FORGE_NEEDS_RUN);
+    return {
+        identifier: t.identifier,
+        branchName: t.branchName,
+        baseBranch: t.baseBranch,
+    };
+}
+function ownedBranch(req, run) {
+    const branch = req.args.branch ?? run.branchName;
+    if (!isOwned(branch, run.branchName))
+        throw new Error(ownershipRefusal(branch, run.branchName));
+    return branch;
+}
+const json = (value) => ({
+    text: JSON.stringify(value, null, 2),
+});
+/** Failure first, then pending, over the required checks. */
+export function overall(checks) {
+    const required = checks.filter((c) => c.required);
+    if (required.some((c) => c.status === 'failure'))
+        return 'failure';
+    if (required.some((c) => c.status !== 'success'))
+        return 'pending';
+    return 'success';
+}
+export function forgeTools(deps) {
+    let loaded;
+    const backend = async () => (loaded = await deps.backend());
+    // Read at redaction time: a backend may mint or refresh its token mid-call.
+    const secrets = () => loaded?.secrets() ?? [];
+    // Every result and error leaves through the redactor.
+    const guarded = (handler) => async (req) => {
+        try {
+            const result = await handler(req);
+            return { text: redact(result.text, secrets()) };
+        }
+        catch (err) {
+            throw new Error(redact(err instanceof Error ? err.message : String(err), secrets()));
+        }
+    };
+    const tools = {
+        forge_fetch: async (req) => {
+            const run = runOf(req);
+            const extra = String(req.args.branches ?? '')
+                .split(/\s+/)
+                .filter(Boolean);
+            const b = await backend();
+            const refs = await fetchBranches(req.worktreePath, await b.gitAuth(), [
+                run.baseBranch,
+                run.branchName,
+                ...extra,
+            ]);
+            return json({ fetched: refs });
+        },
+        forge_push: async (req) => {
+            const run = runOf(req);
+            const branch = ownedBranch(req, run);
+            const b = await backend();
+            const sha = await pushBranch(req.worktreePath, await b.gitAuth(), branch, {
+                forceWithLease: req.args.force_with_lease === true,
+                ...(typeof req.args.expected_sha === 'string'
+                    ? { expectedSha: req.args.expected_sha }
+                    : {}),
+            });
+            return json({ branch, sha });
+        },
+        forge_pr_upsert: async (req) => {
+            const title = String(req.args.title);
+            // Refused before any request reaches the forge.
+            if (!isConventionalTitle(title))
+                throw new Error(TITLE_REFUSAL);
+            const run = runOf(req);
+            const branch = ownedBranch(req, run);
+            const body = req.args.body ?? '';
+            const b = await backend();
+            const open = await b.findOpenPr(branch);
+            const pr = open
+                ? await b.updatePr(open, { title, body })
+                : await b.createPr({
+                    head: branch,
+                    base: derivedBase(branch, run),
+                    title,
+                    body,
+                });
+            return json({
+                url: pr.url,
+                number: pr.number,
+                target: pr.base,
+                created: !open,
+            });
+        },
+        forge_checks: async (req) => {
+            const run = runOf(req);
+            const b = await backend();
+            let ref;
+            let base = run.baseBranch;
+            if (typeof req.args.ref === 'string' && req.args.branch === undefined) {
+                ref = req.args.ref;
+            }
+            else {
+                const branch = ownedBranch(req, run);
+                const pr = await b.findOpenPr(branch);
+                ref = pr?.headSha ?? branch;
+                base = pr?.base ?? derivedBase(branch, run);
+            }
+            const checks = await b.checks(ref, base);
+            return json({ ref, base, overall: overall(checks), checks });
+        },
+        forge_merge: async (req) => {
+            const run = runOf(req);
+            const branch = ownedBranch(req, run);
+            const base = derivedBase(branch, run);
+            const b = await backend();
+            const pr = await b.findOpenPr(branch);
+            if (!pr)
+                throw new Error(`no open PR/MR from '${branch}'; open it with forge_pr_upsert`);
+            if (pr.base !== base)
+                throw new Error(`PR/MR ${pr.url} targets '${pr.base}', but '${branch}' merges into '${base}'; close it and open one into '${base}'`);
+            if (!isConventionalTitle(pr.title))
+                throw new Error(`PR/MR ${pr.url}: ${TITLE_REFUSAL}; retitle it with forge_pr_upsert`);
+            const blocker = await b.mergeBlocker(pr);
+            if (blocker)
+                throw new Error(`PR/MR ${pr.url} cannot merge: ${blocker}`);
+            const checks = await b.checks(pr.headSha, pr.base);
+            const notGreen = checks.filter((c) => c.required && c.status !== 'success');
+            if (notGreen.length > 0)
+                throw new Error(`PR/MR ${pr.url} has required checks that are not green: ${notGreen.map((c) => `${c.name} (${c.status})`).join(', ')}`);
+            const rule = mergeRule(deps.settings, base);
+            const dependents = (await b.openPrsWithBase(branch)).filter((p) => p.number !== pr.number);
+            const deleteSource = rule.delete_source && dependents.length === 0;
+            await b.merge(pr, {
+                method: rule.method,
+                deleteSource,
+                subject: pr.title,
+                body: `Merged-by: bakers.build\nref:${run.identifier}`,
+            });
+            if (!(await b.isMerged(pr)))
+                throw new Error(`PR/MR ${pr.url} does not report merged after the merge call`);
+            return json({
+                url: pr.url,
+                merged: true,
+                into: base,
+                method: rule.method,
+                source_deleted: deleteSource,
+                ...(dependents.length > 0
+                    ? { source_kept_for: dependents.map((p) => p.url) }
+                    : {}),
+            });
+        },
+    };
+    return Object.fromEntries(Object.entries(tools).map(([n, h]) => [n, guarded(h)]));
+}
+/** The live tools for the conductor's effective forge entry `with`. */
+export function toolsFor(options) {
+    const backend = options
+        ?.backend;
+    // Fail closed: a forge entry without a backend stops the conductor's start.
+    if (typeof backend?.use !== 'string' || backend.use === '')
+        throw new Error(FORGE_NEEDS_BACKEND);
+    let loaded;
+    return forgeTools({
+        settings: options,
+        backend: () => {
+            loaded ??= loadForgeBackend(options, homeBbDir()).catch((err) => {
+                loaded = undefined;
+                throw err;
+            });
+            return loaded;
+        },
+    });
+}

package/options.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bakers.build/schema/addon-forge/options.schema.json",
+  "title": "@bakers-build/addon-forge options",
+  "description": "The forge entry's with.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "backend"
+  ],
+  "properties": {
+    "backend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "use"
+      ],
+      "properties": {
+        "use": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The backend package."
+        },
+        "with": {
+          "description": "The backend package's own settings, checked by that package's options.schema.json."
+        }
+      }
+    },
+    "merge": {
+      "type": "object",
+      "description": "Merge rule per base branch; '*' for every other base.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "method",
+          "delete_source"
+        ],
+        "properties": {
+          "method": {
+            "enum": [
+              "squash",
+              "merge"
+            ]
+          },
+          "delete_source": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@bakers-build/addon-forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1-next.2",
+  "description": "bakers.build forge tools: a sandboxed run fetches, pushes its own branches, opens its PR/MR, reads checks and merges through the conductor, which holds the token. Backends implement the ForgeBackend contract (./backend).",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    "./preset": "./dist/src/preset.js",
+    "./backend": "./dist/src/backend.js",
+    "./options.schema.json": "./options.schema.json"
+  },
+  "files": [
+    "dist/src",
+    "options.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/forge"
+  },
+  "peerDependencies": {
+    "@bakers-build/conductor": "^0.8.1-next.2",
+    "@bakers-build/core": "^0.8.1-next.2"
+  },
+  "bakersBuild": {
+    "commit": "0177880667693d1c36c65ffced82d2f3a17cbf2a",
+    "channel": "next"
+  }
+}