@rigkit/cli 0.2.9 → 0.2.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rigkit contributors
+
+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

@@ -7,7 +7,7 @@ npm i -g @rigkit/cli
 rig init
 rig plan
 rig ls
-rig -chdir=examples/smoke plan
+rig --chdir=examples/smoke plan
 ```
 
 `rig init` asks for a project name, Freestyle API key, and package manager. It creates a project folder containing a workflow-based `rig.config.ts`, `.env`, `.env.example`, `package.json`, and local ignore rules.
@@ -23,12 +23,15 @@ defined by the project run as `rig run <workspace> <operation>`, for example
 
 `rig ls` lists workspaces for the selected project. `rig ls snapshots` lists cached snapshot runs, and `rig ls config` shows the resolved project paths.
 
-Use Terraform-style global context options before the command to select another
-project or config:
+Use global context options before the command to select another project or
+config:
 
 ```bash
-rig -chdir=examples/smoke plan
-rig -chdir=examples/global-fragments -config=api.rig.config.ts apply
+rig --chdir=examples/smoke plan
+rig --chdir=examples/global-fragments --config=api.rig.config.ts apply
 ```
 
+Legacy Terraform-style aliases such as `-chdir=...` and `-config=...` are still
+accepted.
+
 Projects should install matching `@rigkit/sdk` versions locally.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@rigkit/cli",
-  "version": "0.2.9",
+  "version": "0.2.11",
+  "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
@@ -22,9 +23,9 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "inquirer": "^13.4.3",
-    "@rigkit/engine": "0.2.9",
-    "@rigkit/provider-cmux": "0.2.9",
-    "@rigkit/runtime-client": "0.2.9"
+    "@rigkit/runtime-client": "0.2.11",
+    "@rigkit/engine": "0.2.11",
+    "@rigkit/provider-cmux": "0.2.11"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cli.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createFileProviderHostStorage } from "@rigkit/engine";
 import { projectIdFor, runtimeFingerprintFor, runtimePaths, SUPPORTED_RUNTIME_API_VERSION } from "@rigkit/runtime-client";
 import { RIGKIT_CLI_VERSION } from "./version.ts";
 
@@ -27,6 +28,7 @@ describe("CLI entrypoint", () => {
     expect(rootHelp.stdout).toContain("rm          Remove a workspace");
     expect(rootHelp.stdout).toContain("run         Run a workspace operation");
     expect(rootHelp.stdout).toContain("cache       Inspect and clear Rigkit cache");
+    expect(rootHelp.stdout).toContain("providers   Manage provider-owned local state");
 
     const version = await runCli(["version"]);
     expect(version.exitCode).toBe(0);
@@ -41,6 +43,77 @@ describe("CLI entrypoint", () => {
     expect(help.stdout).toContain("rm          Remove a workspace");
     expect(help.stdout).toContain("run         Run a workspace operation");
     expect(help.stdout).toContain("cache       Inspect and clear Rigkit cache");
+    expect(help.stdout).toContain("providers   Manage provider-owned local state");
+  });
+
+  test("prints an update notice when latest metadata is newer", async () => {
+    const rigkitHome = mkdtempSync(join(tmpdir(), "rigkit-cli-update-"));
+    const latestVersion = nextPatchVersion(RIGKIT_CLI_VERSION);
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch() {
+        return Response.json({
+          version: latestVersion,
+          installerUrl: "https://www.rigkit.dev/install",
+        });
+      },
+    });
+
+    try {
+      const result = await runCli(["doctor", "--cli"], {
+        env: {
+          RIGKIT_HOME: rigkitHome,
+          RIGKIT_UPDATE_CHECK: "1",
+          RIGKIT_UPDATE_TIMEOUT_MS: "2000",
+          RIGKIT_UPDATE_URL: `http://127.0.0.1:${server.port}/latest.json`,
+        },
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain(RIGKIT_CLI_VERSION);
+      expect(result.stderr).toContain(`rig ${latestVersion} is available`);
+      expect(result.stderr).toContain("update with: curl -fsSL https://www.rigkit.dev/install | sh");
+    } finally {
+      server.stop(true);
+      rmSync(rigkitHome, { recursive: true, force: true });
+    }
+  });
+
+  test("does not print update notices for JSON output", async () => {
+    const rigkitHome = mkdtempSync(join(tmpdir(), "rigkit-cli-update-json-"));
+    let requests = 0;
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch() {
+        requests += 1;
+        return Response.json({
+          version: nextPatchVersion(RIGKIT_CLI_VERSION),
+          installerUrl: "https://www.rigkit.dev/install",
+        });
+      },
+    });
+
+    try {
+      const result = await runCli(["doctor", "--cli", "--json"], {
+        env: {
+          RIGKIT_HOME: rigkitHome,
+          RIGKIT_UPDATE_CHECK: "1",
+          RIGKIT_UPDATE_URL: `http://127.0.0.1:${server.port}/latest.json`,
+        },
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        cliVersion: RIGKIT_CLI_VERSION,
+      });
+      expect(requests).toBe(0);
+    } finally {
+      server.stop(true);
+      rmSync(rigkitHome, { recursive: true, force: true });
+    }
   });
 
   test("rejects operation shorthand at the root", async () => {
@@ -95,7 +168,28 @@ describe("CLI entrypoint", () => {
       expect(result.stderr).toContain("Found named Rigkit configs");
       expect(result.stderr).toContain("api.rig.config.ts");
       expect(result.stderr).toContain("web.rig.config.ts");
-      expect(result.stderr).toContain("rig -chdir=. -config=api.rig.config.ts <command>");
+      expect(result.stderr).toContain("rig --chdir=. --config=api.rig.config.ts <command>");
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  test("accepts conventional double-dash global options", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-global-options-"));
+    mkdirSync(join(cwd, "api"));
+    writeFileSync(join(cwd, "api", "rig.config.ts"), "export default {}\n");
+
+    try {
+      const result = await runCli(["--chdir=api", "projects", "--json"], { cwd });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(JSON.parse(result.stdout)).toEqual({
+        projects: [{
+          projectDir: join(realpathSync(cwd), "api"),
+          configPath: join(realpathSync(cwd), "api", "rig.config.ts"),
+        }],
+      });
     } finally {
       rmSync(cwd, { recursive: true, force: true });
     }
@@ -124,6 +218,56 @@ describe("CLI entrypoint", () => {
     }
   });
 
+  test("clears Freestyle provider host storage without loading a project", async () => {
+    const storageRoot = mkdtempSync(join(tmpdir(), "rigkit-provider-storage-"));
+    const storage = createFileProviderHostStorage({ providerId: "freestyle", rootDir: storageRoot });
+    storage.set("stack-auth:test", { refreshToken: "refresh-token", updatedAt: 1 });
+    storage.set("identity:test", { token: "ssh-token" });
+
+    try {
+      const result = await runCli(["providers", "freestyle", "clear", "--json"], {
+        env: { RIGKIT_HOST_STORAGE_DIR: storageRoot },
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(JSON.parse(result.stdout)).toMatchObject({
+        ok: true,
+        providerId: "freestyle",
+        deleted: 2,
+        storageRoot,
+      });
+      expect(storage.entries()).toEqual([]);
+    } finally {
+      rmSync(storageRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("does not render a success marker when cache invalidation is a no-op", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-cli-cache-invalidate-"));
+
+    await withWorkspaceRuntime({ projectDir, cacheInvalidated: 0 }, async ({ env }) => {
+      const result = await runCli([`-chdir=${projectDir}`, "cache", "invalidate", "missing-task"], { env });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(result.stdout.trim()).toBe("no cache entries invalidated");
+      expect(result.stdout).not.toContain("✓");
+    });
+  });
+
+  test("preserves JSON output for zero cache invalidations", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-cli-cache-invalidate-json-"));
+
+    await withWorkspaceRuntime({ projectDir, cacheInvalidated: 0 }, async ({ env }) => {
+      const result = await runCli([`-chdir=${projectDir}`, "cache", "invalidate", "missing-task", "--json"], { env });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stderr).toBe("");
+      expect(JSON.parse(result.stdout)).toEqual({ ok: true, invalidated: 0 });
+    });
+  });
+
   test("lists workspaces from the project runtime", async () => {
     const projectDir = mkdtempSync(join(tmpdir(), "rigkit-cli-ls-"));
 
@@ -241,6 +385,7 @@ async function runCli(
     stderr: "pipe",
     env: {
       ...process.env,
+      RIGKIT_UPDATE_CHECK: "0",
       ...options.env,
       FORCE_COLOR: "0",
       NO_COLOR: "1",
@@ -255,8 +400,14 @@ async function runCli(
   return { exitCode, stdout, stderr };
 }
 
+function nextPatchVersion(version: string): string {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return "999.0.0";
+  return `${match[1]}.${match[2]}.${Number(match[3]) + 1}`;
+}
+
 async function withWorkspaceRuntime(
-  input: { projectDir: string },
+  input: { projectDir: string; cacheInvalidated?: number },
   run: (context: { env: Record<string, string> }) => Promise<void>,
 ): Promise<void> {
   const rigkitHome = mkdtempSync(join(tmpdir(), "rigkit-home-"));
@@ -306,6 +457,9 @@ async function withWorkspaceRuntime(
           }],
         });
       }
+      if (pathname === "/cache/invalidate") {
+        return runtimeJson({ ok: true, invalidated: input.cacheInvalidated ?? 1 });
+      }
       if (pathname === "/operations") {
         return runtimeJson({
           operations: [{

package/src/cli.ts

@@ -10,6 +10,8 @@ import {
   type RuntimeClient,
 } from "@rigkit/runtime-client";
 import {
+  createFileProviderHostStorage,
+  defaultProviderHostStorageDir,
   type DevMachineEvent,
   type WorkflowPlan,
   type SnapshotRecord,
@@ -25,6 +27,7 @@ import { initProject, normalizeMachineName, type InitProjectResult } from "./ini
 import { openExternalTarget } from "./interaction.ts";
 import { createRunPresenter, type RunPresenter } from "./run-presenter.ts";
 import { createRunLogger, type RunLogger } from "./run-logger.ts";
+import { maybePrintUpdateNotice } from "./update-check.ts";
 import {
   completeRig,
   formatCompletionItems,
@@ -161,6 +164,7 @@ const STATIC_COMMANDS = new Set([
   "run",
   "ls",
   "cache",
+  "providers",
   "projects",
   "doctor",
   "version",
@@ -204,22 +208,32 @@ async function runCli(argv: string[]): Promise<void> {
     .exitOverride()
     .argument("[command]")
     .addOption(new Option("--chdir <dir>", `Switch to a directory containing ${DEFAULT_CONFIG_FILE} before running the command`).hideHelp())
-    .addOption(new Option("--config <file>", "Config file to load, relative to -chdir when set").hideHelp())
+    .addOption(new Option("--config <file>", "Config file to load, relative to --chdir when set").hideHelp())
     .addOption(new Option("--state <file>", "Local runtime state database path").hideHelp())
     .addOption(new Option("--json", "Print machine-readable JSON where supported").hideHelp())
     .addHelpText("after", [
       "",
       "Global Options:",
-      "  -chdir=DIR    Switch to a directory containing rig.config.ts before running the command",
-      "  -config=FILE  Config file to load, relative to -chdir when set",
-      "  -state=FILE   Local runtime state database path",
-      "  -json         Print machine-readable JSON where supported",
+      "  --chdir <dir>     Switch to a directory containing rig.config.ts before running the command",
+      "  --config <file>   Config file to load, relative to --chdir when set",
+      "  --state <file>    Local runtime state database path",
+      "  --json            Print machine-readable JSON where supported",
+      "",
+      "Legacy single-dash global aliases such as -chdir=DIR are still accepted.",
     ].join("\n"))
     .action(async (command?: string) => {
       if (command) program.error(`unknown command '${command}'`);
       await runHelp(makeInvocation(rootOptions(program)));
     });
 
+  program.hook("postAction", async (_thisCommand, actionCommand) => {
+    await maybePrintUpdateNotice({
+      commandName: actionCommand.name(),
+      currentVersion: RIGKIT_CLI_VERSION,
+      json: commandWantsJson(program, actionCommand),
+    });
+  });
+
   program
     .command("init")
     .description("Initialize a Rigkit project")
@@ -351,6 +365,22 @@ async function runCli(argv: string[]): Promise<void> {
       });
     });
 
+  const providers = program
+    .command("providers")
+    .description("Manage provider-owned local state");
+
+  const freestyleProvider = providers
+    .command("freestyle")
+    .description("Manage Freestyle provider local state");
+
+  freestyleProvider
+    .command("clear")
+    .description("Clear Freestyle provider local auth and identity state")
+    .option("--json", "Print machine-readable JSON")
+    .action(async (options: { json?: boolean }) => {
+      await runProvidersFreestyleClear(makeInvocation(rootOptions(program), options.json));
+    });
+
   program
     .command("projects")
     .description("Discover Rigkit projects below the current directory")
@@ -408,6 +438,11 @@ function rootOptions(program: Command): GlobalOptions {
   };
 }
 
+function commandWantsJson(program: Command, actionCommand: Command): boolean {
+  const options = actionCommand.opts<{ json?: boolean }>();
+  return Boolean(rootOptions(program).json || options.json);
+}
+
 function parsePackageManagerOption(value: string | undefined): PackageManager | undefined {
   if (value === undefined) return undefined;
   if (isPackageManager(value)) return value;
@@ -560,7 +595,7 @@ function canPrompt(): boolean {
 function resolveInitProjectPaths(invocation: CliInvocation, name: string): { projectDir: string; configPath: string } {
   const options = invocation.global;
   if (options.config) {
-    throw new Error(`rig init does not support -config. Use -chdir to choose the parent directory.`);
+    throw new Error(`rig init does not support --config. Use --chdir to choose the parent directory.`);
   }
 
   const parentDir = resolve(process.cwd(), options.chdir ?? ".");
@@ -950,7 +985,7 @@ async function runDiscoveredProjectOperation(
   if (!options.all && projects.length > 1) {
     throw new Error([
       "Multiple Rigkit projects found.",
-      "Use `rig projects` to list candidates, pass -chdir or -config to select one, or pass --all to run every discovered project.",
+      "Use `rig projects` to list candidates, pass --chdir or --config to select one, or pass --all to run every discovered project.",
       ...projects.map((project) => `- ${project.configPath}`),
     ].join("\n"));
   }
@@ -1068,7 +1103,7 @@ async function runCacheClear(invocation: CliInvocation, options: CacheClearOptio
 
   if (options.global && options.all) {
     if (invocation.global.chdir || invocation.global.config || invocation.global.state) {
-      throw new Error(`rig cache clear --global --all cannot be combined with -chdir, -config, or -state`);
+      throw new Error(`rig cache clear --global --all cannot be combined with --chdir, --config, or --state`);
     }
     const fragmentRoot = join(defaultRigkitHome(), "fragments");
     rmSync(fragmentRoot, { recursive: true, force: true });
@@ -1090,6 +1125,32 @@ async function runCacheClear(invocation: CliInvocation, options: CacheClearOptio
   console.log(`Cleared ${result.deleted} cache ${result.deleted === 1 ? "entry" : "entries"}.`);
 }
 
+async function runProvidersFreestyleClear(invocation: CliInvocation): Promise<void> {
+  const providerId = "freestyle";
+  const storageRoot = defaultProviderHostStorageDir();
+  const storage = createFileProviderHostStorage({ providerId, rootDir: storageRoot });
+  const keys = storage.entries().map((entry) => entry.key);
+  for (const key of keys) storage.delete(key);
+
+  const result = {
+    ok: true,
+    providerId,
+    deleted: keys.length,
+    storageRoot,
+  };
+
+  if (wantsJson(invocation)) {
+    printJson(result);
+    return;
+  }
+
+  if (keys.length === 0) {
+    console.log("No Freestyle provider local state to clear.");
+    return;
+  }
+  console.log(`Cleared ${keys.length} Freestyle provider ${keys.length === 1 ? "entry" : "entries"}.`);
+}
+
 type CacheInvalidateOptions = {
   step?: string;
   all: boolean;
@@ -1144,6 +1205,10 @@ async function runCacheInvalidate(invocation: CliInvocation, options: CacheInval
     printJson(result);
     return;
   }
+  if (result.invalidated === 0) {
+    console.log(ui.dim("no cache entries invalidated"));
+    return;
+  }
   console.log(
     `${ui.ok(ui.sym.ok)} invalidated ${result.invalidated} cache ${result.invalidated === 1 ? "entry" : "entries"}`,
   );
@@ -1506,6 +1571,7 @@ async function runHelp(invocation: CliInvocation): Promise<void> {
         { name: "run", description: "Run a workspace operation" },
         { name: "ls", description: "List project workspaces" },
         { name: "cache", description: "Inspect and clear Rigkit cache" },
+        { name: "providers", description: "Manage provider-owned local state" },
         { name: "projects", description: "Discover Rigkit projects below the current directory" },
         { name: "doctor", description: "Show Rigkit runtime diagnostics" },
         { name: "version", description: "Show Rigkit CLI version" },
@@ -1517,7 +1583,7 @@ async function runHelp(invocation: CliInvocation): Promise<void> {
   const cmd = (name: string, description: string): string =>
     `  ${ui.bold(name.padEnd(10))}  ${description}`;
   const opt = (flag: string, description: string): string =>
-    `  ${ui.bold(flag.padEnd(12))}  ${description}`;
+    `  ${ui.bold(flag.padEnd(17))}  ${description}`;
 
   console.log([
     `${ui.bold("rig")} ${ui.dim(RIGKIT_CLI_VERSION)}`,
@@ -1535,16 +1601,19 @@ async function runHelp(invocation: CliInvocation): Promise<void> {
     cmd("run",        "Run a workspace operation"),
     cmd("ls",         "List project workspaces"),
     cmd("cache",      "Inspect and clear Rigkit cache"),
+    cmd("providers",  "Manage provider-owned local state"),
     cmd("projects",   "Discover Rigkit projects below the current directory"),
     cmd("doctor",     "Show Rigkit runtime diagnostics"),
     cmd("version",    "Show Rigkit CLI version"),
     cmd("completion", "Generate shell completion script"),
     "",
     ui.dim("Options:"),
-    opt("-chdir=DIR",   "Switch to a directory containing rig.config.ts before running the command"),
-    opt("-config=FILE", "Config file to load, relative to -chdir when set"),
-    opt("-state=FILE",  "Local runtime state database path"),
-    opt("-json",        "Print machine-readable JSON where supported"),
+    opt("--chdir <dir>",   "Switch to a directory containing rig.config.ts before running the command"),
+    opt("--config <file>", "Config file to load, relative to --chdir when set"),
+    opt("--state <file>",  "Local runtime state database path"),
+    opt("--json",          "Print machine-readable JSON where supported"),
+    "",
+    ui.dim("Legacy single-dash global aliases such as -chdir=DIR are still accepted."),
   ].join("\n"));
 }
 
@@ -2098,8 +2167,12 @@ async function promptHostSelect(params: unknown): Promise<string> {
       .filter((item) => item.value)
     : [];
   if (options.length === 0) throw new Error(`Host select prompt has no options`);
-  const defaultValue = stringField(params, "defaultValue") ?? options[0]!.value;
-  if (!canPrompt()) return defaultValue;
+  const configuredDefaultValue = stringField(params, "defaultValue");
+  const defaultValue = configuredDefaultValue ?? options[0]!.value;
+  if (!canPrompt()) {
+    if (configuredDefaultValue !== undefined) return configuredDefaultValue;
+    throw new Error(`Host select prompt requires an interactive terminal: ${message}`);
+  }
   const answers = await inquirer.prompt<{ value: string }>([{
     type: "select",
     name: "value",
@@ -2283,6 +2356,16 @@ function printPlan(plan: WorkflowPlan): void {
   console.log(`${ui.bold(plan.workflow)}  ${ui.dim(`${plan.cachedNodeCount}/${plan.nodeCount} cached`)}`);
   console.log("");
 
+  if (plan.providerChecks?.length) {
+    const rows = plan.providerChecks.map((check) => [
+      { text: check.label || check.providerName, style: ui.dim },
+      { text: check.status, style: providerCheckStatusStyle(check.status) },
+      { text: providerCheckValue(check), style: check.status === "ok" ? ((value: string) => value) : ui.warn },
+    ]);
+    console.log(ui.columns(["provider check", "status", "current"], rows));
+    console.log("");
+  }
+
   const rows = plan.nodes.map((node) => [
     { text: String(node.index + 1), style: ui.dim },
     { text: node.status, style: planStatusStyle(node.status) },
@@ -2292,6 +2375,18 @@ function printPlan(plan: WorkflowPlan): void {
   console.log(ui.columns(["#", "status", "node", "reason"], rows));
 }
 
+function providerCheckValue(check: NonNullable<WorkflowPlan["providerChecks"]>[number]): string {
+  if (check.status === "required" && check.message) return check.message;
+  if (check.detail && check.detail !== check.value && !check.value.includes(check.detail)) {
+    return `${check.value} ${ui.dim(check.detail)}`;
+  }
+  return check.value;
+}
+
+function providerCheckStatusStyle(status: string): (text: string) => string {
+  return status === "ok" ? ui.ok : ui.warn;
+}
+
 function planStatusStyle(status: string): (text: string) => string {
   switch (status) {
     case "cached":