@guidobuilds/forge-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+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

@@ -0,0 +1,147 @@
+# Forge
+
+Forge is a personal project for working with code agents more reliably.
+
+It started as a way to get better results from OpenCode, and now also supports Codex and Claude Code. The idea is to give agents a lightweight operating model for turning vague software requests into smaller, safer, verifiable changes without adding a heavy process around them.
+
+Forge is experimental. It is shaped by hands-on use, and the workflow may change as I learn what works and what does not.
+
+## Why It Exists
+
+Code agents are useful, but they often fail in predictable ways: they start coding too early, lose context between steps, overbuild, or make changes without a clear verification path.
+
+Forge is my attempt to make that work more disciplined:
+
+- clarify intent before implementation when it matters
+- choose the smallest safe workflow for each request
+- keep long-running context in durable project notes
+- separate orchestration from execution
+- make verification part of the work, not an afterthought
+
+Forge is intentionally minimal. It is not a plugin marketplace, a new IDE, or a replacement for your agent. It is just a small workflow layer for getting agents to pause, inspect, plan when needed, and verify their work.
+
+## What It Does
+
+Forge adds a structured agent workflow for:
+
+- inspect an existing codebase before making changes
+- produce design notes for ambiguous or high-risk work
+- turn approved direction into an executable plan
+- implement focused changes with a minimum-change bias
+- run or document validation after implementation
+- preserve important decisions and follow-ups under `.forge/`
+
+For simple requests, Forge should stay out of the way and take the shortest safe path. For larger changes, it can slow the process down just enough to reduce rework and bad assumptions.
+
+## How It Works
+
+Forge uses a thin orchestrator and a single worker model.
+
+The orchestrator decides how much process a request needs. The worker does the actual inspection, design, planning, building, operating, or verification work. This keeps the user conversation focused while still giving the agent a repeatable execution pattern.
+
+Typical routes include:
+
+```text
+inspect -> build -> verify
+inspect -> design -> plan -> build -> verify
+build -> verify
+```
+
+There is no mandatory lifecycle. Forge tries to choose the lightest safe path based on the task, risk, and available context.
+
+## Durable Context
+
+When a task benefits from persistent context, Forge writes notes under `.forge/<feature-slug>/`.
+
+These notes are useful for:
+
+- resuming work across agent sessions
+- reviewing the reasoning behind a change
+- keeping implementation aligned with approved decisions
+- making follow-up work easier to delegate
+
+Small, obvious changes do not need ceremony. The goal is to use durable artifacts only when they reduce ambiguity or risk.
+
+## Supported Agents
+
+Forge currently installs support for:
+
+- OpenCode
+- Codex
+- Claude Code
+
+The same operating model is shared across all supported agents so the workflow stays mostly consistent even when the underlying tool changes.
+
+## Installation
+
+The primary installer is the npm CLI:
+
+```sh
+npx forge-ai install
+```
+
+The installer prompts for the target agent platform and whether Forge should be installed globally for your user or locally for the current project.
+
+To update an existing install:
+
+```sh
+npx forge-ai update
+```
+
+For non-interactive environments:
+
+```sh
+npx forge-ai install --platform all --scope user --yes
+```
+
+Preview the files without writing them:
+
+```sh
+npx forge-ai install --platform all --scope user --dry-run
+```
+
+Validate a local Forge source tree:
+
+```sh
+npx forge-ai validate --source .
+```
+
+## Local Development
+
+From a local checkout:
+
+```sh
+npm install
+npm run build
+node bin/forge-ai.mjs install --source . --platform all --scope user
+```
+
+To preview local output without writing:
+
+```sh
+node bin/forge-ai.mjs install --source . --platform all --scope project --dry-run
+```
+
+## Updating
+
+Run the npm updater:
+
+```sh
+npx forge-ai update
+```
+
+Forge replaces its managed agent and skill definitions in your supported agent configuration directories.
+
+## Uninstalling
+
+Remove Forge from the agent configuration directories for OpenCode, Codex, or Claude Code by deleting the installed Forge agent and skill entries.
+
+If you installed Forge for multiple tools, repeat the removal for each one you no longer want to use.
+
+## Project Status
+
+Forge is experimental and personal.
+
+There is no promise that the workflow will stay stable or that every agent/tool combination will keep working the same way. I am using it, changing it, and keeping the parts that make agent work better in practice.
+
+Feedback, issues, and pull requests are welcome, especially when they come from real usage.

package/agents/forge-worker.md

