@skrr-ai/cli 0.1.127 → 0.1.128

package/dist/lib/northstars.d.ts

@@ -1,25 +1,3 @@
-/**
- * northstars.ts — request-based client for the Northstar portfolio layer
- * (`/api/northstars/*`) and its Portfolio Governor.
- *
- * A **Northstar** groups and prioritizes many Commitments without owning their
- * loop. The **Governor** is a MODE of its periodic review, not a separate
- * entity: a review rolls portfolio health up, allocates each Commitment a
- * cadence band and run budget, and emits TYPED management intents that a single
- * router turns into `CommitmentControl` mutations — advisory, awaiting a human,
- * or (narrowly) automatic.
- *
- * Two dials, deliberately separate:
- *   - `analysisMode`  — does an Agent get to think about this portfolio?
- *   - `executionMode` — how much write authority does the outcome carry?
- *
- * Both default to the safe end (`deterministic` / `advisory`), which is exactly
- * what a Northstar did before the Governor existed.
- *
- * Every vocabulary below is RE-EXPORTED from `@skrr-ai/data-provider`, never
- * re-declared. The API validates against those exact strings; a second copy here
- * is how the CLI silently drifts from the server that rejects it.
- */
 import { NORTHSTAR_ANALYSIS_MODES, NORTHSTAR_APPROVAL_TRIGGERS, NORTHSTAR_EXECUTION_MODES, NORTHSTAR_INTENT_VERDICTS, NORTHSTAR_MANAGEMENT_INTENT_KINDS, NORTHSTAR_REVIEW_STATUSES } from '@skrr-ai/data-provider';
 import type { Northstar, NorthstarAnalysisMode, NorthstarExecutionMode, NorthstarGovernance, NorthstarGovernanceStatus, NorthstarGovernanceUpdateParams, NorthstarListResponse, NorthstarManagementIntent, NorthstarManagementIntentKind, NorthstarRecommendation, NorthstarReviewRecord, NorthstarStatusResponse } from '@skrr-ai/data-provider';
 import { withQuery } from './triggers';
@@ -33,6 +11,16 @@ export type { Northstar, NorthstarAnalysisMode, NorthstarExecutionMode, Northsta
 export declare const NORTHSTAR_STATUSES: readonly ["active", "paused", "achieved", "archived"];
 export declare const NORTHSTAR_PRIORITY_TIERS: readonly ["critical", "high", "medium", "low"];
 export declare const NORTHSTAR_RECOMMENDATION_STATUSES: readonly ["open", "applied", "dismissed"];
+/**
+ * What a configure that changed the allocation inputs (the run budget, the critical reserve, the
+ * cadence band) says it did to the linked commitments. Additive on the server: absent from an
+ * older server, `allocationsPending` only when non-zero, `allocationsRefreshFailed` only on failure.
+ */
+export type AllocationRefreshFields = {
+    allocationsRefreshed?: number;
+    allocationsPending?: number;
+    allocationsRefreshFailed?: boolean;
+};
 export declare const northstarApi: {
     list: (query?: Parameters<typeof withQuery>[1]) => Promise<NorthstarListResponse>;
     create: (body: Record<string, unknown>) => Promise<Northstar>;
@@ -51,23 +39,169 @@ export declare const northstarApi: {
         northstarId: string;
         northstarVersion: number;
         governance: NorthstarGovernance;
-    }>;
+    } & AllocationRefreshFields>;
     reviews: (id: string, query?: Parameters<typeof withQuery>[1]) => Promise<{
         data: NorthstarReviewRecord[];
+        has_more?: boolean;
     }>;
     review: (id: string, reviewId: string) => Promise<NorthstarReviewRecord>;
     reviewNow: (id: string) => Promise<Record<string, unknown>>;
     intents: (id: string, query?: Parameters<typeof withQuery>[1]) => Promise<{
         data: NorthstarManagementIntent[];
+        has_more?: boolean;
     }>;
     decideIntent: (id: string, intentId: string, body: Record<string, unknown>) => Promise<Record<string, unknown>>;
 };
 /** ms → a short human duration, for a table cell that must stay narrow. */
 export declare function humanMs(ms?: number): string;
 export declare function shortDate(value?: string): string;
