sim 2.1.7 → 2.1.8-dev.94.1

package/dist/output/presentation.d.ts

@@ -0,0 +1,4 @@
+/** Embedded output is data; choose plain CLI styling without changing the host's Chalk. */
+export declare function styles(): import("chalk").ChalkInstance;
+/** A hosting server's terminal is never the embedded invocation's progress display. */
+export declare function hasProgressTerminal(): boolean;

package/dist/output/render.d.ts

@@ -0,0 +1,60 @@
+import type { OutputFormat } from '../config/index';
+export interface Column<T> {
+    header: string;
+    value: (row: T) => string;
+}
+/**
+ * Removes terminal control sequences from a server-supplied string.
+ *
+ * Applied where API values become display text, so the colour the CLI adds
+ * afterwards still works — sanitizing the finished cell would strip our own
+ * formatting too.
+ */
+export declare function sanitize(value: string): string;
+/** Flattens untrusted terminal text into one compact, display-safe line. */
+export declare function safeOneLine(value: string): string;
+export declare function text(value: unknown): string;
+/** ISO timestamps are the wire format everywhere; show them without the milliseconds. */
+export declare function timestamp(value: string | null | undefined): string;
+export declare function bool(value: boolean | null | undefined): string;
+export declare function bytes(value: number | null | undefined): string;
+export declare function duration(ms: number | null | undefined): string;
+/**
+ * Visible width of a cell, ignoring ANSI colour codes.
+ *
+ * Padding on the raw string would count the escape sequences as characters and
+ * skew every coloured column, so widths are measured on the stripped text while
+ * the coloured text is what gets printed.
+ */
+/**
+ * Visible width of a cell.
+ *
+ * Delegates to the grapheme-aware measurement: the previous implementation
+ * counted stripped string length, so emoji and East Asian characters measured
+ * as one column and mis-aligned every table containing them.
+ */
+export declare function visibleWidth(value: string): number;
+/**
+ * Prints a list in the profile's output format.
+ *
+ * `text` emits the table's cells tab-separated with no header and no colour —
+ * the shape `cut -f2` and `while read` expect. It uses the formatted cells
+ * rather than the raw values on purpose: it is a human-ish format for shell
+ * plumbing, and a raw ISO timestamp or byte count is worse in that context.
+ */
+export declare function printList<T>(format: OutputFormat, rows: T[], columns: Column<T>[], raw?: unknown): void;
+/**
+ * Prints a payload whose value IS the deliverable — `workflows export`, which
+ * is meant to be redirected to a file and fed back to `import`.
+ *
+ * `table` and `text` are display formats: they flatten, truncate and colour, so
+ * neither can round-trip a document. Rather than emit something that looks like
+ * an export but cannot be re-imported, those two fall back to JSON. Only `yaml`
+ * is honoured, because it round-trips.
+ */
+export declare function printDocument(format: OutputFormat, raw: unknown): void;
+/**
+ * Prints a single record: machine formats from the raw value, otherwise aligned
+ * lines. As in `printList`, only the `table` rendering is clamped.
+ */
+export declare function printRecord(format: OutputFormat, fields: Array<[string, string]>, raw: unknown): void;

package/dist/output/terminal-text.d.ts

@@ -0,0 +1,17 @@
+export declare function graphemes(value: string): Array<{
+    segment: string;
+    index: number;
+}>;
+/** First grapheme cluster of a string, or null when it is empty. */
+export declare function firstGrapheme(value: string): string | null;
+export declare function previousGraphemeIndex(value: string, cursor: number): number;
+export declare function nextGraphemeIndex(value: string, cursor: number): number;
+export declare function lineStart(value: string, cursor: number): number;
+export declare function lineEnd(value: string, cursor: number): number;
+export declare function displayWidth(value: string): number;
+export declare function graphemeWidth(value: string): number;
+export declare function isWideCodePoint(codePoint: number): boolean;
+export declare function truncateDisplay(value: string, width: number): string;
+export declare function tailToWidth(value: string, width: number): string;
+/** Squares off a ragged art line so every box border starts at the same column. */
+export declare function artPad(line: string, width: number): string;

