@stigmer/cli 3.0.8

package/src/backend.ts

@@ -0,0 +1,15 @@
+// Composition root for the backend client.
+//
+// `createBackendClient` (the client module) is deliberately auth-agnostic; this
+// is the one place that injects the refreshing token provider so every command
+// gets silent token refresh without the client module depending on auth. Keep
+// this as the single entry point commands use to reach the backend.
+
+import { createRefreshingTokenProvider } from "./auth/token.js";
+import { type BackendClient, createBackendClient } from "./client/index.js";
+import { type Config, load } from "./config/index.js";
+
+/** Build a backend client for the given (or on-disk) config, with auto-refresh. */
+export function connectBackend(config: Config = load()): BackendClient {
+  return createBackendClient({ config, getAccessToken: createRefreshingTokenProvider(config) });
+}

package/src/cli/stigmer.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Entry point for the `stigmer` CLI. Builds the commander program and runs it.
+//
+// Every command-action failure (and any parse-time rejection) funnels through
+// clierr.handle, the single exit point that maps the error to a stable exit
+// code and prints a user-facing message to stderr.
+
+import { handle } from "../errors/index.js";
+import { buildProgram } from "../program.js";
+
+async function main(): Promise<void> {
+  const program = buildProgram();
+  await program.parseAsync(process.argv);
+}
+
+main().catch(handle);

package/src/client/client.test.ts

@@ -0,0 +1,46 @@
+import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { afterEach, describe, expect, it } from "vitest";
+import type { Config } from "../config/index.js";
+import { createBackendClient } from "./client.js";
+
+function cloud(token?: string): Config {
+  return { backend: { type: "cloud", cloud: { endpoint: "api.stigmer.ai:443", token } } };
+}
+
+afterEach(() => {
+  delete process.env.STIGMER_API_KEY;
+  delete process.env.STIGMER_SERVER_ADDRESS;
+});
+
+describe("createBackendClient — endpoint normalization", () => {
+  it("normalizes the cloud endpoint to an https base URL", () => {
+    const client = createBackendClient({ config: cloud("t") });
+    expect(client.stigmer.baseUrl).toBe("https://api.stigmer.ai:443");
+  });
+
+  it("normalizes the local endpoint to a plaintext base URL", () => {
+    const client = createBackendClient({ config: { backend: { type: "local" } } });
+    expect(client.stigmer.baseUrl).toBe("http://localhost:7234");
+  });
+});
+
+describe("createBackendClient — token precedence", () => {
+  it("prefers STIGMER_API_KEY over the config token", async () => {
+    process.env.STIGMER_API_KEY = "env-key";
+    const client = createBackendClient({ config: cloud("config-token") });
+    expect(await client.stigmer.getAuthCredential()).toBe("env-key");
+  });
+
+  it("falls back to the config token", async () => {
+    const client = createBackendClient({ config: cloud("config-token") });
+    expect(await client.stigmer.getAuthCredential()).toBe("config-token");
+  });
+});
+
+describe("createBackendClient — controller factory", () => {
+  it("creates a raw Connect client for a service controller", () => {
+    const client = createBackendClient({ config: cloud("t") });
+    const platform = client.controller(PlatformQueryController);
+    expect(typeof platform.getServerInfo).toBe("function");
+  });
+});

package/src/client/client.ts

