@rigkit/cli 0.0.0-canary-20260518T014918-c5bc0c2

package/src/init.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { initProject, normalizeMachineName } from "./init.ts";
+import {
+  FREESTYLE_PROVIDER_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_VERSION,
+  PROJECT_PACKAGE_NAME,
+} from "./project.ts";
+import { RIGKIT_CLI_VERSION } from "./version.ts";
+
+describe("initProject", () => {
+  test("creates a full Rigkit project", () => {
+    const parentDir = mkdtempSync(join(tmpdir(), "rigkit-init-"));
+    const projectDir = join(parentDir, "platform-api");
+    const result = initProject({
+      projectDir,
+      configPath: join(projectDir, "rig.config.ts"),
+      name: "Platform API",
+    });
+
+    expect(result.name).toBe("platform-api");
+    expect(result.projectDir).toBe(projectDir);
+    expect(existsSync(projectDir)).toBe(true);
+    expect(result.created).toEqual({
+      config: true,
+      env: false,
+      envExample: false,
+      gitignore: true,
+      packageJson: true,
+    });
+
+    expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).toContain('sequence("platform-api"');
+    expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).toContain("defineConfig({");
+    expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).toContain("new VmSpec()");
+    expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).not.toContain("FREESTYLE_API_KEY");
+    expect(existsSync(join(projectDir, ".env"))).toBe(false);
+    expect(existsSync(join(projectDir, ".env.example"))).toBe(false);
+    expect(readFileSync(join(projectDir, ".gitignore"), "utf8")).toContain(".env\n.rigkit/\n");
+
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+    expect(pkg.name).toBe("platform-api");
+    expect(pkg.scripts.plan).toBe("rig plan");
+    expect(pkg.scripts.apply).toBe("rig apply");
+    expect(pkg.devDependencies[PROJECT_PACKAGE_NAME]).toBe(RIGKIT_CLI_VERSION);
+    expect(pkg.devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME]).toBe(RIGKIT_CLI_VERSION);
+    expect(pkg.devDependencies[FREESTYLE_SDK_PACKAGE_NAME]).toBe(FREESTYLE_SDK_PACKAGE_VERSION);
+  });
+
+  test("updates existing project files without replacing package metadata", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-init-"));
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, ".env"), "OTHER=value\nFREESTYLE_API_KEY=old\n");
+    writeFileSync(join(projectDir, ".gitignore"), "node_modules/\n");
+    writeFileSync(
+      join(projectDir, "package.json"),
+      `${JSON.stringify({ name: "existing", scripts: { test: "bun test" } }, null, 2)}\n`,
+    );
+
+    const result = initProject({
+      projectDir,
+      configPath: join(projectDir, "rig.config.ts"),
+      name: "dev",
+      apiKey: "new-key",
+    });
+
+    expect(result.created.packageJson).toBe(false);
+    expect(result.updated.packageJson).toBe(true);
+    expect(readFileSync(join(projectDir, ".env"), "utf8")).toBe("OTHER=value\nFREESTYLE_API_KEY=new-key\n");
+    expect(readFileSync(join(projectDir, ".gitignore"), "utf8")).toBe("node_modules/\n.env\n.rigkit/\n");
+
+    const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+    expect(pkg.name).toBe("existing");
+    expect(pkg.scripts.test).toBe("bun test");
+    expect(pkg.scripts.plan).toBe("rig plan");
+  });
+});
+
+describe("normalizeMachineName", () => {
+  test("normalizes human names into machine names", () => {
+    expect(normalizeMachineName("  My Platform API  ")).toBe("my-platform-api");
+  });
+
+  test("rejects empty names", () => {
+    expect(() => normalizeMachineName("   ")).toThrow("Project name is required.");
+    expect(() => normalizeMachineName("!!!")).toThrow("Project name is required.");
+  });
+});

package/src/init.ts