package/dist/output/trace.d.ts

@@ -0,0 +1,3 @@
+import type { OutputFormat } from '../config/index';
+/** Prints the complete recursive run trace for an explicitly expanded log. */
+export declare function printTraceSpans(format: OutputFormat, traceSpans: unknown[]): void;

package/dist/program.d.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+/** Root program description, shared by `--help` and the generated docs. */
+export declare const PROGRAM_DESCRIPTION = "Talk to the Sim API from your terminal";
+export declare const HELP_EPILOGUE = "\nProfiles work like the AWS CLI: settings live in ~/.sim/config, keys in\n~/.sim/credentials (0600), or under SIM_CONFIG_DIR when it is set. Select one\nwith -P, --profile, or SIM_PROFILE.\n\nWorkflow, knowledge-base and workspace IDs are bare UUIDs. Table IDs carry a\ntbl_ prefix and file IDs a wf_ one, so wf_ never names a workflow. An audit-log\nor custom-tool ID can open with a dash, which reads as a flag; put -- in front\nof it, as in sim audit-logs get -- -HlDcD1z76nK6R4crsUp0.\n\nExamples:\n  $ sim login                          Authorize the default profile\n  $ sim login --profile dev --endpoint http://localhost:3000\n  $ sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28\n  $ sim workflows list\n  $ sim logs list --level error --limit 20\n  $ sim configure --set-output json    Save a profile output default\n  $ sim --output json tables get tbl_9f3c1a05d4b7426e8c2f0917ab35de64\n  $ sim knowledge search --query \"refund policy\" --kb 4c1b7f60-2d55-4a3e-9c18-70b6ea2f9d31\n  $ sim workflows export 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 > wf.json\n  $ sim workflows import --workflow @wf.json\n  $ sim whoami --profile dev\n";
+/**
+ * Assemble the complete command tree.
+ *
+ * Kept separate from the entrypoint so the documentation generator can walk the
+ * same tree the terminal parses. A generator that rebuilt the surface from the
+ * contract instead would be a second implementation of `buildGeneratedCommands`,
+ * free to drift from the one users actually run.
+ *
+ * `version` is optional because the generator reads the package metadata itself
+ * and the emitted pages must not carry a version that goes stale on every
+ * release.
+ */
+export declare function buildProgram(options?: {
+    version?: boolean;
+    helpText?: string;
+    program?: Command;
+}): Command;

package/dist/runtime/build.d.ts

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+import type { OperationSpec } from './types';
+/**
+ * States the personal-key restriction the way every generated command states it.
+ *
+ * The suffix lives here, once, because a fully hand-written command renders its
+ * own `.description()` and never reaches the generated path — three commands
+ * (`secrets set`, `credentials create`, `credentials connect`/`reconnect`) sat
+ * beside siblings that carried the warning and silently read as accepting a
+ * workspace key. Taking the `OperationSpec` rather than a boolean means a
+ * caller has to name the operation it actually calls, so the two cannot drift.
+ */
+export declare function describeOperation(operationSpec: OperationSpec, described: string): string;
+/**
+ * Sweeps the assembled program for a flag the root already owns.
+ *
+ * `assertNoReservedFlags` runs while a generated leaf is configured, so it sees
+ * nothing that is attached by hand (`attachSecretCommands`,
+ * `attachProtocolCommands`, `attachCredentialCommands`) or added to a leaf
+ * after it is built. Walking the finished tree is what covers those.
+ */
+export declare function assertNoReservedProgramFlags(program: Command): void;
+/**
+ * Refuses `--help` typed after a command that does not exist.
+ *
+ * Commander answers a help flag before it looks at the operands, so `sim
+ * workspaces zzzz --help` printed the group's help and exited `0` while the
+ * same words without the flag exit `1`. A capability probe reading the exit
+ * code therefore concluded a command exists when it does not.
+ *
+ * Only pure dispatchers are guarded. A command that takes arguments or acts on
+ * its own (`sim files restore <fileId>`, `sim profiles`) legitimately sees an
+ * operand it did not register as a subcommand, and refusing there would break
+ * `--help` on argv the CLI accepts.
+ */
+export declare function refuseHelpAfterUnknownCommand(program: Command): void;
+/** Builds every JSON command described by the generated operation table. */
+export declare function buildGeneratedCommands(): Command[];