@@ -0,0 +1,84 @@
+// Backend client façade.
+//
+// Builds a single transport (via the SDK's createNodeTransport + the Go-parity
+// normalizeEndpoint) and exposes:
+//   - `stigmer`: the high-level typed client, used by read verbs.
+//   - `transport` + `controller(service)`: the raw Connect layer, so write
+//     flows (a later wave) can drive generated controllers directly for full
+//     YAML->proto fidelity rather than the high-level client's lossy inputs.
+//
+// This module holds no business logic: backend selection, token precedence, and
+// endpoint shape are delegated to the config layer; org resolution and verb
+// dispatch live with the commands and the registry.
+
+import type { DescService } from "@bufbuild/protobuf";
+import { type Client, createClient, type Transport } from "@connectrpc/connect";
+import { Stigmer, type TokenProvider } from "@stigmer/sdk";
+import { createNodeTransport, normalizeEndpoint } from "@stigmer/sdk/node";
+import { type Config, load, resolveEndpoint, resolveToken } from "../config/index.js";
+import { CliExitError, ExitCode } from "../errors/index.js";
+
+/** The composed backend client returned by {@link createBackendClient}. */
+export interface BackendClient {
+  /** High-level typed client for reads (and high-level writes). */
+  readonly stigmer: Stigmer;
+  /** The shared underlying transport. */
+  readonly transport: Transport;
+  /** The config this client was built from (for org resolution by callers). */
+  readonly config: Config;
+  /** Create a raw Connect client for a generated service controller. */
+  controller<Desc extends DescService>(service: Desc): Client<Desc>;
+  /** Probe the server (unauthenticated) to fail fast on connectivity issues. */
+  connect(timeoutMs?: number): Promise<void>;
+}
+
+export interface BackendClientOptions {
+  /** Config to use; defaults to the on-disk config (or standalone default). */
+  readonly config?: Config;
+  /** Token-provider override (the auth module supplies a refreshing provider). */
+  readonly getAccessToken?: TokenProvider;
+}
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+
+export function createBackendClient(options: BackendClientOptions = {}): BackendClient {
+  const config = options.config ?? load();
+  const baseUrl = normalizeEndpoint(resolveEndpoint(config));
+
+  // Dynamic provider: re-reads env/config on every request so a token refreshed
+  // mid-session is picked up. STIGMER_API_KEY > config token precedence lives in
+  // resolveToken; a caller-supplied provider (refresh-aware) takes over entirely.
+  const tokenProvider: TokenProvider = options.getAccessToken ?? (() => resolveToken(config) || null);
+
+  const transport = createNodeTransport({ baseUrl, getAccessToken: tokenProvider });
+  const stigmer = new Stigmer({ baseUrl, getAccessToken: tokenProvider, customTransport: transport });
+
+  return {
+    stigmer,
+    transport,
+    config,
+    controller(service) {
+      return createClient(service, transport);
+    },
+    async connect(timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS) {
+      await withTimeout(stigmer.platform.getServerInfo(), timeoutMs);
+    },
+  };
+}
+
+// Soft timeout: races the RPC against a timer. It cannot cancel the underlying
+// request, but the CLI exits immediately after, so the dangling call is moot.
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new CliExitError("Timed out connecting to the Stigmer server", ExitCode.Connection)),
+      timeoutMs,
+    );
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,3 @@
+// Public surface of the CLI backend-client module.
+
+export { type BackendClient, type BackendClientOptions, createBackendClient } from "./client.js";

package/src/commands/agent-exec-flags.ts

