@skrr-ai/cli 0.1.128 → 0.1.130

package/dist/lib/iso-instant.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * One reading of "an ISO-8601 UTC instant" for every CLI flag that takes one.
+ *
+ * `tasks remind --at` and `tasks schedule --at` each had their own: remind ran
+ * `new Date(value)` behind a `/^\d{4}-\d{2}-\d{2}T/` check, and schedule forwarded
+ * the string and printed the server's zod issue. `new Date()` is the wrong tool
+ * for an instant, in two ways that both stored a different time than the one
+ * typed and said nothing (OSK-21504, OSK-21506):
+ *
+ *   - a time with no zone is read in the zone of the MACHINE running the CLI, so
+ *     the same command stored different instants on different laptops;
+ *   - a day that does not exist overflows into the next month
+ *     (`2027-02-30` is `2027-03-02`).
+ *
+ * The rule here is the one `tasks schedule --help` already states and the server's
+ * `z.string().datetime()` enforces: a calendar-real date, a time with seconds, and
+ * a literal `Z`. A numeric offset is refused too, even though it names an instant:
+ * the two commands must agree, and the server's schedule door does not take one.
+ *
+ * Never reads the machine's zone. Pure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUtcInstant = parseUtcInstant;
+exports.formatUtcInstant = formatUtcInstant;
+exports.formatLocalInstant = formatLocalInstant;
+exports.describeInstant = describeInstant;
+const EXAMPLE = '2026-12-01T09:00:00Z';
+const UTC_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d+)?Z$/;
+const ZONELESS = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?$/;
+const OFFSET = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?([+-])(\d{2}):?(\d{2})$/;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+/**
+ * What is wrong with the calendar part, or `null` when the date exists.
+ * Checked by construction rather than by `new Date()`, which accepts the overflow.
+ */
+function calendarProblem(year, month, day) {
+    if (month < 1 || month > 12)
+        return `month ${String(month).padStart(2, '0')} does not exist`;
+    const last = daysInMonth(year, month);
+    if (day < 1 || day > last) {
+        return `${MONTH_NAMES[month - 1]} ${year} has ${last} days, so day ${String(day).padStart(2, '0')} does not exist`;
+    }
+    return null;
+}
+function clockProblem(hour, minute, second) {
+    if (hour > 23 || minute > 59 || second > 59) {
+        return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}:${String(second).padStart(2, '0')} is not a time of day`;
+    }
+    return null;
+}
+function rule(label) {
+    return `${label} must be an ISO-8601 UTC time ending in Z, for example ${EXAMPLE}`;
+}
+/**
+ * Parse a flag value as a UTC instant, or say precisely what is wrong with it.
+ *
+ * `label` is what the user typed (`--at`, `scheduledFor`), so the message names
+ * their input rather than a REST field they never saw.
+ */
+function parseUtcInstant(raw, label = '--at') {
+    const value = String(raw ?? '').trim();
+    const fail = (problem, reason) => ({
+        ok: false,
+        problem,
+        message: `${rule(label)}. ${reason}`,
+    });
+    const utc = UTC_INSTANT.exec(value);
+    if (utc) {
+        const [year, month, day, hour, minute, second] = utc.slice(1, 7).map(Number);
+        const calendar = calendarProblem(year, month, day);
+        if (calendar)
+            return fail('not_a_real_date', `"${value}" is not a real date: ${calendar}.`);
+        const clock = clockProblem(hour, minute, second);
+        if (clock)
+            return fail('not_a_real_time', `"${value}" is not a real time: ${clock}.`);
+        const date = new Date(value);
+        if (Number.isNaN(date.getTime())) {
+            return fail('not_a_date', `"${value}" is not a date.`);
+        }
+        return { ok: true, date, iso: date.toISOString() };
+    }
+    const zoneless = ZONELESS.exec(value);
+    if (zoneless) {
+        return fail('no_zone', `"${value}" has no time zone, so it could mean a different moment on each machine. ` +
+            `Add Z if it is UTC, or convert it to UTC first.`);
+    }
+    const offset = OFFSET.exec(value);
+    if (offset) {
+        const [year, month, day, hour, minute] = offset.slice(1, 6).map(Number);
+        const second = Number(offset[6] ?? 0);
+        const sign = offset[8] === '-' ? -1 : 1;
+        const shiftMinutes = sign * (Number(offset[9]) * 60 + Number(offset[10]));
+        let converted = '';
+        if (!calendarProblem(year, month, day) && !clockProblem(hour, minute, second)) {
+            const at = new Date(Date.UTC(year, month - 1, day, hour, minute, second) - shiftMinutes * 60_000);
+            converted = ` (${value} is ${at.toISOString().replace(/\.000Z$/, 'Z')})`;
+        }
+        return fail('numeric_offset', `Numeric offsets such as ${offset[8]}${offset[9]}:${offset[10]} are not accepted; convert the time to UTC and end it with Z${converted}.`);
+    }
+    const dateOnly = DATE_ONLY.exec(value);
+    if (dateOnly) {
+        const calendar = calendarProblem(Number(dateOnly[1]), Number(dateOnly[2]), Number(dateOnly[3]));
+        return fail(calendar ? 'not_a_real_date' : 'date_only', calendar
+            ? `"${value}" is not a real date: ${calendar}.`
+            : `"${value}" is a date without a time; add a time of day, e.g. ${value}T09:00:00Z.`);
+    }
+    return fail('not_a_date', `"${value}" is not an ISO-8601 date and time.`);
+}
+/** `2027-02-02T09:00:00Z` - the instant in UTC, whole seconds when there are no milliseconds. */
+function formatUtcInstant(date) {
+    return date.toISOString().replace(/\.000Z$/, 'Z');
+}
+/**
+ * `2027-02-02 01:00:00 PST` - the same instant on this machine's wall clock, with the
+ * zone NAMED. `toLocaleString()` printed neither the zone nor anything that mapped back
+ * to the instant that was typed (OSK-21505). `timeZone` is for tests and defaults to
+ * the machine's own.
+ */
+function formatLocalInstant(date, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        ...(timeZone ? { timeZone } : {}),
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+        timeZoneName: 'short',
+    }).formatToParts(date);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    return `${get('year')}-${get('month')}-${get('day')} ${get('hour')}:${get('minute')}:${get('second')} ${get('timeZoneName')}`;
+}
+/**
+ * The instant for a person: UTC first (it is what was typed and what is stored), then the
+ * local reading with its zone name. A machine already on UTC gets the UTC form alone.
+ */
+function describeInstant(date, timeZone) {
+    const utc = formatUtcInstant(date);
+    const local = formatLocalInstant(date, timeZone);
+    if (/ (UTC|GMT)$/.test(local))
+        return utc;
+    return `${utc} (${local})`;
+}

package/dist/lib/northstars.d.ts

@@ -1,7 +1,8 @@
-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 { NORTHSTAR_ANALYSIS_MODES, NORTHSTAR_APPROVAL_TRIGGERS, NORTHSTAR_EXECUTION_MODES, NORTHSTAR_INTENT_VERDICTS, NORTHSTAR_MANAGEMENT_INTENT_KINDS, NORTHSTAR_REASON_WORDS, NORTHSTAR_REVIEW_STATUSES, describeNorthstarReason } 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';
 export { NORTHSTAR_ANALYSIS_MODES, NORTHSTAR_APPROVAL_TRIGGERS, NORTHSTAR_EXECUTION_MODES, NORTHSTAR_INTENT_VERDICTS, NORTHSTAR_MANAGEMENT_INTENT_KINDS, NORTHSTAR_REVIEW_STATUSES, };
+export { NORTHSTAR_REASON_WORDS, describeNorthstarReason };
 export type { Northstar, NorthstarAnalysisMode, NorthstarExecutionMode, NorthstarGovernance, NorthstarGovernanceStatus, NorthstarManagementIntent, NorthstarManagementIntentKind, NorthstarRecommendation, NorthstarReviewRecord, };
 /**
  * oclif's `options:` needs runtime arrays, and these two are LIFECYCLE
@@ -11,6 +12,10 @@ 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"];
+export declare function intentRisk(intent: {
+    riskLevel?: string | null;
+} | null | undefined): string;
+export declare function shortReviewId(id: string): string;
 /**
  * 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
@@ -52,12 +57,22 @@ export declare const northstarApi: {
     }>;
     decideIntent: (id: string, intentId: string, body: Record<string, unknown>) => Promise<Record<string, unknown>>;
 };
+/**
+ * One review, from the id a person typed. The full id is asked for first, exactly as before. Only when
+ * the server has no review of that exact id is the typed text read as the start of one, among the
+ * northstar's newest 100 reviews: that is what the REVIEW column of `intents list` prints
+ * (`shortReviewId`), so the table's own output can be pasted back. A prefix of several reviews is
+ * reported, not guessed; one of none, or of a review older than the newest 100, raises the server's
+ * original "not found". Both ids are in `--json`.
+ */
+export declare function lookupReview(northstarId: string, typed: string): Promise<{
+    review: NorthstarReviewRecord;
+} | {
+    ambiguous: string[];
+}>;
 /** 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;
@@ -114,6 +129,48 @@ export declare function listFooter(input: {
     nextCursor?: string | null;
     cursor?: boolean;
 }): string;
+/** What a northstar with no workspace is called wherever a workspace is named. */
+export declare const PERSONAL_NORTHSTAR_WORKSPACE = "personal";
+/** Why a personal northstar can look missing on the web. The one sentence the others build on. */
+export declare const NORTHSTAR_WEB_SCOPE_SENTENCE: string;
+/** Help text shared by `list` and `show`: where a northstar's workspace is printed. */
+export declare const NORTHSTAR_WORKSPACE_READ_HELP: string;
+/** Help text for `create`: which workspace it lands in, and how to choose one. */
+export declare const NORTHSTAR_WORKSPACE_CREATE_HELP: string;
+/**
+ * Anything that may carry a `workspaceId`: a typed Northstar, or the raw record `create` prints (it
+ * is read through `Record<string, unknown>` so `--json` is the server's body plus the url).
+ */
+type WorkspaceBearing = {
+    workspaceId?: unknown;
+} | Record<string, unknown>;
+export declare function shortWorkspaceId(id: string): string;
+/** The workspace a northstar lives in, in one word or id: `personal` when it has none. */
+export declare function northstarWorkspaceLabel(northstar: WorkspaceBearing, options?: {
+    short?: boolean;
+}): string;
+/** The line `show` and `create` print: the full workspace id, or `personal`. */
+export declare function northstarWorkspaceLine(northstar: WorkspaceBearing): string;
+/** What the process that ran `create` asked for: the inputs to which note a personal northstar gets. */
+export type PersonalNorthstarContext = {
+    /** An Agent session: its workspace comes from the session, and `--workspace` is ignored. */
+    autonomous?: boolean;
+    /** The workspace the request carried (`--workspace`, or the one `workspaces use` chose). */
+    requestedWorkspaceId?: string;
+};
+/**
+ * What `create` adds when the northstar landed in no workspace. Three causes, three endings:
+ *
+ *   - an Agent session takes its workspace from the session and ignores `--workspace`, so telling
+ *     it to pass the flag would send it round in a circle;
+ *   - a workspace WAS requested but the person is not a member of it: the server does not refuse,
+ *     it creates the northstar personal (`resolveWorkspaceContext`), so "pass --workspace" would
+ *     be said to someone who just did;
+ *   - nothing was requested, and the way out is the flag.
+ */
+export declare function personalNorthstarNote(context?: PersonalNorthstarContext): string;
+/** The note for a northstar `create` just made: nothing when it is in a workspace. */
+export declare function createdNorthstarNote(northstar: WorkspaceBearing, context?: PersonalNorthstarContext): string | undefined;
 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
@@ -166,6 +223,32 @@ export declare function describeReviewAllocations(result: {
     allocations?: unknown;
     attention?: unknown;
 }): string;
+/**
+ * The sentence for a portfolio run budget smaller than the number of linked active commitments
+ * (OSK-21334): each still gets the floor of 1 run/day, so the ceilings add up to more than the
+ * budget. The server derives it once (`portfolioRunBudgetFloor.js`) and carries it, when it
+ * applies, on the `governance show` read, the `review-now` result and the effective policy's
+ * `portfolio`; every one of those three prints THIS sentence, so none composes its own and they
+ * cannot disagree. Absent from an older server, and from a budget that covers every commitment:
+ * no line, never a guess.
+ *
+ * Takes the carried field as it arrives (`unknown`), because two of the three callers read it off
+ * an untyped body.
+ */
+export declare function runBudgetFloorNote(value: unknown): string | undefined;
+/**
+ * What `critical_commitment` on the always-ask list does and does not do (OSK-21333).
+ *
+ * The list governs PROMOTION to critical (`critical_promotion`): remove the class and a bounded_auto
+ * review applies a small promotion itself. It does not govern the way back: a demotion away from
+ * critical is held for a person in `bounded_auto` whatever the list says (`critical_demotion`,
+ * `NorthstarGovernancePolicy.classifyIntent`: the demotion rule never reads the list). The behaviour
+ * is pinned by `NorthstarGovernancePolicy.spec.js` ("critical_commitment off the approval list"),
+ * the words by `cli/src/commands/northstars/__tests__/critical-approval-help.spec.ts`. The flag help
+ * and the `Approval for` line of `governance show` both read this one sentence, so neither can
+ * drift from the other.
+ */
+export declare const CRITICAL_COMMITMENT_APPROVAL_NOTE = "critical_commitment governs promotion to critical only; demotion away from critical (critical_demotion) is always held for a person, whatever this list says";
 export declare function renderGovernance(status: NorthstarGovernanceStatus, log: (line: string) => void): void;
 /**
  * The automatic-change budget line.