package/dist/runtime/derive.d.ts

@@ -0,0 +1,20 @@
+import { type V2OperationName } from '../generated/v2-api';
+/**
+ * Derives a command path from an operation's route.
+ *
+ * `<resource> [sub-resource] <verb>`, where the verb comes from the method and
+ * whether the path ends in a parameter (an item) or not (a collection). This
+ * covers 41 of the 47 operations; the rest are named in the CLI contract.
+ */
+export declare function deriveCommandPath(operation: V2OperationName): string[];
+/** `conflictTarget` → `conflict-target`. */
+export declare function kebab(value: string): string;
+/**
+ * `min-duration-ms` → `minDurationMs`, the key commander actually stores.
+ *
+ * Commander camelCases every multi-word flag when it builds its options object,
+ * so a lookup by the flag's own name finds nothing and the value is silently
+ * dropped — no error, the field just never reaches the API. Every read of a
+ * parsed flag has to go through this.
+ */
+export declare function camel(flag: string): string;

package/dist/runtime/execute.d.ts

@@ -0,0 +1,30 @@
+import type { CommandSpec } from '../contract/types';
+import type { V2OperationName } from '../generated/v2-api';
+import type { OperationSpec } from './types';
+/**
+ * Bulk operations that answer `200` even when they changed nothing.
+ *
+ * These endpoints are deliberately best-effort: they attempt every item, then
+ * report per-item outcomes in the payload. That is right for a partial
+ * success — some items really were deleted or moved — but a call that touched
+ * nothing at all is a failure the caller has to notice, and exiting `0` left
+ * `sim tables batch-delete --table-ids '["tbl_typo"]'` indistinguishable from a
+ * real deletion in a CI step.
+ *
+ * Only a total miss fails. A partial success still exits `0`: the payload names
+ * every item that did not make it, and failing the process there would break
+ * every caller that legitimately sweeps a list containing already-gone items.
+ */
+/**
+ * Reads a bulk payload, and the request that produced it, for a total miss.
+ *
+ * The request is needed because not every bulk response reports the items it
+ * failed on: `bulkDeleteFiles` answers with a deleted count and nothing else,
+ * so the only place the number of items asked for exists is the body that was
+ * sent.
+ */
+type BulkOutcomeCheck = (payload: Record<string, unknown>, body: Record<string, unknown> | undefined) => string | null;
+export declare const BULK_OUTCOME_CHECKS: Readonly<Partial<Record<V2OperationName, BulkOutcomeCheck>>>;
+/** Executes a parsed generated command, including cursor pagination. */
+export declare function executeOperation(operation: V2OperationName, commandSpec: CommandSpec, operationSpec: OperationSpec, invocation: unknown[]): Promise<void>;
+export {};

package/dist/runtime/naming.d.ts

@@ -0,0 +1,25 @@
+import type { CommandSpec } from '../contract/types';
+import type { V2OperationName } from '../generated/v2-api';
+import type { OperationSpec } from './types';
+/**
+ * The spelling a caller types for a wire field, or `null` when there is none.
+ *
+ * Resolved through the same helpers the command builder uses, never by
+ * kebab-casing the wire name: `folderPath` is typed `--folder` and
+ * `knowledgeBaseIds` is typed `--kb`, so a mechanical translation would name
+ * flags that do not exist — strictly worse than leaving the wire name alone.
+ */
+export declare function spellingFor(operation: V2OperationName, commandSpec: CommandSpec, operationSpec: OperationSpec, field: string): string | null;
+/**
+ * Restates a server validation error in the spellings the terminal accepts.
+ *
+ * The API names its own fields, correctly — `drop includeJobRuns` is right for
+ * an OpenAPI reader and untypeable here, where the flag is
+ * `--include-job-runs`. Applied at the one frame that still holds the
+ * operation, its command spec and its operation spec; by the time the error
+ * reaches the entrypoint that context is gone.
+ *
+ * A CLI-raised error (`status: 0`) is already phrased in flags and passes
+ * through untouched, as does anything that is not a `SimApiError`.
+ */
+export declare function retypeApiError(error: unknown, operation: V2OperationName, commandSpec: CommandSpec, operationSpec: OperationSpec): unknown;

