@cubis/foundry 0.3.53 → 0.3.55

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+import { runCli } from "./core.js";
+
+void runCli();

package/src/cli/init/banner.ts

@@ -0,0 +1,20 @@
+export function renderInitWelcome({ version }: { version: string }) {
+  const safeVersion = String(version || "").trim() || "dev";
+  const lines = [
+    "╔══════════════════════════════════════════════════════════════╗",
+    "║                     Cubis Foundry CLI                      ║",
+    "║                      Interactive Init                      ║",
+    "╚══════════════════════════════════════════════════════════════╝",
+    "",
+    "      ██████╗",
+    "     ██╔════╝",
+    "     ██║      Cubis Foundry",
+    "     ██║      C icon",
+    "     ╚██████╗",
+    "      ╚═════╝",
+    "",
+    `CLI Version ${safeVersion}`,
+    "",
+  ];
+  return lines.join("\n");
+}

package/src/cli/init/execute.ts

@@ -0,0 +1,88 @@
+import type {
+  InitExecutionPlan,
+  InitExecutionPlanItem,
+  InitMcpId,
+  InitWizardSelections,
+} from "./types.js";
+
+function hasMcpSelection(selectedMcps: InitMcpId[], mcpId: InitMcpId) {
+  return selectedMcps.includes(mcpId);
+}
+
+export function buildInitExecutionPlan({
+  selections,
+  dryRun,
+  target,
+}: {
+  selections: InitWizardSelections;
+  dryRun: boolean;
+  target?: string;
+}): InitExecutionPlan {
+  const planItems: InitExecutionPlanItem[] = [];
+  const wantsPostman = hasMcpSelection(selections.selectedMcps, "postman");
+  const wantsStitch = hasMcpSelection(selections.selectedMcps, "stitch");
+  const wantsFoundry = hasMcpSelection(selections.selectedMcps, "cubis-foundry");
+
+  for (const platform of selections.platforms) {
+    const stitchSupported = platform === "antigravity";
+    const stitchEnabled = wantsStitch && stitchSupported;
+    const warnings: string[] = [];
+    if (wantsStitch && !stitchSupported) {
+      warnings.push(
+        `Stitch is not supported on '${platform}'. It will be skipped for this platform.`,
+      );
+    }
+
+    const installOptions: Record<string, unknown> = {
+      platform,
+      scope: selections.skillsScope,
+      bundle: selections.bundleId,
+      skillProfile: selections.skillProfile,
+      allSkills: selections.skillProfile === "full",
+      dryRun,
+      yes: true,
+      target,
+      postman: wantsPostman,
+      stitch: stitchEnabled,
+      stitchDefaultForAntigravity: false,
+      mcpScope: selections.mcpScope,
+      foundryMcp: wantsFoundry,
+      mcpToolSync: wantsPostman || stitchEnabled,
+      mcpRuntime: wantsPostman || stitchEnabled ? selections.mcpRuntime : "local",
+      mcpFallback: "local",
+      mcpBuildLocal:
+        wantsPostman || stitchEnabled ? selections.mcpBuildLocal : false,
+      postmanMode: wantsPostman ? selections.postmanMode : undefined,
+      postmanWorkspaceId: wantsPostman
+        ? selections.postmanWorkspaceId
+        : undefined,
+      initWizardMode: true,
+    };
+
+    planItems.push({
+      platform,
+      installOptions,
+      warnings,
+    });
+  }
+
+  return {
+    items: planItems,
+  };
+}
+
+export function formatInitSummary(selections: InitWizardSelections) {
+  const postmanSelected = selections.selectedMcps.includes("postman");
+  return [
+    "Init plan summary:",
+    `- Bundle: ${selections.bundleId}`,
+    `- Platforms: ${selections.platforms.join(", ")}`,
+    `- Skill profile: ${selections.skillProfile}`,
+    `- Skills scope: ${selections.skillsScope}`,
+    `- MCP scope: ${selections.mcpScope}`,
+    `- MCP runtime: ${selections.mcpRuntime}${selections.mcpRuntime === "docker" ? selections.mcpBuildLocal ? " (build local image)" : " (pull image)" : ""}`,
+    `- MCP selections: ${selections.selectedMcps.length > 0 ? selections.selectedMcps.join(", ") : "(none)"}`,
+    `- Postman mode: ${postmanSelected ? selections.postmanMode : "(not selected)"}`,
+    `- Postman workspace: ${postmanSelected ? selections.postmanWorkspaceId === null ? "null" : selections.postmanWorkspaceId : "(not selected)"}`,
+  ].join("\n");
+}

package/src/cli/init/index.ts

@@ -0,0 +1,4 @@
+export * from "./banner.js";
+export * from "./execute.js";
+export * from "./prompts.js";
+export * from "./types.js";

package/src/cli/init/prompts.ts

