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

package/dist/src/host.d.ts

@@ -0,0 +1,30 @@
+import { type CommandDescriptor } from '@bakers-build/core';
+import { Command } from 'commander';
+/** The built-in command registry. `$BB_COMMANDS` (JSON array of descriptors)
+ *  overrides it wholesale. */
+export declare const DEFAULT_COMMANDS: CommandDescriptor[];
+/** Resolve the registry: `$BB_COMMANDS` override else the built-in set. */
+export declare function resolveCommands(): CommandDescriptor[];
+export { resolveCliVersion } from '@bakers-build/core';
+/** Host bases for ESLint-style sibling resolution: the meta install → cwd. */
+export declare function hostBases(): string[];
+/**
+ * Value-aware argv pre-scan: find the first positional token that names a
+ * registered command. Skips the host's value-taking global (`--conductor <v>`)
+ * and maps `help <name>` → `<name>`. Returns undefined for `--help`, an unknown
+ * first positional, or a bare invocation.
+ */
+export declare function scanTarget(argv: string[], names: string[]): string | undefined;
+/** Build the top-level host program, mounting only the target command (the rest
+ *  are describe-only stubs). */
+export declare function buildHostProgram(argv: string[], opts?: {
+    forceTarget?: string;
+    bases?: string[];
+}): Promise<Command>;
+/** Parse argv against the host program, mapping commander's clean exits. */
+export declare function runHost(argv: string[], opts?: {
+    forceTarget?: string;
+    bases?: string[];
+}): Promise<void>;
+/** The `bakers` entrypoint: drop node + script path, run the host. */
+export declare function main(argv: string[]): Promise<void>;

package/dist/src/host.js

