sim 2.1.17-preview.127.1 → 2.1.18-dev.129.1

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,39 @@
+type CliAuthScope = 'copilot' | 'platform';
+export interface AuthRequest {
+    /** Semi-public rendezvous handle; travels in the browser URL. */
+    request: string;
+    /** Never leaves this process until the poll redeems it. */
+    pollSecret: string;
+    /** BASE64URL(SHA256(pollSecret)), registered when the user approves. */
+    challenge: string;
+    /** Printed for the user to compare against the browser. Never sent to the API. */
+    pairing: string;
+}
+export interface MintedKey {
+    id: string;
+    apiKey: string;
+    scope: CliAuthScope;
+    /** The workspace picked in the browser — the profile's default target. */
+    workspaceId: string | null;
+    /** Whether the key can *only* reach that workspace. */
+    workspaceBound: boolean;
+}
+export declare function createAuthRequest(): AuthRequest;
+export declare function buildApprovalUrl(endpoint: string, auth: AuthRequest, workspaceId?: string): string;
+/**
+ * Polls until the user approves in the browser.
+ *
+ * Transport failures are swallowed and retried rather than aborting the login:
+ * a laptop that slept, a VPN reconnecting, or a deploy rolling the server mid-
+ * wait are all recoverable, and the approval sits in Redis with its own TTL. A
+ * non-2xx *response*, by contrast, is the server refusing on purpose and is
+ * surfaced immediately.
+ *
+ * Retried is not the same as unreported: once
+ * {@link TRANSPORT_FAILURES_BEFORE_WARNING} attempts in a row fail to reach the
+ * endpoint at all, the reason is printed once to stderr and the poll carries on.
+ * Without it a typo'd endpoint was indistinguishable from a slow approval for
+ * the entire 15-minute timeout.
+ */
+export declare function pollForKey(endpoint: string, auth: AuthRequest, signal?: AbortSignal): Promise<MintedKey>;
+export {};

package/dist/auth/oauth-flow.d.ts