@@ -0,0 +1,163 @@
+import { checkbox, confirm, password, select } from "@inquirer/prompts";
+import type {
+  InitMcpId,
+  InitMcpRuntime,
+  InitPlatformId,
+  InitPostmanMode,
+  InitScope,
+  InitSkillProfile,
+} from "./types.js";
+
+export async function promptInitBundle({
+  bundleIds,
+  defaultBundle,
+}: {
+  bundleIds: string[];
+  defaultBundle: string;
+}) {
+  return select({
+    message: "Select workflow bundle:",
+    default: defaultBundle,
+    choices: bundleIds.map((bundleId) => ({
+      name: bundleId,
+      value: bundleId,
+    })),
+  });
+}
+
+export async function promptInitPlatforms({
+  defaultPlatforms,
+}: {
+  defaultPlatforms: InitPlatformId[];
+}) {
+  return checkbox<InitPlatformId>({
+    message: "Select target platform(s):",
+    required: true,
+    choices: [
+      { name: "Codex", value: "codex", checked: defaultPlatforms.includes("codex") },
+      {
+        name: "Antigravity",
+        value: "antigravity",
+        checked: defaultPlatforms.includes("antigravity"),
+      },
+      {
+        name: "GitHub Copilot",
+        value: "copilot",
+        checked: defaultPlatforms.includes("copilot"),
+      },
+    ],
+  });
+}
+
+export async function promptInitSkillProfile(defaultSkillProfile: InitSkillProfile) {
+  return select<InitSkillProfile>({
+    message: "Select skills install profile:",
+    default: defaultSkillProfile,
+    choices: [
+      { name: "core", value: "core" },
+      { name: "web-backend", value: "web-backend" },
+      { name: "full", value: "full" },
+    ],
+  });
+}
+
+export async function promptInitMcpSelection(defaultMcps: InitMcpId[]) {
+  return checkbox<InitMcpId>({
+    message: "Select which MCP integrations to configure:",
+    choices: [
+      {
+        name: "Cubis Foundry",
+        value: "cubis-foundry",
+        checked: defaultMcps.includes("cubis-foundry"),
+      },
+      { name: "Postman", value: "postman", checked: defaultMcps.includes("postman") },
+      { name: "Stitch", value: "stitch", checked: defaultMcps.includes("stitch") },
+    ],
+  });
+}
+
+export async function promptInitScope({
+  message,
+  defaultScope,
+}: {
+  message: string;
+  defaultScope: InitScope;
+}) {
+  return select<InitScope>({
+    message,
+    default: defaultScope,
+    choices: [
+      { name: defaultScope === "global" ? "Global (recommended)" : "Global", value: "global" },
+      {
+        name: defaultScope === "project" ? "Project (recommended)" : "Project",
+        value: "project",
+      },
+    ],
+  });
+}
+
+export async function promptInitPostmanMode(defaultMode: InitPostmanMode) {
+  return select<InitPostmanMode>({
+    message: "Select Postman installation mode:",
+    default: defaultMode,
+    choices: [
+      { name: "full", value: "full" },
+      { name: "minimal", value: "minimal" },
+    ],
+  });
+}
+
+export async function promptInitMcpRuntime({
+  defaultRuntime,
+  defaultBuildLocal,
+}: {
+  defaultRuntime: InitMcpRuntime;
+  defaultBuildLocal: boolean;
+}) {
+  const defaultChoice =
+    defaultRuntime === "docker"
+      ? defaultBuildLocal
+        ? "docker-build-local"
+        : "docker-pull"
+      : "local";
+
+  const choice = await select<"local" | "docker-pull" | "docker-build-local">({
+    message: "Select MCP runtime mode:",
+    default: defaultChoice,
+    choices: [
+      {
+        name: "Local command server (cbx mcp serve)",
+        value: "local",
+      },
+      {
+        name: "Docker runtime (pull image)",
+        value: "docker-pull",
+      },
+      {
+        name: "Docker runtime (build image locally)",
+        value: "docker-build-local",
+      },
+    ],
+  });
+
+  return {
+    mcpRuntime: choice === "local" ? "local" : ("docker" as const),
+    mcpBuildLocal: choice === "docker-build-local",
+  };
+}
+
+export async function promptOptionalSecret(message: string) {
+  const value = await password({
+    message,
+    mask: "*",
+  });
+  const normalized = String(value || "").trim();
+  return normalized || null;
+}
+
+export async function promptInitApplyConfirmation(summary: string) {
+  return confirm({
+    message: `${summary}\n\nApply this installation plan?`,
+    default: true,
+  });
+}

package/src/cli/init/types.ts