@@ -0,0 +1,239 @@
+import { pathToFileURL } from 'node:url';
+import { commands as agentsCommands } from '@bakers-build/addon-agents/preset';
+import { commands as deploymentCommands } from '@bakers-build/addon-deployment/preset';
+import { commands as dropshCommands } from '@bakers-build/addon-dropsh/preset';
+import { commands as infoCommands } from '@bakers-build/addon-info/preset';
+import { commands as portsCommands } from '@bakers-build/addon-ports/preset';
+import { commands as trackCommands } from '@bakers-build/addon-track/preset';
+import { commands as conductorCommands } from '@bakers-build/conductor/preset';
+import { resolveCliVersion, resolveConfigPath, resolveModuleEslintStyle, } from '@bakers-build/core';
+import { commands as uiCommands } from '@bakers-build/ui/preset';
+import { Command } from 'commander';
+import { registerConfig } from './config.js';
+import { registerUpdate } from './update.js';
+import { registerValidate } from './validate.js';
+// BB-201: the `bakers` plugin HOST. The meta package `@bakers-build/bakers` owns the
+// CLI entrypoint (AC-1); ui / conductor / dropsh / deployment are declared,
+// ESLint-style resolved, LAZILY mounted command plugins (AC-2). The host
+// discovers + mounts; it hard-wires nothing. Only the invoked subcommand's module
+// is imported — `bakers --help` lists all four via describe-only stubs and imports
+// none; `bakers oven …` imports only the conductor module.
+//
+// BB-215: the registry is DERIVED from the command surface — the command
+// addons' preset `commands` accumulators — rather than a hand-written list.
+// Those presets are LIGHT (they import no runtime, only return descriptors), so
+// composing them at boot keeps `bakers --help` import-light. `$BB_COMMANDS`
+// still overrides the whole registry. BB-224 (Finding 7) added the fourth
+// command surface, `@bakers-build/addon-deployment` (`bakers deployment …`), which the
+// `conductor` command plugin used to register as a side effect.
+/** Compose the built-in command registry from the command addons' presets. The
+ *  accumulators are synchronous descriptor builders (light presets), threaded in
+ *  the conductor → ui → dropsh → deployment order. */
+function composeCommandSurface() {
+    const accumulators = [
+        conductorCommands,
+        uiCommands,
+        dropshCommands,
+        deploymentCommands,
+        agentsCommands,
+        infoCommands,
+        portsCommands,
+        trackCommands,
+    ];
+    let acc = [];
+    for (const fn of accumulators) {
+        if (typeof fn === 'function')
+            acc = fn(acc, undefined);
+    }
+    return acc;
+}
+/** The built-in command registry. `$BB_COMMANDS` (JSON array of descriptors)
+ *  overrides it wholesale. */
+export const DEFAULT_COMMANDS = composeCommandSurface();
+/** Resolve the registry: `$BB_COMMANDS` override else the built-in set. */
+export function resolveCommands() {
+    const override = process.env.BB_COMMANDS;
+    if (override && override.trim() !== '') {
+        const parsed = JSON.parse(override);
+        if (!Array.isArray(parsed)) {
+            throw new Error('$BB_COMMANDS must be a JSON array of command descriptors');
+        }
+        return parsed;
+    }
+    return DEFAULT_COMMANDS;
+}
+export { resolveCliVersion } from '@bakers-build/core';
+/** Host bases for ESLint-style sibling resolution: the meta install → cwd. */
+export function hostBases() {
+    return [import.meta.url, pathToFileURL(`${process.cwd()}/`).href];
+}
+/** Load a command descriptor's `BbCommandPlugin` (default export, or the named
+ *  `export`), resolving the module over the host bases. */
+async function loadCommandPlugin(entry, bases) {
+    const resolved = resolveModuleEslintStyle(entry.plugin, bases);
+    if (resolved === undefined) {
+        throw new Error(`bakers: cannot resolve command plugin '${entry.plugin}' (command '${entry.name}')`);
+    }
+    const mod = (await import(pathToFileURL(resolved).href));
+    const factory = entry.export ? mod[entry.export] : mod.default;
+    if (factory === undefined || factory === null) {
+        throw new Error(`bakers: command plugin '${entry.plugin}' has no ${entry.export ?? 'default'} export`);
+    }
+    return factory;
+}
+/**
+ * Value-aware argv pre-scan: find the first positional token that names a
+ * registered command. Skips the host's value-taking global (`--conductor <v>`)
+ * and maps `help <name>` → `<name>`. Returns undefined for `--help`, an unknown
+ * first positional, or a bare invocation.
+ */
+export function scanTarget(argv, names) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--conductor') {
+            i++; // skip its value
+            continue;
+        }
+        if (a === 'help') {
+            const next = argv[i + 1];
+            return next !== undefined && names.includes(next) ? next : undefined;
+        }
+        if (a.startsWith('-'))
+            continue; // any other flag
+        return names.includes(a) ? a : undefined;
+    }
+    return undefined;
+}
+/** Add a describe-only stub for a not-loaded command so `--help` stays complete.
+ *  If it is ever dispatched (a mis-scan), its action self-loads the real plugin
+ *  and re-runs the host forcing that target. */
+function addStub(program, entry, bases, argv) {
+    program
+        .command(entry.name)
+        .description(pluginDescribe(entry))
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .helpOption(false)
+        .action(async () => {
+        await runHost(argv, { forceTarget: entry.name, bases });
+    });
+}
+/** Best-effort describe text for a stub without importing the plugin. BB-215:
+ *  the descriptor now carries its own `describe` (from the addon's preset); this
+ *  falls back only for a `$BB_COMMANDS` entry that omits it. */
+function pluginDescribe(entry) {
+    if (typeof entry.describe === 'string' && entry.describe.trim() !== '') {
+        return entry.describe;
+    }
+    switch (entry.name) {
+        case 'oven':
+            return 'node-agent lifecycle + local registry';
+        case 'ui':
+            return 'interactive terminal UI: dashboard, projects, tickets';
+        case 'dropsh':
+            return 'JSON:API shell (dropsh) bound to the bakers.build connection config';
+        case 'deployment':
+            return 'release / deployment helpers';
+        default:
+            return `${entry.name} command`;
+    }
+}
+/** Build the top-level host program, mounting only the target command (the rest
+ *  are describe-only stubs). */
+export async function buildHostProgram(argv, opts = {}) {
+    const bases = opts.bases ?? hostBases();
+    const commands = resolveCommands();
+    const names = commands.map((c) => c.name);
+    const target = opts.forceTarget ?? scanTarget(argv, names);
+    const projectContext = target === 'ui'
+        ? await import('@bakers-build/conductor/project-context')
+        : undefined;
+    const host = {
+        resolveBases: bases,
+        workspacePlugin: async (workspaceId) => {
+            const { workspacePlugin } = await import('@bakers-build/addon-workspace');
+            return workspacePlugin({ workspace_id: workspaceId });
+        },
+        ...(projectContext
+            ? {
+                projectContext: {
+                    resolveConfigPath: (cwd) => resolveConfigPath(undefined, cwd),
+                    readWorkspace: (configPath) => projectContext.readBbProjectSelection(configPath).workspace,
+                    resolveContext: async (configPath, connection) => {
+                        const { createBbConnectionClient } = await import('@bakers-build/core');
+                        const { resolveBbProjectContext } = await import('@bakers-build/conductor/contract');
+                        const selection = projectContext.readBbProjectSelection(configPath);
+                        return resolveBbProjectContext(await createBbConnectionClient(connection), selection);
+                    },
+                    writeWorkspace: async (configPath, name) => {
+                        await projectContext.writeBbWorkspaceSelection(projectContext.bakersProjectOwner(configPath), name, `Set bakers.workspace in ${configPath} to switch manually.`);
+                    },
+                },
+            }
+            : {}),
+    };
+    const program = new Command();
+    // exitOverride so commander surfaces help/version/unknown-command as thrown
+    // CommanderErrors (mapped in runHost) instead of calling process.exit —
+    // otherwise an unknown command would kill the host process directly.
+    program.exitOverride();
+    program
+        .name('bakers')
+        .description('bakers.build conductor + client CLI')
+        .option('--conductor <name>', 'select a conductor by stem (conductor→conductor.config.js, else <name>.conductor.config.js; env $BB_CONDUCTOR)');
+    // The global --conductor flag threads into $BB_CONDUCTOR (flag wins over env)
+    // so every command selects the named engine config without per-command wiring.
+    program.hook('preAction', () => {
+        const name = program.opts().conductor;
+        if (typeof name === 'string' && name !== '') {
+            process.env.BB_CONDUCTOR = name;
+        }
+    });
+    const cliVersion = resolveCliVersion();
+    program.version(cliVersion); // -V, --version
+    program
+        .command('version')
+        .description('output the bakers CLI version')
+        .action(() => {
+        console.log(cliVersion);
+    });
+    registerConfig(program, { host });
+    registerUpdate(program);
+    registerValidate(program);
+    for (const entry of commands) {
+        if (entry.name === target) {
+            const plugin = await loadCommandPlugin(entry, bases);
+            await plugin.register(program, host);
+        }
+        else {
+            addStub(program, entry, bases, argv);
+        }
+    }
+    return program;
+}
+/** Parse argv against the host program, mapping commander's clean exits. */
+export async function runHost(argv, opts = {}) {
+    const program = await buildHostProgram(argv, opts);
+    try {
+        await program.parseAsync(argv, { from: 'user' });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'commander.helpDisplayed' ||
+            e.code === 'commander.version') {
+            return;
+        }
+        if (typeof e.code === 'string' && e.code.startsWith('commander.')) {
+            if (!process.exitCode)
+                process.exitCode = 1;
+            return;
+        }
+        process.stderr.write(`${e.message ?? String(err)}\n`);
+        if (!process.exitCode)
+            process.exitCode = 1;
+    }
+}
+/** The `bakers` entrypoint: drop node + script path, run the host. */
+export async function main(argv) {
+    await runHost(argv.slice(2));
+}