@@ -0,0 +1,60 @@
+---
+name: forge-worker
+description: Forge universal worker for inspect, design, plan, build, operate, and verify work
+claude:
+  permissions:
+    tools: [TodoWrite, Read, Write, Edit, Bash, Glob, Grep, LS, MultiEdit, WebFetch]
+opencode:
+  mode: subagent
+  permissions:
+    todowrite: true
+    read: true
+    write: true
+    edit: true
+    bash: true
+    glob: true
+    grep: true
+    list: true
+    patch: true
+    skill: true
+    webfetch: true
+---
+
+You are the Forge worker.
+
+Load and follow the `forge-worker` skill before doing work.
+
+You are the only worker type in Forge. The orchestrator may launch multiple instances of you in parallel or sequence.
+
+## Inputs
+- Orchestrator prompt with the assigned subgoal, expected boundaries, and any approval context.
+- Optional: `.forge/<feature-slug>/explore.md`
+- Optional: `.forge/<feature-slug>/design.md`
+- Optional: `.forge/<feature-slug>/plan.md`
+- Optional: `.forge/<feature-slug>/build-log.md`
+
+The skill defines routing by work type, artifact guidance, approval handling, bounded execution, escalation rules, and validation expectations.
+
+## Contract (strict)
+Return only:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <brief point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+2) <question>
+```
+
+Include `QUESTIONS` only when blocked.
+
+Do not interact directly with the user. Escalate open decisions back to the orchestrator through the contract.
+Do not add extra format outside the defined worker contract.

package/agents/forge.md

@@ -0,0 +1,61 @@
+---
+name: forge
+description: Forge orchestrator with dynamic runtime routing and a single worker type
+claude:
+  permissions:
+    tools: [Task, AskUserQuestion, TodoWrite]
+opencode:
+  mode: primary
+  permissions:
+    task: true
+    question: true
+    todowrite: true
+---
+
+# Role
+You are Forge, the Forge orchestrator.
+
+Load and follow the `using-forge` skill before routing work.
+
+You are a coordinator, not an executor.
+
+The `using-forge` skill owns runtime routing, operating principles, approval heuristics, artifact conventions, concurrency guidance, and shared definitions.
+
+## Orchestrator rules
+- Never do worker work inline.
+- Never do non-development execution work inline.
+- Delegate all technical and operational work to Forge workers.
+- Keep one thin thread with the user.
+- Choose the lightest safe routing permitted by the skill.
+- Enforce the Forge worker contract strictly.
+
+## Worker model
+- `forge-worker` is the only worker type in Forge.
+- You may launch one worker instance for a bounded task.
+- You may launch multiple `forge-worker` instances in sequence when one result should shape the next delegation.
+- You may launch multiple `forge-worker` instances in parallel when subgoals are sufficiently independent.
+- Keep each worker invocation narrowly scoped so multiple instances do not collide on the same ownership or files unless deliberate.
+
+## Contract enforcement
+Each worker response must include:
+
+```text
+STATUS: success|partial|blocked
+WORK_TYPE: inspect|design|plan|build|operate|verify|mixed
+FEATURE_SLUG: <kebab-case>
+ARTIFACTS:
+- <path or None>
+SUMMARY:
+- <point>
+NEXT_RECOMMENDED: inspect|design|plan|build|operate|verify|ask-user|none
+RISKS:
+- <risk or None>
+QUESTIONS:
+1) <question>
+```
+
+`QUESTIONS` appears only when `STATUS: blocked`.
+
+If output is malformed:
+1) request one reformat retry with same task_id
+2) if malformed again, stop with actionable error

package/bin/forge-ai.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../dist/src/cli.js';
+
+main().then((code) => { process.exitCode = code; }, (error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/dist/src/adapters/claude.js

@@ -0,0 +1,32 @@
+import { stringifyYaml } from '../frontmatter.js';
+import { diagnostic } from '../diagnostics.js';
+import { isRecord, stringList } from './shared.js';
+export function renderClaudeAgent(agent) {
+    const diagnostics = [];
+    const fm = { name: agent.name, description: agent.description };
+    if (agent.claude?.model)
+        fm.model = agent.claude.model;
+    const permissions = agent.claude?.permissions;
+    const tools = isRecord(permissions) ? stringList(permissions.tools) : stringList(permissions);
+    if (tools)
+        fm.tools = tools;
+    else if (permissions !== undefined)
+        diagnostics.push(diagnostic('info', 'CLAUDE_AGENT_TOOLS_IGNORED', `Claude agent permissions must be a tools string list for ${agent.name}`, { platform: 'claude' }));
+    return { content: `${stringifyYaml(fm)}${agent.definition}\n`, diagnostics };
+}
+export function renderClaudeSkill(skill) {
+    const diagnostics = [];
+    const fm = { name: skill.name, description: skill.description };
+    const permissions = skill.claude?.permissions;
+    const allowedTools = isRecord(permissions) ? stringList(permissions['allowed-tools']) : undefined;
+    if (allowedTools) {
+        fm['allowed-tools'] = allowedTools;
+        diagnostics.push(diagnostic('warning', 'CLAUDE_SKILL_ALLOWED_TOOLS', `Claude skill allowed-tools preapproves tools but does not universally restrict them for ${skill.name}`, { platform: 'claude' }));
+    }
+    else if (permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_PERMISSIONS_IGNORED', `Claude skill permissions are not emitted for ${skill.name}`, { platform: 'claude' }));
+    }
+    if (skill.claude?.model)
+        diagnostics.push(diagnostic('info', 'CLAUDE_SKILL_MODEL_IGNORED', `Claude skill model is not emitted for ${skill.name}`, { platform: 'claude' }));
+    return { content: `${stringifyYaml(fm)}${skill.instructions}\n`, diagnostics };
+}

package/dist/src/adapters/codex.js

@@ -0,0 +1,29 @@
+import { stringifyYaml } from '../frontmatter.js';
+import { diagnostic } from '../diagnostics.js';
+import { isRecord, tomlString } from './shared.js';
+const safeSandboxModes = new Set(['read-only', 'workspace-write']);
+export function renderCodexAgent(agent) {
+    const diagnostics = [diagnostic('info', 'CODEX_PARTIAL_AGENT_SUPPORT', `Codex agent output is partial and does not generate AGENTS.md or profiles for ${agent.name}`, { platform: 'codex' })];
+    const lines = [`name = ${tomlString(agent.name)}`, `description = ${tomlString(agent.description)}`, `developer_instructions = ${tomlString(agent.definition)}`];
+    if (agent.codex?.model)
+        lines.push(`model = ${tomlString(agent.codex.model)}`);
+    const permissions = agent.codex?.permissions;
+    if (isRecord(permissions) && typeof permissions.sandbox_mode === 'string') {
+        if (safeSandboxModes.has(permissions.sandbox_mode))
+            lines.push(`sandbox_mode = ${tomlString(permissions.sandbox_mode)}`);
+        else
+            diagnostics.push(diagnostic('warning', 'CODEX_UNSAFE_SANDBOX_IGNORED', `Unsafe Codex sandbox_mode ignored for ${agent.name}`, { platform: 'codex' }));
+    }
+    else if (permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'CODEX_AGENT_PERMISSIONS_IGNORED', `Codex agent permissions are not emitted for ${agent.name}`, { platform: 'codex' }));
+    }
+    return { content: `${lines.join('\n')}\n`, diagnostics };
+}
+export function renderCodexSkill(skill) {
+    const diagnostics = [];
+    if (skill.codex?.permissions)
+        diagnostics.push(diagnostic('info', 'CODEX_SKILL_PERMISSIONS_IGNORED', `Codex skill permissions are not emitted for ${skill.name}`, { platform: 'codex' }));
+    if (skill.codex?.model)
+        diagnostics.push(diagnostic('info', 'CODEX_SKILL_MODEL_IGNORED', `Codex skill model is not emitted for ${skill.name}`, { platform: 'codex' }));
+    return { content: `${stringifyYaml({ name: skill.name, description: skill.description })}${skill.instructions}\n`, diagnostics };
+}

package/dist/src/adapters/opencode.js

@@ -0,0 +1,20 @@
+import { stringifyYaml } from '../frontmatter.js';
+import { diagnostic } from '../diagnostics.js';
+export function renderOpenCodeAgent(agent) {
+    const fm = { description: agent.description };
+    if (agent.opencode?.mode)
+        fm.mode = agent.opencode.mode;
+    if (agent.opencode?.model)
+        fm.model = agent.opencode.model;
+    if (agent.opencode?.permissions)
+        fm.permission = agent.opencode.permissions;
+    return { content: `${stringifyYaml(fm)}${agent.definition}\n`, diagnostics: [] };
+}
+export function renderOpenCodeSkill(skill) {
+    const diagnostics = [];
+    if (skill.opencode?.permissions)
+        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_PERMISSIONS_IGNORED', `OpenCode skill permissions are not emitted for ${skill.name}`, { platform: 'opencode' }));
+    if (skill.opencode?.model)
+        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_MODEL_IGNORED', `OpenCode skill model is not emitted for ${skill.name}`, { platform: 'opencode' }));
+    return { content: `${stringifyYaml({ name: skill.name, description: skill.description })}${skill.instructions}\n`, diagnostics };
+}

package/dist/src/adapters/shared.js

@@ -0,0 +1,9 @@
+export function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function stringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && /^[A-Za-z0-9_*.,:-]+$/.test(item)) ? value : undefined;
+}
+export function tomlString(value) {
+    return JSON.stringify(value);
+}

package/dist/src/cli.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { formatDiagnostic, hasErrors } from './diagnostics.js';
+import { buildWritePlan, parsePlatform, parseScope } from './processor.js';
+import { writeOutputs } from './writer.js';
+export async function main(argv = process.argv.slice(2), promptIO = {}) {
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        showUsage();
+        return 0;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        console.log(readPackageVersion());
+        return 0;
+    }
+    const parsed = parseArgs(argv);
+    if ('error' in parsed) {
+        console.error(parsed.error);
+        return 1;
+    }
+    const options = parsed.options;
+    const command = normalizeCommand(options.command);
+    if (!command) {
+        console.error(`Unknown command ${options.command ?? ''}`);
+        showUsage();
+        return 1;
+    }
+    const install = command === 'install' || command === 'update';
+    if (install && !options.sourceExplicit)
+        options.source = bundledSourceRoot();
+    if (command === 'update' || options.yes)
+        options.force = true;
+    const interactive = install && isInteractivePrompt(promptIO);
+    if (interactive)
+        p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
+    if (install) {
+        const prompted = await promptForMissingInstallOptions(options, promptIO);
+        if (!prompted) {
+            if (interactive)
+                p.cancel('Cancelled', clackIO(promptIO));
+            return 1;
+        }
+    }
+    let plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, checkCollisions: install && !options.dryRun, force: options.force });
+    if (install && !options.dryRun && !options.force && canOfferUpdate(plan.diagnostics)) {
+        const accepted = await promptForUpdate(plan, promptIO);
+        if (accepted === undefined) {
+            if (interactive)
+                p.cancel('Cancelled', clackIO(promptIO));
+            return 1;
+        }
+        if (accepted) {
+            options.force = true;
+            plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, checkCollisions: true, force: true });
+        }
+    }
+    printPlan(command, plan.sourceCount, plan.files, plan.diagnostics);
+    if (hasErrors(plan.diagnostics)) {
+        if (interactive)
+            p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
+        return 1;
+    }
+    if (install && !options.dryRun) {
+        if (interactive) {
+            const spinner = p.spinner(clackIO(promptIO));
+            spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
+            try {
+                await writeOutputs(plan.files);
+                spinner.stop(`Wrote ${plan.files.length} file(s).`);
+            }
+            catch (error) {
+                spinner.error('Failed to write Forge files');
+                throw error;
+            }
+        }
+        else {
+            await writeOutputs(plan.files);
+            console.log(`Wrote ${plan.files.length} file(s).`);
+        }
+    }
+    else if (install && interactive) {
+        p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
+    }
+    if (install && interactive) {
+        p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+    }
+    return 0;
+}
+function parseArgs(argv) {
+    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, yes: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--dry-run')
+            options.dryRun = true;
+        else if (arg === '--force')
+            options.force = true;
+        else if (arg === '--yes' || arg === '-y')
+            options.yes = true;
+        else if (arg === '--platform') {
+            const value = argv[++index];
+            const platform = value ? parsePlatform(value) : undefined;
+            if (!platform)
+                return { error: `Invalid --platform ${value ?? ''}` };
+            options.platform = platform;
+            options.platformExplicit = true;
+        }
+        else if (arg === '--scope') {
+            const value = argv[++index];
+            const scope = value ? parseScope(value) : undefined;
+            if (!scope)
+                return { error: `Invalid --scope ${value ?? ''}` };
+            options.scope = scope;
+            options.scopeExplicit = true;
+        }
+        else if (arg === '--source') {
+            const value = argv[++index];
+            if (!value)
+                return { error: 'Missing --source value' };
+            options.source = value;
+            options.sourceExplicit = true;
+        }
+        else {
+            return { error: `Unknown argument ${arg}` };
+        }
+    }
+    const command = normalizeCommand(options.command);
+    if (command === 'validate' && (options.dryRun || options.force || options.yes || options.scopeExplicit))
+        return { error: 'validate only accepts --platform and --source' };
+    return { options };
+}
+async function promptForMissingInstallOptions(options, promptIO) {
+    if (options.yes)
+        return true;
+    if (options.platformExplicit && options.scopeExplicit)
+        return true;
+    if (!isInteractivePrompt(promptIO))
+        return true;
+    const io = clackIO(promptIO);
+    if (!options.platformExplicit) {
+        const platform = await p.select({
+            message: 'Install Forge for which coding agent?',
+            initialValue: 'all',
+            options: [
+                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, and Claude Code' },
+                { value: 'opencode', label: 'OpenCode' },
+                { value: 'codex', label: 'Codex' },
+                { value: 'claude', label: 'Claude Code' }
+            ],
+            ...io
+        });
+        if (p.isCancel(platform))
+            return false;
+        options.platform = platform;
+    }
+    if (!options.scopeExplicit) {
+        const scope = await p.select({
+            message: 'Where should Forge be installed?',
+            initialValue: 'user',
+            options: [
+                { value: 'user', label: 'User', hint: 'Available in every project' },
+                { value: 'project', label: 'Project', hint: 'Only this repository' }
+            ],
+            ...io
+        });
+        if (p.isCancel(scope))
+            return false;
+        options.scope = scope;
+    }
+    return true;
+}
+async function promptForUpdate(plan, promptIO) {
+    if (!isInteractivePrompt(promptIO))
+        return false;
+    const existing = plan.diagnostics.filter((item) => item.code === 'DESTINATION_EXISTS');
+    const count = existing.length;
+    p.log.warn(`${count} Forge output${count === 1 ? '' : 's'} already exist.`, clackIO(promptIO));
+    const accepted = await p.confirm({
+        message: 'Update the existing Forge files?',
+        active: 'Update',
+        inactive: 'Cancel',
+        initialValue: false,
+        ...clackIO(promptIO)
+    });
+    if (p.isCancel(accepted))
+        return undefined;
+    return accepted;
+}
+function normalizeCommand(command) {
+    if (command === 'install' || command === 'i')
+        return 'install';
+    if (command === 'update' || command === 'upgrade')
+        return 'update';
+    if (command === 'validate')
+        return 'validate';
+    return undefined;
+}
+function canOfferUpdate(diagnostics) {
+    const errors = diagnostics.filter((item) => item.severity === 'error');
+    return errors.length > 0 && errors.every((item) => item.code === 'DESTINATION_EXISTS');
+}
+function isInteractivePrompt(promptIO) {
+    const env = promptIO.env ?? process.env;
+    const interactive = promptIO.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    return interactive && env.CI !== 'true';
+}
+function clackIO(promptIO) {
+    return { input: promptIO.input, output: promptIO.output };
+}
+function bundledSourceRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+function readPackageVersion() {
+    try {
+        const packageJson = JSON.parse(readFileSync(path.join(bundledSourceRoot(), 'package.json'), 'utf8'));
+        return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function showUsage() {
+    console.log('Usage: forge-ai install [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
+    console.log('       forge-ai update [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--yes]');
+    console.log('       forge-ai validate [--platform opencode|claude|codex|all] [--source <dir>]');
+}
+function printPlan(command, sourceCount, files, diagnostics) {
+    console.log(`${command}: ${sourceCount} source(s), ${files.length} output(s)`);
+    for (const file of files)
+        console.log(`- ${file.platform} ${file.kind} ${file.name} -> ${file.path}`);
+    for (const item of diagnostics)
+        console.log(formatDiagnostic(item));
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().then((code) => { process.exitCode = code; }, (error) => { console.error(error); process.exitCode = 1; });
+}

package/dist/src/diagnostics.js

@@ -0,0 +1,14 @@
+export function diagnostic(severity, code, message, extras = {}) {
+    return { severity, code, message, ...extras };
+}
+export function hasErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === 'error');
+}
+export function formatDiagnostic(diagnostic) {
+    const location = diagnostic.sourcePath ? ` ${diagnostic.sourcePath}` : '';
+    const platform = diagnostic.platform ? ` [${diagnostic.platform}]` : '';
+    return `${diagnostic.severity.toUpperCase()} ${diagnostic.code}${platform}${location}: ${diagnostic.message}`;
+}
+export function info(code, message, platform) {
+    return diagnostic('info', code, message, platform ? { platform } : {});
+}