@skrr-ai/cli 0.1.47 → 0.1.48

package/dist/lib/commerce-command.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The shape every commerce and governed-store write shares.
+ *
+ * These endpoints validate rich bodies with their own zod schemas, and the CLI
+ * deliberately does not restate those shapes as flags. Two reasons, and the
+ * second is the one that bites:
+ *
+ * 1. A vocabulary declared twice drifts. The server owns what a contract, an
+ *    offer version or a budget policy looks like; a flag table here would be a
+ *    second declaration that silently falls behind the API that rejects it.
+ * 2. These are financial writes. A flag table invites a half-specified body
+ *    assembled from defaults; a file you wrote and can diff is a document you
+ *    reviewed. `-` reads stdin, so a pipeline still works.
+ *
+ * What the CLI DOES own is refusing to send nothing: a mutation whose body is
+ * required will not be fired with `{}` just because a path was omitted.
+ */
+export declare const jsonBodyFlags: {
+    file: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};
+export interface JsonBodyOwner {
+    error(message: string, options?: {
+        exit?: number;
+    }): never | void;
+}
+/**
+ * Read `--file`, refusing an empty body when the endpoint requires one.
+ *
+ * `required: false` is for the verbs whose body is genuinely optional — an
+ * offer `publish` carries nothing but its id — where `{}` is the honest
+ * request rather than a missing argument.
+ */
+export declare function jsonBodyFrom(command: JsonBodyOwner, file: string | undefined, { required }?: {
+    required?: boolean;
+}): Promise<Record<string, unknown>>;
+/**
+ * Print a result.
+ *
+ * Deliberately JSON-by-default for these surfaces rather than a summary line.
+ * A contract, a budget evaluation or an entitlement explanation is a DOCUMENT
+ * whose fields an operator is about to reason about; summarising it would be
+ * choosing for them which parts of a financial record matter, and every field
+ * this CLI hides is one they would have to open a browser to see.
+ */
+export declare function printResult(command: {
+    log(message: string): void;
+}, result: unknown, humanSummary?: string[]): void;

package/dist/lib/commerce-command.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonBodyFlags = void 0;
+exports.jsonBodyFrom = jsonBodyFrom;
+exports.printResult = printResult;
+const core_1 = require("@oclif/core");
+const prompt_1 = require("./prompt");
+/**
+ * The shape every commerce and governed-store write shares.
+ *
+ * These endpoints validate rich bodies with their own zod schemas, and the CLI
+ * deliberately does not restate those shapes as flags. Two reasons, and the
+ * second is the one that bites:
+ *
+ * 1. A vocabulary declared twice drifts. The server owns what a contract, an
+ *    offer version or a budget policy looks like; a flag table here would be a
+ *    second declaration that silently falls behind the API that rejects it.
+ * 2. These are financial writes. A flag table invites a half-specified body
+ *    assembled from defaults; a file you wrote and can diff is a document you
+ *    reviewed. `-` reads stdin, so a pipeline still works.
+ *
+ * What the CLI DOES own is refusing to send nothing: a mutation whose body is
+ * required will not be fired with `{}` just because a path was omitted.
+ */
+exports.jsonBodyFlags = {
+    file: core_1.Flags.string({
+        description: 'Path to the JSON body, or - to read stdin',
+    }),
+    json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+};
+/**
+ * Read `--file`, refusing an empty body when the endpoint requires one.
+ *
+ * `required: false` is for the verbs whose body is genuinely optional — an
+ * offer `publish` carries nothing but its id — where `{}` is the honest
+ * request rather than a missing argument.
+ */
+async function jsonBodyFrom(command, file, { required = true } = {}) {
+    if (!file) {
+        if (!required)
+            return {};
+        command.error('This write needs a body: pass --file <path> (or --file - to read stdin). The body is ' +
+            'validated by the server, which owns its shape — see the command help for what it expects.', { exit: 2 });
+        return {};
+    }
+    try {
+        return await (0, prompt_1.readJsonBody)(file);
+    }
+    catch (error) {
+        command.error(error instanceof Error ? error.message : String(error), { exit: 1 });
+        return {};
+    }
+}
+/**
+ * Print a result.
+ *
+ * Deliberately JSON-by-default for these surfaces rather than a summary line.
+ * A contract, a budget evaluation or an entitlement explanation is a DOCUMENT
+ * whose fields an operator is about to reason about; summarising it would be
+ * choosing for them which parts of a financial record matter, and every field
+ * this CLI hides is one they would have to open a browser to see.
+ */
+function printResult(command, result, humanSummary) {
+    if (humanSummary?.length) {
+        for (const line of humanSummary)
+            command.log(line);
+        return;
+    }
+    command.log(JSON.stringify(result, null, 2));
+}