@@ -0,0 +1,43 @@
+export type InitScope = "project" | "global";
+export type InitSkillProfile = "core" | "web-backend" | "full";
+export type InitMcpId = "cubis-foundry" | "postman" | "stitch";
+export type InitPostmanMode = "full" | "minimal";
+export type InitPlatformId = "codex" | "antigravity" | "copilot";
+export type InitMcpRuntime = "local" | "docker";
+
+export interface InitWizardSelections {
+  bundleId: string;
+  platforms: InitPlatformId[];
+  skillProfile: InitSkillProfile;
+  skillsScope: InitScope;
+  mcpScope: InitScope;
+  mcpRuntime: InitMcpRuntime;
+  mcpBuildLocal: boolean;
+  selectedMcps: InitMcpId[];
+  postmanMode: InitPostmanMode;
+  postmanWorkspaceId: string | null;
+  postmanApiKey: string | null;
+  stitchApiKey: string | null;
+}
+
+export interface InitExecutionPlanItem {
+  platform: InitPlatformId;
+  installOptions: Record<string, unknown>;
+  warnings: string[];
+}
+
+export interface InitExecutionPlan {
+  items: InitExecutionPlanItem[];
+}
+
+export interface PerPlatformInitResult {
+  platform: InitPlatformId;
+  status: "success" | "failed";
+  warnings: string[];
+  error?: string;
+}
+
+export interface InitWarnings {
+  global: string[];
+  perPlatform: Record<string, string[]>;
+}

package/src/cli/io.ts

@@ -0,0 +1 @@
+export {};

package/src/cli/mcp/commands.ts

@@ -0,0 +1,131 @@
+import type { Command } from "commander";
+import type { WorkflowAction } from "../types.js";
+
+export interface McpCommandDeps {
+  runMcpServe: WorkflowAction;
+  runMcpToolsSync: WorkflowAction;
+  runMcpToolsList: WorkflowAction;
+  runMcpRuntimeStatus: WorkflowAction;
+  runMcpRuntimeUp: WorkflowAction;
+  runMcpRuntimeDown: WorkflowAction;
+  defaultMcpDockerContainerName: string;
+}
+
+export function registerMcpCommands(program: Command, deps: McpCommandDeps) {
+  const mcpCommand = program
+    .command("mcp")
+    .description("Manage Cubis MCP runtime catalogs and tool discovery");
+
+  mcpCommand
+    .command("serve")
+    .description(
+      "Launch bundled Cubis Foundry MCP server (canonical local entrypoint)",
+    )
+    .option("--transport <transport>", "stdio|http", "stdio")
+    .option("--scope <scope>", "auto|global|project", "auto")
+    .option("--port <port>", "HTTP port override")
+    .option("--host <host>", "HTTP host override")
+    .option("--scan-only", "scan vault and exit")
+    .option("--config <path>", "explicit MCP server config file path")
+    .option("--debug", "enable debug logging in MCP server")
+    .action(deps.runMcpServe);
+
+  const mcpToolsCommand = mcpCommand
+    .command("tools")
+    .description("Discover and inspect upstream MCP tool catalogs");
+
+  mcpToolsCommand
+    .command("sync")
+    .description("Discover upstream tools and persist local non-secret catalogs")
+    .option("--service <service>", "postman|stitch|all", "all")
+    .option(
+      "--scope <scope>",
+      "config scope: project|workspace|global|user",
+      "global",
+    )
+    .option("--dry-run", "preview sync without writing catalog files")
+    .action(deps.runMcpToolsSync);
+
+  mcpToolsCommand
+    .command("list")
+    .description("List cached tool names from local MCP catalog")
+    .requiredOption("--service <service>", "postman|stitch")
+    .option(
+      "--scope <scope>",
+      "config scope: project|workspace|global|user",
+      "global",
+    )
+    .action(deps.runMcpToolsList);
+
+  const mcpRuntimeCommand = mcpCommand
+    .command("runtime")
+    .description("Manage local Docker runtime container for Cubis MCP gateway");
+
+  mcpRuntimeCommand
+    .command("status")
+    .description("Show Docker runtime status and configured MCP runtime defaults")
+    .option(
+      "--scope <scope>",
+      "config scope: project|workspace|global|user",
+      "global",
+    )
+    .option(
+      "--name <name>",
+      "container name",
+      deps.defaultMcpDockerContainerName,
+    )
+    .option(
+      "--skills-root <path>",
+      "host skills directory to resolve/mount (default: auto-detect)",
+    )
+    .action(deps.runMcpRuntimeStatus);
+
+  mcpRuntimeCommand
+    .command("up")
+    .description("Start Docker runtime container for Cubis MCP gateway")
+    .option(
+      "--scope <scope>",
+      "config scope: project|workspace|global|user",
+      "global",
+    )
+    .option(
+      "--name <name>",
+      "container name",
+      deps.defaultMcpDockerContainerName,
+    )
+    .option("--image <image:tag>", "docker image to run")
+    .option("--update-policy <policy>", "pinned|latest")
+    .option(
+      "--fallback <fallback>",
+      "when endpoint is unreachable: local|fail|skip",
+    )
+    .option(
+      "--build-local",
+      "build MCP Docker image from local package mcp/ directory instead of pulling",
+    )
+    .option("--port <port>", "host port to map to container :3100")
+    .option(
+      "--skills-root <path>",
+      "host skills directory to mount into /workflows/skills (default: auto-detect)",
+    )
+    .option("--replace", "remove existing container with same name before start")
+    .action(deps.runMcpRuntimeUp);
+
+  mcpRuntimeCommand
+    .command("down")
+    .description("Stop and remove Docker runtime container")
+    .option(
+      "--name <name>",
+      "container name",
+      deps.defaultMcpDockerContainerName,
+    )
+    .action(deps.runMcpRuntimeDown);
+
+  mcpRuntimeCommand.action(() => {
+    mcpRuntimeCommand.help();
+  });
+
+  mcpCommand.action(() => {
+    mcpCommand.help();
+  });
+}

