Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

6.1 KB
Raw Blame
#!/usr/bin/env node
/**
 * @cobusgreyling/loop — unified front door for Loop Engineering CLIs.
 * Additive: loop-init, loop-audit, and siblings stay fully supported.
 */
import { runTool } from './pass-through.js';
import { runDoctor, formatDoctorHuman } from './doctor.js';
import { runStatus, formatStatusHuman } from './status.js';
import {
  defaultPlan,
  executePlan,
  printNonInteractiveHelp,
  resolvePattern,
  resolveTool,
  runInteractiveWizard,
  type WizardPlan,
} from './wizard.js';

const VERSION = '0.2.0';

const PASS_THROUGH = new Set([
  'init',
  'audit',
  'cost',
  'sync',
  'context',
  'worktree',
  'gate',
  'mcp',
  'sandbox',
]);

function printHelp(): void {
  console.log(`loop — Loop Engineering unified CLI v${VERSION}

Usage:
  loop                          Week-one help (or wizard if TTY + --interactive)
  loop init [args…]             → loop-init (scaffold)
  loop audit [args…]            → loop-audit (Loop Ready score)
  loop cost [args…]             → loop-cost
  loop sync [args…]             → loop-sync
  loop doctor [path] [--json]   Audit + sync + files → top 3 actions
  loop status [path] [--json]   Day-2 dashboard from STATE / run-log
  loop badge [path]             README badge (→ loop-audit --badge)
  loop wizard [--yes]           Guided scaffold + doctor
  loop context|worktree|gate|mcp|sandbox [args…]

Week-one (recommended):
  npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
  npx @cobusgreyling/loop doctor .

Doctor exit codes:
  0  healthy
  1  warnings (score/sync/budget gaps)
  2  blocked (score < 40, critical drift, or unscaffolded)

Compatibility (old doors stay open):
  npx @cobusgreyling/loop-init .
  npx @cobusgreyling/loop-audit . --suggest

Docs: https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md
Showcase: https://cobusgreyling.github.io/loop-engineering/
`);
}

async function cmdDoctor(args: string[]): Promise<number> {
  const json = args.includes('--json');
  const target = args.find((a) => !a.startsWith('-')) || '.';
  if (args.includes('--help') || args.includes('-h')) {
    console.log(`loop doctor [path] [--json]

Combines loop-audit + loop-sync + structural file checks.
Prints severity and the top 3 next actions.

Exit: 0 healthy · 1 warning · 2 blocked
`);
    return 0;
  }
  const report = await runDoctor(target);
  if (json) console.log(JSON.stringify(report, null, 2));
  else console.log(formatDoctorHuman(report));
  return report.exitCode;
}

async function cmdStatus(args: string[]): Promise<number> {
  const json = args.includes('--json');
  const target = args.find((a) => !a.startsWith('-')) || '.';
  if (args.includes('--help') || args.includes('-h')) {
    console.log(`loop status [path] [--json]

Shows pattern, Loop Ready score, last runs from loop-run-log.md, ledger, budget.
`);
    return 0;
  }
  const report = await runStatus(target);
  if (json) console.log(JSON.stringify(report, null, 2));
  else console.log(formatStatusHuman(report));
  return 0;
}

async function cmdBadge(args: string[]): Promise<number> {
  const target = args.find((a) => !a.startsWith('-')) || '.';
  return runTool('audit', [target, '--badge']);
}

async function cmdWizard(args: string[]): Promise<number> {
  const yes = args.includes('--yes') || args.includes('-y');
  const interactive = args.includes('--interactive') || args.includes('-i');

  // Allow: loop wizard -p daily-triage -t claude .
  let plan: WizardPlan = defaultPlan();
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a === '--pattern' || a === '-p') plan.pattern = resolvePattern(args[++i] ?? '');
    else if (a === '--tool' || a === '-t') plan.tool = resolveTool(args[++i] ?? '');
    else if (a === '--with-foundry') plan.withFoundry = true;
    else if (a === '--yes' || a === '-y' || a === '--interactive' || a === '-i') continue;
    else if (!a.startsWith('-')) plan.target = a;
  }

  if (interactive && process.stdin.isTTY) {
    plan = await runInteractiveWizard();
    return executePlan(plan);
  }

  if (yes || args.some((a) => a === '--pattern' || a === '-p')) {
    return executePlan(plan);
  }

  printNonInteractiveHelp();
  return 0;
}

async function main(): Promise<void> {
  const argv = process.argv.slice(2);

  if (argv.length === 0) {
    if (process.stdin.isTTY && argv.includes('--interactive')) {
      // unreachable when length 0 — handled below
    }
    printNonInteractiveHelp();
    return;
  }

  const [cmd, ...rest] = argv;

  if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
    printHelp();
    return;
  }
  if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
    console.log(VERSION);
    return;
  }
  if (cmd === '--interactive' || cmd === '-i') {
    // Mirrors cmdWizard()'s TTY gate below: runInteractiveWizard() drives
    // readline.question(), which resolves immediately with '' when stdin
    // isn't a TTY (a CI step, piped input, `< /dev/null`) instead of
    // waiting for a human. Without this guard, loop --interactive in a
    // non-interactive context silently ran the wizard with every prompt
    // answered blank and scaffolded files nobody asked for.
    if (!process.stdin.isTTY) {
      printNonInteractiveHelp();
      process.exitCode = 0;
      return;
    }
    const plan = await runInteractiveWizard();
    process.exitCode = await executePlan(plan);
    return;
  }

  if (PASS_THROUGH.has(cmd)) {
    const code = await runTool(cmd as 'init', rest);
    process.exitCode = code;
    return;
  }

  if (cmd === 'doctor') {
    process.exitCode = await cmdDoctor(rest);
    return;
  }
  if (cmd === 'status') {
    process.exitCode = await cmdStatus(rest);
    return;
  }
  if (cmd === 'badge') {
    process.exitCode = await cmdBadge(rest);
    return;
  }
  if (cmd === 'wizard') {
    process.exitCode = await cmdWizard(rest);
    return;
  }

  // Unknown: if it looks like a path or init flags, hint; else help
  console.error(`Unknown command: ${cmd}\n`);
  printHelp();
  process.exitCode = 1;
}

main().catch((err) => {
  console.error('loop failed:', err instanceof Error ? err.message : err);
  process.exit(1);
});