package/dist/lib/commerce.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `/api/commerce` — marketplace terms, the offer governance pipeline, trials,
+ * promotions, and the incident queue behind fulfillment and integrity.
+ *
+ * Most of it is `checkAdmin` on the server, which is not a reason to leave it
+ * in a browser: the API enforces that either way, so a CLI grants nothing and
+ * only gives an operator a path that is not a page. The incident queue and the
+ * offer pipeline are the two most CLI-shaped things in the file — a queue you
+ * triage and a lifecycle you advance are exactly what a headless operator does
+ * at 2am, which is the case the parity doctrine names.
+ *
+ * Every route is written out at its own call site rather than composed from a
+ * builder: the parity checker reads a LITERAL there and deliberately refuses a
+ * composed path.
+ *
+ * **Bodies are passed through, not re-declared.** The complex writes (a
+ * product, an offer version, an entitlement question) take JSON the server
+ * validates with its own zod schema. Restating those shapes here would be a
+ * second declaration of a vocabulary the server owns — the way a surface
+ * silently drifts from the API that rejects it.
+ */
+export type MarketplaceTermsScope = 'buyer' | 'publisher';
+/**
+ * `GET /marketplace/terms/current` — the terms in force for one side of a deal.
+ *
+ * The query rides in `withQuery` rather than being interpolated into the
+ * literal. That is not style: the parity checker reads the LITERAL at the call
+ * site, and a `?scope=${…}` baked into it resolves to a path with a query
+ * attached, which matches no route — so a covered endpoint reports as
+ * unreachable. `withQuery` is the wrapper the checker already understands, and
+ * it is the one the other libs use.
+ */
+export declare function getMarketplaceTerms(scope: MarketplaceTermsScope): Promise<unknown>;
+/**
+ * `POST /marketplace/terms/accept` — record that you accept them.
+ *
+ * `accepted: true` is a literal the server requires; it is not a flag the CLI
+ * may default, because the whole value of the receipt is that somebody said so.
+ */
+export declare function acceptMarketplaceTerms(scope: MarketplaceTermsScope): Promise<unknown>;
+/** `GET /admin/marketplace/incidents/:kind` — the queue. */
+export declare function listMarketplaceIncidents(kind: string, params?: {
+    status?: string;
+    limit?: number;
+}): Promise<unknown>;
+/** `GET /admin/marketplace/incidents/:kind/:incidentId` — one incident. */
+export declare function getMarketplaceIncident(kind: string, incidentId: string): Promise<unknown>;
+/** `GET /admin/marketplace/incidents/:kind/:incidentId/audit` — what was done to it. */
+export declare function listMarketplaceIncidentAudit(kind: string, incidentId: string): Promise<unknown>;
+/**
+ * `POST /admin/marketplace/incidents/integrity/:incidentId/resolve` — close an
+ * integrity incident with a stated resolution.
+ *
+ * Integrity only. A fulfillment incident is retried, not resolved, and the two
+ * are different acts: one says the work can run again, the other says a human
+ * looked and decided. The CLI keeps them as separate verbs for that reason.
+ */
+export declare function resolveIntegrityIncident(incidentId: string, body: Record<string, unknown>): Promise<unknown>;
+/** `POST /admin/marketplace/fulfillment-reconciliations/:id/retry` — run it again. */
+export declare function retryFulfillmentReconciliation(reconciliationId: string, body?: Record<string, unknown>): Promise<unknown>;
+/** `POST /admin/products` — create a product. Body is the server's schema. */
+export declare function createCommerceProduct(body: Record<string, unknown>): Promise<unknown>;
+/** `POST /admin/offers` — create an offer VERSION. Body is the server's schema. */
+export declare function createCommerceOfferVersion(body: Record<string, unknown>): Promise<unknown>;
+/**
+ * The offer pipeline, in the order it is meant to run: validate → approve →
+ * publish, with retire as the exit. Four doors rather than one `--state` flag,
+ * because each is a distinct act with a distinct authority behind it, and a
+ * single mutate-the-state verb is how a governance pipeline becomes a field.
+ */
+/** `POST /admin/offers/:offerVersionId/validate` — is it ready to be approved? */
+export declare function validateCommerceOffer(offerVersionId: string): Promise<unknown>;
+/** `POST /admin/offers/:offerVersionId/approve` — somebody signs off. */
+export declare function approveCommerceOffer(offerVersionId: string): Promise<unknown>;
+/** `POST /admin/offers/:offerVersionId/publish` — it becomes buyable. */
+export declare function publishCommerceOffer(offerVersionId: string): Promise<unknown>;
+/** `POST /admin/offers/:offerVersionId/retire` — it stops being buyable. */
+export declare function retireCommerceOffer(offerVersionId: string): Promise<unknown>;
+/** `POST /trials` — enrol the calling user. The subject is the credential, never a field. */
+export declare function startCommerceTrial(body: Record<string, unknown>): Promise<unknown>;
+/** `GET /trials/:enrollmentId/conversion-preview` — what converting would cost. */
+export declare function previewCommerceTrialConversion(enrollmentId: string): Promise<unknown>;
+/** `POST /promotions/redeem` — redeem a promotional offer version. */
+export declare function redeemCommercePromotion(offerVersionId: string): Promise<unknown>;
+/**
+ * `POST /admin/entitlements/explain` — WHY a subject does or does not have a
+ * capability.
+ *
+ * The most useful read on this mount and the reason a CLI is worth having:
+ * "this account cannot do X" is a support question answered by tracing an
+ * entitlement, and tracing it from a terminal beats clicking through a console.
+ */
+export declare function explainCommerceEntitlement(body: Record<string, unknown>): Promise<unknown>;

