@ultimat3/core 22.9.0 → 22.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.9.0",
+  "version": "22.10.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.9.0"
+    "@ultimat3/schema": "22.10.0"
   }
 }

package/src/config-site.ts

@@ -19,13 +19,36 @@ export interface SeoRobotsConfig {
   readonly disallow: readonly string[];
 }
 
+/**
+ * Where each sitemap `<lastmod>` comes from. `'none'` (the default): no `<lastmod>`, as before.
+ * `'git'`: the last commit that touched the route's source file, read with `git log` — and the
+ * file's mtime where the process has no work tree (a container image). `'mtime'`: the file's mtime.
+ * `'build'`: one timestamp for every URL, the moment the process built its sitemap.
+ */
+export type SitemapLastmod = 'none' | 'git' | 'mtime' | 'build';
+
+export const SITEMAP_LASTMOD_SOURCES: readonly SitemapLastmod[] = ['none', 'git', 'mtime', 'build'];
+
+export interface SeoSitemapConfig {
+  /**
+   * Public pages OUTSIDE `site/` to list — an `app/` route anyone may open, e.g. `['/verificar']`.
+   * Each must match a registered route that declares no policy (checked when the sitemap is built,
+   * `X_SITEMAP_EXTRA_INVALID`), and is listed per routed locale with hreflang alternates exactly
+   * as a `site/` page is.
+   */
+  readonly extra: readonly string[];
+  readonly lastmod: SitemapLastmod;
+}
+
 export interface SeoConfig {
   readonly robots: SeoRobotsConfig;
+  readonly sitemap: SeoSitemapConfig;
 }
 
 /** `robots` is NESTED for `AiConfigInput`'s reason: `section` applies a patch one level deep. */
 export interface SeoConfigInput {
   readonly robots?: Input<SeoRobotsConfig> | undefined;
+  readonly sitemap?: Input<SeoSitemapConfig> | undefined;
 }
 
 export interface SiteSections {
@@ -50,6 +73,10 @@ export function mergeSite(layers: readonly SiteSectionsInput[]): SiteSections {
         { disallow: [] },
         layers.map((layer) => layer.seo?.robots),
       ),
+      sitemap: layered<SeoSitemapConfig>(
+        { extra: [], lastmod: 'none' },
+        layers.map((layer) => layer.seo?.sitemap),
+      ),
     },
   };
 }