package/dist/runtime/options.d.ts

@@ -0,0 +1,7 @@
+import { type Command } from 'commander';
+import type { CommandSpec } from '../contract/types';
+import type { V2OperationName } from '../generated/v2-api';
+import type { OperationSpec } from './types';
+export declare const DEFAULT_LIMIT = 100;
+/** Adds request-field and safety options for one generated operation. */
+export declare function addOperationOptions(command: Command, operation: V2OperationName, commandSpec: CommandSpec, operationSpec: OperationSpec): void;

package/dist/runtime/renamed.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Support for spellings the CLI has moved on from.
+ *
+ * A rename is not an alias. {@link CommandSpec.aliases} are ergonomic shorthands
+ * — `ls`, `mv` — that the CLI wants people to use, so they appear in help. A
+ * renamed spelling is kept only so a script written against the old name keeps
+ * working: it stays out of help and out of the generated docs, and says once,
+ * on stderr, what to write instead.
+ *
+ * Warnings go to stderr rather than stdout because the old name is most likely
+ * to survive inside exactly the kind of script that pipes stdout into `jq`, and
+ * a deprecation notice in the middle of a JSON document is a worse bug than the
+ * one it reports.
+ */
+/** Announces a command path that has been renamed, naming its current spelling. */
+export declare function warnRenamedCommand(from: string, to: string): void;
+/** Announces a flag that has been renamed, naming its current spelling. */
+export declare function warnRenamedFlag(from: string, to: string): void;
+/** Test seam: renames warn once per process, and each test needs a clean slate. */
+export declare function resetRenameWarnings(): void;

package/dist/runtime/request.d.ts