+export declare const NORTHSTAR_REASON_WORDS: Readonly<Record<string, string>>;
+/** A code in words; an unknown code comes back unchanged, an absent one says so. */
+export declare function describeNorthstarReason(code: string | null | undefined): string;
+export type NorthstarDecisionContext = {
+    northstarId: string;
+    intentId: string;
+    decision: 'approve' | 'reject';
+    /** The CLI binary name, for the command a sentence tells the reader to run. */
+    bin?: string;
+};
+/**
+ * A refused decision, as one sentence with its next step.
+ *
+ * `body` is the server's refusal (`reason`, plus the context it adds: the two
+ * northstar versions, or when and by whom the intent was already decided).
+ */
+export declare function describeDecisionRefusal(body: Record<string, unknown>, ctx: NorthstarDecisionContext): {
+    code: string;
+    text: string;
+};
+export type NorthstarDecisionOutcome = {
+    /** The arrow line (`nsi_x → applied`), printed before any explanation. */
+    headline: string;
+    /** 0 only when the thing asked for now holds. */
+    exitCode: 0 | 1;
+    /** What to say after the headline. */
+    text?: string;
+    /** The raw code behind a non-zero exit, for `--json` and `Code:`. */
+    code?: string;
+};
+/**
+ * What a decision that the server ACCEPTED (HTTP 200) actually did.
+ *
+ * One exit rule: an approval exits 0 only when the intent is `applied`, and a
+ * rejection only when it is `rejected`. An approval the version fence
+ * invalidated, or one whose change has not landed, used to print a line shaped
+ * like success and exit 0, so a script could not tell it from one that worked.
+ */
+export declare function describeDecisionOutcome(result: Record<string, unknown>, ctx: NorthstarDecisionContext): NorthstarDecisionOutcome;
+/** What the server returned before `--limit` existed; sent explicitly so a page is never silently smaller. */
+export declare const NORTHSTAR_LIST_DEFAULT_LIMIT = 50;
+/**
+ * The footer under a list that was cut short. `has_more: false` used to be
+ * unconditional on these lists, so a page of `--limit` rows read as the whole
+ * answer; the server now says when there is more and this says what to do.
+ * Empty when the page is complete.
+ *
+ * `cursor` is true only for a list that can be paged (`northstars list`); the
+ * reviews and intents lists have no cursor, so their way on is a larger
+ * `--limit`, or a narrower `--status` once `--limit` is at its ceiling.
+ */
+export declare function listFooter(input: {
+    shown: number;
+    hasMore: boolean;
+    limit: number;
+    max: number;
+    nextCursor?: string | null;
+    cursor?: boolean;
+}): string;
 export declare function renderNorthstarList(rows: Northstar[], log: (line: string) => void): void;
+/**
+ * The active-commitment cap, in words. `0` is accepted and stored, and a review
+ * treats it as "no cap" (it does not flag every commitment over a cap of zero),
+ * so the screen says that rather than letting `0` read as a limit.
+ */
+export declare function describeMaxActive(value: number | undefined): string;
 export declare function renderNorthstar(status: NorthstarStatusResponse, log: (line: string) => void): void;
 export declare function renderRecommendationList(rows: NorthstarRecommendation[], log: (line: string) => void): void;