@@ -84,4 +111,18 @@ export function siteIssues(config: SiteSections, issues: string[]): void {
   for (const path of config.seo.robots.disallow) {
     if (!path.startsWith('/')) issues.push(`seo.robots.disallow entry "${path}" must start with /`);
   }
+  for (const path of config.seo.sitemap.extra) {
+    // A PATH, never a URL: every `<loc>` is built against the one declared origin, and a query or
+    // a fragment names a variant of a page, which a sitemap lists by its canonical URL alone.
+    if (!path.startsWith('/') || path.startsWith('//') || /[?#]/.test(path)) {
+      issues.push(
+        `seo.sitemap.extra entry "${path}" must be a path starting with / — no origin, query or fragment`,
+      );
+    }
+  }
+  if (!SITEMAP_LASTMOD_SOURCES.includes(config.seo.sitemap.lastmod)) {
+    issues.push(
+      `seo.sitemap.lastmod "${String(config.seo.sitemap.lastmod)}" must be one of ${SITEMAP_LASTMOD_SOURCES.join(', ')}`,
+    );
+  }
 }

package/src/errors.ts

@@ -26,6 +26,18 @@ export interface UltimateErrorInit {
   readonly cause: string;
   /** The exact command or edit that fixes it. */
   readonly fix: string;
+  /**
+   * The fix for a REMOTE caller — an agent over MCP, a client reading a problem document — when
+   * `fix` names something only the app's developer can do (`x policy explain`, an edit to a
+   * declaration). Omitted, every surface reads `fix`. The developer's `fix` is never replaced: the
+   * terminal, the log line and `--json` keep it, and a dev-mode problem document does too.
+   */
+  readonly callerFix?: string | undefined;
+  /**
+   * Where the reader goes next. Defaults to the code's registered page. An app may point it at its
+   * own guide — `docs://recipes/refund-a-payment` — and `@ultimat3/mcp` then prints it as a fourth
+   * `docs:` line in the tool result, the moment the agent is stuck.
+   */
   readonly docs?: string | undefined;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
   /**
@@ -43,6 +55,8 @@ export interface UltimateErrorJSON {
   readonly title: string;
   readonly cause: string;
   readonly fix: string;
+  /** Present only when the error declared one. See `UltimateErrorInit.callerFix`. */
+  readonly callerFix?: string | undefined;
   readonly docs: string;
   /** Whether a client may try again. Always present — a client never has to infer it. */
   readonly retry: ErrorRetry;
@@ -50,9 +64,26 @@ export interface UltimateErrorJSON {
   readonly stack?: string | undefined;
 }
 
+/**
+ * Who reads a rendering. `'developer'` (the default) is the terminal, a log line, `--json`: the
+ * `fix` the author wrote. `'caller'` is a remote client that cannot run the app's CLI — an MCP
+ * tool result, a production problem document: `callerFix` when the error declared one, else `fix`.
+ */
+export type ErrorAudience = 'developer' | 'caller';
+
 export interface FormatErrorOptions {
   /** Append a 4th `docs:` line. Off by default — the contract's rendering is 3 lines. */
   readonly docs?: boolean | undefined;
+  /** Whose fix the `fix:` line carries. See `ErrorAudience`. */
+  readonly audience?: ErrorAudience | undefined;
+}
+
+/** The fix line a reader of `audience` is given: `callerFix` for a caller when one exists. */
+export function fixFor(
+  error: { readonly fix: string; readonly callerFix?: string | undefined },
+  audience: ErrorAudience | undefined,
+): string {
+  return audience === 'caller' && error.callerFix !== undefined ? error.callerFix : error.fix;
 }
 
 export class UltimateError extends Error {
@@ -63,6 +94,7 @@ export class UltimateError extends Error {
   /** Set by `Error`'s `cause` option; always a human-readable string in Ultimate. */
   declare readonly cause: string;
   readonly fix: string;
+  readonly callerFix: string | undefined;
   readonly docs: string;
   readonly retry: ErrorRetry;
   readonly meta: Readonly<Record<string, unknown>> | undefined;
@@ -90,6 +122,7 @@ export class UltimateError extends Error {
     this.code = code;
     this.title = title;
     this.fix = singleLine(init.fix);
+    this.callerFix = init.callerFix === undefined ? undefined : singleLine(init.callerFix);
     this.docs = singleLine(init.docs ?? described.docs);
     this.retry = init.retry ?? retryFor(init.code);
     this.meta = init.meta;
@@ -110,7 +143,8 @@ export class UltimateError extends Error {
     // would be a second place that has to be right — and the one that gets forgotten. This method
     // is line-oriented and stays exactly 3 lines (4 with `docs`) because the fields cannot carry
     // a line break, not because this joiner removes them.
-    const lines = [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`];
+    const fix = fixFor(this, options?.audience);
+    const lines = [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${fix}`];
     if (options?.docs === true) lines.push(`  docs:  ${this.docs}`);
     return lines.join('\n');
   }
@@ -128,6 +162,7 @@ export class UltimateError extends Error {
       title: this.title,
       cause: this.cause,
       fix: this.fix,
+      ...(this.callerFix === undefined ? {} : { callerFix: this.callerFix }),
       docs: this.docs,
       retry: this.retry,
       meta: renderMetaRecord(this.meta),
@@ -147,6 +182,21 @@ export function isUltimateError(value: unknown): value is UltimateError {
   }
 }
 
+/**
+ * The `callerFix` of an authorization denial (`X_FORBIDDEN`), ONE sentence for the five packages
+ * that refuse one — policy, action, query, auth, http — so a remote caller reads the same
+ * instruction whichever layer said no. A permission is granted by whoever administers the account,
+ * never by retrying, and saying so is what stops an agent looping on a refusal. `permission`, when
+ * the denial names a bare `resource:verb`, is what to ask for.
+ */
+export function deniedCallerFix(permission?: string): string {
+  const ask =
+    permission === undefined
+      ? 'this caller is not permitted to do this: ask the account owner or an administrator for access'
+      : `this caller lacks the permission ${permission}: ask the account owner or an administrator to grant it`;
+  return `${ask}, or call with credentials that have it — retrying the same call is refused the same way`;
+}
+
 /** Init for a subclass that owns its code. */
 export type CodedErrorInit = Omit<UltimateErrorInit, 'code'>;
 

package/src/exports/error-contract.ts

@@ -46,14 +46,17 @@ export {
 } from '../error-retry';
 export type {
   CodedErrorInit,
+  ErrorAudience,
   FormatErrorOptions,
   UltimateErrorInit,
   UltimateErrorJSON,
 } from '../errors';
 export {
   ConfigInvalidError,
+  deniedCallerFix,
   EnvMissingError,
   errorRetry,
+  fixFor,
   formatError,
   InternalError,
   isUltimateError,

package/src/index.ts

@@ -135,10 +135,13 @@ export type {
   SeoConfig,
   SeoConfigInput,
   SeoRobotsConfig,
+  SeoSitemapConfig,
   SiteConfig,
+  SitemapLastmod,
   SiteSections,
   SiteSectionsInput,
 } from './config-site';
+export { SITEMAP_LASTMOD_SOURCES } from './config-site';
 export type { ConflictPolicy, ResolveConflictOptions, Row } from './conflict-policy';
 export { resolveConflict } from './conflict-policy';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
@@ -206,6 +209,7 @@ export {
 export type {
   CodedErrorInit,
   CoreErrorCode,
+  ErrorAudience,
   ErrorCodeDeclaration,
   ErrorCodeDescriptor,
   ErrorCodeEntry,
@@ -220,6 +224,7 @@ export {
   classifyThrown,
   DEFAULT_ERROR_RETRY,
   declaredErrorRetry,
+  deniedCallerFix,
   describeErrorCode,
   describeValue,
   EnvMissingError,
@@ -227,6 +232,7 @@ export {
   ERROR_RETRY_KINDS,
   errorCodeSnapshot,
   errorRetry,
+  fixFor,
   formatError,
   hasErrorCode,
   InternalError,