@@ -0,0 +1,269 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { RIGKIT_CLI_VERSION } from "./version.ts";
+import {
+  FREESTYLE_PROVIDER_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_VERSION,
+  PROJECT_PACKAGE_NAME,
+} from "./project.ts";
+
+export type InitProjectInput = {
+  projectDir: string;
+  configPath: string;
+  name: string;
+  apiKey?: string;
+  force?: boolean;
+};
+
+export type InitProjectResult = {
+  name: string;
+  projectDir: string;
+  configPath: string;
+  envPath: string;
+  envExamplePath: string;
+  gitignorePath: string;
+  packageJsonPath: string;
+  created: {
+    config: boolean;
+    env: boolean;
+    envExample: boolean;
+    packageJson: boolean;
+    gitignore: boolean;
+  };
+  updated: {
+    envApiKey: boolean;
+    gitignore: boolean;
+    packageJson: boolean;
+    sdkDependency: boolean;
+  };
+};
+
+export function initProject(input: InitProjectInput): InitProjectResult {
+  const name = normalizeMachineName(input.name);
+  mkdirSync(input.projectDir, { recursive: true });
+
+  if (existsSync(input.configPath) && !input.force) {
+    throw new Error(`${input.configPath} already exists. Pass --force to overwrite it.`);
+  }
+
+  const wroteConfig = !existsSync(input.configPath) || Boolean(input.force);
+  if (wroteConfig) {
+    writeFileSync(input.configPath, starterConfig(name));
+  }
+
+  const apiKey = input.apiKey?.trim();
+  const envPath = join(input.projectDir, ".env");
+  const env = apiKey
+    ? writeEnvFile(envPath, apiKey)
+    : { created: false, updated: false };
+
+  const envExamplePath = join(input.projectDir, ".env.example");
+  const wroteEnvExample = Boolean(apiKey) && !existsSync(envExamplePath);
+  if (wroteEnvExample) {
+    writeFileSync(envExamplePath, "FREESTYLE_API_KEY=\n");
+  }
+
+  const gitignore = ensureGitignore(input.projectDir);
+  const packageJson = ensureProjectPackageJson(input.projectDir, name);
+
+  return {
+    name,
+    projectDir: input.projectDir,
+    configPath: input.configPath,
+    envPath,
+    envExamplePath,
+    gitignorePath: gitignore.path,
+    packageJsonPath: packageJson.path,
+    created: {
+      config: wroteConfig,
+      env: env.created,
+      envExample: wroteEnvExample,
+      gitignore: gitignore.created,
+      packageJson: packageJson.created,
+    },
+    updated: {
+      envApiKey: env.updated,
+      gitignore: gitignore.updated,
+      packageJson: packageJson.updated,
+      sdkDependency: packageJson.sdkDependencyChanged,
+    },
+  };
+}
+
+export function normalizeMachineName(value: string): string {
+  const name = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!name) {
+    throw new Error("Project name is required.");
+  }
+  return name;
+}
+
+export function starterConfig(name: string): string {
+  const workflowName = JSON.stringify(normalizeMachineName(name));
+
+  return `import { defineConfig, sequence } from "@rigkit/sdk";
+import { freestyle, VmBaseImage, VmSpec } from "@rigkit/provider-freestyle";
+
+const vmIdleTimeoutSeconds = 3600;
+const vmSpec = new VmSpec()
+  .baseImage(new VmBaseImage("FROM node:22"))
+  .idleTimeoutSeconds(vmIdleTimeoutSeconds);
+
+const freestyleProvider = freestyle.provider();
+
+const dev = sequence(${workflowName})
+  .step("verify-node-22", async ({ providers }) => {
+    console.log("creating verification vm");
+    const { vm, vmId } = await providers.freestyle.client.vms.create({
+      spec: vmSpec,
+      logger: console.log,
+    });
+    try {
+      const result = await vm.exec("node --version");
+      if ((result.statusCode ?? 0) !== 0 || !result.stdout.trim().startsWith("v22.")) {
+        throw new Error(\`Expected Node.js v22, got: \${result.stdout}\${result.stderr}\`);
+      }
+      const snapshot = await vm.snapshot();
+      return { ctx: { snapshotId: snapshot.snapshotId } };
+    } finally {
+      await providers.freestyle.client.vms.delete({ vmId });
+    }
+  })
+  .workspace({
+    create: async ({ workflow, providers }) => {
+      console.log("booting workspace vm");
+      const { vmId } = await providers.freestyle.client.vms.create({
+        snapshotId: workflow.ctx.snapshotId,
+        idleTimeoutSeconds: vmIdleTimeoutSeconds,
+        logger: console.log,
+      });
+      return {
+        vmId,
+      };
+    },
+    remove: async ({ providers, workspace }) => {
+      await providers.freestyle.client.vms.delete({ vmId: workspace.ctx.vmId });
+    },
+  });
+
+export default defineConfig({
+  providers: {
+    freestyle: freestyleProvider,
+  },
+  workflows: {
+    dev,
+  },
+});
+`;
+}
+
+function writeEnvFile(path: string, apiKey: string): { created: boolean; updated: boolean } {
+  const created = !existsSync(path);
+  const existing = created ? "" : readFileSync(path, "utf8");
+  const lines = existing ? existing.split(/\r?\n/) : [];
+  const nextLine = `FREESTYLE_API_KEY=${apiKey}`;
+  let found = false;
+  let updated = created;
+
+  const next = lines.map((line) => {
+    if (!line.startsWith("FREESTYLE_API_KEY=")) return line;
+    found = true;
+    if (line === nextLine) return line;
+    updated = true;
+    return nextLine;
+  });
+
+  if (!found) {
+    if (next.length > 0 && next[next.length - 1] !== "") next.push("");
+    next.push(nextLine);
+    updated = true;
+  }
+
+  if (updated) {
+    writeFileSync(path, `${next.join("\n").replace(/\n+$/, "")}\n`);
+  }
+
+  return { created, updated };
+}
+
+function ensureGitignore(projectDir: string): { path: string; created: boolean; updated: boolean } {
+  const path = join(projectDir, ".gitignore");
+  const created = !existsSync(path);
+  const existing = created ? "" : readFileSync(path, "utf8");
+  const entries = existing.split(/\r?\n/).filter(Boolean);
+  let updated = false;
+
+  for (const entry of [".env", ".rigkit/"]) {
+    if (!entries.includes(entry)) {
+      entries.push(entry);
+      updated = true;
+    }
+  }
+
+  if (created || updated) {
+    writeFileSync(path, `${entries.join("\n")}\n`);
+  }
+
+  return { path, created, updated: created || updated };
+}
+
+function ensureProjectPackageJson(
+  projectDir: string,
+  name: string,
+): { path: string; created: boolean; updated: boolean; sdkDependencyChanged: boolean } {
+  const path = join(projectDir, "package.json");
+  const created = !existsSync(path);
+  const pkg = created
+    ? {
+        name,
+        private: true,
+        type: "module",
+        scripts: {},
+      }
+    : JSON.parse(readFileSync(path, "utf8")) as Record<string, any>;
+
+  let updated = created;
+
+  if (!isRecord(pkg.scripts)) {
+    pkg.scripts = {};
+    updated = true;
+  }
+
+  const scripts = pkg.scripts as Record<string, string>;
+  for (const [key, value] of Object.entries({ plan: "rig plan", apply: "rig apply" })) {
+    if (scripts[key] !== value) {
+      scripts[key] = value;
+      updated = true;
+    }
+  }
+  pkg.scripts = sortObject(scripts);
+
+  const devDependencies = isRecord(pkg.devDependencies) ? pkg.devDependencies : {};
+  const sdkDependencyChanged =
+    devDependencies[PROJECT_PACKAGE_NAME] !== RIGKIT_CLI_VERSION ||
+    devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME] !== RIGKIT_CLI_VERSION ||
+    devDependencies[FREESTYLE_SDK_PACKAGE_NAME] !== FREESTYLE_SDK_PACKAGE_VERSION;
+  if (sdkDependencyChanged) {
+    delete devDependencies["@rigkit/runtime"];
+    devDependencies[PROJECT_PACKAGE_NAME] = RIGKIT_CLI_VERSION;
+    devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME] = RIGKIT_CLI_VERSION;
+    devDependencies[FREESTYLE_SDK_PACKAGE_NAME] = FREESTYLE_SDK_PACKAGE_VERSION;
+    updated = true;
+  }
+  pkg.devDependencies = sortObject(devDependencies);
+
+  if (created || updated) {
+    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+
+  return { path, created, updated, sdkDependencyChanged };
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function sortObject<T>(value: Record<string, T>): Record<string, T> {
+  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)));
+}

