@bakers-build/conductor 0.0.0-stage → 0.1.0-next.42

package/dist/src/cli/config-schema.d.ts

@@ -0,0 +1,137 @@
+/**
+ * A single, discrete, testable upgrade method `vN → vN+1`, registered in order —
+ * exactly like a Drupal `hook_update_N` chain. `bakers config upgrade` resolves a config's
+ * current version and applies each method in sequence up to CURRENT (it does not
+ * blindly overwrite), so a method can PRESERVE operator-set fields across a bump.
+ */
+export interface ConnectionConfigMigration {
+    /** The schema version this method upgrades FROM. */
+    from: number;
+    /** The schema version this method upgrades TO (=== from + 1). */
+    to: number;
+    /** What shape change this method performs (human-readable). */
+    description: string;
+    /**
+     * Upgrade the config text from `from` to `to`, returning the new file text
+     * WITHOUT the version header — the runner re-stamps `@bakers-schema-version to`.
+     */
+    apply(currentText: string): string;
+}
+/**
+ * BB-226: the package name whose `plugins[]` entry contributes the `md`
+ * renderer (plus the authoritative JSON:API schema) to a connection config. The
+ * AGGREGATOR is named, not `@dropsh/plugin-markdown` directly: a direct
+ * `@dropsh/*` descriptor is unresolvable from `loadBbConfig`'s bases
+ * (config dir / host module / cwd), whereas `@bakers-build/addon-essentials` is a
+ * real dependency of both the host and the engine and therefore resolves in the
+ * monorepo AND from a global `@bakers-build/bakers` install. No `export:` is needed —
+ * the package default-exports its factory.
+ */
+export declare const RENDERER_PLUGIN_PACKAGE = "@bakers-build/addon-essentials";
+/** The exact `plugins[]` element text the v1→v2 migration and the scaffold emit. */
+export declare const RENDERER_PLUGIN_ENTRY = "{ plugin: '@bakers-build/addon-essentials' },";
+/**
+ * BB-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
+ * element, so `bakers dropsh --format md` works instead of failing with
+ * `E_CONFIG: Unknown format 'md'. Available: json`.
+ *
+ * A pure TEXT transform — the upgrade runner must never execute a possibly
+ * side-effecting config module. Idempotent: text that already names the package
+ * in CODE is returned unchanged (whole-line `//` comments are stripped for that
+ * probe, so the template's own explanatory header does not read as a hit), and a
+ * config with no `plugins: [` array literal (an `addons: []`-shaped or
+ * hand-reshaped file) is left alone rather than guessed at.
+ */
+export declare function addRendererPluginEntry(text: string): string;
+/** The dropsh plugin package whose entries carry a connection's OAuth identity. */
+export declare const OAUTH2_PLUGIN_PACKAGE = "@dropsh/plugin-oauth2";
+/**
+ * The id of the ONE oauth2 provider a bakers.build connection declares (BB-391 D1).
+ *
+ * `bakers`, not `session`: the entry names the CONNECTION, not a capability. Until
+ * v3 a config declared two providers that differed only by scope — `session`
+ * (`bb:session`) and `pm` (`bakers:project_manager`) — and every write had to
+ * pick one. What that choice cost is what BB-391 removes; the id therefore
+ * names the connection, and the surviving scope carries the capability.
+ */
+export declare const OAUTH2_PROVIDER_ID = "bakers";
+/**
+ * The ONE OAuth2 scope a bakers.build connection requests (BB-391 D1, as revised).
+ *
+ * There is exactly one, and there is not zero. `bb:session`'s role carries
+ * the ceiling of what a machine identity may do.
+ *
+ * Zero was the original design, and a live control plane refuted it:
+ * `simple_oauth`'s Oauth2AccessPolicy rewrites a token account's permissions
+ * with `overwrite: TRUE`, and for a `client_credentials` token — every bakers.build
+ * machine identity — the set becomes EXACTLY the scope's permissions, with
+ * neither user_role nor OG-rank permissions surviving. A request naming no scope
+ * against a consumer holding no default scopes does not even mint a token.
+ */
+export declare const OAUTH2_SCOPE = "bb:session";
+/**
+ * BB-391 (v2 → v3): collapse a connection's oauth2 entries into ONE `bakers`
+ * provider on ONE scope — the whole of the one-identity change, as a pure text
+ * transform.
+ *
+ * A MIGRATION rather than a cutover (spec D3): operators have hand-edited these
+ * files — a pinned literal `baseUrl`, a per-install `workspace_id`, an extra
+ * `addons[]` entry — so every value outside the two elements being merged is
+ * carried over verbatim, and the runner never EXECUTES a possibly
+ * side-effecting config module.
+ *
+ * The FIRST oauth2 element survives (it is the one v2 marked `default: true`);
+ * the rest are removed line-and-all. A config with no oauth2 element is left
+ * exactly as it is — that is the one silent no-op, and it is silent because
+ * there is nothing to collapse. An element that IS there but cannot be given the
+ * `bakers` identity throws (see {@link ensureProviderId}) rather than passing
+ * through unchanged.
+ */
+export declare function collapseOauth2Providers(text: string): string;
+/**
+ * The ordered, contiguous migration chain. v1 was the pre-BB-226 shape (auth
+ * plugins only); v2 adds the markdown renderer entry; v3 collapses the two
+ * differently-scoped oauth2 providers into ONE identity on ONE scope (BB-391)
+ * — one, not zero: see {@link OAUTH2_SCOPE} for why the scope survives.
+ * Nothing below v1 is a versioned config (v0 = seed / hand-authored / untouched).
+ * `BB_CONFIG_SCHEMA_VERSION` derives from the chain's last `to` — never
+ * hardcode it.
+ */
+export declare const CONNECTION_MIGRATIONS: ConnectionConfigMigration[];
+/** The current connection-config schema version — single source of truth. */
+export declare const BB_CONFIG_SCHEMA_VERSION: number;
+/** Parse the `@bakers-schema-version` marker from config text; `0` when absent. */
+export declare function schemaVersionOf(text: string): number;
+/**
+ * Read the schema version from a connection config FILE by regex (sync, never
+ * executes the module). `0` when the file is absent, unreadable, or carries no
+ * marker (legacy / hand-authored).
+ */
+export declare function readConfigSchemaVersion(path: string): number;
+/** Strip a leading `// @bakers-schema-version <N>` header line, if present. */
+export declare function stripVersionHeader(text: string): string;
+/** Prepend (replacing any existing) a `// @bakers-schema-version <N>` header. */
+export declare function stampVersion(text: string, version: number): string;
+/**
+ * Re-stamp the in-body `schema_version: <N>` field, which the generated config
+ * carries alongside the header marker for programmatic reads. The header is the
+ * upgrade decision's source of truth and is stamped by the runner; this keeps the
+ * FIELD from going stale when a migration bumps the version (BB-226 — the first
+ * migration is where the two could first disagree). No-op when the field is
+ * absent (a hand-authored config need not carry it).
+ */
+export declare function stampSchemaVersionField(text: string, version: number): string;
+/**
+ * Validate a migration chain is contiguous: each `to === from + 1`, the first
+ * migrates from v1, no gaps, and the chain ends at `current` (default CURRENT).
+ * An empty chain is valid iff `current === 1`. Throws with an actionable message.
+ */
+export declare function assertContiguous(chain: ConnectionConfigMigration[], current?: number): void;
+/**
+ * Walk the migration chain from `from` up to `to`, applying each method's
+ * `apply` in sequence. Input/output text is WITHOUT the version header — the
+ * caller stamps CURRENT after. After each step the in-body `schema_version:`
+ * field is re-stamped to that step's `to`, so no individual method has to know
+ * (or hardcode) its own number twice. `chain` is injectable for tests.
+ */
+export declare function applyMigrations(text: string, from: number, to: number, chain?: ConnectionConfigMigration[]): string;

