feat(macp): add registerMacpCommand for mosaic macp CLI surface

Adds mosaic macp tasks list|submit|gate|events tail subcommands to
@mosaicstack/macp, wires registerMacpCommand into the root mosaic CLI,
and ships a smoke test asserting command structure without touching disk
or starting an event emitter. Ref CU-05-08.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Jarvis
2026-04-05 00:16:47 -05:00
parent 37545de79c
commit 690f479380
10 changed files with 584 additions and 3 deletions

View File

@@ -26,7 +26,8 @@
"test": "vitest run --passWithNoTests"
},
"dependencies": {
"@mosaicstack/macp": "workspace:*"
"@mosaicstack/macp": "workspace:*",
"commander": "^13.0.0"
},
"devDependencies": {
"@types/node": "^22.0.0",

View File

@@ -0,0 +1,57 @@
import { Command } from 'commander';
import { describe, expect, it } from 'vitest';
import { registerForgeCommand } from './cli.js';
describe('registerForgeCommand', () => {
it('registers a "forge" command on the parent program', () => {
const program = new Command();
registerForgeCommand(program);
const forgeCmd = program.commands.find((c) => c.name() === 'forge');
expect(forgeCmd).toBeDefined();
});
it('registers the four required subcommands under forge', () => {
const program = new Command();
registerForgeCommand(program);
const forgeCmd = program.commands.find((c) => c.name() === 'forge');
expect(forgeCmd).toBeDefined();
const subNames = forgeCmd!.commands.map((c) => c.name());
expect(subNames).toContain('run');
expect(subNames).toContain('status');
expect(subNames).toContain('resume');
expect(subNames).toContain('personas');
});
it('registers "personas list" as a subcommand of "forge personas"', () => {
const program = new Command();
registerForgeCommand(program);
const forgeCmd = program.commands.find((c) => c.name() === 'forge');
const personasCmd = forgeCmd!.commands.find((c) => c.name() === 'personas');
expect(personasCmd).toBeDefined();
const personasSubNames = personasCmd!.commands.map((c) => c.name());
expect(personasSubNames).toContain('list');
});
it('does not modify the parent program name or description', () => {
const program = new Command('mosaic');
program.description('Mosaic Stack CLI');
registerForgeCommand(program);
expect(program.name()).toBe('mosaic');
expect(program.description()).toBe('Mosaic Stack CLI');
});
it('can be called multiple times without throwing', () => {
const program = new Command();
expect(() => {
registerForgeCommand(program);
}).not.toThrow();
});
});

280
packages/forge/src/cli.ts Normal file
View File

@@ -0,0 +1,280 @@
import fs from 'node:fs';
import path from 'node:path';
import type { Command } from 'commander';
import { classifyBrief } from './brief-classifier.js';
import { STAGE_LABELS, STAGE_SEQUENCE } from './constants.js';
import { getEffectivePersonas, loadBoardPersonas } from './persona-loader.js';
import { generateRunId, getPipelineStatus, loadManifest, runPipeline } from './pipeline-runner.js';
import type { PipelineOptions, RunManifest, TaskExecutor } from './types.js';
// ---------------------------------------------------------------------------
// Stub executor — used when no real executor is wired at CLI invocation time.
// ---------------------------------------------------------------------------
const stubExecutor: TaskExecutor = {
async submitTask(task) {
console.log(` [forge] stage submitted: ${task.id} (${task.title})`);
},
async waitForCompletion(taskId, _timeoutMs) {
console.log(` [forge] stage complete: ${taskId}`);
return {
task_id: taskId,
status: 'completed' as const,
completed_at: new Date().toISOString(),
exit_code: 0,
gate_results: [],
};
},
async getTaskStatus(_taskId) {
return 'completed' as const;
},
};
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
function formatDuration(startedAt?: string, completedAt?: string): string {
if (!startedAt || !completedAt) return '-';
const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
const secs = Math.round(ms / 1000);
return secs < 60 ? `${secs}s` : `${Math.floor(secs / 60)}m${secs % 60}s`;
}
function printManifestTable(manifest: RunManifest): void {
console.log(`\nRun ID : ${manifest.runId}`);
console.log(`Status : ${manifest.status}`);
console.log(`Brief : ${manifest.brief}`);
console.log(`Class : ${manifest.briefClass} (${manifest.classSource})`);
console.log(`Updated: ${manifest.updatedAt}`);
console.log('');
console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
console.log('-'.repeat(50));
for (const stage of STAGE_SEQUENCE) {
const s = manifest.stages[stage];
if (!s) continue;
const label = (STAGE_LABELS[stage] ?? stage).padEnd(22);
const status = s.status.padEnd(14);
const dur = formatDuration(s.startedAt, s.completedAt);
console.log(`${label}${status}${dur}`);
}
console.log('');
}
function resolveRunDir(runId: string, projectRoot?: string): string {
const root = projectRoot ?? process.cwd();
return path.join(root, '.forge', 'runs', runId);
}
function listRecentRuns(projectRoot?: string): void {
const root = projectRoot ?? process.cwd();
const runsDir = path.join(root, '.forge', 'runs');
if (!fs.existsSync(runsDir)) {
console.log('No runs found. Run `mosaic forge run` to start a pipeline.');
return;
}
const entries = fs
.readdirSync(runsDir)
.filter((name) => fs.statSync(path.join(runsDir, name)).isDirectory())
.sort()
.reverse()
.slice(0, 10);
if (entries.length === 0) {
console.log('No runs found.');
return;
}
console.log('\nRecent runs:');
console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
console.log('-'.repeat(70));
for (const runId of entries) {
const runDir = path.join(runsDir, runId);
try {
const manifest = loadManifest(runDir);
const status = manifest.status.padEnd(14);
const brief = path.basename(manifest.brief);
console.log(`${runId.padEnd(22)}${status}${brief}`);
} catch {
console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
}
}
console.log('');
}
// ---------------------------------------------------------------------------
// Register function
// ---------------------------------------------------------------------------
/**
* Register forge subcommands on an existing Commander program.
* Mirrors the pattern used by registerQualityRails in @mosaicstack/quality-rails.
*/
export function registerForgeCommand(parent: Command): void {
const forge = parent.command('forge').description('Run and manage Forge pipelines');
// ── forge run ────────────────────────────────────────────────────────────
forge
.command('run')
.description('Run a Forge pipeline from a brief markdown file')
.requiredOption('--brief <path>', 'Path to the brief markdown file')
.option('--run-id <id>', 'Override the auto-generated run ID')
.option('--resume', 'Resume an existing run instead of starting a new one', false)
.option('--config <path>', 'Path to forge config file (.forge/config.yaml)')
.option('--codebase <path>', 'Codebase root to pass to the pipeline', process.cwd())
.option('--dry-run', 'Print planned stages without executing', false)
.action(
async (opts: {
brief: string;
runId?: string;
resume: boolean;
config?: string;
codebase: string;
dryRun: boolean;
}) => {
const briefPath = path.resolve(opts.brief);
if (!fs.existsSync(briefPath)) {
console.error(`[forge] brief not found: ${briefPath}`);
process.exitCode = 1;
return;
}
const briefContent = fs.readFileSync(briefPath, 'utf-8');
const briefClass = classifyBrief(briefContent);
const projectRoot = opts.codebase;
if (opts.resume) {
const runId = opts.runId ?? generateRunId();
const runDir = resolveRunDir(runId, projectRoot);
console.log(`[forge] resuming run: ${runId}`);
const { resumePipeline } = await import('./pipeline-runner.js');
const result = await resumePipeline(runDir, stubExecutor);
console.log(`[forge] pipeline complete: ${result.runId}`);
return;
}
const pipelineOptions: PipelineOptions = {
briefClass,
codebase: projectRoot,
dryRun: opts.dryRun,
executor: stubExecutor,
};
if (opts.dryRun) {
const { stagesForClass } = await import('./brief-classifier.js');
const stages = stagesForClass(briefClass);
console.log(`[forge] dry-run — brief class: ${briefClass}`);
console.log('[forge] planned stages:');
for (const stage of stages) {
console.log(` - ${stage} (${STAGE_LABELS[stage] ?? stage})`);
}
return;
}
console.log(`[forge] starting pipeline for brief: ${briefPath}`);
console.log(`[forge] classified as: ${briefClass}`);
try {
const result = await runPipeline(briefPath, projectRoot, pipelineOptions);
console.log(`[forge] pipeline complete: ${result.runId}`);
console.log(`[forge] run directory: ${result.runDir}`);
} catch (err) {
console.error(
`[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
);
process.exitCode = 1;
}
},
);
// ── forge status ─────────────────────────────────────────────────────────
forge
.command('status [runId]')
.description('Show the status of a pipeline run (omit runId to list recent runs)')
.option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
.action(async (runId: string | undefined, opts: { project: string }) => {
if (!runId) {
listRecentRuns(opts.project);
return;
}
const runDir = resolveRunDir(runId, opts.project);
try {
const manifest = getPipelineStatus(runDir);
printManifestTable(manifest);
} catch (err) {
console.error(
`[forge] could not load run "${runId}": ${err instanceof Error ? err.message : String(err)}`,
);
process.exitCode = 1;
}
});
// ── forge resume ─────────────────────────────────────────────────────────
forge
.command('resume <runId>')
.description('Resume a stopped or failed pipeline run')
.option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
.action(async (runId: string, opts: { project: string }) => {
const runDir = resolveRunDir(runId, opts.project);
if (!fs.existsSync(runDir)) {
console.error(`[forge] run not found: ${runDir}`);
process.exitCode = 1;
return;
}
console.log(`[forge] resuming run: ${runId}`);
try {
const { resumePipeline } = await import('./pipeline-runner.js');
const result = await resumePipeline(runDir, stubExecutor);
console.log(`[forge] pipeline complete: ${result.runId}`);
console.log(`[forge] run directory: ${result.runDir}`);
} catch (err) {
console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
process.exitCode = 1;
}
});
// ── forge personas ────────────────────────────────────────────────────────
const personas = forge.command('personas').description('Manage Forge board personas');
personas
.command('list')
.description('List configured board personas')
.option(
'--project <path>',
'Project root for persona overrides (defaults to cwd)',
process.cwd(),
)
.option('--board-dir <path>', 'Override the board agents directory')
.action((opts: { project: string; boardDir?: string }) => {
const effectivePersonas = opts.boardDir
? loadBoardPersonas(opts.boardDir)
: getEffectivePersonas(opts.project);
if (effectivePersonas.length === 0) {
console.log('[forge] no board personas configured.');
return;
}
console.log(`\nBoard personas (${effectivePersonas.length}):\n`);
console.log('Slug'.padEnd(24) + 'Name');
console.log('-'.repeat(50));
for (const p of effectivePersonas) {
console.log(`${p.slug.padEnd(24)}${p.name}`);
}
console.log('');
});
}

View File

@@ -80,3 +80,6 @@ export {
resumePipeline,
getPipelineStatus,
} from './pipeline-runner.js';
// CLI
export { registerForgeCommand } from './cli.js';

View File

@@ -21,6 +21,9 @@
"typecheck": "tsc --noEmit",
"test": "vitest run --passWithNoTests"
},
"dependencies": {
"commander": "^13.0.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
"@vitest/coverage-v8": "^2.0.0",

View File

@@ -0,0 +1,77 @@
import { describe, it, expect } from 'vitest';
import { Command } from 'commander';
import { registerMacpCommand } from './cli.js';
describe('registerMacpCommand', () => {
function buildProgram(): Command {
const program = new Command();
program.exitOverride(); // prevent process.exit in tests
registerMacpCommand(program);
return program;
}
it('registers a "macp" command on the parent', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp');
expect(macpCmd).toBeDefined();
});
it('registers "macp tasks" subcommand group', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const tasksCmd = macpCmd.commands.find((c) => c.name() === 'tasks');
expect(tasksCmd).toBeDefined();
});
it('registers "macp tasks list" subcommand with --status and --type flags', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const tasksCmd = macpCmd.commands.find((c) => c.name() === 'tasks')!;
const listCmd = tasksCmd.commands.find((c) => c.name() === 'list');
expect(listCmd).toBeDefined();
const optionNames = listCmd!.options.map((o) => o.long);
expect(optionNames).toContain('--status');
expect(optionNames).toContain('--type');
});
it('registers "macp submit" subcommand', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const submitCmd = macpCmd.commands.find((c) => c.name() === 'submit');
expect(submitCmd).toBeDefined();
});
it('registers "macp gate" subcommand with --fail-on flag', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const gateCmd = macpCmd.commands.find((c) => c.name() === 'gate');
expect(gateCmd).toBeDefined();
const optionNames = gateCmd!.options.map((o) => o.long);
expect(optionNames).toContain('--fail-on');
});
it('registers "macp events" subcommand group', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const eventsCmd = macpCmd.commands.find((c) => c.name() === 'events');
expect(eventsCmd).toBeDefined();
});
it('registers "macp events tail" subcommand', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const eventsCmd = macpCmd.commands.find((c) => c.name() === 'events')!;
const tailCmd = eventsCmd.commands.find((c) => c.name() === 'tail');
expect(tailCmd).toBeDefined();
});
it('has all required top-level subcommands', () => {
const program = buildProgram();
const macpCmd = program.commands.find((c) => c.name() === 'macp')!;
const topLevel = macpCmd.commands.map((c) => c.name());
expect(topLevel).toContain('tasks');
expect(topLevel).toContain('submit');
expect(topLevel).toContain('gate');
expect(topLevel).toContain('events');
});
});

92
packages/macp/src/cli.ts Normal file
View File

@@ -0,0 +1,92 @@
import type { Command } from 'commander';
/**
* Register macp subcommands on an existing Commander program.
* This avoids cross-package Commander version mismatches by using the
* caller's Command instance directly.
*/
export function registerMacpCommand(parent: Command): void {
const macp = parent.command('macp').description('MACP task and gate management');
// ─── tasks ───────────────────────────────────────────────────────────────
const tasks = macp.command('tasks').description('Manage MACP tasks');
tasks
.command('list')
.description('List MACP tasks')
.option(
'--status <status>',
'Filter by task status (pending|running|gated|completed|failed|escalated)',
)
.option(
'--type <type>',
'Filter by task type (coding|deploy|research|review|documentation|infrastructure)',
)
.action((opts: { status?: string; type?: string }) => {
// not yet wired — task persistence layer is not present in @mosaicstack/macp
console.log('[macp] tasks list: not yet wired — use macp package programmatically');
if (opts.status) {
console.log(` status filter: ${opts.status}`);
}
if (opts.type) {
console.log(` type filter: ${opts.type}`);
}
process.exitCode = 0;
});
// ─── submit ──────────────────────────────────────────────────────────────
macp
.command('submit <path>')
.description('Submit a task from a JSON/YAML spec file')
.action((specPath: string) => {
// not yet wired — task submission requires a running MACP server
console.log('[macp] submit: not yet wired — use macp package programmatically');
console.log(` spec path: ${specPath}`);
console.log(' task id: (unavailable — no MACP server connected)');
console.log(' status: (unavailable — no MACP server connected)');
process.exitCode = 0;
});
// ─── gate ────────────────────────────────────────────────────────────────
macp
.command('gate <spec>')
.description('Run a gate from a spec string or file path (wraps runGate/runGates)')
.option('--fail-on <mode>', 'Gate fail-on mode: ai|fail|both|none', 'fail')
.option('--cwd <path>', 'Working directory for gate execution', process.cwd())
.option('--log <path>', 'Path to write gate log output', '/tmp/macp-gate.log')
.option('--timeout <seconds>', 'Gate timeout in seconds', '60')
.action((spec: string, opts: { failOn: string; cwd: string; log: string; timeout: string }) => {
// not yet wired — gate execution requires a task context and event sink
console.log('[macp] gate: not yet wired — use macp package programmatically');
console.log(` spec: ${spec}`);
console.log(` fail-on: ${opts.failOn}`);
console.log(` cwd: ${opts.cwd}`);
console.log(` log: ${opts.log}`);
console.log(` timeout: ${opts.timeout}s`);
process.exitCode = 0;
});
// ─── events ──────────────────────────────────────────────────────────────
const events = macp.command('events').description('Stream MACP events');
events
.command('tail')
.description('Tail MACP events from the event log (wraps event emitter)')
.option('--file <path>', 'Path to the MACP events NDJSON file')
.option('--follow', 'Follow the file for new events (like tail -f)')
.action((opts: { file?: string; follow?: boolean }) => {
// not yet wired — event streaming requires a live event source
console.log('[macp] events tail: not yet wired — use macp package programmatically');
if (opts.file) {
console.log(` file: ${opts.file}`);
}
if (opts.follow) {
console.log(' mode: follow');
}
process.exitCode = 0;
});
}

View File

@@ -41,3 +41,6 @@ export type { NormalizedGate } from './gate-runner.js';
// Event emitter
export { nowISO, appendEvent, emitEvent } from './event-emitter.js';
// CLI
export { registerMacpCommand } from './cli.js';

View File

@@ -3,6 +3,7 @@
import { createRequire } from 'module';
import { Command } from 'commander';
import { registerQualityRails } from '@mosaicstack/quality-rails';
import { registerMacpCommand } from '@mosaicstack/macp';
import { registerAgentCommand } from './commands/agent.js';
import { registerMissionCommand } from './commands/mission.js';
// prdy is registered via launch.ts
@@ -314,6 +315,10 @@ registerAgentCommand(program);
registerMissionCommand(program);
// ─── macp ────────────────────────────────────────────────────────────────
registerMacpCommand(program);
// ─── quality-rails ──────────────────────────────────────────────────────
registerQualityRails(program);

64
pnpm-lock.yaml generated
View File

@@ -382,6 +382,9 @@ importers:
'@mosaicstack/macp':
specifier: workspace:*
version: link:../macp
commander:
specifier: ^13.0.0
version: 13.1.0
devDependencies:
'@types/node':
specifier: ^22.0.0
@@ -401,6 +404,9 @@ importers:
'@mosaicstack/db':
specifier: workspace:*
version: link:../db
commander:
specifier: ^13.0.0
version: 13.1.0
drizzle-orm:
specifier: ^0.45.1
version: 0.45.1(@electric-sql/pglite@0.2.17)(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.15.6)(better-sqlite3@12.8.0)(kysely@0.28.11)(postgres@3.4.8)
@@ -413,6 +419,10 @@ importers:
version: 2.1.9(@types/node@24.12.0)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
packages/macp:
dependencies:
commander:
specifier: ^13.0.0
version: 13.1.0
devDependencies:
'@types/node':
specifier: ^22.0.0
@@ -565,6 +575,9 @@ importers:
'@mosaicstack/types':
specifier: workspace:*
version: link:../types
commander:
specifier: ^13.0.0
version: 13.1.0
ioredis:
specifier: ^5.10.0
version: 5.10.0
@@ -634,10 +647,10 @@ importers:
dependencies:
'@mariozechner/pi-agent-core':
specifier: ^0.63.1
version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
'@mariozechner/pi-ai':
specifier: ^0.63.1
version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
'@sinclair/typebox':
specifier: ^0.34.41
version: 0.34.48
@@ -7012,6 +7025,12 @@ snapshots:
'@jridgewell/gen-mapping': 0.3.13
'@jridgewell/trace-mapping': 0.3.31
'@anthropic-ai/sdk@0.73.0(zod@3.25.76)':
dependencies:
json-schema-to-ts: 3.1.1
optionalDependencies:
zod: 3.25.76
'@anthropic-ai/sdk@0.73.0(zod@4.3.6)':
dependencies:
json-schema-to-ts: 3.1.1
@@ -8353,6 +8372,18 @@ snapshots:
- ws
- zod
'@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
dependencies:
'@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
transitivePeerDependencies:
- '@modelcontextprotocol/sdk'
- aws-crt
- bufferutil
- supports-color
- utf-8-validate
- ws
- zod
'@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
dependencies:
'@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
@@ -8401,6 +8432,30 @@ snapshots:
- ws
- zod
'@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
dependencies:
'@anthropic-ai/sdk': 0.73.0(zod@3.25.76)
'@aws-sdk/client-bedrock-runtime': 3.1008.0
'@google/genai': 1.45.0(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))
'@mistralai/mistralai': 1.14.1
'@sinclair/typebox': 0.34.48
ajv: 8.18.0
ajv-formats: 3.0.1(ajv@8.18.0)
chalk: 5.6.2
openai: 6.26.0(ws@8.20.0)(zod@3.25.76)
partial-json: 0.1.7
proxy-agent: 6.5.0
undici: 7.24.3
zod-to-json-schema: 3.25.1(zod@3.25.76)
transitivePeerDependencies:
- '@modelcontextprotocol/sdk'
- aws-crt
- bufferutil
- supports-color
- utf-8-validate
- ws
- zod
'@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
dependencies:
'@anthropic-ai/sdk': 0.73.0(zod@4.3.6)
@@ -12776,6 +12831,11 @@ snapshots:
dependencies:
mimic-function: 5.0.1
openai@6.26.0(ws@8.20.0)(zod@3.25.76):
optionalDependencies:
ws: 8.20.0
zod: 3.25.76
openai@6.26.0(ws@8.20.0)(zod@4.3.6):
optionalDependencies:
ws: 8.20.0