package/src/cli/mcp/index.ts

@@ -0,0 +1 @@
+export {};

package/src/cli/pathing.ts

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { AGENT_ASSETS_SUBDIR } from "./constants.js";
+
+export function packageRoot() {
+  let currentDir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i += 1) {
+    const candidatePackageJson = path.join(currentDir, "package.json");
+    if (existsSync(candidatePackageJson)) {
+      return currentDir;
+    }
+    const parentDir = path.resolve(currentDir, "..");
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  return process.cwd();
+}
+
+export function agentAssetsRoot() {
+  const preferred = path.join(packageRoot(), AGENT_ASSETS_SUBDIR);
+  return existsSync(preferred) ? preferred : packageRoot();
+}
+
+export function workflowSkillsRoot() {
+  return path.join(agentAssetsRoot(), "skills");
+}
+
+export function expandPath(inputPath: string, cwd = process.cwd()) {
+  if (!inputPath) return cwd;
+  if (inputPath === "~") return os.homedir();
+  if (inputPath.startsWith("~/"))
+    return path.join(os.homedir(), inputPath.slice(2));
+  if (path.isAbsolute(inputPath)) return inputPath;
+  return path.resolve(cwd, inputPath);
+}
+
+export function findWorkspaceRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startDir);
+    current = parent;
+  }
+}

package/src/cli/platforms.ts

@@ -0,0 +1 @@
+export type PlatformId = "codex" | "antigravity" | "copilot";

package/src/cli/rules/commands.ts

@@ -0,0 +1,40 @@
+import type { Command } from "commander";
+import type { WorkflowAction } from "../types.js";
+
+export interface RulesCommandDeps {
+  runRulesInit: WorkflowAction;
+  runRulesTechMd: WorkflowAction;
+}
+
+export function registerRulesCommands(program: Command, deps: RulesCommandDeps) {
+  const rulesCommand = program
+    .command("rules")
+    .description(
+      "Create and sync strict engineering rules and generated TECH.md",
+    );
+
+  rulesCommand
+    .command("init")
+    .description(
+      "Create/update ENGINEERING_RULES.md, patch active platform rule file with managed guardrail block, and generate TECH.md",
+    )
+    .option("-p, --platform <platform>", "target platform id")
+    .option("--scope <scope>", "target scope: project|global", "project")
+    .option("--overwrite", "overwrite existing ENGINEERING_RULES.md and TECH.md")
+    .option("--skip-tech", "skip TECH.md generation")
+    .option("--dry-run", "preview changes without writing files")
+    .action(deps.runRulesInit);
+
+  rulesCommand
+    .command("tech-md")
+    .description("Scan the codebase and generate/update TECH.md")
+    .option("--output <path>", "output path (default: <workspace-root>/TECH.md)")
+    .option("--overwrite", "overwrite existing TECH.md")
+    .option("--compact", "generate compact TECH.md (stack + context budget only)")
+    .option("--dry-run", "preview generation without writing files")
+    .action(deps.runRulesTechMd);
+
+  rulesCommand.action(() => {
+    rulesCommand.help();
+  });
+}

package/src/cli/rules/index.ts

@@ -0,0 +1 @@
+export {};

package/src/cli/tech/index.ts

@@ -0,0 +1 @@
+export {};

package/src/cli/types.ts

@@ -0,0 +1,15 @@
+import type { Command } from "commander";
+
+export type AnyOptions = Record<string, unknown>;
+
+export type WorkflowAction = (options: AnyOptions) => Promise<void> | void;
+export type WorkflowTargetAction = (
+  target: string,
+  options: AnyOptions,
+) => Promise<void> | void;
+export type WorkflowDoctorAction = (
+  platform: string | undefined,
+  options: AnyOptions,
+) => Promise<void> | void;
+
+export type CommandDecorator = (command: Command) => Command;