@@ -0,0 +1,119 @@
+import { SimApiError } from '../http/client';
+/**
+ * The OAuth half of `sim login`: authorization code + PKCE with a loopback
+ * redirect (RFC 8252), the flow gcloud, the AWS CLI, Wrangler and Railway use.
+ *
+ * The CLI is a public client — there is no secret to keep — so PKCE is what
+ * binds the code to this process: the browser carries only the SHA-256 of a
+ * verifier that never leaves memory, and the token endpoint refuses a code
+ * presented without it. `state` guards the loopback listener against a stray
+ * or forged redirect, and the listener binds the loopback interface only, for
+ * the life of one login.
+ *
+ * The result is a short-lived access token and a rotating refresh token, both
+ * revocable from Settings → General → Authorized apps, instead of the permanent API key
+ * the pairing-code handoff in `device-flow.ts` mints. That handoff remains the
+ * path for a terminal whose browser cannot reach it (SSH, containers).
+ */
+/** The client id migration `0323_oauth_provider` seeds; a public client, no secret. */
+export declare const OAUTH_CLIENT_ID = "sim-cli";
+/**
+ * Everything the CLI does, and nothing more: renew itself, and read and change
+ * workspace resources.
+ *
+ * Sim's provider deliberately exposes OAuth API authorization rather than an
+ * OpenID Connect identity surface, so the CLI requests no identity claims.
+ */
+export declare const OAUTH_SCOPES_FULL: readonly ['offline_access', 'api:read', 'api:write'];
+/** `--read-only`: a token that can inspect but never change anything. */
+export declare const OAUTH_SCOPES_READ_ONLY: readonly ['offline_access', 'api:read'];
+/**
+ * Refuses to run the OAuth flow over cleartext.
+ *
+ * The code, the verifier, and both tokens cross this connection. An API key
+ * over `http` earns a warning because the user typed the endpoint and may know
+ * something we do not; a login is different, because the flow itself is what
+ * would leak, and because a tampered discovery response silently downgrades
+ * `sim login` to the pairing-code handoff — which mints a permanent key.
+ * Loopback is exempt: it never leaves the machine.
+ */
+export declare function requireSecureEndpoint(endpoint: string): void;
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Epoch milliseconds at which `accessToken` stops working. */
+    expiresAt: number;
+    scope: string;
+}
+/** A refusal from the token endpoint, carrying the RFC 6749 error code. */
+export declare class OAuthTokenError extends SimApiError {
+    readonly oauthError: string;
+    constructor(oauthError: string, description: string | undefined, status: number);
+}
+export interface Pkce {
+    verifier: string;
+    challenge: string;
+    state: string;
+}
+/** A fresh verifier (43 chars, 256 bits), its S256 challenge, and a `state` nonce. */
+export declare function createPkce(): Pkce;
+export declare function buildRedirectUri(port: number): string;
+export declare function buildAuthorizeUrl(endpoint: string, args: {
+    redirectUri: string;
+    scopes: readonly string[];
+    pkce: Pkce;
+}): string;
+export type OAuthProviderStatus = 'available' | 'unavailable' | 'unreachable';
+/**
+ * Whether the endpoint is an OAuth authorization server, from the RFC 8414
+ * discovery document. A 404 is a definite "no" — an older Sim, or one with the
+ * provider switched off — and sends login to the pairing-code handoff; a
+ * transport failure is reported as such so a typo'd endpoint is not mistaken
+ * for a server that lacks the feature.
+ */
+export declare function discoverOAuthProvider(endpoint: string): Promise<OAuthProviderStatus>;
+export declare function grantsWriteAccess(scope: string): boolean;
+/** Redeems an authorization code with its PKCE verifier. */
+export declare function exchangeCode(endpoint: string, args: {
+    code: string;
+    redirectUri: string;
+    verifier: string;
+    requestedScopes: readonly string[];
+}, signal?: AbortSignal): Promise<OAuthTokens>;
+/**
+ * Trades a refresh token for a new pair. The server rotates: the token used
+ * here is dead afterwards, and presenting it again invalidates every access
+ * and refresh token from this login. Other independently authorized CLI
+ * logins remain active. Callers serialize local refreshes through the
+ * credentials lock before reaching this.
+ */
+export declare function refreshTokens(endpoint: string, refreshToken: string, expectedScopes?: readonly string[], signal?: AbortSignal): Promise<OAuthTokens>;
+/**
+ * Revokes a refresh token server-side, which also kills every access and
+ * refresh token in that login family. RFC 7009 answers 200 for an unknown
+ * token, so this only fails when the server cannot be reached or refuses the
+ * client.
+ */
+export declare function revokeToken(endpoint: string, token: string): Promise<void>;
+export interface BrowserLoginOptions {
+    scopes: readonly string[];
+    /** Pin the loopback port when an SSH tunnel forwards that same port. */
+    callbackPort?: number;
+    /** Called with the authorize URL once the listener is up, before waiting. */
+    onAuthorizeUrl: (url: string) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/**
+ * Runs the whole browser login: listener, authorize URL, callback, exchange.
+ * Resolves with tokens only after the code has been redeemed, so a caller that
+ * gets a result holds a working credential.
+ */
+export declare function loginWithBrowser(endpoint: string, options: BrowserLoginOptions): Promise<OAuthTokens>;
+/**
+ * Whether this terminal's browser is unlikely to reach a loopback listener on
+ * this machine: an SSH session, or a Linux box with no display. An explicit
+ * `--method` selects the flow without this guess; `--callback-port` opts into
+ * OAuth when a forwarded port makes the loopback listener reachable.
+ */
+export declare function isLikelyRemoteSession(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;

package/dist/auth/refresh.d.ts

@@ -0,0 +1,16 @@
+import { type ResolvedProfile, type StoredOAuthCredential } from '../config/index';
+/**
+ * Renews a stored OAuth login and persists the rotated pair.
+ *
+ * Under the credentials lock because the refresh token is single-use and two
+ * local processes must not race it. After taking the lock the file is read
+ * again: if another process already rotated the token, its result is adopted
+ * and no request is made. This coordinates trusted local processes; detecting
+ * and containing a copied token remains the authorization server's job.
+ *
+ * `invalid_grant` means the server no longer honours the refresh token — it
+ * was revoked from Settings → General → Authorized apps, expired, or was already rotated
+ * by a process this one could not see — and the remedy is logout followed by a
+ * new login.
+ */
+export declare function refreshStoredOAuth(profile: Pick<ResolvedProfile, 'name' | 'endpoint' | 'authProfile'>, current: StoredOAuthCredential): Promise<StoredOAuthCredential>;

package/dist/commands/auth.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+export declare function loginCommand(): Command;
+export declare function logoutCommand(): Command;
+export declare function whoamiCommand(): Command;
+export declare function profilesCommand(): Command;

package/dist/commands/configure.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function configureCommand(): Command;

package/dist/commands/credentials.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+/** Adds the human-facing OAuth connection commands backed by the v2 credentials API. */
+export declare function attachCredentialCommands(program: Command): void;

package/dist/commands/protocol/chat.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+/**
+ * Adds `sim chat`.
+ *
+ * A protocol command rather than a generated one: the generated pass can only
+ * make one JSON request, while a chat turn can run for minutes and is consumed
+ * as an NDJSON stream so the reply prints as it generates and heartbeats keep
+ * proxies from idling the connection out. The generated `chat` operation is
+ * hidden in the CLI contract in favour of this command.
+ */
+export declare function attachChat(program: Command): void;

package/dist/commands/protocol/files-get.d.ts

@@ -0,0 +1,25 @@
+import { type WriteStream } from 'node:fs';
+import { type Writable } from 'node:stream';
+import type { Command } from 'commander';
+/** Streams a fetch body to disk while honoring write-stream backpressure. */
+export declare function streamToFile(body: ReadableStream<Uint8Array>, file: Writable & Pick<WriteStream, 'path'>, reportedPath?: WriteStream['path']): Promise<void>;
+/**
+ * Removes the staging directory when a signal ends the process.
+ *
+ * `saveStagedFile` cleans up in normal control flow, which a signal never
+ * reaches: the process is torn down mid-`pipeline`, so every Ctrl-C left
+ * another `.sim-download-*` holding a partial payload beside the destination.
+ * The removal is synchronous because the termination that follows gives an
+ * async `rm` no turn to run.
+ *
+ * Exported for its own test: driving it through a real interrupt would take the
+ * test runner down with it.
+ */
+export declare function removeStagingOnSignal(stagingDirectory: () => string | null, terminate?: (signal: NodeJS.Signals) => void): () => void;
+/** Publishes a complete staged body atomically, with overwrite requiring explicit force. */
+export declare function saveToFile(body: ReadableStream<Uint8Array>, target: string, force: boolean): Promise<void>;
+/** Streams a fetch body to stdout without closing the process-wide stream. */
+export declare function streamToStdout(body: ReadableStream<Uint8Array>, output?: NodeJS.WriteStream): Promise<void>;
+/** Returns whether content can be written directly to an interactive terminal. */
+export declare function isTerminalSafeContentType(contentType: string | null): boolean;
+export declare function attachFileGet(files: Command): void;

package/dist/commands/protocol/files-upload.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function attachFileUpload(files: Command): void;

package/dist/commands/protocol/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+/** Attaches commands whose multi-request or binary protocols cannot be generated. */
+export declare function attachProtocolCommands(program: Command): void;

package/dist/commands/protocol/knowledge-document-upload.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from 'commander';
+export declare function attachKnowledgeDocumentUpload(documents: Command): void;

package/dist/commands/protocol/knowledge-export.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+/**
+ * The file name a `Content-Disposition: attachment` header carries, or `null`
+ * when it names none.
+ *
+ * The RFC 5987 `filename*` form is read first, because the server only emits it
+ * when the real name is not printable ASCII — and in exactly that case the
+ * quoted form beside it has had every such character replaced, so reading the
+ * quoted form alone would save a knowledge base named "Suporte técnico" as
+ * `Suporte t_cnico`. Only the base name is kept, so a directory in the header
+ * can never decide where the archive lands on the caller's disk.
+ */
+export declare function attachmentFileName(contentDisposition: string | null): string | null;
+export declare function attachKnowledgeExport(knowledge: Command): void;

package/dist/commands/protocol/logs-follow.d.ts

@@ -0,0 +1,39 @@
+import { type Command } from 'commander';
+import { type ListLogsResponse } from '../../generated/v2-api';
+/** One run, as `GET /api/v2/logs` returns it. */
+export type LogRow = ListLogsResponse['data'][number];
+/** Widest a table column renders, matching the `logs list` table. */
+export declare const MAX_CELL_WIDTH = 60;
+export interface FollowStatus {
+    /** Replaces the status line, if there is a terminal to draw it on. */
+    note: (message: string) => void;
+    /**
+     * Reports something the reader has to know, on its own line.
+     *
+     * Unlike {@link note} this is not progress and is never erased: it records
+     * that rows are missing, which stays true after the follow moves on. It is
+     * written even when stderr is not a terminal, because a piped log is exactly
+     * where an unexplained hole is hardest to spot.
+     */
+    warn: (message: string) => void;
+    /** Erases the line, if anything was ever written to it. */
+    clear: () => void;
+}
+/**
+ * Reports what the follow is doing, on stderr.
+ *
+ * The rule `pageProgress` follows: stdout is the stream of rows and gets piped,
+ * so anything that is not a row goes to stderr, and only to a terminal.
+ */
+export declare function followStatus(): FollowStatus;
+/**
+ * Adds `sim logs follow`.
+ *
+ * A sibling command rather than `logs list --follow`, because `logs list` is
+ * generated from the CLI contract, which describes the HTTP surface: `--follow`
+ * has no wire counterpart, and its paging is the inverse of the contract's —
+ * re-reading the newest page forever, rather than walking a cursor to the end
+ * once. The filters are the same ones `logs list` exposes, so the two commands
+ * take the same arguments and render the same columns.
+ */
+export declare function attachLogsFollow(logs: Command): void;

package/dist/commands/protocol/resource-directory.d.ts

@@ -0,0 +1,24 @@
+import { type Command } from 'commander';
+type ResourceDirectoryConfig = {
+    kind: 'file';
+    resources: 'listFiles';
+    folders: 'listFileFolders';
+    createFolder: 'createFileFolder';
+} | {
+    kind: 'knowledge';
+    resources: 'listKnowledgeBases';
+    folders: 'listKnowledgeFolders';
+    createFolder: 'createKnowledgeFolder';
+} | {
+    kind: 'table';
+    resources: 'listTables';
+    folders: 'listTableFolders';
+    createFolder: 'createTableFolder';
+} | {
+    kind: 'workflow';
+    resources: 'listWorkflows';
+    folders: 'listWorkflowFolders';
+    createFolder: 'createWorkflowFolder';
+};
+export declare function attachResourceDirectoryCommands(group: Command, config: ResourceDirectoryConfig): void;
+export {};

package/dist/commands/protocol/result.d.ts

@@ -0,0 +1,2 @@
+import type { OutputFormat } from '../../config/index';
+export declare function printProtocolResult(format: OutputFormat, result: Record<string, unknown>): void;

package/dist/commands/protocol/tables-import.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from 'commander';
+export declare function attachTableImport(tables: Command): void;

package/dist/commands/protocol/workflow-run-follow.d.ts

@@ -0,0 +1,56 @@
+import type { Command } from 'commander';
+/** The sink live commentary is written to; `process.stderr` satisfies it. */
+export interface CommentaryWriter {
+    write(text: string): unknown;
+}
+export interface FollowOptions {
+    includeThinking: boolean;
+    includeToolCalls: boolean;
+    stderr: CommentaryWriter;
+}
+type WorkflowRunSelection = {
+    source: 'manual';
+} | {
+    source: 'manual';
+    entry: {
+        type: 'trigger';
+        blockId?: string;
+        useMockPayload?: boolean;
+    };
+} | {
+    source: 'manual';
+    entry: {
+        type: 'block';
+        blockId: string;
+        sourceRunId: string;
+    };
+};
+/** Projects friendly CLI flags into the API's strict nested run selector. */
+export declare function resolveWorkflowRunSelection(flags: Record<string, unknown>): WorkflowRunSelection | undefined;
+/**
+ * Renders one execute stream, returning the `final` envelope.
+ *
+ * Everything rendered here is commentary and goes to `stderr`: the payload a
+ * script captures is the final envelope, which the caller prints to stdout in
+ * the profile's output format. Streaming the answer text to stdout as well
+ * would put the same content in the redirect twice, once unparseable.
+ *
+ * Throws on a terminal `error` frame and on a stream that stops before either
+ * terminal frame arrives — a truncated stream is a failed run, and reporting it
+ * as an empty success is the one outcome a caller cannot detect afterwards.
+ */
+export declare function renderRunStream(body: ReadableStream<Uint8Array>, options: FollowOptions): Promise<Record<string, unknown>>;
+/**
+ * Teaches the generated `workflows run` leaf to stream.
+ *
+ * `--follow` rides on `run` rather than standing up a sibling command because
+ * it is the same operation with a different response encoding: the input,
+ * output-selection, and `--async` flags all still apply, and a second command
+ * would have to restate every one of them and then drift.
+ *
+ * Commander offers no way to read the action it already holds, so the existing
+ * handler is captured for async execution. Synchronous execution uses the same
+ * generated request and result builders with a heartbeat-capable response.
+ */
+export declare function attachWorkflowRunFollow(workflows: Command): void;
+export {};

package/dist/commands/protocol/workflow-run-get.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from 'commander';
+/**
+ * Teaches the generated `workflows runs get` leaf the block names
+ * `workflows run --select-output` already takes.
+ *
+ * The run resource matches recorded block ids only — it never loads the
+ * workflow — so `--select-output summarize.result`, the spelling the run was
+ * started with, came back `400` and the fix was to go and look up an id. The
+ * lookup is done here instead: a selection with any name-headed selector reads
+ * the workflow's blocks once, rewrites names onto ids, and reads the run keyed
+ * the way it was asked. A selection of ids alone, or no selection, still runs
+ * the generated handler byte for byte. Commander offers no way to read the
+ * action it holds, so it is captured and delegated to, as `--follow` does.
+ */
+export declare function attachWorkflowRunGet(runs: Command): void;

package/dist/commands/protocol/workflow-run-wait.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+/** Adds `workflows runs wait` — poll one run until it stops moving. */
+export declare function attachWorkflowRunWait(runs: Command): void;

package/dist/commands/protocol/workspace-operation-wait.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+import { type GetWorkspaceOperationResponse } from '../../generated/v2-api';
+import { type SimClient } from '../../http/client';
+type WorkspaceOperation = GetWorkspaceOperationResponse['data'];
+export declare function readWorkspaceOperation(raw: unknown): WorkspaceOperation;
+export declare function workspaceWaitTimeout(raw: unknown): number;
+export declare function assertWorkspaceOperationOutcome(report: WorkspaceOperation, timedOut?: boolean): void;
+/** Polls only the existing operation; uncertain mutations are never retried with a new ID. */
+export declare function waitWorkspaceOperation(client: SimClient, workspaceId: string, operationId: string, timeoutSeconds: number, initial?: WorkspaceOperation): Promise<{
+    report: WorkspaceOperation;
+    timedOut: boolean;
+}>;
+export declare function attachWorkspaceOperationWait(operations: Command): void;
+export {};

package/dist/commands/secrets.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+/** Adds interactive secret entry while preserving an explicit value flag for scripts. */
+export declare function attachSecretCommands(program: Command): void;

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function telemetryCommand(): Command;

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function updateCommand(): Command;

package/dist/config/index.d.ts

@@ -0,0 +1,2 @@
+export { configDir, configPath, credentialsPath, telemetryStatePath } from './paths';
+export { DEFAULT_ENDPOINT, DEFAULT_PROFILE, deleteProfile, FORBIDDEN_IN_VALUE, listAuthenticationDependents, listProfiles, normalizeEndpoint, normalizeWorkspaceId, OUTPUT_FORMATS, type OutputFormat, oauthIssuerForEndpoint, PROFILE_NAME_PATTERN, ProfileConfigError, type ProfileOverrides, type ResolvedProfile, readConfigProfile, readCredentialsProfile, readStoredCredential, readStoredOAuth, resolveAuthenticationProfileName, resolveProfile, type SettingSource, type StoredCredential, type StoredOAuthCredential, validateProfileName, withCredentialsLock, withProfileLoginLease, writeConfigProfile, writeCredentialsProfile, } from './profile';

package/dist/config/ini.d.ts

@@ -0,0 +1,111 @@
+/**
+ * A minimal INI reader/writer for the AWS-style `~/.sim/config` and
+ * `~/.sim/credentials` files.
+ *
+ * Parsing keeps every line it did not understand — comments, blank lines,
+ * unrecognized keys — and writing re-emits them in place. These are files people
+ * hand-edit, so a round trip through `sim login` must not silently delete the
+ * comment above someone's staging endpoint.
+ *
+ * Deliberately not a general INI implementation: no nested sections, no `[a.b]`
+ * paths, no quoting rules beyond trimming. The format only has to carry a
+ * handful of flat string settings.
+ */
+/**
+ * An invalid stored setting, or a value the config files cannot represent.
+ *
+ * Defined here rather than in `profile.ts` because the writer below is the
+ * lowest layer that rejects input, and `profile.ts` already imports this module.
+ * `profile.ts` re-exports it, so callers keep seeing one error type — the one
+ * the entrypoint renders as a message instead of a stack trace.
+ */
+export declare class ProfileConfigError extends Error {
+    constructor(message: string);
+}
+type Entry = {
+    kind: 'kv';
+    key: string;
+    value: string;
+} | {
+    kind: 'raw';
+    text: string;
+};
+interface Section {
+    name: string;
+    /**
+     * The header line exactly as it was read, re-emitted verbatim.
+     *
+     * {@link parseIni} trims the bracketed text to get {@link name}, so writing
+     * `[${name}]` back rewrote the header of every section in the file — a
+     * `configure --set-output` on `default` silently reformatted a hand-written
+     * `[profile   padded   ]` it was never asked to touch. Absent only on a
+     * section {@link setSectionValues} created, which has no original line.
+     */
+    header?: string;
+    entries: Entry[];
+}
+export interface IniDocument {
+    /** Lines before the first section header. */
+    preamble: string[];
+    sections: Section[];
+}
+/**
+ * Characters a stored value may not contain.
+ *
+ * The format has no escape syntax (see the module note), so text that can end a
+ * line is structure, not data: a value carrying a line break was written
+ * verbatim and read back on the next load as a *second* setting in the same
+ * section. That is the class of bug this closes — untrusted text reaching the
+ * serializer could add settings nobody typed.
+ *
+ * The set is every C0 and C1 control character plus U+2028 and U+2029, the two
+ * Unicode line separators. The separators matter for a second reason: they are
+ * not line breaks to the reader below, so {@link KV_PATTERN} (whose `.` never
+ * matches them) fails and the line is kept as opaque `raw` text — the key
+ * silently vanishes on the next read although the write reported success, and
+ * because the dead line no longer matches the key, the write after that appends
+ * a duplicate.
+ *
+ * Exported because callers that refuse untrusted text *before* writing — so they
+ * can say which side produced it — have to refuse exactly this set. A second
+ * hand-kept copy drifted from this one once already, and the gap let a rejected
+ * write land after an accepted one.
+ */
+export declare const FORBIDDEN_IN_VALUE: RegExp;
+export declare function parseIni(text: string): IniDocument;
+export declare function serializeIni(doc: IniDocument): string;
+/**
+ * Reads a section's keys, merging every block that repeats its name.
+ *
+ * A hand-edited file can carry two `[default]` blocks; reading only the first
+ * silently dropped the second's keys and reported them as unset. The merge is
+ * **first wins** per key, matching {@link setSectionValues}, which upserts into
+ * the first block — so a value written through this module is the one read back.
+ */
+export declare function getSection(doc: IniDocument, name: string): Record<string, string> | null;
+export declare function listSections(doc: IniDocument): string[];
+/**
+ * Upserts values into a section, creating it when absent. A `null` value removes
+ * the key. Existing keys are updated where they sit so surrounding comments keep
+ * describing the line they were written above.
+ *
+ * A write targets the first block of that name, matching the first-wins read in
+ * {@link getSection}. A removal instead has to clear every block and every
+ * repeat of the key within one: deleting only the first left a later duplicate
+ * to win the merged read, so `--unset` reported success while the value stayed
+ * in force. A removal against a section that is not there writes nothing at all.
+ *
+ * This is the one place untrusted text enters the document, so it is where the
+ * write is refused: see {@link FORBIDDEN_IN_VALUE} for what cannot be stored
+ * and why the answer is a refusal rather than an escape.
+ */
+export declare function setSectionValues(doc: IniDocument, name: string, values: Record<string, string | null>): void;
+/**
+ * Drops every block carrying the name, and reports whether one was there.
+ *
+ * A hand-edited file can repeat a section, and {@link getSection} merges them
+ * all — so removing only the first left `sim logout` reporting a profile gone
+ * while its later block still answered every read.
+ */
+export declare function removeSection(doc: IniDocument, name: string): boolean;
+export {};

package/dist/config/json-file.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reads and parses a JSON file, or returns `null` for anything at all wrong.
+ *
+ * Follows no symlink and reads no more than `maxBytes`: the file lives where
+ * the user, or anything running as the user, can replace it, and the caller's
+ * only interest is in a small document it wrote itself. Shape validation is
+ * the caller's — this returns whatever JSON was there.
+ */
+export declare function readJsonFile(path: string, maxBytes: number): unknown;
+/**
+ * Replaces a JSON file atomically, creating its directory if needed.
+ *
+ * An exclusive adjacent temporary file renamed into place means a reader never
+ * sees a partial document and a linked target is never modified through the
+ * link. Failures are swallowed: the callers are caches and preferences whose
+ * loss costs one extra request or one repeated notice.
+ */
+export declare function writeJsonFile(path: string, value: unknown, mode?: number): void;

package/dist/config/paths.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where the CLI keeps its state. `SIM_CONFIG_DIR` overrides the location
+ * wholesale, which is what lets tests and CI point at a scratch directory
+ * instead of the invoking user's real credentials.
+ */
+export declare function configDir(): string;
+/** Non-secret per-profile settings. Safe to commit to a dotfiles repo. */
+export declare function configPath(): string;
+/** API keys, written 0600. Kept apart from `config` so the two can be handled differently. */
+export declare function credentialsPath(): string;
+/**
+ * Where the once-a-day update check remembers that it ran.
+ *
+ * Cache, not configuration, so it is safe to delete at any time and gets no
+ * `SIM_*` override of its own: nobody relocates a cache deliberately, and
+ * `SIM_CONFIG_DIR` already moves it for the two callers that matter — the test
+ * harness and anyone keeping `~/.sim` somewhere else. It is kept out of the
+ * config file because that file is INI the user edits, and a timestamp inside a
+ * `[profile x]` section would surface in `sim configure` and `sim whoami`.
+ */
+export declare function updateCachePath(): string;
+/**
+ * Where usage telemetry keeps its device id, session, and on/off setting.
+ *
+ * State rather than configuration, so it follows `SIM_CONFIG_DIR` the way the
+ * update cache does and gets no override of its own. Deleting it forgets the
+ * device id and shows the first-run notice again; nothing else is lost.
+ */
+export declare function telemetryStatePath(): string;