package/dist/src/cli/config-schema.js

@@ -0,0 +1,239 @@
+import { readFileSync } from 'node:fs';
+import { ConfigSourceEditor } from './config-source-edit.js';
+// BB-216: schema versioning for the generated CONNECTION config
+// (`bakers.config.js`, project + home). Decoupled from the npm package semver —
+// the schema version bumps only when the config SHAPE changes, not every
+// release. Every generated connection config carries a machine-readable header
+// comment `// @bakers-schema-version <N>` (the source of truth for the upgrade
+// decision, read by regex so `bakers config upgrade` NEVER executes a possibly
+// side-effecting config module) and a `schema_version: <N>` field for
+// programmatic reads.
+/** The header marker prepended to every generated connection config. */
+const MARKER_RE = /@bakers-schema-version\s+(\d+)/;
+const HEADER_LINE_RE = /^\/\/ @bakers-schema-version \d+\n/;
+/**
+ * BB-226: the package name whose `plugins[]` entry contributes the `md`
+ * renderer (plus the authoritative JSON:API schema) to a connection config. The
+ * AGGREGATOR is named, not `@dropsh/plugin-markdown` directly: a direct
+ * `@dropsh/*` descriptor is unresolvable from `loadBbConfig`'s bases
+ * (config dir / host module / cwd), whereas `@bakers-build/addon-essentials` is a
+ * real dependency of both the host and the engine and therefore resolves in the
+ * monorepo AND from a global `@bakers-build/bakers` install. No `export:` is needed —
+ * the package default-exports its factory.
+ */
+export const RENDERER_PLUGIN_PACKAGE = '@bakers-build/addon-essentials';
+/** The exact `plugins[]` element text the v1→v2 migration and the scaffold emit. */
+export const RENDERER_PLUGIN_ENTRY = `{ plugin: '${RENDERER_PLUGIN_PACKAGE}' },`;
+/**
+ * BB-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
+ * element, so `bakers dropsh --format md` works instead of failing with
+ * `E_CONFIG: Unknown format 'md'. Available: json`.
+ *
+ * A pure TEXT transform — the upgrade runner must never execute a possibly
+ * side-effecting config module. Idempotent: text that already names the package
+ * in CODE is returned unchanged (whole-line `//` comments are stripped for that
+ * probe, so the template's own explanatory header does not read as a hit), and a
+ * config with no `plugins: [` array literal (an `addons: []`-shaped or
+ * hand-reshaped file) is left alone rather than guessed at.
+ */
+export function addRendererPluginEntry(text) {
+    const e = new ConfigSourceEditor(text);
+    const array = e.property('plugins');
+    if (array?.nodeType !== 'ArrayExpression')
+        return text;
+    if ([...e.source.properties].some(([key, p]) => /^plugins\[\d+\]\.plugin$/.test(key) &&
+        p.value === RENDERER_PLUGIN_PACKAGE))
+        return text;
+    e.replace(array.valueStart + 1, array.valueStart + 1, `\n    ${RENDERER_PLUGIN_ENTRY}`);
+    return e.text;
+}
+/** The dropsh plugin package whose entries carry a connection's OAuth identity. */
+export const OAUTH2_PLUGIN_PACKAGE = '@dropsh/plugin-oauth2';
+/**
+ * The id of the ONE oauth2 provider a bakers.build connection declares (BB-391 D1).
+ *
+ * `bakers`, not `session`: the entry names the CONNECTION, not a capability. Until
+ * v3 a config declared two providers that differed only by scope — `session`
+ * (`bb:session`) and `pm` (`bakers:project_manager`) — and every write had to
+ * pick one. What that choice cost is what BB-391 removes; the id therefore
+ * names the connection, and the surviving scope carries the capability.
+ */
+export const OAUTH2_PROVIDER_ID = 'bakers';
+/**
+ * The ONE OAuth2 scope a bakers.build connection requests (BB-391 D1, as revised).
+ *
+ * There is exactly one, and there is not zero. `bb:session`'s role carries
+ * the ceiling of what a machine identity may do.
+ *
+ * Zero was the original design, and a live control plane refuted it:
+ * `simple_oauth`'s Oauth2AccessPolicy rewrites a token account's permissions
+ * with `overwrite: TRUE`, and for a `client_credentials` token — every bakers.build
+ * machine identity — the set becomes EXACTLY the scope's permissions, with
+ * neither user_role nor OG-rank permissions surviving. A request naming no scope
+ * against a consumer holding no default scopes does not even mint a token.
+ */
+export const OAUTH2_SCOPE = 'bb:session';
+/**
+ * BB-391 (v2 → v3): collapse a connection's oauth2 entries into ONE `bakers`
+ * provider on ONE scope — the whole of the one-identity change, as a pure text
+ * transform.
+ *
+ * A MIGRATION rather than a cutover (spec D3): operators have hand-edited these
+ * files — a pinned literal `baseUrl`, a per-install `workspace_id`, an extra
+ * `addons[]` entry — so every value outside the two elements being merged is
+ * carried over verbatim, and the runner never EXECUTES a possibly
+ * side-effecting config module.
+ *
+ * The FIRST oauth2 element survives (it is the one v2 marked `default: true`);
+ * the rest are removed line-and-all. A config with no oauth2 element is left
+ * exactly as it is — that is the one silent no-op, and it is silent because
+ * there is nothing to collapse. An element that IS there but cannot be given the
+ * `bakers` identity throws (see {@link ensureProviderId}) rather than passing
+ * through unchanged.
+ */
+export function collapseOauth2Providers(text) {
+    const e = new ConfigSourceEditor(text);
+    const entries = [...e.source.properties]
+        .filter(([key, p]) => /^plugins\[\d+\]\.plugin$/.test(key) &&
+        p.value === OAUTH2_PLUGIN_PACKAGE)
+        .map(([key]) => key.replace(/\.plugin$/, ''));
+    const first = entries[0];
+    if (!first)
+        return text;
+    if (e.property(`${first}.with`)?.nodeType !== 'ObjectExpression')
+        throw new Error('Cannot migrate oauth2 without a with object.');
+    for (const duplicate of entries.slice(1).reverse()) {
+        for (const key of ['client_id', 'client_secret', 'token_url', 'type']) {
+            if (e.expression(`${first}.with.${key}`) !==
+                e.expression(`${duplicate}.with.${key}`))
+                throw new Error('OAuth providers have conflicting connection inputs.');
+        }
+        e.remove(duplicate);
+    }
+    for (const [key, value] of [
+        ['id', "'bakers'"],
+        ['scope', "'bb:session'"],
+        ['default', 'true'],
+    ]) {
+        if (e.expression(`${first}.with.${key}`) !== value)
+            e.set(`${first}.with.${key}`, value);
+    }
+    return e.text;
+}
+/**
+ * The ordered, contiguous migration chain. v1 was the pre-BB-226 shape (auth
+ * plugins only); v2 adds the markdown renderer entry; v3 collapses the two
+ * differently-scoped oauth2 providers into ONE identity on ONE scope (BB-391)
+ * — one, not zero: see {@link OAUTH2_SCOPE} for why the scope survives.
+ * Nothing below v1 is a versioned config (v0 = seed / hand-authored / untouched).
+ * `BB_CONFIG_SCHEMA_VERSION` derives from the chain's last `to` — never
+ * hardcode it.
+ */
+export const CONNECTION_MIGRATIONS = [
+    {
+        from: 1,
+        to: 2,
+        description: `add the ${RENDERER_PLUGIN_PACKAGE} renderer entry to plugins[]`,
+        apply: addRendererPluginEntry,
+    },
+    {
+        from: 2,
+        to: 3,
+        description: `collapse the two ${OAUTH2_PLUGIN_PACKAGE} entries into one ` +
+            `'${OAUTH2_PROVIDER_ID}' provider on scope '${OAUTH2_SCOPE}'`,
+        apply: collapseOauth2Providers,
+    },
+    {
+        from: 3,
+        to: 4,
+        description: 'connection owns credentials and workspace independently of machine context',
+        apply: (text) => {
+            const source = new ConfigSourceEditor(text);
+            if (/const (baseUrl|clientId|clientSecret|workspaceId) = [^;]*machine\.(base_url|client_id|client_secret|workspace_id)/.test(text) ||
+                [...source.source.properties.keys()].some((key) => /\bmachine\.(base_url|client_id|client_secret|workspace_id)\b/.test(source.expression(key) ?? '')))
+                throw new Error('Connection ownership requires scoped cross-file planning.');
+            return text;
+        },
+    },
+];
+/** The current connection-config schema version — single source of truth. */
+export const BB_CONFIG_SCHEMA_VERSION = CONNECTION_MIGRATIONS.at(-1)?.to ?? 1;
+/** Parse the `@bakers-schema-version` marker from config text; `0` when absent. */
+export function schemaVersionOf(text) {
+    const m = MARKER_RE.exec(text);
+    return m ? Number.parseInt(m[1], 10) : 0;
+}
+/**
+ * Read the schema version from a connection config FILE by regex (sync, never
+ * executes the module). `0` when the file is absent, unreadable, or carries no
+ * marker (legacy / hand-authored).
+ */
+export function readConfigSchemaVersion(path) {
+    try {
+        return schemaVersionOf(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return 0;
+    }
+}
+/** Strip a leading `// @bakers-schema-version <N>` header line, if present. */
+export function stripVersionHeader(text) {
+    return text.replace(HEADER_LINE_RE, '');
+}
+/** Prepend (replacing any existing) a `// @bakers-schema-version <N>` header. */
+export function stampVersion(text, version) {
+    return `// @bakers-schema-version ${version}\n${stripVersionHeader(text)}`;
+}
+/**
+ * Re-stamp the in-body `schema_version: <N>` field, which the generated config
+ * carries alongside the header marker for programmatic reads. The header is the
+ * upgrade decision's source of truth and is stamped by the runner; this keeps the
+ * FIELD from going stale when a migration bumps the version (BB-226 — the first
+ * migration is where the two could first disagree). No-op when the field is
+ * absent (a hand-authored config need not carry it).
+ */
+export function stampSchemaVersionField(text, version) {
+    return text.replace(/^([ \t]*)schema_version:\s*\d+\s*,/m, `$1schema_version: ${version},`);
+}
+/**
+ * Validate a migration chain is contiguous: each `to === from + 1`, the first
+ * migrates from v1, no gaps, and the chain ends at `current` (default CURRENT).
+ * An empty chain is valid iff `current === 1`. Throws with an actionable message.
+ */
+export function assertContiguous(chain, current = BB_CONFIG_SCHEMA_VERSION) {
+    let prev = 1;
+    chain.forEach((m, i) => {
+        if (m.to !== m.from + 1) {
+            throw new Error(`migration[${i}]: to (${m.to}) must equal from+1 (${m.from + 1})`);
+        }
+        const expectedFrom = i === 0 ? 1 : prev;
+        if (m.from !== expectedFrom) {
+            throw new Error(`migration[${i}]: from (${m.from}) must equal ${expectedFrom} (no gaps; chain starts at v1)`);
+        }
+        prev = m.to;
+    });
+    const end = chain.at(-1)?.to ?? 1;
+    if (end !== current) {
+        throw new Error(`migration chain ends at v${end}, expected CURRENT v${current}`);
+    }
+}
+/**
+ * Walk the migration chain from `from` up to `to`, applying each method's
+ * `apply` in sequence. Input/output text is WITHOUT the version header — the
+ * caller stamps CURRENT after. After each step the in-body `schema_version:`
+ * field is re-stamped to that step's `to`, so no individual method has to know
+ * (or hardcode) its own number twice. `chain` is injectable for tests.
+ */
+export function applyMigrations(text, from, to, chain = CONNECTION_MIGRATIONS) {
+    let cur = from;
+    let out = text;
+    while (cur < to) {
+        const step = chain.find((m) => m.from === cur);
+        if (step === undefined) {
+            throw new Error(`no migration from v${cur} (chain incomplete)`);
+        }
+        out = stampSchemaVersionField(step.apply(out), step.to);
+        cur = step.to;
+    }
+    return out;
+}

package/dist/src/cli/config-source-edit.d.ts

@@ -0,0 +1,17 @@
+import { type ConfigSourceProperty } from '@bakers-build/core';
+/** Small span editor. Every operation re-parses so offsets never become stale. */
+export declare class ConfigSourceEditor {
+    text: string;
+    constructor(text: string);
+    get source(): import("@bakers-build/core").ConfigSourceInspection;
+    property(key: string): ConfigSourceProperty | undefined;
+    expression(key: string): string | undefined;
+    replace(start: number, end: number, value: string): void;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    rename(key: string, next: string): void;
+    stamp(version: number): void;
+}
+export declare function sameValue(a: ConfigSourceProperty, b: ConfigSourceProperty): boolean;
+/** Hide all computed source and every credential-bearing statement in previews. */
+export declare function redactConfigSource(text: string): string;

package/dist/src/cli/config-source-edit.js

@@ -0,0 +1,95 @@
+import { inspectConfigSource, } from '@bakers-build/core';
+/** Small span editor. Every operation re-parses so offsets never become stale. */
+export class ConfigSourceEditor {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    get source() {
+        return inspectConfigSource(this.text);
+    }
+    property(key) {
+        return this.source.properties.get(key);
+    }
+    expression(key) {
+        const p = this.property(key);
+        return p ? this.text.slice(p.valueStart, p.valueEnd) : undefined;
+    }
+    replace(start, end, value) {
+        this.text = this.text.slice(0, start) + value + this.text.slice(end);
+    }
+    set(key, value) {
+        const existing = this.property(key);
+        if (existing) {
+            this.replace(existing.valueStart, existing.valueEnd, value);
+            return;
+        }
+        const dot = key.lastIndexOf('.');
+        const parentKey = dot < 0 ? null : key.slice(0, dot);
+        const name = dot < 0 ? key : key.slice(dot + 1);
+        const source = this.source;
+        const parent = parentKey ? source.properties.get(parentKey) : undefined;
+        if (parentKey && !parent) {
+            this.set(parentKey, `{ ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name)}: ${value} }`);
+            return;
+        }
+        const start = parent ? parent.valueStart : source.object?.start;
+        if (start === undefined ||
+            (parent && parent.nodeType !== 'ObjectExpression'))
+            throw new Error('Unsupported insertion');
+        this.replace(start + 1, start + 1, `\n  ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name)}: ${value},`);
+    }
+    remove(key) {
+        const p = this.property(key);
+        if (!p)
+            return;
+        let end = p.end;
+        while (/\s/.test(this.text[end] ?? '') && end < this.text.length)
+            end++;
+        if (this.text[end] === ',')
+            this.replace(p.start, end + 1, '');
+        else {
+            let start = p.start - 1;
+            while (start >= 0 && /\s/.test(this.text[start] ?? ''))
+                start--;
+            this.replace(this.text[start] === ',' ? start : p.start, p.end, '');
+        }
+    }
+    rename(key, next) {
+        const p = this.property(key);
+        if (!p)
+            return;
+        const colon = this.text.indexOf(':', p.start);
+        if (colon < 0 || colon >= p.valueStart)
+            throw new Error('Unsupported key');
+        this.replace(p.start, colon, next);
+    }
+    stamp(version) {
+        this.set('schema_version', String(version));
+        this.text = this.text
+            .replace(/^\s*\/\/ @bakers-schema-version \d+\s*$/gm, '')
+            .replace(/^\n/, '');
+        this.text = `// @bakers-schema-version ${version}\n${this.text}`;
+    }
+}
+export function sameValue(a, b) {
+    return (a.staticallyDetermined &&
+        b.staticallyDetermined &&
+        a.value !== undefined &&
+        a.value === b.value);
+}
+/** Hide all computed source and every credential-bearing statement in previews. */
+export function redactConfigSource(text) {
+    const editor = new ConfigSourceEditor(text);
+    const source = editor.source;
+    if (source.syntax !== 'valid' || !source.object)
+        return '[SOURCE REDACTED]';
+    const spans = source.propertyOccurrences.filter((p) => /secret|token|password|credential|client_id|authorization|url/i.test(p.key) ||
+        (!p.staticallyDetermined &&
+            !['ObjectExpression', 'ArrayExpression'].includes(p.nodeType)));
+    const outer = spans.filter((p) => !spans.some((q) => q !== p && q.valueStart <= p.valueStart && q.valueEnd >= p.valueEnd));
+    for (const p of outer.sort((a, b) => b.valueStart - a.valueStart))
+        editor.replace(p.valueStart, p.valueEnd, "'[REDACTED]'");
+    const clean = editor.source;
+    return `[Module preamble redacted]\nexport default ${editor.text.slice(clean.object?.start, clean.object?.end)};`;
+}

package/dist/src/cli/config-templates.d.ts

@@ -0,0 +1,43 @@
+export declare const DEFAULT_CONDUCTOR_AGENT_ADDONS = "[{ use: '@bakers-build/addon-herdr' }, { use: '@bakers-build/addon-claude', alias: 'opus' }]";
+/**
+ * A dynamic-import expression for a user-global config file, as source text.
+ *
+ * The result goes into a COMMITTED file, so it must name no path from the
+ * machine that generated it: an absolute path resolves nowhere on the next
+ * checkout, and loadMachine() swallows that failure, leaving conductor_id
+ * undefined with nothing erroring. BB_HOME is the relocation knob; HOME
+ * stays the fallback so the generated text works on a machine that sets
+ * neither.
+ */
+export declare function configImportExpression(name: string): string;
+export type ConnectionAuthType = 'oauth2_client_credentials' | 'oauth2_device_code';
+/** Current connection template inputs never come from machine context. */
+export interface ConnectionInputs {
+    baseUrl: string;
+    clientId: string;
+    /** Absent for `oauth2_device_code`: a public client holds no secret. */
+    secret?: string;
+    workspaceId?: string;
+    authType: ConnectionAuthType;
+}
+export declare function renderGlobalConnection(inputs: ConnectionInputs): string;
+export declare function renderHostMachine(inputs: {
+    machineId: string;
+    userId: string;
+    maxParallel: number;
+}): string;
+export declare function renderCommittedConfig(inputs: {
+    project: string;
+    bakersWorkspace?: string;
+    /**
+     * The operator's own answer for each lifecycle hook — never invented here.
+     * `bakers-cli` names no provisioning tool: an absent or empty command omits
+     * that hook's key entirely, and an all-absent `hooks` omits the whole block
+     * rather than writing an empty one, because an empty `hooks: {}` would
+     * state a decision no one made.
+     */
+    hooks?: {
+        after_create?: string;
+        after_done?: string;
+    };
+}): string;

package/dist/src/cli/config-templates.js

@@ -0,0 +1,130 @@
+export const DEFAULT_CONDUCTOR_AGENT_ADDONS = "[{ use: '@bakers-build/addon-herdr' }, { use: '@bakers-build/addon-claude', alias: 'opus' }]";
+/**
+ * A dynamic-import expression for a user-global config file, as source text.
+ *
+ * The result goes into a COMMITTED file, so it must name no path from the
+ * machine that generated it: an absolute path resolves nowhere on the next
+ * checkout, and loadMachine() swallows that failure, leaving conductor_id
+ * undefined with nothing erroring. BB_HOME is the relocation knob; HOME
+ * stays the fallback so the generated text works on a machine that sets
+ * neither.
+ */
+export function configImportExpression(name) {
+    return `\`\${process.env.BB_HOME ?? \`\${process.env.HOME}/.bakers\`}/${name}\``;
+}
+export function renderGlobalConnection(inputs) {
+    // The device-code grant has no client_secret in @dropsh/plugin-oauth2's
+    // config union, so the key is omitted rather than rendered undefined
+    // (BB-496), and it carries device_authorization_url instead.
+    const baseUrl = inputs.baseUrl.replace(/\/$/, '');
+    // The client-credentials branch renders byte-identical to the pre-BB-496
+    // template (a single-quoted `type:` literal): only the device-code branch,
+    // which is new, uses JSON.stringify for its type value.
+    const type = inputs.authType === 'oauth2_device_code'
+        ? JSON.stringify(inputs.authType)
+        : "'oauth2_client_credentials'";
+    const credential = inputs.authType === 'oauth2_device_code'
+        ? `client_id: ${JSON.stringify(inputs.clientId)},
+      device_authorization_url: ${JSON.stringify(`${baseUrl}/oauth/device_authorization`)},`
+        : `client_id: ${JSON.stringify(inputs.clientId)}, client_secret: ${JSON.stringify(inputs.secret ?? '')},`;
+    return `// @bakers-schema-version 4
+// Global bakers.build connection: credentials and optional legacy workspace. Keep this file private.
+export default {
+  schema_version: 4,
+  site: { base_url: ${JSON.stringify(inputs.baseUrl)}, jsonapi_prefix: '/jsonapi' },
+${inputs.workspaceId ? `  workspace_id: ${JSON.stringify(inputs.workspaceId)},\n` : ''}
+  plugins: [
+    { plugin: '@bakers-build/addon-essentials' },
+    { plugin: '@dropsh/plugin-oauth2', export: 'oauth2Plugin', with: {
+      id: 'bakers', default: true, type: ${type}, scope: 'bb:session',
+      ${credential}
+      token_url: ${JSON.stringify(`${baseUrl}/oauth/token`)},
+    } },
+  ],
+};
+`;
+}
+export function renderHostMachine(inputs) {
+    return `// @bakers-schema-version 2
+// Local host identity and capacity. Server credentials belong to bakers.config.js.
+export default {
+ schema_version: 2,
+ machine_id: ${JSON.stringify(inputs.machineId)},
+ user_id: ${JSON.stringify(inputs.userId)},
+ max_parallel: ${inputs.maxParallel},
+};
+`;
+}
+export function renderCommittedConfig(inputs) {
+    return `// Canonical bakers.build conductor engine configuration — committed.
+// Host identity comes from machine.config.js; the optional local override
+// composes this project's conductor identity. Connections belong to bakers.config.js.
+//
+// IMPORT-FREE (BB-78): the plugin slots are \`{ plugin, with }\` descriptors
+// naming the REAL published package, not \`import\`ed constructors.
+// loadConductorConfig resolves each name ESLint-style (config dir → cwd →
+// conductor install). Every addon package default-exports its single factory, so
+// no slot needs an \`export:\` — EXCEPT the merged herdr workspace
+// (\`@bakers-build/addon-herdr\` default-exports the executor, so the workspace names
+// \`export: 'herdrWorkspace'\` — BB-139). BB-224 replaced the old
+// \`{ plugin: '@bakers-build/bakers/plugins', export: 'drupalRemote' }\` host-barrel
+// descriptor with the real addon package \`@bakers-build/addon-remote-drupal\`.
+
+// The user-global machine context: host identity and capacity, shared
+// by every project on this machine. Never committed.
+async function loadMachine() {
+  try {
+    return (await import(${configImportExpression('machine.config.js')})).default ?? {};
+  } catch {}
+  return {};
+}
+
+// OPTIONAL per-project override — create conductor.config.local.js beside this
+// file to override machine-local values (conductor_id, model, …).
+async function loadLocal() {
+  try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
+  return {};
+}
+
+const machine = await loadMachine();
+const local = await loadLocal();
+const project = ${JSON.stringify(inputs.project)};
+const composedConductorId =
+  machine.user_id && machine.machine_id
+    ? \`\${machine.user_id}-\${machine.machine_id}-\${project}\`
+    : undefined;
+
+export default {
+  bakers: { project: ${JSON.stringify(inputs.project)}${inputs.bakersWorkspace ? `, workspace: ${JSON.stringify(inputs.bakersWorkspace)}` : ''} },
+  // Registration key (BB-353 renamed from machine_id). Host capacity lives on
+  // machine.config.js as max_parallel — do not set max_parallel here.
+  conductor_id: local.conductor_id ?? composedConductorId,
+  // Set to false to keep this conductor's transcripts out of the log store
+  // (e.g. large, uninteresting, or subject to a local policy). Default true;
+  // metrics are unaffected either way.
+  capture_logs: true,
+${inputs.hooks?.after_create || inputs.hooks?.after_done
+        ? `  // Lifecycle hooks are executor-owned (BB-84): they live at the config top
+  // level — NOT on a plugin descriptor's \`with.hooks\`.
+  hooks: { ${[
+            inputs.hooks.after_create
+                ? `after_create: ${JSON.stringify(inputs.hooks.after_create)}`
+                : '',
+            inputs.hooks.after_done
+                ? `after_done: ${JSON.stringify(inputs.hooks.after_done)}`
+                : '',
+        ]
+            .filter(Boolean)
+            .join(', ')} },\n`
+        : ''}  remote: { plugin: '@bakers-build/addon-remote-drupal' },
+  executor: { plugin: '@bakers-build/addon-herdr' },
+  addons: ${DEFAULT_CONDUCTOR_AGENT_ADDONS},
+  // BB-139: the herdr workspace ships in @bakers-build/addon-herdr, which
+  // default-exports the EXECUTOR — so the workspace slot names export: 'herdrWorkspace'.
+  workspace: {
+    plugin: '@bakers-build/addon-herdr',
+    export: 'herdrWorkspace',
+  },
+};
+`;
+}