@@ -0,0 +1,109 @@
+import type { CommandSpec, FlagSpec } from '../contract/types';
+import { type V2OperationName } from '../generated/v2-api';
+import { type QueryValue } from '../http/client';
+import type { OperationSpec } from './types';
+/** One request field, as the generator describes it. */
+export interface FieldSpec {
+    kind: 'string' | 'number' | 'integer' | 'boolean' | 'enum' | 'array' | 'object' | 'unknown';
+    required?: boolean;
+    values?: readonly string[];
+    default?: unknown;
+    /** The field's `.describe()` from the route contract, used as `--help` text. */
+    describe?: string;
+}
+/**
+ * The workspace never becomes a flag.
+ *
+ * It is the one field every workspace-scoped operation declares, and it comes
+ * from the profile — surfacing it as `--workspace-id` on 30-odd commands would
+ * duplicate the global `--workspace` and invite the two to disagree.
+ */
+export declare const PROFILE_INJECTED_FIELD = "workspaceId";
+/** Whether this path segment comes from the active profile's workspace. */
+export declare function isProfileWorkspacePath(commandSpec: CommandSpec, param: string): boolean;
+/**
+ * The slot a cursor-paginated operation carries its `cursor` field in.
+ *
+ * Pagination, not the name of a field, is what makes `limit` a page size. It
+ * lives here rather than beside its reader in `execute.ts` because `options.ts`
+ * has to ask the same question while it builds the flag, and importing
+ * `execute.ts` from `options.ts` would close a module cycle — `execute.ts`
+ * already reads `DEFAULT_LIMIT` from `options.ts`.
+ */
+export declare function cursorSlot(operationSpec: Pick<OperationSpec, 'query' | 'body'>): 'query' | 'body' | null;
+export declare function flagSpecFor(operation: V2OperationName, field: string): FlagSpec;
+/**
+ * Long and short flags the root program has already claimed.
+ *
+ * Commander matches the root's own options across the whole of argv, including
+ * after a subcommand name, so a leaf that declares one of these never sees what
+ * the caller typed. The two failure modes differ only in how loud they are:
+ * `--version` and `--help` terminate, so `sim workflows rollback wf_1 --version
+ * 1` printed the CLI version and exited `0` without issuing a request; the
+ * root's value flags do not terminate, so a colliding leaf simply reads
+ * `undefined` and acts as though the flag were never typed.
+ */
+export declare const RESERVED_PROGRAM_FLAGS: ReadonlySet<string>;
+/** The flag name a field is exposed under, honouring any contract override. */
+export declare function flagNameFor(operation: V2OperationName, field: string): string;
+/** The named option used for a path parameter that is contextual rather than primary. */
+export declare function pathFlagNameFor(commandSpec: CommandSpec, param: string): string;
+export declare function takesJson(field: FieldSpec, flag: FlagSpec): boolean;
+export declare function readArgumentSource(raw: string, flagName: string): Promise<{
+    text: string;
+    from: string;
+}>;
+/**
+ * Reads a primitive list from argv or a newline-delimited file.
+ *
+ * Exported for the one augmentation that has to read a list before the
+ * generated path does (`workflows runs get --select-output`), so a `@-` or
+ * `@path` source is read exactly once, by whichever of the two sees it first.
+ */
+export declare function readListValues(raw: unknown, flagName: string): Promise<string[]>;
+/**
+ * Rewrites one folder path into the API's canonical wire form.
+ *
+ * The wire form encodes each segment, so `/Folder 1` in the app is
+ * `/Folder%201` to the API — and typing the name you can see was rejected with
+ * a message that never said the word encoding. Splitting on `/` first is what
+ * keeps the separators: `encodeURIComponent` over the whole path would turn
+ * every one of them into `%2F` and address a single top-level folder whose name
+ * contains slashes.
+ *
+ * Decoding each segment before encoding it is what makes this idempotent, and
+ * it has to be: the encoded spelling is what the CLI prints today, what the
+ * README shows, and therefore what people will paste back. `/Folder 1` and
+ * `/Folder%201` must reach the same folder, and `%2520` is the failure to
+ * avoid. The limit of that rule is a folder whose name really contains a `%`
+ * followed by two hex digits — `100%20off` reads as `100 off`. A stray `%` is
+ * safe, because it fails to decode and is encoded literally, and the ambiguous
+ * name can always be typed in its encoded form (`100%2520off`).
+ */
+export declare function encodeFolderPath(value: string): string;
+/**
+ * Turns the string argv provides into the value the contract expects.
+ *
+ * Every failure names the flag rather than the field, because the flag is what
+ * the caller typed — and every one of these is caught before any request is
+ * made, so a typo costs nothing.
+ */
+export declare function coerce(raw: unknown, field: FieldSpec, flag: FlagSpec, flagName: string): Promise<unknown>;
+export interface BuiltRequest {
+    path: string;
+    query: Record<string, QueryValue>;
+    body: Record<string, unknown> | undefined;
+    /** Contract-declared request headers, absent when the operation declares none. */
+    headers?: Record<string, string>;
+}
+/**
+ * Assembles one operation's HTTP request from positional args, parsed flags,
+ * and the profile's workspace.
+ *
+ * Primary path params come from positional arguments in declared order. A
+ * contextual path param can instead come from a named option declared by the
+ * CLI contract. Every other field is looked up by its flag name in the slot the
+ * API contract declares it in, so a field that moved from query to body moves
+ * here on the next regeneration.
+ */
+export declare function buildRequest(operation: V2OperationName, positional: string[], flags: Record<string, unknown>, workspaceId: string | null): Promise<BuiltRequest>;