package/dist/src/plugins-barrel.d.ts

@@ -0,0 +1,4 @@
+export { basicAuthProvider } from '@bakers-build/addon-auth-basic';
+export { DrupalBbRemote, drupalRemote, } from '@bakers-build/addon-remote-drupal';
+export { GitWorkspace, gitWorkspace, loadInstructions, } from '@bakers-build/addon-workspace-git';
+export { type AgentCandidate, type ResolvedAgent, selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '@bakers-build/conductor/contract';

package/dist/src/plugins-barrel.js

@@ -0,0 +1,16 @@
+// BB-224 (Finding 6, decision 11): the `@bakers-build/bakers/plugins` BACK-COMPAT
+// barrel. It used to be a single `export * from '@bakers-build/core/plugins'`; that
+// core barrel is deleted, because core no longer ships plugin implementations.
+// The barrel itself stays (published configs may still name
+// `{ plugin: '@bakers-build/bakers/plugins', export: 'drupalRemote' }`), but it now
+// aggregates the CONTRIBUTIONS from where they actually live: the impl addons +
+// the conductor-surface selectors. "plugins" is the right word for a
+// contribution barrel (decision 16) — only the *package* prefix became `addon-`.
+//
+// The fakes (`fakeRemote`/`fakeWorkspace`) are deliberately NOT re-exported:
+// they moved into `@bakers-build/addon-fake`, a workspace-only test fixture that is
+// never published, so the published meta package must not depend on it.
+export { basicAuthProvider } from '@bakers-build/addon-auth-basic';
+export { DrupalBbRemote, drupalRemote, } from '@bakers-build/addon-remote-drupal';
+export { GitWorkspace, gitWorkspace, loadInstructions, } from '@bakers-build/addon-workspace-git';
+export { selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '@bakers-build/conductor/contract';

package/dist/src/update.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+export type SpawnUpdate = (cmd: string, args: string[]) => Promise<number>;
+export type SpawnCapture = (cmd: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+export interface UpdateOptions {
+    out?: (line: string) => void;
+}
+export declare function runUpdate(run?: SpawnUpdate, query?: SpawnCapture, options?: UpdateOptions): Promise<{
+    ok: boolean;
+    before: string | null;
+    after: string | null;
+}>;
+export declare function registerUpdate(program: Command): void;

package/dist/src/update.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { BB_PACKAGE } from '@bakers-build/core';
+const spawnUpdate = (cmd, args) => new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: false });
+    child.on('error', () => resolve(1));
+    child.on('close', (code) => resolve(code ?? 1));
+});
+const capture = (cmd, args) => new Promise((resolve) => {
+    let stdout = '';
+    const child = spawn(cmd, args, {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        shell: false,
+    });
+    child.stdout?.on('data', (chunk) => {
+        stdout += String(chunk);
+    });
+    child.on('error', () => resolve({ code: 1, stdout }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout }));
+});
+async function installedVersion(run) {
+    try {
+        const result = await run('npm', [
+            'ls',
+            '-g',
+            BB_PACKAGE,
+            '--json',
+            '--depth',
+            '0',
+        ]);
+        if (result.code !== 0)
+            return null;
+        const parsed = JSON.parse(result.stdout);
+        const version = parsed.dependencies?.[BB_PACKAGE]?.version;
+        return typeof version === 'string' ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runUpdate(run = spawnUpdate, query = capture, options = {}) {
+    const before = await installedVersion(query);
+    if ((await run('npm', ['install', '-g', `${BB_PACKAGE}@latest`])) !== 0)
+        return { ok: false, before, after: before };
+    const after = await installedVersion(query);
+    if (after === null)
+        return { ok: false, before, after };
+    (options.out ?? console.log)(`${before ?? 'unknown'} → ${after}`);
+    return { ok: true, before, after };
+}
+export function registerUpdate(program) {
+    program
+        .command('update')
+        .description('install the latest bakers CLI')
+        .action(async () => {
+        const result = await runUpdate();
+        if (!result.ok)
+            process.exitCode = 1;
+    });
+}

package/dist/src/validate.d.ts

@@ -0,0 +1,78 @@
+import { type EmptyLoaderShape, type SkillContract, type StepContractErrorCode } from '@bakers-build/core';
+import type { Command } from 'commander';
+/** A `SKILL.md` whose frontmatter is not a readable skill contract. */
+export interface SkillReadFailure {
+    path: string;
+    reason: string;
+}
+/** What the skill scan found: the name index, plus what it could not read. */
+export interface SkillIndex {
+    byName: Map<string, SkillContract>;
+    /** Paths that parsed, in scan order — for the green summary's count. */
+    indexed: string[];
+    /** A later `SKILL.md` re-declaring an already-indexed name (first wins). */
+    shadowed: {
+        name: string;
+        path: string;
+    }[];
+    failures: SkillReadFailure[];
+}
+/** The verdict: `ok`, or the first contract defect with its message. */
+export interface ValidateReport {
+    ok: boolean;
+    workflowPath: string;
+    roots: string[];
+    index: SkillIndex;
+    /** Loaded leaf skills — owners plus helpers — when the load got that far. */
+    loaded?: {
+        owners: string[];
+        helpers: string[];
+    };
+    tripleCount?: number;
+    error?: string;
+    /**
+     * The contract defect's classification, when core tagged one. BB-436: this is
+     * the seam `formatReport` branches on — it replaced a regex over core's message
+     * text, which matched only one of the two throw sites that need a hint and would
+     * have broken silently the next time a message was reworded.
+     */
+    errorCode?: StepContractErrorCode;
+    /** For `unresolved_skill`: the skill name the load could not resolve. */
+    unresolvedSkill?: string;
+    /**
+     * For `empty_loader`: what the `## Loaded skills` section actually holds. Core
+     * raises that code for three shapes and its message can only describe one of
+     * them, so the shape is measured here and `formatReport` prints the remedy that
+     * fits the document rather than the one that fits the common case.
+     */
+    emptyLoader?: EmptyLoaderShape;
+}
+/**
+ * Index every skill reachable from `roots` by its declared `name` — the key a
+ * `WORKFLOW.md` bullet resolves on, whatever namespace prefix the bullet wears.
+ *
+ * A `SKILL.md` that is not a readable bakers.build skill contract is RECORDED rather than
+ * thrown on: a project's skill tree legitimately holds third-party skills that
+ * declare no bakers.build frontmatter, and failing the whole validation over one of them
+ * would make the command useless exactly where it is most needed. The record is
+ * printed only when a bullet then fails to resolve, where it is the likely cause.
+ */
+export declare function indexSkills(roots: string[]): SkillIndex;
+export interface ValidateOptions {
+    /** A project directory, or a loader document (`WORKFLOW.md`) directly. */
+    path?: string | undefined;
+    /** Project root for default skill-root discovery; defaults from `path`. */
+    project?: string | undefined;
+    /** Extra skill roots, in precedence order before the defaults. */
+    skills?: string[] | undefined;
+}
+/**
+ * Validate a project's loader: read `WORKFLOW.md`, index the skills it can reach,
+ * expand the load, derive the project's triple set, and enforce the contract.
+ *
+ * Returns the verdict rather than throwing, so the caller owns the exit code.
+ */
+export declare function runValidate(options?: ValidateOptions): ValidateReport;
+/** Render the report for a terminal. Returns the lines, so tests can read them. */
+export declare function formatReport(report: ValidateReport): string[];
+export declare function registerValidate(program: Command): void;