package/src/interaction.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { createLocalInteractionPresenter } from "./interaction.ts";
+
+describe("local interaction presenter", () => {
+  test("presents provider-owned URLs without waiting for completion", async () => {
+    const previousNoBrowser = process.env.RIGKIT_NO_BROWSER;
+    process.env.RIGKIT_NO_BROWSER = "1";
+
+    try {
+      const presenter = createLocalInteractionPresenter();
+      await presenter({
+        id: "interaction-1",
+        nodePath: "login",
+        title: "GitHub auth",
+        url: "http://127.0.0.1:1234/?token=test",
+        instructions: "Authenticate GitHub inside the VM.",
+      });
+
+      expect(true).toBe(true);
+    } finally {
+      if (previousNoBrowser === undefined) {
+        delete process.env.RIGKIT_NO_BROWSER;
+      } else {
+        process.env.RIGKIT_NO_BROWSER = previousNoBrowser;
+      }
+    }
+  });
+});

package/src/interaction.ts

@@ -0,0 +1,33 @@
+import type { InteractionPresenter } from "@rigkit/engine";
+
+export function createLocalInteractionPresenter(): InteractionPresenter {
+  return async (request) => {
+    console.error(`\nInteractive task: ${request.title}`);
+    if (request.instructions) console.error(request.instructions);
+    console.error(`Open ${request.url}`);
+
+    openExternalTarget(request.url);
+  };
+}
+
+export function openExternalTarget(url: string): void {
+  if (process.env.RIGKIT_NO_BROWSER === "1") return;
+
+  const command =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", "", url]
+        : ["xdg-open", url];
+
+  try {
+    const proc = Bun.spawn(command, {
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    proc.exited.catch(() => {});
+  } catch {
+    // The engine also emits the URL, so failed auto-open still leaves a manual path.
+  }
+}

package/src/project.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverProjectConfigs, resolveConfigPaths } from "./project.ts";
+
+describe("CLI project resolution", () => {
+  test("resolves -chdir to that directory's rig.config.ts", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-"));
+    mkdirSync(join(cwd, "example"));
+    writeFileSync(join(cwd, "example", "rig.config.ts"), "export default {}\n");
+    const paths = resolveConfigPaths({ cwd, chdir: "example" });
+
+    expect(paths.projectDir).toBe(join(cwd, "example"));
+    expect(paths.configPath).toBe(join(cwd, "example", "rig.config.ts"));
+  });
+
+  test("resolves -config project root from the config dirname", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-"));
+    const paths = resolveConfigPaths({ cwd, config: "machines/platform.ts" });
+
+    expect(paths.projectDir).toBe(join(cwd, "machines"));
+    expect(paths.configPath).toBe(join(cwd, "machines", "platform.ts"));
+  });
+
+  test("searches upward from cwd for the nearest config", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-"));
+    mkdirSync(join(cwd, "project", "nested"), { recursive: true });
+    writeFileSync(join(cwd, "project", "rig.config.ts"), "export default {}\n");
+
+    const paths = resolveConfigPaths({ cwd: join(cwd, "project", "nested") });
+
+    expect(paths.projectDir).toBe(join(cwd, "project"));
+    expect(paths.configPath).toBe(join(cwd, "project", "rig.config.ts"));
+  });
+
+  test("reports named configs when the default config is missing", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-"));
+    writeFileSync(join(cwd, "api.rig.config.ts"), "export default {}\n");
+    writeFileSync(join(cwd, "web.rig.config.ts"), "export default {}\n");
+
+    expect(() => resolveConfigPaths({ cwd })).toThrow(
+      /Found named Rigkit configs[\s\S]*api\.rig\.config\.ts[\s\S]*web\.rig\.config\.ts[\s\S]*rig -chdir=\. -config=api\.rig\.config\.ts <command>/,
+    );
+  });
+
+  test("discovers projects downward without entering dependency directories", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-"));
+    mkdirSync(join(cwd, "api"), { recursive: true });
+    mkdirSync(join(cwd, "node_modules", "ignored"), { recursive: true });
+    writeFileSync(join(cwd, "api", "rig.config.ts"), "export default {}\n");
+    writeFileSync(join(cwd, "node_modules", "ignored", "rig.config.ts"), "export default {}\n");
+
+    const projects = discoverProjectConfigs({ cwd });
+
+    expect(projects).toEqual([{
+      projectDir: join(cwd, "api"),
+      configPath: join(cwd, "api", "rig.config.ts"),
+    }]);
+  });
+
+  test("discovers named configs downward", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-"));
+    mkdirSync(join(cwd, "global-fragments"), { recursive: true });
+    writeFileSync(join(cwd, "global-fragments", "api.rig.config.ts"), "export default {}\n");
+    writeFileSync(join(cwd, "global-fragments", "web.rig.config.ts"), "export default {}\n");
+
+    const projects = discoverProjectConfigs({ cwd });
+
+    expect(projects).toEqual([
+      {
+        projectDir: join(cwd, "global-fragments"),
+        configPath: join(cwd, "global-fragments", "api.rig.config.ts"),
+      },
+      {
+        projectDir: join(cwd, "global-fragments"),
+        configPath: join(cwd, "global-fragments", "web.rig.config.ts"),
+      },
+    ]);
+  });
+});