package/dist/lib/commerce.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMarketplaceTerms = getMarketplaceTerms;
+exports.acceptMarketplaceTerms = acceptMarketplaceTerms;
+exports.listMarketplaceIncidents = listMarketplaceIncidents;
+exports.getMarketplaceIncident = getMarketplaceIncident;
+exports.listMarketplaceIncidentAudit = listMarketplaceIncidentAudit;
+exports.resolveIntegrityIncident = resolveIntegrityIncident;
+exports.retryFulfillmentReconciliation = retryFulfillmentReconciliation;
+exports.createCommerceProduct = createCommerceProduct;
+exports.createCommerceOfferVersion = createCommerceOfferVersion;
+exports.validateCommerceOffer = validateCommerceOffer;
+exports.approveCommerceOffer = approveCommerceOffer;
+exports.publishCommerceOffer = publishCommerceOffer;
+exports.retireCommerceOffer = retireCommerceOffer;
+exports.startCommerceTrial = startCommerceTrial;
+exports.previewCommerceTrialConversion = previewCommerceTrialConversion;
+exports.redeemCommercePromotion = redeemCommercePromotion;
+exports.explainCommerceEntitlement = explainCommerceEntitlement;
+const api_fetch_1 = require("./api-fetch");
+const triggers_1 = require("./triggers");
+/**
+ * `GET /marketplace/terms/current` — the terms in force for one side of a deal.
+ *
+ * The query rides in `withQuery` rather than being interpolated into the
+ * literal. That is not style: the parity checker reads the LITERAL at the call
+ * site, and a `?scope=${…}` baked into it resolves to a path with a query
+ * attached, which matches no route — so a covered endpoint reports as
+ * unreachable. `withQuery` is the wrapper the checker already understands, and
+ * it is the one the other libs use.
+ */
+async function getMarketplaceTerms(scope) {
+    return (0, api_fetch_1.apiFetch)((0, triggers_1.withQuery)('/api/commerce/marketplace/terms/current', { scope }));
+}
+/**
+ * `POST /marketplace/terms/accept` — record that you accept them.
+ *
+ * `accepted: true` is a literal the server requires; it is not a flag the CLI
+ * may default, because the whole value of the receipt is that somebody said so.
+ */
+async function acceptMarketplaceTerms(scope) {
+    return (0, api_fetch_1.apiFetch)('/api/commerce/marketplace/terms/accept', {
+        method: 'POST',
+        body: { scope, accepted: true },
+    });
+}
+/** `GET /admin/marketplace/incidents/:kind` — the queue. */
+async function listMarketplaceIncidents(kind, params = {}) {
+    return (0, api_fetch_1.apiFetch)((0, triggers_1.withQuery)(`/api/commerce/admin/marketplace/incidents/${encodeURIComponent(kind)}`, params));
+}
+/** `GET /admin/marketplace/incidents/:kind/:incidentId` — one incident. */
+async function getMarketplaceIncident(kind, incidentId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/marketplace/incidents/${encodeURIComponent(kind)}/${encodeURIComponent(incidentId)}`);
+}
+/** `GET /admin/marketplace/incidents/:kind/:incidentId/audit` — what was done to it. */
+async function listMarketplaceIncidentAudit(kind, incidentId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/marketplace/incidents/${encodeURIComponent(kind)}/${encodeURIComponent(incidentId)}/audit`);
+}
+/**
+ * `POST /admin/marketplace/incidents/integrity/:incidentId/resolve` — close an
+ * integrity incident with a stated resolution.
+ *
+ * Integrity only. A fulfillment incident is retried, not resolved, and the two
+ * are different acts: one says the work can run again, the other says a human
+ * looked and decided. The CLI keeps them as separate verbs for that reason.
+ */
+async function resolveIntegrityIncident(incidentId, body) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/marketplace/incidents/integrity/${encodeURIComponent(incidentId)}/resolve`, { method: 'POST', body });
+}
+/** `POST /admin/marketplace/fulfillment-reconciliations/:id/retry` — run it again. */
+async function retryFulfillmentReconciliation(reconciliationId, body = {}) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/marketplace/fulfillment-reconciliations/${encodeURIComponent(reconciliationId)}/retry`, { method: 'POST', body });
+}
+/** `POST /admin/products` — create a product. Body is the server's schema. */
+async function createCommerceProduct(body) {
+    return (0, api_fetch_1.apiFetch)('/api/commerce/admin/products', { method: 'POST', body });
+}
+/** `POST /admin/offers` — create an offer VERSION. Body is the server's schema. */
+async function createCommerceOfferVersion(body) {
+    return (0, api_fetch_1.apiFetch)('/api/commerce/admin/offers', { method: 'POST', body });
+}
+/**
+ * The offer pipeline, in the order it is meant to run: validate → approve →
+ * publish, with retire as the exit. Four doors rather than one `--state` flag,
+ * because each is a distinct act with a distinct authority behind it, and a
+ * single mutate-the-state verb is how a governance pipeline becomes a field.
+ */
+/** `POST /admin/offers/:offerVersionId/validate` — is it ready to be approved? */
+async function validateCommerceOffer(offerVersionId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/offers/${encodeURIComponent(offerVersionId)}/validate`, { method: 'POST', body: {} });
+}
+/** `POST /admin/offers/:offerVersionId/approve` — somebody signs off. */
+async function approveCommerceOffer(offerVersionId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/offers/${encodeURIComponent(offerVersionId)}/approve`, { method: 'POST', body: {} });
+}
+/** `POST /admin/offers/:offerVersionId/publish` — it becomes buyable. */
+async function publishCommerceOffer(offerVersionId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/offers/${encodeURIComponent(offerVersionId)}/publish`, { method: 'POST', body: {} });
+}
+/** `POST /admin/offers/:offerVersionId/retire` — it stops being buyable. */
+async function retireCommerceOffer(offerVersionId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/admin/offers/${encodeURIComponent(offerVersionId)}/retire`, { method: 'POST', body: {} });
+}
+/** `POST /trials` — enrol the calling user. The subject is the credential, never a field. */
+async function startCommerceTrial(body) {
+    return (0, api_fetch_1.apiFetch)('/api/commerce/trials', { method: 'POST', body });
+}
+/** `GET /trials/:enrollmentId/conversion-preview` — what converting would cost. */
+async function previewCommerceTrialConversion(enrollmentId) {
+    return (0, api_fetch_1.apiFetch)(`/api/commerce/trials/${encodeURIComponent(enrollmentId)}/conversion-preview`);
+}
+/** `POST /promotions/redeem` — redeem a promotional offer version. */
+async function redeemCommercePromotion(offerVersionId) {
+    return (0, api_fetch_1.apiFetch)('/api/commerce/promotions/redeem', {
+        method: 'POST',
+        body: { offerVersionId },
+    });
+}
+/**
+ * `POST /admin/entitlements/explain` — WHY a subject does or does not have a
+ * capability.
+ *
+ * The most useful read on this mount and the reason a CLI is worth having:
+ * "this account cannot do X" is a support question answered by tracing an
+ * entitlement, and tracing it from a terminal beats clicking through a console.
+ */
+async function explainCommerceEntitlement(body) {
+    return (0, api_fetch_1.apiFetch)('/api/commerce/admin/entitlements/explain', { method: 'POST', body });
+}

package/dist/lib/commitment-product.js

@@ -125,7 +125,7 @@ function renderExecutionReceiptQuarterlyMetrics(response, log, verbose = false)
     log(`  Execute starts:        ${metrics.executeStarts}`);
     log(`  Declared deliveries:   ${metrics.declaredDeliveries}`);
     log(`  Verified outcomes:     ${metrics.verifiedOutcomes}`);
-    log(`  Blocked:               ${metrics.blocked}`);
+    log(`  Blocked / failed:      ${metrics.blocked} / ${metrics.failed ?? '—'}`);
     log('');
     log('Rates');
     log(`  Verified per eligible wake:   ${ratio(metrics.verifiedOutcomesPerEligibleMaterialWake)}`);