+/**
+ * No reviewer configured, a ready one, and an unreachable one are three
+ * different answers — and the third is the one an operator needs spelled out,
+ * because a scheduled review trigger says nothing about whether the agent that
+ * would run it is online.
+ */
+export declare function reviewerReadiness(reviewer: NorthstarGovernanceStatus['reviewer']): string;
+/** The `governance configure` flags that move what a commitment's allocation is computed from. */
+export declare const ALLOCATION_INPUT_FLAGS: readonly ["max-runs-per-day", "clear-max-runs-per-day", "critical-reserve", "min-interval-hours", "max-interval-hours", "max-relative-change"];
+export type AllocationRefresh = {
+    refreshed: number;
+    pending: number;
+    failed: boolean;
+};
+/** The refresh summary a configure response carries, or undefined from a server that sends none. */
+export declare function readAllocationRefresh(response: AllocationRefreshFields | undefined): AllocationRefresh | undefined;
+/**
+ * What `governance configure` says about the linked commitments. The server re-applies a changed
+ * budget or cadence band to every linked active commitment at once and answers how many it wrote,
+ * how many it could not, and whether the refresh itself failed; the command discarded all of it and
+ * re-read the status, so "nothing happened" and "applied to three" looked the same (OSK-21245).
+ *
+ * `inputsSent` is whether this call touched an allocation input: only then is "already up to date" a
+ * true statement, since a zero is also what an unrelated change (the analysis mode) answers.
+ */
+export declare function describeAllocationRefresh(refresh: AllocationRefresh | undefined, options: {
+    northstarId: string;
+    inputsSent: boolean;
+    bin?: string;
+}): {
+    lines: string[];
+    warnings: string[];
+};
+/**
+ * The `Allocations` line of `review-now`. The count is of commitments WRITTEN, so `0` does not say
+ * "nothing happened": it is what a review prints when a configure already applied the budget, or
+ * when no active commitment is linked, or when no review row could be opened to write under.
+ */
+export declare function describeReviewAllocations(result: {
+    review?: unknown;
+    allocations?: unknown;
+    attention?: unknown;
+}): string;
 export declare function renderGovernance(status: NorthstarGovernanceStatus, log: (line: string) => void): void;
+/**
+ * The automatic-change budget line.
+ *
+ * `0/day` is a MODE (automatic changes off, everything waits for approval), and `used` can
+ * legitimately exceed any cap, because the changes were made before the owner lowered it. A bare
+ * `2/0 used today · 0 left` collapses both into a ratio over 100% that says neither (OSK-21233).
+ */
+export declare function describeAutoBudget(budget: NorthstarGovernanceStatus['mutationBudget']): string;
+/** One cell of words for what a review did beyond "it ran"; empty when there is nothing to add. */
+export declare function reviewNote(review: NorthstarReviewRecord): string;
+/** `Reason` line of one review: the words, with the raw code kept beside them for grep. */
+export declare function describeReviewReason(reason: string): string;
 export declare function renderReviewList(reviews: NorthstarReviewRecord[], log: (line: string) => void): void;
-export declare function renderIntentList(intents: NorthstarManagementIntent[], log: (line: string) => void): void;
+/** `--wide` on every command that prints the intents table. */
+export declare const northstarWideFlag: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+export type IntentTableOptions = {
+    /** Never clip the reason, and keep the machine code beside it as `[code]`. */
+    wide?: boolean;
+    /** Terminal width to fit the table to; defaults to the real terminal, else 250. */
+    columns?: number;
+};
+/**
+ * The intents table.
+ *
+ * WHY is the HUMAN reason the governor wrote (`reason`), not the machine code in
+ * `verdictReason`, which says why an intent needed approval (`execution_mode_approval`)
+ * and is no reason for the change itself. The code stays in `--json`, and beside
+ * the sentence as `[code]` under `--wide`. By default the sentence is cut at a
+ * word boundary to what the terminal leaves after the other columns.
+ */
+export declare function renderIntentList(intents: NorthstarManagementIntent[], log: (line: string) => void, options?: IntentTableOptions): void;
+/**
+ * The line that says a review's intent budget cut something off. A cap of 0
+ * records nothing at all, which a screen reading "No management intents." made
+ * indistinguishable from a review with nothing to say; the count was only in
+ * `--json` (`deterministicSnapshot.truncatedIntents`).
+ */
+export declare function intentBudgetNote(truncated: unknown, cap?: unknown): string;