@ranker/raxflow 0.2.0

package/src/hub/styles/colors.ts

@@ -0,0 +1,129 @@
+// RAXFLOW Design System - Colors
+// Based on cli-design.md specifications
+
+export const colors = {
+  // Backgrounds
+  background: "#050505",
+  surface: "#0a0a0a",
+  surfaceElev: "#0d0d0d",
+
+  // Primary
+  primary: "#f97316", // Orange vif
+  primaryGlow: "rgba(249, 115, 22, 0.3)",
+  primaryGlowHover: "rgba(249, 115, 22, 0.5)",
+
+  // Text
+  textPrimary: "#ffffff",
+  textSecondary: "#a1a1aa",
+  textTertiary: "#71717a",
+  textQuaternary: "#3f3f46",
+
+  // Status
+  success: "#22c55e",
+  warning: "#f59e0b",
+  error: "#ef4444",
+
+  // Borders
+  border: "#27272a",
+
+  // Mutations
+  mutation: "#f59e0b",
+  mutationGlow: "rgba(245, 158, 11, 0.4)",
+};
+
+// ANSI color codes for terminal
+export const ansiColors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  
+  // Foreground colors
+  black: "\x1b[30m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+  
+  // Bright colors
+  brightRed: "\x1b[91m",
+  brightGreen: "\x1b[92m",
+  brightYellow: "\x1b[93m",
+  brightBlue: "\x1b[94m",
+  brightMagenta: "\x1b[95m",
+  brightCyan: "\x1b[96m",
+  brightWhite: "\x1b[97m",
+  
+  // Background colors
+  bgBlack: "\x1b[40m",
+  bgRed: "\x1b[41m",
+  bgGreen: "\x1b[42m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+  bgMagenta: "\x1b[45m",
+  bgCyan: "\x1b[46m",
+  bgWhite: "\x1b[47m",
+  bgGray: "\x1b[100m",
+};
+
+// Status indicators
+export const statusIndicators = {
+  online: "●",
+  offline: "○",
+  running: "▶",
+  loading: "◐",
+  mutation: "◆",
+  checkpoint: "■",
+  pending: "○",
+  done: "✓",
+};
+
+// Provider indicators
+export const providerIndicators: Record<string, string> = {
+  host: "[H]",
+  claude: "[C]",
+  opencode: "[O]",
+  kilo: "[K]",
+  anthropic: "[A]",
+  gemini: "[G]",
+  mistral: "[M]",
+  groq: "[Q]",
+  openai: "[O]",
+};
+
+// Utility functions
+export function colorize(text: string, color: keyof typeof ansiColors): string {
+  return `${ansiColors[color]}${text}${ansiColors.reset}`;
+}
+
+export function statusColor(status: string): string {
+  switch (status.toLowerCase()) {
+    case "online":
+    case "ready":
+    case "active":
+    case "done":
+    case "success":
+      return ansiColors.green;
+    case "running":
+    case "busy":
+      return ansiColors.yellow;
+    case "error":
+    case "failed":
+      return ansiColors.red;
+    case "queued":
+    case "pending":
+    case "idle":
+      return ansiColors.gray;
+    default:
+      return ansiColors.reset;
+  }
+}
+
+export function formatStatus(status: string): string {
+  const indicator = statusIndicators[status.toLowerCase() as keyof typeof statusIndicators] || "○";
+  const color = statusColor(status);
+  return `${color}${indicator}${ansiColors.reset}`;
+}

package/src/hub/styles/typography.ts

