/**
 * Railway start-command pin helper.
 *
 * Owns the one place that knows how to format a Studiograph start command
 * and shove it onto a Railway service. Three callers existed before this
 * file: `studiograph deploy railway`, `studiograph redeploy`, and the web
 * agent's `redeploy_railway` tool. Each pinned the version independently;
 * `redeploy` swallowed pin failures and continued — see cli-owner-audit
 * §6.2 and the codex review appendix.
 *
 * Contract:
 *   - `pinStartCommand` throws on Railway API errors. Callers should NOT
 *     try/catch and continue: a failed pin means the deploy or redeploy
 *     will boot the wrong version. Fail loud.
 *   - The resolved start command string is returned so callers can log
 *     it (matches the existing UX from redeploy/deploy).
 *   - Version selection is the caller's responsibility — pass the exact
 *     version you want pinned. Today every caller reads it from
 *     `package.json`. The recommended invocation is
 *       npx -y studiograph@<exact-version> <command>
 *     which produces a CLI whose `package.json` already matches the npx
 *     version, eliminating the cli-version-pin footgun.
 *
 * `studiograph init` runs once on first boot when the workspace volume
 * is empty (the `deploy` command's start command threads it in); after
 * that, the start command is just `npx --yes studiograph@<v> serve`.
 * `pinStartCommand` overwrites whatever's there, so a redeploy after the
 * volume already has `.studiograph/workspace.json` correctly skips the
 * init guard inline.
 */
import { RailwayQuery, RailwayServiceContext } from './railway-provisioning.js';
export interface PinStartCommandOpts {
    /** Override the rendered start command verbatim. Used by `deploy.ts`
     *  which prefixes a one-shot `studiograph init` guard for empty
     *  volumes. When omitted, defaults to `npx --yes studiograph@<v> serve`. */
    startCommand?: string;
}
/**
 * Set the Railway service's start command to the given Studiograph version.
 * Returns the resolved start command string.
 *
 * Throws if the Railway API returns an error. Callers must not swallow.
 */
export declare function pinStartCommand(query: RailwayQuery, ctx: {
    serviceId: string;
    environmentId: string;
}, version: string, opts?: PinStartCommandOpts): Promise<string>;
/**
 * Convenience: query the npm registry for the latest published `@next`
 * version of studiograph. Non-blocking — returns `null` on failure (network
 * blip, registry down, malformed response) so callers can log an
 * informational note without bailing.
 *
 * Used by `redeploy` to print "Heads up: @next is now X; you're pinning Y"
 * when the local CLI lags the published @next. Doesn't block redeploy —
 * the owner may be intentionally pinning an earlier tested version.
 */
export declare function fetchLatestNextVersion(opts?: {
    fetchFn?: typeof fetch;
    timeoutMs?: number;
}): Promise<string | null>;
/**
 * Read the running CLI's own package.json version. Centralized so callers
 * don't duplicate the `new URL('../../../package.json', import.meta.url)`
 * dance and pick up the same answer.
 */
export declare function readOwnVersion(): string;
export type { RailwayQuery, RailwayServiceContext };