@@ -0,0 +1,75 @@
+// The agent-execution flag set shared by `run` and `draft` (Go's
+// registerAgentExecFlags). Centralized so both commands stay in lockstep — a new
+// execution flag is added here once and both surfaces pick it up.
+
+import type { Command } from "commander";
+import type { AgentExecFlags, RunMode } from "../resources/run/prepare.js";
+
+/** Commander collector for repeatable string options. */
+export const collect = (value: string, previous: string[]): string[] => [...previous, value];
+
+/** The parsed shape of the shared agent-exec options on a commander command. */
+export interface AgentExecOptions {
+  message?: string;
+  attach: string[];
+  approveDefault?: string;
+  verbose?: boolean;
+  detach?: boolean;
+  workspace: string[];
+  branch?: string;
+  commit?: string;
+  env: string[];
+  envFile: string[];
+  secret: string[];
+  secretFile: string[];
+  model?: string;
+  autoApprove?: boolean;
+  mode?: string;
+}
+
+/**
+ * Register the shared agent-exec options on `command`. `requireMessage` marks
+ * `-m/--message` as required (draft requires a prompt; run does not).
+ */
+export function addAgentExecFlags(command: Command, requireMessage = false): Command {
+  const messageDesc = "initial message/prompt for execution";
+  if (requireMessage) command.requiredOption("-m, --message <text>", messageDesc);
+  else command.option("-m, --message <text>", messageDesc);
+
+  return command
+    .option("--attach <path>", "file or directory to attach as input (repeatable)", collect, [])
+    .option("--approve-default <action>", "auto-resolve approvals in headless mode (approve, skip, reject, approve-all)")
+    .option("-v, --verbose", "show execution IDs and phase transitions")
+    .option("--detach", "start execution and return immediately without streaming")
+    .option("-w, --workspace <source>", "workspace: HTTPS git URL or local path (repeatable)", collect, [])
+    .option("--branch <name>", "git branch to clone (single git workspace only)")
+    .option("--commit <sha>", "git commit SHA to checkout (single git workspace only)")
+    .option("--env <kv>", "runtime env var KEY=VALUE (repeatable)", collect, [])
+    .option("--env-file <path>", "load env from file (repeatable, later override earlier)", collect, [])
+    .option("--secret <kv>", "secret env var KEY=VALUE (repeatable, encrypted)", collect, [])
+    .option("--secret-file <path>", "load secrets from file (repeatable, encrypted)", collect, [])
+    .option("--model <model>", "LLM model to use (e.g. claude-sonnet-4-6)")
+    .option("--auto-approve", "automatically approve all tool executions")
+    .option("--mode <mode>", 'interaction mode: "agent" (default) or "plan" (read-only)');
+}
+
+/** Map parsed commander options onto the shared {@link AgentExecFlags} shape. */
+export function toAgentExecFlags(options: AgentExecOptions): AgentExecFlags {
+  return {
+    message: options.message ?? "",
+    attach: options.attach,
+    approveDefault: options.approveDefault ?? "",
+    verbose: options.verbose === true,
+    detach: options.detach === true,
+    workspace: options.workspace,
+    branch: options.branch ?? "",
+    commit: options.commit ?? "",
+    env: options.env,
+    envFile: options.envFile,
+    secret: options.secret,
+    secretFile: options.secretFile,
+    model: options.model ?? "",
+    autoApprove: options.autoApprove === true,
+    mode: (options.mode ?? "") as RunMode,
+  };
+}

package/src/commands/apikey/duration.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { UsageError } from "../../errors/index.js";
+import { parseExpiration } from "./duration.js";
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const YEAR = 365 * DAY;
+
+describe("parseExpiration", () => {
+  it.each([
+    ["30m", 30 * MINUTE],
+    ["6h", 6 * HOUR],
+    ["30d", 30 * DAY],
+    ["1y", YEAR],
+  ])("parses %s", (input, expected) => {
+    expect(parseExpiration(input)).toBe(expected);
+  });
+
+  it.each(["", "d", "30x", "abc", "0d", "-5d", "1.5d"])("rejects %s as a usage error", (input) => {
+    expect(() => parseExpiration(input)).toThrow(UsageError);
+  });
+});

package/src/commands/apikey/duration.ts

@@ -0,0 +1,35 @@
+// Parse human expiration durations like "30d", "6h", "1y" into milliseconds.
+// Ported from the Go CLI's ParseExpirationDuration; invalid input is a usage
+// error (exit 2). Units: m (minutes), h (hours), d (days), y (years).
+
+import { UsageError } from "../../errors/index.js";
+
+const UNIT_MS: Record<string, number> = {
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  y: 365 * 24 * 60 * 60 * 1000,
+};
+
+export function parseExpiration(input: string): number {
+  if (input.length < 2) {
+    throw new UsageError(`invalid duration format: "${input}" (expected e.g. 30d, 6h, 1y)`);
+  }
+
+  const unit = input[input.length - 1];
+  const valueText = input.slice(0, -1);
+  const multiplier = UNIT_MS[unit];
+  if (multiplier === undefined) {
+    throw new UsageError(`invalid duration unit '${unit}' (valid: m, h, d, y)`);
+  }
+
+  if (!/^\d+$/.test(valueText)) {
+    throw new UsageError(`invalid duration value in "${input}"`);
+  }
+  const value = Number.parseInt(valueText, 10);
+  if (value <= 0) {
+    throw new UsageError(`duration must be positive, got ${value}`);
+  }
+
+  return value * multiplier;
+}

package/src/commands/apikey/index.ts

