@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/command-support.d.ts

@@ -0,0 +1,438 @@
+import { JsonOptions, handleAsyncAction } from "./cli-output.js";
+import { type CliProfileSource } from "./cli-profile-context.js";
+import { type ProfileResolution, type StoredCredentials, type StoredProfileIdentity, type StoredOrganization } from "./credentials.js";
+import { type CliRunWaitConfig } from "./run-wait.js";
+import { type AutomaticSkillsInstallResult } from "./skills.js";
+import { type CollabSubjectKind } from "@oxygen/shared/collab";
+/** `--on` / `--path` help, shared by every command that addresses a subject. */
+export declare const COLLAB_SUBJECT_REF_HELP: string;
+export declare const COLLAB_SUBJECT_PATH_HELP = "Narrow to a sub-object: \"row:<rowId>\" for one row, \"row:<rowId>#<columnKey>\" for one cell, or \"column:<columnKey>\" for one column.";
+/**
+ * Both group descriptions end with this, because a surface that is one release
+ * old should say so where a user meets it. Beta here means exactly what it means
+ * for Agents, the Knowledge Graph, and Recipes: WEB NAV VISIBILITY. Nothing
+ * about the gate, the client role, or credit rules is softened by the toggle,
+ * and this command group is reachable at either setting — which is what keeps a
+ * gate armed from the terminal answerable from the terminal.
+ */
+export declare const COLLAB_BETA_NOTE: string;
+/**
+ * Parse `--on <kind>:<id>`. Client-side so a typo costs no round trip and the
+ * error can list every legal kind — `parseSubjectRef` already throws a typed
+ * `invalid_subject_ref` (exit 2) carrying `details.valid_kinds`.
+ */
+export declare function requireCollabSubject(value: string | undefined): {
+    kind: CollabSubjectKind;
+    id: string;
+};
+/** Validate and canonicalize `--path`; undefined when the flag was not passed. */
+export declare function readCollabPath(value: string | undefined): string | undefined;
+export type DirectoryUpdateOptions = JsonOptions & {
+    name?: string;
+    slug?: string;
+    logoUrl?: string;
+    logoFile?: string;
+    tagline?: string;
+    description?: string;
+    descriptionFile?: string;
+    website?: string;
+    companyLinkedin?: string;
+    foundersJson?: string;
+    bookingUrl?: string;
+    contactEmail?: string;
+    services?: string;
+    regions?: string;
+    profileJson?: string;
+};
+export type LogoutOptions = JsonOptions & {
+    profile?: string;
+    all?: boolean;
+};
+export type LinkedinAccountsConnectOptions = JsonOptions & {
+    reconnect?: string;
+    country?: string;
+    salesNav?: boolean;
+    cookieAuth?: boolean;
+    customProxy?: boolean;
+    count?: string;
+    inboxScope?: string;
+    acknowledgeRisk?: boolean;
+    ownerConsent?: boolean;
+    established?: boolean;
+    shareLink?: boolean;
+};
+export type LinkedinAccountsSyncOptions = JsonOptions & {
+    connectionId?: string;
+};
+export type TablesDeleteOptions = JsonOptions & {
+    now?: boolean;
+    yes?: boolean;
+    purgeAfter?: string;
+    reason?: string;
+};
+export type CrmPhotosOptions = JsonOptions & {
+    limit?: string;
+    live?: boolean;
+    dryRun?: boolean;
+};
+export type CrmSignalRecordOptions = JsonOptions & {
+    event?: string;
+    externalEventId?: string;
+    email?: string;
+    linkedinUrl?: string;
+    companyDomain?: string;
+    companyName?: string;
+    firstName?: string;
+    lastName?: string;
+    pageUrl?: string;
+    sessionId?: string;
+    payloadJson?: string;
+};
+export type CrmLeadsTodayOptions = JsonOptions & {
+    limit?: string;
+    withinDays?: string;
+};
+export type ContextProfileUpdateOptions = JsonOptions & {
+    dataJson?: string;
+    summary?: string;
+};
+export type ContextResolveOptions = JsonOptions & {
+    purpose?: string;
+    assetType?: string;
+    assetStatus?: string;
+    tags?: string;
+    includeArchived?: boolean;
+    maxAssets?: string;
+    requireReady?: boolean;
+};
+export type KnowledgeSyncOptions = JsonOptions & {
+    full?: boolean;
+    ifStale?: boolean;
+    ttl?: string;
+    all?: boolean;
+};
+export type TableRunsListOptions = JsonOptions & {
+    table?: string;
+    status?: string;
+    limit?: string;
+    format?: string;
+    output?: string;
+};
+export type TableRunsWaitOptions = JsonOptions & {
+    timeoutSeconds?: string;
+    intervalSeconds?: string;
+};
+export declare const CADENCE_FLAG_DESCRIPTION = "Shorthand schedule: hourly, every_6h, daily@<hour>, or weekly@<day><hour> (e.g. weekly@mon9). Hours 0-23 UTC.";
+export type LimitOptions = JsonOptions & {
+    limit?: string;
+};
+export type WhoamiResponse = {
+    user: {
+        id: string;
+        email: string | null;
+        firstName?: string | null;
+        lastName?: string | null;
+    };
+    organization: {
+        id: string;
+        name: string;
+        slug: string | null;
+        billing_owner_organization_id?: string | null;
+        shared_billing?: boolean;
+        monthly_credit_cap?: number | null;
+        plan_tier?: string;
+        plan_name?: string;
+    };
+    membership?: {
+        id: string;
+        role: string;
+    };
+    apiKey?: {
+        id: string;
+        name: string;
+        tokenPrefix: string;
+        tokenSuffix: string;
+        kind?: "org_api_key" | "user_session" | "oauth";
+    };
+    authType?: "org_api_key" | "user_session" | "oauth";
+};
+export type OrganizationOption = WhoamiResponse["organization"] & {
+    clerkOrgId?: string | null;
+    iconUrl?: string | null;
+    membership?: {
+        id?: string;
+        role: string;
+        clerkOrgId?: string;
+        clerkUserId?: string;
+    };
+    selected?: boolean;
+};
+export type OrgsCredentialBlock = {
+    kind?: string;
+    switchable?: boolean;
+    reason?: string;
+    message?: string;
+    next_commands?: string[];
+    web_url?: string;
+};
+export type OrgsListResponse = {
+    user: WhoamiResponse["user"];
+    currentOrganization: OrganizationOption | null;
+    organizations: OrganizationOption[];
+    selectionRequired?: boolean;
+    credential?: OrgsCredentialBlock;
+    web_url?: string;
+};
+export type OrgsSelectResponse = {
+    user: WhoamiResponse["user"];
+    currentOrganization: OrganizationOption;
+    credential?: OrgsCredentialBlock;
+};
+export declare const TABLE_INGESTION_WAIT_DEFAULT_TIMEOUT_SECONDS = 600;
+export declare const TABLE_INGESTION_WAIT_DEFAULT_INTERVAL_SECONDS = 5;
+export declare function formatDisabledWorkflowNotices(data: unknown): string[];
+export declare function writeListCapNotice(data: unknown, noun: string, hint?: string): void;
+export declare function parseJsonArray(value: string): unknown[];
+/**
+ * Parse a JSON command-input value, mapping `JSON.parse` syntax failures to a
+ * typed `invalid_json` envelope. A raw `JSON.parse` throw is an ordinary `Error`,
+ * which `@oxygen/shared`'s `toFailure` flattens to a machine-hostile
+ * `unexpected_error`; routing through here keeps malformed user JSON actionable.
+ * Shape validation, where a caller needs it, stays with the caller. `inputName`
+ * is the user-facing flag or source label, e.g. "--steps-file".
+ */
+export declare function parseJsonValue(value: string, inputName: string): unknown;
+/**
+ * Read a local file and parse it as JSON command input, surfacing syntax
+ * failures as a typed `invalid_json` envelope tagged with `inputName`. File-read
+ * errors (missing/unreadable path) propagate unchanged — they are not JSON.
+ */
+export declare function readJsonFileValue(path: string, inputName: string): unknown;
+export declare function readFileIfPresent(value: string): string;
+export declare function readPublishingPostText(options: {
+    text?: string;
+    textFile?: string;
+}, required: true): string;
+export declare function readPublishingPostText(options: {
+    text?: string;
+    textFile?: string;
+}, required: false): string | null;
+export declare function readPublishingTextFile(textFile: string, flag?: string): string;
+export declare function splitCommaList(value: string | undefined): string[];
+export declare function buildCrmSignalRecordBody(options: CrmSignalRecordOptions): Record<string, unknown>;
+export declare function buildCrmLeadsTodayPath(options: CrmLeadsTodayOptions): string;
+export declare function isUuid(value: string): boolean;
+export declare function tableWebhookDeliveriesPath(options: {
+    endpointId?: string | undefined;
+    table?: string | undefined;
+    status?: string | undefined;
+    autoRunStatus?: string | undefined;
+    limit?: string | undefined;
+}): string;
+export declare function tableRunsListPath(options: TableRunsListOptions & {
+    traceId?: string;
+}): string;
+export declare function readRangeOption(value: string | undefined, flag: string): {
+    min?: number;
+    max?: number;
+} | null;
+export declare function readSearchPlanJson(value: string): Record<string, unknown>;
+export declare function readFilterSelectionOption(value: string | undefined): Record<string, unknown> | undefined;
+export declare function readFilterJsonOption(value: string | undefined): Record<string, unknown>[] | undefined;
+export declare function readFormulaValuesOption(value: string | undefined): "materialized" | null;
+interface GetSurfaceRunWaitParams {
+    retryTransientNetworkErrors?: boolean;
+    runId: string;
+    endpoint: string;
+    view?: string;
+    requestedTimeoutSeconds?: string | undefined;
+    requestedIntervalSeconds?: string | undefined;
+    defaultTimeoutSeconds: number;
+    defaultIntervalSeconds: number;
+    isTerminal: (status: string | null) => boolean;
+    runKey: string;
+    runIdKey: string;
+    timeoutCode: string;
+    timeoutMessage: string;
+    timeoutDetailIdKey: string;
+}
+export declare function buildGetSurfaceRunWaitConfig(params: GetSurfaceRunWaitParams): CliRunWaitConfig;
+export declare function waitForTableActionRun(runId: string, options: TableRunsWaitOptions): Promise<Record<string, unknown>>;
+export type QueryColumnDescriptor = {
+    id?: string;
+    key: string;
+    label?: string;
+    dataType?: string;
+    kind?: string;
+    semanticType?: string | null;
+    definition?: Record<string, unknown>;
+    position?: number;
+    /**
+     * The fields this column's output declares — what `{{column.path}}` can name.
+     * Absent for a column that declares nothing.
+     */
+    output_fields?: Array<{
+        path: string;
+        label?: string;
+        dataType?: string | null;
+    }>;
+};
+export type DescribeTableResponse = {
+    table?: {
+        id?: string;
+        slug?: string;
+        displayName?: string;
+        name?: string;
+        projectSlug?: string;
+    };
+    columns?: QueryColumnDescriptor[];
+};
+export declare function normalizeExportRowsFormat(value: string | undefined): "json" | "jsonl" | "csv" | "table";
+export declare function formatRows(rows: Record<string, unknown>[], format: "json" | "jsonl" | "csv" | "table", columns?: Array<{
+    key: string;
+    label?: string;
+    dataType?: string;
+}>): {
+    content: string;
+    rescuedCount: number;
+};
+export declare function clipCell(value: string, width: number): string;
+export declare function readCount(value: unknown): number;
+/**
+ * Hops one and two of the avatar upload: presign, then PUT the raw bytes straight
+ * to Oxygen object storage. Returns the storage key the caller confirms with.
+ *
+ * Shared because two commands stage the same bytes in the same bucket and then
+ * diverge: `managed-inboxes upload-avatar` confirms against the avatars route to
+ * get a public URL to paste into an order, while `senders profiles set-photo`
+ * hands the key to the profile writer as `avatar_upload_key`, which re-checks org
+ * ownership and re-sniffs the bytes itself. Copying the two hops into the second
+ * caller would have duplicated the abort timeout and the failure taxonomy, and
+ * the copy is exactly where they drift.
+ */
+export declare function putAvatarBytesToStorage(path: string): Promise<string>;
+export declare function readRecord(value: unknown, key: string): Record<string, unknown> | null;
+export declare function isTerminalTableIngestionStatus(status: string | null): boolean;
+export type ProfileSource = CliProfileSource;
+export type ResolvedProfileContext = {
+    resolution: ProfileResolution;
+    source: ProfileSource;
+};
+export declare function resolveActiveProfileWithSource(): Promise<ResolvedProfileContext>;
+/**
+ * Write a completed org selection back onto the stored profile.
+ *
+ * Shared by `orgs use` and `oxygen login --org` so the two-step (log in, then
+ * switch) and the one-step collapse cannot drift apart.
+ *
+ * Gated on the credential being one that can actually carry a selection: an
+ * org-bound key's active workspace is a property of the key, not of the profile,
+ * so persisting a different one would only produce a profile that lies about
+ * where its commands land.
+ */
+export declare function persistOrganizationSelection(input: {
+    profile: string | null;
+    credentials: StoredCredentials | null;
+    organization: OrganizationOption | null | undefined;
+}): Promise<boolean>;
+export declare function shellQuote(value: string): string;
+export declare function handleLogoutAction(options: LogoutOptions): Promise<void>;
+export type LoginIdentity = {
+    credentials: StoredCredentials;
+    whoami: WhoamiResponse | null;
+    user: WhoamiResponse["user"];
+    activeOrganization: StoredOrganization | null;
+    organizations: OrganizationOption[];
+    selectionRequired: boolean;
+};
+export declare function resolveLoginIdentity(token: string, apiUrl: string): Promise<LoginIdentity>;
+export declare function pickProfileForLogin(loginIdentity: LoginIdentity): Promise<{
+    name: string;
+    renamed: boolean;
+}>;
+export declare function readEnvProfileName(): string | null;
+export declare function identityFromWhoami(response: WhoamiResponse): StoredProfileIdentity;
+export declare function storedOrganizationFromOption(organization: Pick<OrganizationOption, "id" | "name" | "slug">): StoredOrganization;
+export declare function buildPostLoginHint(activeProfile: string): Promise<string>;
+export declare function formatLoginSuccessForResolved(loginIdentity: LoginIdentity, profile: string, options?: {
+    renamed?: boolean;
+    skillsInstall?: AutomaticSkillsInstallResult;
+}): string;
+export declare function formatFingerprint(hex: string): string;
+export declare function createCredentialFingerprint(token: string): string;
+/** Column-aligned plain-text table, two-space indented. Shared by the sequence-variant lenses and the collaboration lists. */
+export declare function renderTextTable(headers: string[], rows: string[][]): string[];
+/** A read command that prints a readable block instead of the raw envelope.
+ *  `--json` still emits the untouched API envelope, so the lens is presentation
+ *  only and never becomes a second contract. Used by the sequencer lenses and by
+ *  `crm objects`. */
+export declare function handleReadActionWithLens(command: string, options: JsonOptions, action: () => Promise<unknown>, render: (data: Record<string, unknown>) => string): Promise<void>;
+export declare function handleCollabAction(command: string, options: JsonOptions, action: () => Promise<unknown>, render: (data: Record<string, unknown>) => string): Promise<void>;
+export declare function collabStyles(): {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+};
+export declare function collabText(value: unknown, fallback?: string): string;
+export declare function collabLink(data: Record<string, unknown>): string | null;
+/** Coarse age for a list column: seconds, minutes, hours, then days. */
+export declare function formatCollabAge(value: unknown): string;
+/** First line of a body, clipped — a thread's subject line in one cell. */
+export declare function collabSnippet(value: unknown, width?: number): string;
+/** Trailer every collab render shares: what to do next, then the deep-link. */
+export declare function collabTrailer(data: Record<string, unknown>): string[];
+/**
+ * Generic confirmation for a write whose payload is one object. The API already
+ * writes a `next_step` sentence for each of these, so the renderer's only job is
+ * to say what changed and keep the deep-link visible.
+ */
+export declare function formatCollabWriteResult(data: Record<string, unknown>): string;
+export declare function describeProfileSource(source: ProfileSource): string;
+export declare function formatAutomaticSkillsInstallStatusLines(result?: AutomaticSkillsInstallResult): string[];
+export declare function ansi(enabled: boolean): {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+};
+export declare function collectRepeatable(value: string, previous: string[]): string[];
+export declare function readSelectedTranscriptExcerpt(text: string): string;
+export declare function readCsvOption(value: string | undefined): string[];
+export declare function buildDirectoryProfileBody(options: DirectoryUpdateOptions): Promise<Record<string, unknown>>;
+export declare function collectMultiple(value: string, previous: string[]): string[];
+export declare function buildContextResolveBody(options: ContextResolveOptions): Record<string, unknown>;
+export declare const KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES = 15;
+type KnowledgeMirrorTarget = {
+    dir: string;
+    apiHost: string;
+    orgId: string;
+    webUrl: string;
+};
+export declare function knowledgeMirrorTargetFor(apiUrl: string, orgId: string): KnowledgeMirrorTarget;
+export declare function resolveKnowledgeMirrorTarget(): Promise<KnowledgeMirrorTarget>;
+export declare function runKnowledgeMirrorSync(// skipcq: JS-R1005 -- one linear sync pipeline: staleness gate, lock, delta loop, generated files.
+options: KnowledgeSyncOptions, orgOverride?: {
+    orgId: string;
+    selector: string;
+}): Promise<Record<string, unknown>>;
+export declare function runKnowledgeMirrorSyncAll(options: KnowledgeSyncOptions): Promise<Record<string, unknown>>;
+export declare function readPositiveNumber(value: string | undefined, nextStep?: string): number | undefined;
+/**
+ * A spend ceiling where ZERO IS VALID and meaningful: `find company
+ * --max-credits 0` asks for the lanes that cost nothing (crustdata's identify
+ * lane resolves domain↔LinkedIn for 0 credits) and skips every priced one.
+ * readPositiveNumber rejected it client-side, so the free lanes were
+ * unreachable from the CLI at all (Plain T-111). Fractional ceilings stay legal
+ * — lane estimates are fractional — so this is not the whole-number reader.
+ */
+export declare function readCreditCeilingOrZero(value: string | undefined): number | undefined;
+/**
+ * A whole count (days, rows, windows). Its positive-number sibling accepts 2.5,
+ * which for a scan bound is always a typo — rejected here so it costs no round trip,
+ * and rejected rather than rounded so a bound nobody asked for is never scanned.
+ */
+export declare function readPositiveInteger(value: string | undefined): number | undefined;
+export declare function readNonNegativeNumber(value: string | undefined): number | undefined;
+export type ExtractedCommandActionHandler = typeof handleAsyncAction;
+export {};