@@ -0,0 +1,68 @@
+// RAXFLOW Design System - Typography
+// Space Grotesk for titles, Space Mono for system text
+
+export const typography = {
+  // Font families
+  primary: "Space Grotesk",
+  monospace: "Space Mono",
+
+  // Font weights
+  weights: {
+    light: 300,
+    regular: 400,
+    medium: 500,
+    bold: 700,
+  },
+
+  // Sizes (in terminal columns roughly)
+  sizes: {
+    hero: 4,      // text-4xl
+    section: 2,   // text-2xl
+    label: 0,     // text-[10px]
+    body: 1,      // text-sm
+    code: 0,      // text-xs
+    status: -1,   // text-[9px]
+    agent: 0,     // text-xs
+    provider: -1, // text-[9px]
+  },
+
+  // Tracking (letter-spacing)
+  tracking: {
+    none: "",
+    tight: "",
+    normal: "",
+    wide: " ",
+    label: "  ", // 0.15em equivalent in monospace
+  },
+};
+
+// Text formatting utilities for terminal
+export function upperCase(text: string): string {
+  return text.toUpperCase();
+}
+
+export function padCenter(text: string, width: number): string {
+  const padding = Math.max(0, width - text.length);
+  const leftPad = Math.floor(padding / 2);
+  const rightPad = padding - leftPad;
+  return " ".repeat(leftPad) + text + " ".repeat(rightPad);
+}
+
+export function padRight(text: string, width: number): string {
+  const padding = Math.max(0, width - text.length);
+  return text + " ".repeat(padding);
+}
+
+export function padLeft(text: string, width: number): string {
+  const padding = Math.max(0, width - text.length);
+  return " ".repeat(padding) + text;
+}
+
+export function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+export function formatLabel(text: string): string {
+  return upperCase(text).split("").join(" ");
+}

package/src/hub/types.ts