package/src/project.ts

@@ -0,0 +1,184 @@
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+
+export const DEFAULT_CONFIG_FILE = "rig.config.ts";
+export const PROJECT_PACKAGE_NAME = "@rigkit/sdk";
+export const FREESTYLE_PROVIDER_PACKAGE_NAME = "@rigkit/provider-freestyle";
+export const FREESTYLE_SDK_PACKAGE_NAME = "freestyle";
+export const FREESTYLE_SDK_PACKAGE_VERSION = "^0.1.51";
+
+export type ConfigPathOptions = {
+  chdir?: string;
+  config?: string;
+  cwd?: string;
+};
+
+export type ResolvedConfigPaths = {
+  projectDir: string;
+  configPath: string;
+};
+
+export type DiscoveredProject = ResolvedConfigPaths;
+
+export function resolveConfigPaths(options: ConfigPathOptions): ResolvedConfigPaths {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const workingDir = options.chdir ? resolve(cwd, options.chdir) : cwd;
+  if (options.config) {
+    const configPath = resolve(workingDir, options.config);
+    return {
+      projectDir: dirname(configPath),
+      configPath,
+    };
+  }
+
+  const projectDir = options.chdir ? workingDir : findNearestProjectDir(workingDir);
+  const configPath = join(projectDir, DEFAULT_CONFIG_FILE);
+
+  if (!existsSync(configPath)) {
+    throw new Error(formatConfigNotFoundAt(configPath, {
+      commandCwd: cwd,
+      hint: namedRigConfigFilesHint(projectDir),
+    }));
+  }
+
+  return {
+    projectDir,
+    configPath,
+  };
+}
+
+export function discoverProjectConfigs(options: ConfigPathOptions = {}): DiscoveredProject[] {
+  if (options.config) return [resolveConfigPaths(options)];
+
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const root = resolve(cwd, options.chdir ?? ".");
+  const projects: DiscoveredProject[] = [];
+  visitProjectDirs(root, projects);
+  return projects.sort((left, right) => left.configPath.localeCompare(right.configPath));
+}
+
+function findNearestProjectDir(start: string): string {
+  let current = start;
+  let hint: ConfigFilesHint | undefined;
+  for (;;) {
+    if (existsSync(join(current, DEFAULT_CONFIG_FILE))) return current;
+    hint ??= namedRigConfigFilesHint(current);
+    const parent = dirname(current);
+    if (parent === current) {
+      throw new Error(formatConfigNotFoundFrom(start, { commandCwd: start, hint }));
+    }
+    current = parent;
+  }
+}
+
+function visitProjectDirs(dir: string, projects: DiscoveredProject[]): void {
+  const configFiles = rigConfigFilesInDir(dir);
+  if (configFiles.length > 0) {
+    for (const configFile of configFiles) {
+      projects.push({ projectDir: dir, configPath: join(dir, configFile) });
+    }
+    return;
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (shouldSkipDiscoveryDir(entry.name)) continue;
+    visitProjectDirs(join(dir, entry.name), projects);
+  }
+}
+
+function shouldSkipDiscoveryDir(name: string): boolean {
+  return name === ".git" ||
+    name === ".rigkit" ||
+    name === "node_modules" ||
+    name === "dist" ||
+    name === "build";
+}
+
+export function rigConfigFilesInDir(dir: string): string[] {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isFile() && isRigConfigFileName(entry.name))
+    .map((entry) => entry.name)
+    .sort((left, right) => {
+      if (left === DEFAULT_CONFIG_FILE) return -1;
+      if (right === DEFAULT_CONFIG_FILE) return 1;
+      return left.localeCompare(right);
+    });
+}
+
+export function isRigConfigFileName(name: string): boolean {
+  return name === DEFAULT_CONFIG_FILE || name.endsWith(".rig.config.ts");
+}
+
+type ConfigFilesHint = {
+  dir: string;
+  files: string[];
+};
+
+function namedRigConfigFilesHint(dir: string): ConfigFilesHint | undefined {
+  const files = rigConfigFilesInDir(dir).filter((file) => file !== DEFAULT_CONFIG_FILE);
+  return files.length > 0 ? { dir, files } : undefined;
+}
+
+function formatConfigNotFoundAt(
+  configPath: string,
+  options: { commandCwd: string; hint?: ConfigFilesHint },
+): string {
+  return appendConfigFilesHint(
+    `No Rigkit config found at ${configPath}.`,
+    options,
+  );
+}
+
+function formatConfigNotFoundFrom(
+  start: string,
+  options: { commandCwd: string; hint?: ConfigFilesHint },
+): string {
+  return appendConfigFilesHint(
+    `No Rigkit config found from ${start} upward.`,
+    options,
+  );
+}
+
+function appendConfigFilesHint(
+  message: string,
+  options: { commandCwd: string; hint?: ConfigFilesHint },
+): string {
+  const hint = options.hint;
+  if (!hint) return `${message} Run "rig init" or pass -config=<file>.`;
+
+  const configFile = hint.files[0]!;
+  const configPath = displayPath(options.commandCwd, join(hint.dir, configFile));
+  const projectDir = displayPath(options.commandCwd, hint.dir);
+
+  return [
+    message,
+    `Found named Rigkit configs in ${hint.dir}:`,
+    ...hint.files.map((file) => `- ${file}`),
+    "",
+    "Choose one explicitly:",
+    `  rig -config=${configPath} <command>`,
+    `  rig -chdir=${projectDir} -config=${configFile} <command>`,
+  ].join("\n");
+}
+
+function displayPath(from: string, path: string): string {
+  const relativePath = relative(from, path);
+  if (!relativePath) return ".";
+  if (!relativePath.startsWith("..") && !isAbsolute(relativePath)) return relativePath;
+  return path;
+}