@bakers-build/core 0.0.0-stage → 0.1.0-next.38

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/core
 
-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 surface-agnostic kernel: host contract, split-config helpers, addon preset/discovery machinery, shared primitives.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://git.key-tec.de/bakers-build/bakers-build (bakers-cli/).

package/dist/src/cli/bakers-dir.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The conductor stem a config file name denotes, or `undefined` when the file
+ * is not a conductor config at all.
+ *
+ * The inverse of {@link fileForStem}, exported because the naming rule has to
+ * stay in one place: a conductor reporting which config it was started from
+ * would otherwise slice the filename itself and quietly disagree with the
+ * loader about the near-miss cases this rule exists to exclude
+ * (`myconductor.config.js`, `vite.config.js`, `bakers.config.js`).
+ *
+ * Takes a bare file name, not a path — callers pass `basename(config_path)`.
+ */
+export declare function stemForConfigFile(fileName: string): string | undefined;
+/**
+ * The user-global `.bakers` dir. Core owns where the split-config files live,
+ * so a consumer that must recognise the home dir (e.g. to exclude it from a
+ * project walk-up, BB-219 AC-9) asks for it rather than joining it itself.
+ *
+ * This is the ONE place that decides where `.bakers` lives. `BB_HOME` names
+ * that directory itself — not a home containing one — so an isolated test, a
+ * second identity on one machine, or a container can relocate it without
+ * redirecting HOME. A relative value is resolved against the cwd, because the
+ * value travels into generated config text where an ambiguous path is a bug.
+ * An explicit `home` argument still wins: callers that already know whose home
+ * they mean (a fixture, another user's layer) are not overridden by the
+ * environment.
+ */
+export declare function homeBbDir(home?: string): string;
+/**
+ * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
+ * `.bakers/` dir holds at least one conductor config; return that `.bakers/` dir, or
+ * `undefined` if none is found up to the filesystem root.
+ */
+export declare function findBbDir(cwd: string): string | undefined;
+/**
+ * Resolve the ENGINE (`conductor.config.js`) config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$BB_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.bakers/` dir holding a conductor
+ *    config — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$BB_CONDUCTOR` selector resolves the stem's
+ *      file (`conductor` → `conductor.config.js`, else `<name>.conductor.config.js`).
+ *    - No selector: `conductor.config.js` present → the default; else exactly
+ *      one config → use it (back-compat); else → error naming the stems.
+ * 3. No `.bakers/` config anywhere up the tree → an `ENOENT` error naming
+ *    `bakers config init --scope project`.
+ */
+export declare function resolveConfigPath(override?: string, cwd?: string, conductorName?: string): string;
+/**
+ * Which leg of the connection precedence produced the resolved path. Purely
+ * diagnostic (BB-219 D4): it lets a consumer report project-vs-home without
+ * re-deriving the rule, which would be a second precedence implementation.
+ */
+export type BbConfigSource = 'explicit' | 'project' | 'home';
+/** A current resolved connection with diagnostic source metadata. */
+export interface BbConfigResolution {
+    path: string;
+    /** Current connections never use a credential fallback. */
+    fallback: boolean;
+    /** Current resolution never selects a historical engine connection. */
+    legacy: boolean;
+    /** Which leg produced `path` (BB-219 D4). */
+    source: BbConfigSource;
+}
+/** Walk upward for current project connection files only. Legacy engine files
+ * are migration input, never runtime connection sources. */
+export declare function findBbConfig(cwd: string): {
+    path: string;
+    legacy: boolean;
+} | undefined;
+/**
+ * Walk root-ward for the nearest `.bakers/` dir that marks a **project** — one
+ * holding any bakers config at all, a `bakers.config.js` or at least one conductor
+ * config. Returns that `.bakers/` dir, or `undefined` up to the filesystem root.
+ *
+ * Deliberately a different question from `findBbConfig` (BB-219 AC-9):
+ * "which project am I standing in" is not "where does my connection come from".
+ * Since BB-230 the connection walk-up skips an engine-only
+ * `conductor.config.js`, and BB-218 makes exactly that the canonical repo
+ * shape — so keying project detection on the connection would stop recognising
+ * the most common project as a project. It is content-agnostic for the same
+ * reason `findBbDir` is: a `.bakers/` dir is the marker.
+ *
+ * It is a superset of `findBbDir`, which requires a *conductor* config
+ * because it resolves the engine config; a repo carrying only a project
+ * connection override is a project here and not there.
+ */
+export declare function findProjectBbDir(cwd: string): string | undefined;
+/** Configuration management also recognizes an empty/partial .bakers directory.
+ * Keep runtime engine and connection root resolution unchanged.
+ */
+export declare function findConfigProjectBbDir(cwd: string, home?: string): string | undefined;
+/** Resolve explicit → project → global connection. An absent global still
+ * names its canonical owner so callers can provide a precise init remedy. */
+export declare function resolveBbConfigPath(opts?: {
+    cwd?: string;
+    explicit?: string | undefined;
+    home?: string;
+}): BbConfigResolution;