@@ -0,0 +1,31 @@
+export interface HubOptions {
+  cwd: string;
+  config?: HubConfig;
+}
+
+export interface HubConfig {
+  project?: string;
+  providers?: string[];
+  theme?: 'industrial' | 'minimal' | 'high-contrast';
+}
+
+export interface Command {
+  name: string;
+  args: string[];
+  flags: Record<string, string | boolean>;
+}
+
+export interface HubContext {
+  currentWorkflow?: string;
+  currentRun?: string;
+  config: HubConfig;
+}
+
+export type CommandHandler = (args: string[], flags: Record<string, string | boolean>, context: HubContext) => Promise<void>;
+
+export interface CommandDefinition {
+  name: string;
+  description: string;
+  handler: CommandHandler;
+  aliases?: string[];
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./install.js";
+export * from "./run.js";
+export * from "./benchmark.js";
+export * from "./doctor.js";
+export * from "./bridge-test.js";
+export * from "./init-host.js";
+export * from "./bootstrap.js";
+export * from "./host-init-templates.js";
+export * from "./bridge-adapter-templates.js";
+export * from "./vendor-manifests.js";

package/src/init-host.ts

@@ -0,0 +1,285 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { c } from "./styles.js";
+import { HOST_TEMPLATES, HostTarget, buildBootstrapPrompt, listHostTargets, parseHostTarget } from "./host-init-templates.js";
+import { generateVendorManifest, vendorManifestFilename, type HostManifestModel } from "./vendor-manifests.js";
+import { bridgeAdapterFilename, renderBridgeAdapter } from "./bridge-adapter-templates.js";
+
+interface InitHostOptions {
+  cwd: string;
+  target?: string;
+  printOnly?: boolean;
+  all?: boolean;
+  task?: string;
+}
+
+function bridgeCommand(adapterFile: string): string {
+  return `node ${adapterFile}`;
+}
+
+function renderSetupScript(command: string): string {
+  return [
+    "#!/usr/bin/env bash",
+    "set -e",
+    `export RAX_HOST_BRIDGE_COMMAND=\"${command}\"`,
+    'echo "RAX_HOST_BRIDGE_COMMAND configured"',
+    "echo \"Run: npx raxflow doctor\"",
+    "echo \"Run: npx raxflow run --prompt 'Build feature X' --stream\""
+  ].join("\n");
+}
+
+function renderInstructions(params: {
+  title: string;
+  envHint: string;
+  chatHint: string;
+  command: string;
+  adapterFile: string;
+  quickCommands: string[];
+  sessionEntryExamples: string[];
+  autoInjectMode: "native" | "scripted" | "manual";
+  task?: string;
+}): string {
+  const taskSection = params.task?.trim()
+    ? ["", "## Task context", `- ${params.task.trim()}`, "- Embedded into BOOTSTRAP_PROMPT.txt"]
+    : [];
+
+  return [
+    `# ${params.title} - Non-UI Initialization`,
+    "",
+    "## 1) Configure bridge command",
+    `- ${params.envHint}`,
+    `- Command: \`${params.command}\``,
+    `- Bridge adapter scaffold: \`${params.adapterFile}\``,
+    "- Replace callHostModel() with your editor runtime model call implementation.",
+    "- Configure bridge runtime values in `bridge-runtime-config.json`.",
+    "- Use `bridge-smoke-test.json` to validate structured response mapping.",
+    "",
+    "## 2) Chat bootstrap",
+    `- ${params.chatHint}`,
+    "- Use BOOTSTRAP_PROMPT.txt content.",
+    ...taskSection,
+    "",
+    "## 3) Session launch patterns",
+    `- Auto inject mode: \`${params.autoInjectMode}\``,
+    ...params.sessionEntryExamples.map((line) => `- \`${line}\``),
+    "",
+    "## 4) Validate",
+    ...params.quickCommands.map((cmd) => `- \`${cmd}\``)
+  ].join("\n");
+}
+
+function renderSessionStartScript(target: HostTarget, sessionEntryExamples: string[]): string {
+  const lines = [
+    "#!/usr/bin/env bash",
+    "set -e",
+    `echo \"RAXFLOW session starter (${target})\"`,
+    "echo \"Use one of these commands (adapt to your local CLI):\""
+  ];
+
+  for (const entry of sessionEntryExamples) {
+    lines.push(`echo \"- ${entry}\"`);
+  }
+
+  lines.push("echo \"If unsupported, copy/paste BOOTSTRAP_PROMPT.txt manually.\"");
+  return lines.join("\n");
+}
+
+function renderRuntimeConfig(target: HostTarget, task?: string): string {
+  const payload = {
+    version: 1,
+    vendor: target,
+    model: "host-managed",
+    endpoint: null,
+    authEnv: null,
+    structuredMode: "json",
+    timeoutMs: 20000,
+    taskContext: task?.trim() || null,
+    notes: [
+      "Fill endpoint/auth fields if your host runtime requires external transport.",
+      "If host runtime is in-process, keep endpoint null and call runtime SDK directly in bridge adapter."
+    ]
+  };
+  return JSON.stringify(payload, null, 2);
+}
+
+function renderBridgeSmokeTest(target: HostTarget): string {
+  const payload = {
+    version: 1,
+    action: "callStructured",
+    prompt: "Smoke test structured output",
+    schema: {
+      type: "object",
+      required: ["agent", "success", "confidence", "risks", "logs", "data"],
+      properties: {
+        agent: { type: "string" },
+        success: { type: "boolean" },
+        confidence: { type: "number" },
+        risks: { type: "array" },
+        logs: { type: "array" },
+        data: { type: "object" }
+      }
+    },
+    options: { model: "host-managed", temperature: 0, maxTokens: 256 },
+    meta: { target }
+  };
+  return JSON.stringify(payload, null, 2);
+}
+
+function renderManifest(params: {
+  target: HostTarget;
+  title: string;
+  autoInjectMode: "native" | "scripted" | "manual";
+  bridgeCommand: string;
+  quickCommands: string[];
+  sessionEntryExamples: string[];
+  bootstrapPromptFile: string;
+  instructionsFile: string;
+  adapterFile: string;
+  runtimeConfigFile: string;
+  smokeTestFile: string;
+  vendorFile: string;
+  task?: string;
+}): HostManifestModel {
+  return {
+    version: 2,
+    target: params.target,
+    title: params.title,
+    autoInjectMode: params.autoInjectMode,
+    bridgeCommand: params.bridgeCommand,
+    quickCommands: params.quickCommands,
+    sessionEntryExamples: params.sessionEntryExamples,
+    task: params.task ?? null,
+    files: {
+      bootstrapPrompt: params.bootstrapPromptFile,
+      instructions: params.instructionsFile,
+      bridgeAdapter: params.adapterFile,
+      bridgeRuntimeConfig: params.runtimeConfigFile,
+      bridgeSmokeTest: params.smokeTestFile,
+      vendorManifest: params.vendorFile
+    }
+  };
+}
+
+async function generateForTarget(cwd: string, target: HostTarget, task?: string): Promise<{ dir: string; bootstrapPrompt: string; quickCommands: string[] }> {
+  const template = HOST_TEMPLATES[target];
+  const baseDir = path.join(cwd, ".raxflow", "host-init", target);
+  const adapterFile = path.join(baseDir, bridgeAdapterFilename(target));
+  const command = bridgeCommand(adapterFile);
+
+  await mkdir(baseDir, { recursive: true });
+
+  const setupSh = renderSetupScript(command);
+  const sessionStartSh = renderSessionStartScript(target, template.sessionEntryExamples);
+  const bootstrapPrompt = buildBootstrapPrompt(target, task);
+  const bridgeAdapter = renderBridgeAdapter(target);
+  const instructions = renderInstructions({
+    title: template.title,
+    envHint: template.envHint,
+    chatHint: template.chatHint,
+    command,
+    adapterFile,
+    quickCommands: template.quickCommands,
+    sessionEntryExamples: template.sessionEntryExamples,
+    autoInjectMode: template.autoInjectMode,
+    task
+  });
+
+  const bootstrapPromptFile = path.join(baseDir, "BOOTSTRAP_PROMPT.txt");
+  const instructionsFile = path.join(baseDir, "INSTRUCTIONS.md");
+  const runtimeConfigFile = path.join(baseDir, "bridge-runtime-config.json");
+  const smokeTestFile = path.join(baseDir, "bridge-smoke-test.json");
+  const vendorFile = vendorManifestFilename(target);
+  const manifestObj = renderManifest({
+    target,
+    title: template.title,
+    autoInjectMode: template.autoInjectMode,
+    bridgeCommand: command,
+    quickCommands: template.quickCommands,
+    sessionEntryExamples: template.sessionEntryExamples,
+    bootstrapPromptFile,
+    instructionsFile,
+    adapterFile,
+    runtimeConfigFile,
+    smokeTestFile,
+    vendorFile: path.join(baseDir, vendorFile),
+    task
+  });
+  const manifest = JSON.stringify(manifestObj, null, 2);
+  const vendorManifest = generateVendorManifest(target, baseDir, manifestObj);
+
+  await writeFile(path.join(baseDir, "setup-bridge.sh"), `${setupSh}\n`, "utf8");
+  await writeFile(path.join(baseDir, "start-session.sh"), `${sessionStartSh}\n`, "utf8");
+  await writeFile(adapterFile, `${bridgeAdapter}\n`, "utf8");
+  await writeFile(runtimeConfigFile, `${renderRuntimeConfig(target, task)}\n`, "utf8");
+  await writeFile(smokeTestFile, `${renderBridgeSmokeTest(target)}\n`, "utf8");
+  await writeFile(bootstrapPromptFile, `${bootstrapPrompt}\n`, "utf8");
+  await writeFile(instructionsFile, `${instructions}\n`, "utf8");
+  await writeFile(path.join(baseDir, "host-manifest.json"), `${manifest}\n`, "utf8");
+  await writeFile(path.join(baseDir, vendorFile), `${JSON.stringify(vendorManifest, null, 2)}\n`, "utf8");
+
+  return { dir: baseDir, bootstrapPrompt, quickCommands: template.quickCommands };
+}
+
+async function generateSummary(cwd: string, generated: Array<{ target: HostTarget; dir: string }>, task?: string): Promise<string> {
+  const summaryFile = path.join(cwd, ".raxflow", "host-init", "INIT_SUMMARY.md");
+  const body = [
+    "# RAXFLOW Host Init Summary",
+    "",
+    ...(task?.trim() ? ["Task context:", `- ${task.trim()}`, ""] : []),
+    "Generated targets:",
+    ...generated.map((item) => `- ${item.target}: \`${item.dir}\``),
+    "",
+    "Recommended sequence:",
+    "1. Review bridge-adapter-*.mjs and wire host runtime in callHostModel",
+    "2. Source setup-bridge.sh for your target",
+    "3. Run start-session.sh for launch hints",
+    "4. Paste BOOTSTRAP_PROMPT.txt into chat start",
+    "5. Run `npx raxflow doctor`",
+    "6. Run `npx raxflow run --prompt \"Build feature X\" --stream`"
+  ].join("\n");
+  await writeFile(summaryFile, `${body}\n`, "utf8");
+  return summaryFile;
+}
+
+export async function runInitHost(options: InitHostOptions): Promise<number> {
+  const targets = options.all ? listHostTargets() : [parseHostTarget(options.target)];
+
+  if (options.printOnly) {
+    for (const target of targets) {
+      const template = HOST_TEMPLATES[target];
+      const bootstrapPrompt = buildBootstrapPrompt(target, options.task);
+      console.log(c.blue(`RAXFLOW Host Init (print) - ${target}`));
+      console.log(bootstrapPrompt);
+      console.log("quick commands:");
+      template.quickCommands.forEach((cmd) => console.log(`- ${cmd}`));
+      console.log("session launch patterns:");
+      template.sessionEntryExamples.forEach((line) => console.log(`- ${line}`));
+    }
+    return 0;
+  }
+
+  const generated: Array<{ target: HostTarget; dir: string }> = [];
+
+  for (const target of targets) {
+    const out = await generateForTarget(options.cwd, target, options.task);
+    generated.push({ target, dir: out.dir });
+    console.log(c.blue("RAXFLOW Host Init"));
+    console.log(`target: ${target}`);
+    if (options.task?.trim()) {
+      console.log(`task context: ${options.task.trim()}`);
+    }
+    console.log(c.green(`Generated ${path.join(out.dir, "INSTRUCTIONS.md")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, "BOOTSTRAP_PROMPT.txt")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, "setup-bridge.sh")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, "start-session.sh")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, bridgeAdapterFilename(target))}`));
+    console.log(c.green(`Generated ${path.join(out.dir, "bridge-runtime-config.json")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, "bridge-smoke-test.json")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, "host-manifest.json")}`));
+    console.log(c.green(`Generated ${path.join(out.dir, vendorManifestFilename(target))}`));
+  }
+
+  const summary = await generateSummary(options.cwd, generated, options.task);
+  console.log(c.green(`Generated ${summary}`));
+  return 0;
+}

package/src/install.ts

@@ -0,0 +1,118 @@
+import { mkdir, writeFile, access, copyFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { c } from "./styles.js";
+
+interface InstallOptions {
+  cwd: string;
+  openUi: boolean;
+  autoConfirm?: boolean;
+}
+
+async function detectBridges(): Promise<string[]> {
+  const candidates = [
+    { id: "claude-code", cmd: "claude-code --version" },
+    { id: "codex", cmd: "codex --version" },
+    { id: "opencode", cmd: "opencode --version" },
+    { id: "kilo", cmd: "kilo --version" }
+  ];
+
+  const detected: string[] = [];
+  for (const tool of candidates) {
+    try {
+      execSync(tool.cmd, { stdio: "ignore" });
+      detected.push(tool.id);
+    } catch {
+      // Not in path
+    }
+  }
+  return detected;
+}
+
+async function ensureRaxrc(targetDir: string, detectedBridge?: string): Promise<string> {
+  const file = path.join(targetDir, ".raxrc");
+  const body = {
+    version: 1,
+    defaultProvider: detectedBridge ? "host" : "openai",
+    strongProvider: "openai",
+    providers: {
+      host: {
+        model: detectedBridge ?? "host-managed",
+        mode: "auto",
+        bridgeCommand: detectedBridge ?? "claude-code", // Store direct command if found
+        bridgeCommandEnv: "RAX_HOST_BRIDGE_COMMAND"
+      },
+      openai: { model: "gpt-4o", apiKeyEnv: "OPENAI_API_KEY" },
+      claude: { model: "claude-3-5-sonnet-latest", apiKeyEnv: "ANTHROPIC_API_KEY" }
+    },
+    privacyMode: true,
+    verifyFixLoops: 3
+  };
+  await writeFile(file, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+  return file;
+}
+
+async function ensureExampleWorkflow(targetDir: string): Promise<string> {
+  const workflowsDir = path.join(targetDir, ".raxflow", "workflows");
+  await mkdir(workflowsDir, { recursive: true });
+  const file = path.join(workflowsDir, "fullstack-feature.json");
+  const sample = {
+    id: "fullstack-feature",
+    nodes: [
+      { id: "analyze", agent: "IntentClassifierAgent", dependsOn: [] },
+      { id: "spec", agent: "SpecAgent", dependsOn: ["analyze"] },
+      { id: "implement", agent: "CodeGeneratorAgent", dependsOn: ["spec"] },
+      { id: "verify", agent: "ValidatorAgent", dependsOn: ["implement"] }
+    ]
+  };
+  await writeFile(file, `${JSON.stringify(sample, null, 2)}\n`, "utf8");
+  return file;
+}
+
+async function validateEnvironment(): Promise<{ ok: boolean; missing: string[] }> {
+  const optional = ["OPENAI_API_KEY", "RAX_HOST_BRIDGE_COMMAND"];
+  const missing = optional.filter((k) => !process.env[k]);
+  return { ok: true, missing };
+}
+
+export async function runInstall(options: InstallOptions): Promise<number> {
+  console.log(c.blue("RAXFLOW Installer - Professional Setup"));
+
+  console.log("- Scanning for local coding tools...");
+  const detected = await detectBridges();
+  if (detected.length > 0) {
+    console.log(c.green(`  [OK] Detected: ${detected.join(", ")}`));
+  } else {
+    console.log(c.yellow("  [!] No local coding tools (Claude Code/Codex) detected in PATH."));
+  }
+
+  const primaryBridge = detected[0];
+  const raxrc = await ensureRaxrc(options.cwd, primaryBridge);
+  const workflow = await ensureExampleWorkflow(options.cwd);
+
+  console.log(c.green(`- Project Initialized: ${raxrc}`));
+  console.log(c.green(`- Default Blueprint Created: ${workflow}`));
+
+  const env = await validateEnvironment();
+  if (env.missing.length > 0) {
+    console.log(c.yellow(`- Note: Optional env vars missing: ${env.missing.join(", ")}`));
+  }
+
+  const localHome = path.join(os.homedir(), ".raxflow");
+  await mkdir(localHome, { recursive: true });
+
+  console.log("\n" + c.blue("--- Zero-Error Compliance Checklist ---"));
+  console.log(c.green("✓ Host Bridge Architecture: Scalable & Compliant"));
+  console.log(c.green("✓ Dynamic Planner: Enabled (Self-Optimizing)"));
+  console.log(c.green("✓ Long-term Memory: Configured"));
+
+  console.log("\n" + c.yellow("Next Logical Steps:"));
+  console.log("1. Run `raxflow doctor` to verify bridge connectivity.");
+  console.log("2. Launch a task: `raxflow run --prompt \"Implement feature Y\" --stream`.");
+
+  console.log("\n" + c.green("RAXFLOW is now the operational backbone of your CLI workflow."));
+  return 0;
+}
+