@@ -0,0 +1,133 @@
+// `stigmer apikey create|fingerprint` — manage API keys for programmatic access.
+//
+// API keys are the non-interactive alternative to browser OAuth, for CI/CD and
+// service accounts. The unified get/list/delete verbs cover the rest.
+
+import { createHash } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { type ApiKey, ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import { ApiKeyHashSchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/io_pb";
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveContextOrganization } from "../../config/index.js";
+import { type OutputFlags, type OutputFormat, renderProtoJson, renderProtoYaml } from "../../output/index.js";
+import { addReadFlags, readFormat } from "../shared.js";
+import { parseExpiration } from "./duration.js";
+
+const DEFAULT_EXPIRATION_DAYS = 90;
+
+interface ApiKeyCreateFlags extends OutputFlags {
+  name?: string;
+  neverExpires?: boolean;
+  expiresIn?: string;
+}
+
+export function registerApiKey(program: Command): void {
+  const apikey = program.command("apikey").description("manage API keys for Stigmer Cloud authentication");
+
+  const create = apikey
+    .command("create")
+    .description("create a new API key")
+    .option("--name <name>", "display name for the API key")
+    .option("--never-expires", "create a key that never expires")
+    .option("--expires-in <duration>", "custom expiration (e.g. 30d, 6h, 1y)")
+    .action(async (options: ApiKeyCreateFlags) => {
+      await runCreate(options);
+    });
+  addReadFlags(create);
+
+  const fingerprint = apikey
+    .command("fingerprint <raw-key>")
+    .description("look up which API key matches a raw token")
+    .action(async (rawKey: string, options: OutputFlags) => {
+      await runFingerprint(rawKey, options);
+    });
+  addReadFlags(fingerprint);
+}
+
+async function runCreate(options: ApiKeyCreateFlags): Promise<void> {
+  const expiresAt = resolveExpiry(options);
+
+  const { connectBackend } = await import("../../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const created = await client.stigmer.apiKey.create({
+    name: options.name ?? "",
+    org: resolveContextOrganization(client.config),
+    neverExpires: options.neverExpires,
+    expiresAt,
+  });
+
+  const format = readFormat(options);
+  if (format === "json") {
+    process.stdout.write(renderProtoJson(ApiKeySchema, created));
+    return;
+  }
+  if (format === "yaml") {
+    process.stdout.write(renderProtoYaml(ApiKeySchema, created));
+    return;
+  }
+  process.stdout.write(renderCreatedBanner(created));
+}
+
+async function runFingerprint(rawKey: string, options: OutputFlags): Promise<void> {
+  const hash = createHash("sha256").update(rawKey).digest("hex");
+
+  const { connectBackend } = await import("../../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const key = await client.stigmer.apiKey.getByKeyHash(create(ApiKeyHashSchema, { value: hash }));
+  renderApiKey(key, readFormat(options));
+}
+
+function resolveExpiry(options: ApiKeyCreateFlags): Date | undefined {
+  if (options.neverExpires === true) return undefined;
+  if (options.expiresIn !== undefined && options.expiresIn !== "") {
+    return new Date(Date.now() + parseExpiration(options.expiresIn));
+  }
+  return new Date(Date.now() + DEFAULT_EXPIRATION_DAYS * 24 * 60 * 60 * 1000);
+}
+
+function renderApiKey(key: ApiKey, format: OutputFormat): void {
+  if (format === "json") {
+    process.stdout.write(renderProtoJson(ApiKeySchema, key));
+    return;
+  }
+  if (format === "yaml") {
+    process.stdout.write(renderProtoYaml(ApiKeySchema, key));
+    return;
+  }
+  const lines = [`API Key: ${key.metadata?.id ?? ""}`, ""];
+  if (key.metadata?.name) lines.push(`  Name:        ${key.metadata.name}`);
+  if (key.spec?.fingerprint) lines.push(`  Fingerprint: ***${key.spec.fingerprint}`);
+  lines.push(`  Expires:     ${formatExpiry(key)}`);
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+function renderCreatedBanner(key: ApiKey): string {
+  const divider = "═".repeat(63);
+  const lines = [
+    "",
+    "API key created successfully!",
+    "",
+    "IMPORTANT: Save this API key now — it will not be shown again!",
+    "",
+    divider,
+    `  ${key.spec?.keyHash ?? ""}`,
+    divider,
+    "",
+    `  ID:          ${key.metadata?.id ?? ""}`,
+  ];
+  if (key.metadata?.name) lines.push(`  Name:        ${key.metadata.name}`);
+  if (key.spec?.fingerprint) lines.push(`  Fingerprint: ***${key.spec.fingerprint}`);
+  lines.push(`  Expires:     ${formatExpiry(key)}`, "", "Usage:", `  export STIGMER_API_KEY='${key.spec?.keyHash ?? ""}'`, "");
+  return `${lines.join("\n")}\n`;
+}
+
+function formatExpiry(key: ApiKey): string {
+  if (key.spec?.neverExpires) return "Never";
+  if (key.spec?.expiresAt !== undefined) return timestampDate(key.spec.expiresAt).toISOString();
+  return "Never";
+}

package/src/commands/apply.ts

@@ -0,0 +1,213 @@
+// `stigmer apply` — deploy resources to the backend.
+//
+//   File mode (-f):     apply individual YAML resource files (or a directory)
+//   Declarative mode:   a stigmer.yaml project directory (scan + reconcile)
+//
+// Resources marshal strictly from YAML to full protos and apply through the raw
+// command controllers (preserving metadata.id so updates aren't misrouted as
+// creates). Heavy modules are lazy-imported so `--help` stays fast (DD-001).
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import { CommandResult, type OutputFlags, type OutputFormat, renderResult } from "../output/index.js";
+import { addResultFlags, globalOrg, resultFormat } from "./shared.js";
+
+interface ApplyFlags extends OutputFlags {
+  file?: string;
+  config?: string;
+  prune?: boolean;
+  dryRun?: boolean;
+}
+
+export function registerApply(program: Command): void {
+  const apply = program
+    .command("apply")
+    .description("apply resources from files or a project directory")
+    .option("-f, --file <path>", "path to a YAML file or directory")
+    .option("--config <path>", "path to a project directory (declarative mode)")
+    // S1: Go plumbs --prune but never sends it — the server always reconciles
+    // orphans by member set-difference. We reproduce the flag (default on) for
+    // parity; it is intentionally a no-op client-side. Tracked as a Go follow-up.
+    .option("--prune", "delete orphaned resources (declarative mode)", true)
+    .option("--dry-run", "validate without applying")
+    .action((options: ApplyFlags, command: Command) => runApply(options, command));
+  addResultFlags(apply);
+}
+
+async function runApply(options: ApplyFlags, command: Command): Promise<void> {
+  const format = resultFormat(options);
+  const orgOverride = globalOrg(command);
+
+  if (options.file !== undefined && options.file !== "") {
+    await runFileApply(options.file, orgOverride, options.dryRun === true, format);
+    return;
+  }
+
+  await runDeclarativeApply(options, orgOverride, format);
+}
+
+// Declarative mode: detect stigmer.yaml (walk up). Absent → atomic guidance.
+// entry_point set → SDK/project synthesis track. Otherwise scan the project and
+// reconcile membership. Both project tracks converge on the shared reconciler.
+async function runDeclarativeApply(
+  options: ApplyFlags,
+  orgOverride: string | undefined,
+  format: OutputFormat,
+): Promise<void> {
+  const { detectTrack, applyDeclarative, previewDeclarative } = await import("../resources/apply/declarative.js");
+
+  const startDir = options.config !== undefined && options.config !== "" ? options.config : process.cwd();
+  const detect = detectTrack(startDir);
+
+  if (detect.track === "atomic") {
+    renderResult(buildAtomicGuidance(), format);
+    return;
+  }
+
+  if (detect.track === "project") {
+    await runProjectApply(detect, orgOverride, format, options.dryRun === true);
+    return;
+  }
+
+  if (options.dryRun === true) {
+    const { results, summary } = previewDeclarative(detect, {
+      controller: throwingController,
+      warn: (line) => emitWarning(line),
+    });
+    for (const result of results) renderResult(result, format);
+    renderResult(summary, format);
+    return;
+  }
+
+  const { connectBackend } = await import("../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveDeclarativeOrg(client.config, detect.project?.metadata?.org, orgOverride);
+
+  const result = await applyDeclarative(detect, {
+    controller: client.controller,
+    stigmer: client.stigmer,
+    org,
+    info: (line) => process.stderr.write(`${line}\n`),
+    warn: (line) => emitWarning(line),
+  });
+  renderResult(result, format);
+}
+
+// Project (SDK synthesis) track: run the user's entry_point, read the `.pb`
+// output, and reconcile membership through the same reconciler the declarative
+// track uses. Lazy-imported to preserve the DD-001 boundary (`--help` stays
+// fast).
+async function runProjectApply(
+  detect: import("../resources/apply/declarative.js").DetectResult,
+  orgOverride: string | undefined,
+  format: OutputFormat,
+  dryRun: boolean,
+): Promise<void> {
+  const { applyProjectTrack, previewProjectTrack } = await import("../resources/apply/synth/project-track.js");
+
+  if (dryRun) {
+    renderResult(previewProjectTrack(detect), format);
+    return;
+  }
+
+  const { connectBackend } = await import("../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveDeclarativeOrg(client.config, detect.project?.metadata?.org, orgOverride);
+
+  const result = await applyProjectTrack(detect, {
+    controller: client.controller,
+    stigmer: client.stigmer,
+    org,
+    info: (line) => process.stderr.write(`${line}\n`),
+    warn: (line) => emitWarning(line),
+  });
+  renderResult(result, format);
+}
+
+// Org precedence mirrors Go's resolveApplyOrganization: --org flag, then
+// metadata.org in stigmer.yaml, then the configured context. Empty → a clear
+// "set your org" usage error.
+function resolveDeclarativeOrg(
+  config: import("../config/index.js").Config,
+  projectOrg: string | undefined,
+  override: string | undefined,
+): string {
+  const resolved = resolveOrganization(config, override ?? (projectOrg !== "" ? projectOrg : undefined));
+  if (resolved === "") {
+    throw new UsageError(
+      "organization not set\n\n" +
+        "Specify organization in one of these ways:\n" +
+        "  1. Set metadata.org in stigmer.yaml\n" +
+        "  2. Use --org flag: stigmer apply --org <org>\n" +
+        "  3. Set context: stigmer context set --org <org>",
+    );
+  }
+  return resolved;
+}
+
+async function runFileApply(
+  path: string,
+  orgOverride: string | undefined,
+  dryRun: boolean,
+  format: OutputFormat,
+): Promise<void> {
+  const [{ connectBackend }, { resolveApplyItems, requiresOrgContext, applyItem }, { discoverAppliedMcpServers }] =
+    await Promise.all([
+      import("../backend.js"),
+      import("../resources/apply/apply.js"),
+      import("../resources/apply/discovery.js"),
+    ]);
+
+  const items = resolveApplyItems(path);
+
+  // Dry-run never touches the backend: marshal + preview only.
+  if (dryRun) {
+    for (const item of items) {
+      const outcome = await applyItem(throwingController, item, "", true);
+      emitWarning(outcome.warning);
+      renderResult(outcome.result, format);
+    }
+    return;
+  }
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = requiresOrgContext(items) ? resolveOrganization(client.config, orgOverride) : "";
+
+  const appliedMcpServers = [];
+  for (const item of items) {
+    const outcome = await applyItem(client.controller, item, org, false);
+    emitWarning(outcome.warning);
+    renderResult(outcome.result, format);
+    if (outcome.appliedMcpServer !== undefined) appliedMcpServers.push(outcome.appliedMcpServer);
+  }
+
+  await discoverAppliedMcpServers(client.stigmer, appliedMcpServers, (line) => process.stderr.write(`${line}\n`));
+}
+
+function buildAtomicGuidance(): CommandResult {
+  const result = CommandResult.warning("No stigmer.yaml found in current directory or parents");
+  result
+    .addSection("")
+    .item("The 'stigmer apply' command (without -f) requires a project with stigmer.yaml")
+    .item("This enables resource discovery and project-based reconciliation");
+  result
+    .addSection("For single-resource deployment, use file mode")
+    .item("stigmer apply -f agent.yaml")
+    .item("stigmer apply -f workflow.yaml")
+    .item("stigmer apply -f mcpserver.yaml");
+  result.hint("To create a project: add a stigmer.yaml with your project name, then run 'stigmer apply'");
+  return result;
+}
+
+function emitWarning(warning: string | undefined): void {
+  if (warning !== undefined) process.stderr.write(`${warning}\n`);
+}
+
+// In dry-run we still call applyItem but it never reaches the controller; this
+// guard makes that contract explicit (and fails loudly if it ever regresses).
+const throwingController = (() => {
+  throw new Error("controller must not be used during dry-run");
+}) as unknown as import("../resources/apply/handlers.js").ControllerFn;