package/dist/runtime/result.d.ts

@@ -0,0 +1,50 @@
+import type { OutputFormat } from '../config/index';
+import type { CommandSpec } from '../contract/types';
+import type { V2OperationName } from '../generated/v2-api';
+interface RenderResultOptions {
+    expandedTrace?: boolean;
+}
+/**
+ * Undoes the wire encoding of a folder path for the human formats.
+ *
+ * The inverse of `encodeFolderPath`, per segment for the same reason: `%2F` is
+ * a slash inside one folder's name, not a separator. A segment that fails to
+ * decode is shown as it arrived rather than dropped — the point is to show the
+ * name, and a malformed one is still the truth about what the server holds.
+ *
+ * A segment whose decoded name contains the separator is shown in wire form for
+ * the same reason: decoding it would print a root folder named `a/b` as
+ * `/a/b`, byte-identical to a folder `b` nested under `a` — and the printed
+ * path is what people paste back, so `folders delete` addressed the other
+ * folder. Rendering must not manufacture structure that is not there.
+ *
+ * Callers must reach this only from a `table` or `text` rendering path — the
+ * hand-written `ls` builds its own columns and so decodes through here directly.
+ * `json` and `yaml` render from the raw payload so that switching format never
+ * changes the data, and a script piping a path back needs the wire form.
+ */
+export declare function decodeFolderPath(value: string): string;
+export declare function renderPage(format: OutputFormat, rows: unknown[], spec: CommandSpec, envelope?: unknown, options?: {
+    truncated?: boolean;
+}): void;
+/**
+ * Carries a truncation stated on any page, not only the first.
+ *
+ * The envelope is otherwise the first page's, because a fact about the whole
+ * query (billing's `scope`) is stated once — but `toolNamesTruncated` is
+ * computed per page, so a walk that clipped on page 7 would have said nothing.
+ */
+export declare function foldPageEnvelope(current: unknown, page: unknown): unknown;
+/**
+ * States that the walk stopped at `--limit` while more pages remained.
+ *
+ * `sim tools list` answered 100 of 4708 rows with an exit code of 0 and nothing
+ * on stderr, in every format — indistinguishable from a complete inventory.
+ * Said whenever a cursor survives, including when the caller set a small limit:
+ * the answer is incomplete either way, and the caller who capped it is the one
+ * most likely to reuse the result as if it were whole.
+ */
+export declare function writeCursorTruncation(count: number, truncated: boolean): void;
+/** Renders one non-paginated operation result according to its CLI contract. */
+export declare function renderResult(operation: V2OperationName, format: OutputFormat, raw: unknown, spec: CommandSpec, options?: RenderResultOptions, envelope?: unknown): void;
+export {};

package/dist/runtime/types.d.ts

@@ -0,0 +1,23 @@
+import type { RequestOptions } from '../http/client';
+import type { FieldSpec } from './request';
+export interface OperationSpec {
+    method: NonNullable<RequestOptions['method']>;
+    path: string;
+    pathParams: readonly string[];
+    /** `.describe()` per path parameter, used as positional-argument help. */
+    pathParamDocs?: Record<string, string>;
+    query?: Record<string, FieldSpec>;
+    body?: Record<string, FieldSpec>;
+    /** Contract-declared request headers, minus any the CLI sets itself. */
+    headers?: Record<string, FieldSpec>;
+    opaqueBody?: boolean;
+    summary?: string;
+    /**
+     * The operation rejects a workspace API key; only a personal one works.
+     *
+     * Emitted by `scripts/generate-v2-cli-api.ts` from the OpenAPI description so
+     * `--help` states the restriction the caller would otherwise meet as a `403`.
+     */
+    personalKeyOnly?: true;
+    responseMode?: 'json' | 'binary' | 'stream';
+}

package/dist/runtime.d.ts

@@ -0,0 +1,4 @@
+export { Command } from 'commander';
+export { SimApiError } from './http/client';
+export { buildProgram } from './program';
+export { runTerminalCli } from './terminal';