package/dist/src/cli/bakers-dir.js

@@ -0,0 +1,228 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** A repo's config files live in this dir, one conductor config per conductor. */
+const BB_DIR = '.bakers';
+/** The default conductor's file name; its stem is `conductor`. */
+const DEFAULT_CONFIG = 'conductor.config.js';
+/** Variant files are `<stem>.conductor.config.js`. */
+const VARIANT_SUFFIX = '.conductor.config.js';
+/** The connection config file name (project + home). */
+const BB_CONFIG = 'bakers.config.js';
+/**
+ * List the conductor-config stems in a `.bakers/` dir. A file is a conductor
+ * config iff it is exactly `conductor.config.js` (stem `conductor`, the
+ * default) or ends with `.conductor.config.js` (stem = the leading part).
+ * Every other file (`vite.config.js`, the near-miss `myconductor.config.js`,
+ * and `bakers.config.js` itself) is ignored.
+ */
+function configStems(bakersDir) {
+    return readdirSync(bakersDir)
+        .map(stemForConfigFile)
+        .filter((s) => s !== undefined)
+        .sort();
+}
+/**
+ * The conductor stem a config file name denotes, or `undefined` when the file
+ * is not a conductor config at all.
+ *
+ * The inverse of {@link fileForStem}, exported because the naming rule has to
+ * stay in one place: a conductor reporting which config it was started from
+ * would otherwise slice the filename itself and quietly disagree with the
+ * loader about the near-miss cases this rule exists to exclude
+ * (`myconductor.config.js`, `vite.config.js`, `bakers.config.js`).
+ *
+ * Takes a bare file name, not a path — callers pass `basename(config_path)`.
+ */
+export function stemForConfigFile(fileName) {
+    if (fileName === DEFAULT_CONFIG)
+        return 'conductor';
+    if (fileName.endsWith(VARIANT_SUFFIX)) {
+        const stem = fileName.slice(0, -VARIANT_SUFFIX.length);
+        return stem === '' ? undefined : stem;
+    }
+    return undefined;
+}
+/** Map a conductor stem back to its file name. */
+function fileForStem(stem) {
+    return stem === 'conductor' ? DEFAULT_CONFIG : `${stem}${VARIANT_SUFFIX}`;
+}
+/**
+ * The user-global `.bakers` dir. Core owns where the split-config files live,
+ * so a consumer that must recognise the home dir (e.g. to exclude it from a
+ * project walk-up, BB-219 AC-9) asks for it rather than joining it itself.
+ *
+ * This is the ONE place that decides where `.bakers` lives. `BB_HOME` names
+ * that directory itself — not a home containing one — so an isolated test, a
+ * second identity on one machine, or a container can relocate it without
+ * redirecting HOME. A relative value is resolved against the cwd, because the
+ * value travels into generated config text where an ambiguous path is a bug.
+ * An explicit `home` argument still wins: callers that already know whose home
+ * they mean (a fixture, another user's layer) are not overridden by the
+ * environment.
+ */
+export function homeBbDir(home) {
+    if (home !== undefined)
+        return join(home, BB_DIR);
+    const override = process.env.BB_HOME;
+    return override ? resolve(override) : join(homedir(), BB_DIR);
+}
+/**
+ * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
+ * `.bakers/` dir holds at least one conductor config; return that `.bakers/` dir, or
+ * `undefined` if none is found up to the filesystem root.
+ */
+export function findBbDir(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const bakersDir = join(dir, BB_DIR);
+        if (existsSync(bakersDir) && configStems(bakersDir).length > 0) {
+            return bakersDir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Resolve the ENGINE (`conductor.config.js`) config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$BB_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.bakers/` dir holding a conductor
+ *    config — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$BB_CONDUCTOR` selector resolves the stem's
+ *      file (`conductor` → `conductor.config.js`, else `<name>.conductor.config.js`).
+ *    - No selector: `conductor.config.js` present → the default; else exactly
+ *      one config → use it (back-compat); else → error naming the stems.
+ * 3. No `.bakers/` config anywhere up the tree → an `ENOENT` error naming
+ *    `bakers config init --scope project`.
+ */
+export function resolveConfigPath(override, cwd = process.cwd(), conductorName) {
+    const explicit = override ?? process.env.BB_CONDUCTOR_CONFIG;
+    if (explicit) {
+        return explicit;
+    }
+    const bakersDir = findBbDir(cwd);
+    if (bakersDir === undefined) {
+        // `ENOENT`, because that is what this is: the file the caller asked for
+        // does not exist. A caller for whom the project layer is optional then
+        // treats a failed walk and an absent file the same way, instead of
+        // discriminating one Error's message from another's.
+        //
+        // The remedy names `config init --scope project`, never `bakers init`: the
+        // latter writes machine and connection and deliberately leaves the project
+        // layer alone, so recommending it sends the reader back to the command
+        // they have already run.
+        throw Object.assign(new Error(`no .bakers/conductor.config.js found from ${cwd} upward; ` +
+            'run `bakers config init --scope project` in a project checkout'), { code: 'ENOENT' });
+    }
+    const stems = configStems(bakersDir);
+    const name = conductorName ?? process.env.BB_CONDUCTOR;
+    if (name !== undefined && name !== '') {
+        const candidate = join(bakersDir, fileForStem(name));
+        if (!existsSync(candidate)) {
+            throw new Error(`no conductor '${name}' in ${bakersDir}; available: ${stems.join(', ')}`);
+        }
+        return candidate;
+    }
+    if (stems.includes('conductor')) {
+        return join(bakersDir, DEFAULT_CONFIG);
+    }
+    if (stems.length === 1) {
+        return join(bakersDir, fileForStem(stems[0]));
+    }
+    throw new Error(`${stems.length} conductors in ${bakersDir} (${stems.join(', ')}); ` +
+        'select one with --conductor <name> or $BB_CONDUCTOR');
+}
+/** Walk upward for current project connection files only. Legacy engine files
+ * are migration input, never runtime connection sources. */
+export function findBbConfig(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const bakersDir = join(dir, BB_DIR);
+        if (existsSync(bakersDir)) {
+            const bakersCfg = join(bakersDir, BB_CONFIG);
+            if (existsSync(bakersCfg))
+                return { path: bakersCfg, legacy: false };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Walk root-ward for the nearest `.bakers/` dir that marks a **project** — one
+ * holding any bakers config at all, a `bakers.config.js` or at least one conductor
+ * config. Returns that `.bakers/` dir, or `undefined` up to the filesystem root.
+ *
+ * Deliberately a different question from `findBbConfig` (BB-219 AC-9):
+ * "which project am I standing in" is not "where does my connection come from".
+ * Since BB-230 the connection walk-up skips an engine-only
+ * `conductor.config.js`, and BB-218 makes exactly that the canonical repo
+ * shape — so keying project detection on the connection would stop recognising
+ * the most common project as a project. It is content-agnostic for the same
+ * reason `findBbDir` is: a `.bakers/` dir is the marker.
+ *
+ * It is a superset of `findBbDir`, which requires a *conductor* config
+ * because it resolves the engine config; a repo carrying only a project
+ * connection override is a project here and not there.
+ */
+export function findProjectBbDir(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const bakersDir = join(dir, BB_DIR);
+        if (existsSync(bakersDir) &&
+            (existsSync(join(bakersDir, BB_CONFIG)) ||
+                configStems(bakersDir).length > 0)) {
+            return bakersDir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Configuration management also recognizes an empty/partial .bakers directory.
+ * Keep runtime engine and connection root resolution unchanged.
+ */
+export function findConfigProjectBbDir(cwd, home) {
+    let dir = resolve(cwd);
+    const globalDir = resolve(homeBbDir(home));
+    for (;;) {
+        const bakersDir = join(dir, BB_DIR);
+        if (bakersDir !== globalDir && existsSync(bakersDir))
+            return bakersDir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Resolve explicit → project → global connection. An absent global still
+ * names its canonical owner so callers can provide a precise init remedy. */
+export function resolveBbConfigPath(opts = {}) {
+    const homeCfg = join(homeBbDir(opts.home), BB_CONFIG);
+    const explicit = opts.explicit;
+    if (explicit !== undefined && explicit.trim() !== '') {
+        return {
+            path: explicit,
+            fallback: false,
+            legacy: false,
+            source: 'explicit',
+        };
+    }
+    const cwd = opts.cwd ?? process.cwd();
+    const project = findBbConfig(cwd);
+    if (project !== undefined) {
+        return {
+            path: project.path,
+            fallback: false,
+            legacy: project.legacy,
+            source: project.path === homeCfg ? 'home' : 'project',
+        };
+    }
+    return { path: homeCfg, fallback: false, legacy: false, source: 'home' };
+}

package/dist/src/cli/commands.d.ts

@@ -0,0 +1,42 @@
+import type { Command } from 'commander';
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { BbConnectionConfig } from './load-bakers-config.js';
+/**
+ * What the host hands each command plugin at mount time. `resolveBases` is the
+ * ESLint-style base order the plugin passes to `resolveModuleEslintStyle` for
+ * pnpm-safe sibling resolution (renderer, dropsh auth plugins) — the host owns
+ * it because only the host knows its own install location; a plugin resolving
+ * from its own `import.meta.url` breaks under pnpm's isolated store.
+ */
+export interface BbCommandHost {
+    /** Base dirs/URLs for ESLint-style module resolution: host install → cwd. */
+    resolveBases: string[];
+    /** Host-owned product-workspace plugin factory for scoped command surfaces. */
+    workspacePlugin?: (workspaceId: string) => DropSHPlugin | Promise<DropSHPlugin>;
+    /** Conductor-owned project context, supplied by the meta host when present. */
+    projectContext?: {
+        resolveConfigPath(cwd: string): string;
+        readWorkspace(configPath: string): string | undefined;
+        writeWorkspace(configPath: string, name: string): Promise<void>;
+        resolveContext?(configPath: string, connection: BbConnectionConfig): Promise<{
+            projectId: string;
+            workspaceId: string;
+            workspace: string;
+        }>;
+    };
+}
+/**
+ * A command plugin the host mounts under its `name` (`bakers <name> …`).
+ * `describe` is shown in `bakers --help` even when the plugin is NOT loaded (the
+ * host renders a describe-only stub), so lazy mounting keeps `--help` complete.
+ * `register` receives the top-level `commander` program and the host; it adds
+ * the plugin's subcommand tree.
+ */
+export interface BbCommandPlugin {
+    /** BB-215: the total-tag discriminant — a command plugin self-identifies its
+     *  surface, like every other bakers.build plugin carries a `.kind`. */
+    readonly kind: 'command';
+    name: string;
+    describe: string;
+    register(program: Command, host: BbCommandHost): void | Promise<void>;
+}

package/dist/src/cli/commands.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,30 @@
+import { type ConfigFileKind, type ConfigOperation, type ConfigReport } from './config-report.js';
+import { type ConfigSourceInspection } from './config-source.js';
+export interface ConfigInventoryOptions {
+    operation?: ConfigOperation;
+    scope?: string;
+    cwd?: string;
+    path?: string;
+    home?: string;
+    machinePath?: string;
+    connectionPath?: string;
+    project?: string;
+    /**
+     * The `bakers init` shortcut's own scope resolution: `all` without ever
+     * pulling the project layer in, even when a project root resolves. Never
+     * set by `bakers config init --scope all`, which keeps today's behaviour of
+     * including a resolved project root (BB-496 finding 1).
+     */
+    excludeProjectLayer?: boolean;
+    /** Schema policy is supplied by the owning command/migration registry. */
+    currentVersions?: Partial<Record<ConfigFileKind, number>>;
+    /** Internal planner overlay: proposed modules are validated without filesystem writes. */
+    sourceTexts?: ReadonlyMap<string, string | null>;
+}
+export interface ConfigInventory {
+    report: ConfigReport;
+    /** Secret-bearing data for the planner, never part of the public report. */
+    sources: Map<string, ConfigSourceInspection>;
+}
+/** Collect selected files and prerequisite sources without importing any module. */
+export declare function inventoryConfig(options?: ConfigInventoryOptions): ConfigInventory;