@hotmeshio/long-tail 0.13.1 → 0.14.0

package/build/services/topics/system-topics.js

@@ -261,6 +261,26 @@ const SYSTEM_TOPICS = [
         example_payload: { workflowId: 'wf-abc', workflowName: 'processOrder', milestones: [{ name: 'items_processed', value: 42 }] },
         tags: ['progress', 'core'],
     },
+    // Surfaces
+    {
+        topic: 'system.surfaces.dashboard',
+        description: 'A dashboard announcement was published or removed. Delivery reaches ' +
+            'every authenticated subscriber — role targeting is display scoping, ' +
+            'so bodies must never carry secrets.',
+        category: 'surfaces',
+        payload_schema: objectSchema({
+            action: { type: 'string', description: 'created | deleted' },
+            announcement: {
+                type: 'object',
+                description: 'The announcement row (id, title, body, layout, roles, expires_at)',
+            },
+        }),
+        example_payload: {
+            action: 'created',
+            announcement: { id: 'ann-001', title: 'Maintenance tonight', layout: 'banner', roles: [] },
+        },
+        tags: ['surface', 'dashboard'],
+    },
 ];
 // ── Seeding ─────────────────────────────────────────────────────────────────────
 /**

package/build/shared/form-validation/index.d.ts

@@ -13,5 +13,6 @@ export * from './x-lt-labels';
 export * from './x-lt-query';
 export * from './x-lt-submit-guard';
 export * from './x-lt-show-if';
+export * from './x-lt-require-any';
 export * from './field-validator';
 export * from './validate-resolver-payload';

package/build/shared/form-validation/index.js

@@ -29,5 +29,6 @@ __exportStar(require("./x-lt-labels"), exports);
 __exportStar(require("./x-lt-query"), exports);
 __exportStar(require("./x-lt-submit-guard"), exports);
 __exportStar(require("./x-lt-show-if"), exports);
+__exportStar(require("./x-lt-require-any"), exports);
 __exportStar(require("./field-validator"), exports);
 __exportStar(require("./validate-resolver-payload"), exports);

package/build/shared/form-validation/validate-resolver-payload.d.ts

@@ -15,6 +15,9 @@
  *   - x-lt-require-all against the checklist items resolved from context
  *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)
  *
+ * Root-level x-lt-require-any groups run after the per-field pass: each group
+ * needs a value in at least one visible member (all-hidden groups are waived).
+ *
  * The showIf/`resolver.*` domain is always the FLAT form representation, so a
  * condition like `resolver.approved` reads the same on both sides.
  */

package/build/shared/form-validation/validate-resolver-payload.js

@@ -19,12 +19,16 @@ exports.validateResolverPayload = validateResolverPayload;
  *   - x-lt-require-all against the checklist items resolved from context
  *   - static + dynamic bounds (minimum/x-lt-minimum, lengths, patterns)
  *
+ * Root-level x-lt-require-any groups run after the per-field pass: each group
+ * needs a value in at least one visible member (all-hidden groups are waived).
+ *
  * The showIf/`resolver.*` domain is always the FLAT form representation, so a
  * condition like `resolver.approved` reads the same on both sides.
  */
 const field_validator_1 = require("./field-validator");
 const x_lt_show_if_1 = require("./x-lt-show-if");
 const x_lt_bind_1 = require("./x-lt-bind");
+const x_lt_require_any_1 = require("./x-lt-require-any");
 /**
  * Validate FLAT form values against the form schema. This is the dashboard's
  * entry point (the values the user edits, keyed by field name).
@@ -46,6 +50,21 @@ function validateResolverForm(schema, formValues, ctx) {
         if (err)
             errors.push({ field, message: err });
     }
+    // Require-any groups: at least one VISIBLE member per group carries a value.
+    // A member hidden by showIf (or naming no property) can neither satisfy nor
+    // be demanded; an all-hidden group is waived.
+    for (const group of (0, x_lt_require_any_1.readRequireAnyGroups)(schema)) {
+        const visible = group.filter((k) => properties[k] && (0, x_lt_show_if_1.evaluateShowIf)(properties[k]['x-lt-showIf'], liveCtx));
+        if (visible.length === 0)
+            continue;
+        if (visible.some((k) => (0, x_lt_require_any_1.hasRequireAnyValue)(formValues[k])))
+            continue;
+        const titles = visible.map((k) => properties[k].title ?? k);
+        errors.push({
+            field: visible[0],
+            message: `Enter a value for at least one of: ${titles.join(', ')}`,
+        });
+    }
     return errors;
 }
 /**

package/build/shared/form-validation/x-lt-labels.d.ts

@@ -10,19 +10,30 @@
  * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
  * ```
  *
- * Only the five known targets are read; unknown keys and non-string values are
- * ignored. Any target the schema omits keeps its default label, so a schema
- * overrides just the controls it cares about.
+ * `cancel` additionally accepts `false` to remove the control entirely —
+ * for roles where cancelling is not part of the process ("Send to Service"
+ * flows escalate instead). The other targets are rename-only: hiding
+ * claim/submit/release would strand the footer.
+ *
+ * Only the five known targets are read; unknown keys and non-string values
+ * (except `cancel: false`) are ignored. Any target the schema omits keeps its
+ * default label, so a schema overrides just the controls it cares about.
  */
 export declare const X_LT_LABELS = "x-lt-labels";
 /** The footer controls a schema may rename. */
 export declare const FOOTER_LABEL_TARGETS: readonly ["claim", "cancel", "submit", "escalate", "release"];
 export type FooterLabelTarget = (typeof FOOTER_LABEL_TARGETS)[number];
-/** A partial map of target → override label. Absent targets keep their default. */
-export type FooterLabels = Partial<Record<FooterLabelTarget, string>>;
+/**
+ * A partial map of target → override label. Absent targets keep their
+ * default. `cancel: false` removes the cancel control from the footer.
+ */
+export type FooterLabels = Partial<Record<Exclude<FooterLabelTarget, 'cancel'>, string>> & {
+    cancel?: string | false;
+};
 /**
  * The schema's footer label overrides, or an empty map when none are declared.
  * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
- * blank or non-string values are dropped.
+ * blank or non-string values are dropped — except `cancel: false`, which is
+ * preserved as the hide instruction.
  */
 export declare function readFooterLabels(schema: Record<string, unknown> | null | undefined): FooterLabels;

package/build/shared/form-validation/x-lt-labels.js

@@ -11,9 +11,14 @@
  * { "x-lt-labels": { "claim": "Claim and Submit", "submit": "Approve" } }
  * ```
  *
- * Only the five known targets are read; unknown keys and non-string values are
- * ignored. Any target the schema omits keeps its default label, so a schema
- * overrides just the controls it cares about.
+ * `cancel` additionally accepts `false` to remove the control entirely —
+ * for roles where cancelling is not part of the process ("Send to Service"
+ * flows escalate instead). The other targets are rename-only: hiding
+ * claim/submit/release would strand the footer.
+ *
+ * Only the five known targets are read; unknown keys and non-string values
+ * (except `cancel: false`) are ignored. Any target the schema omits keeps its
+ * default label, so a schema overrides just the controls it cares about.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FOOTER_LABEL_TARGETS = exports.X_LT_LABELS = void 0;
@@ -24,7 +29,8 @@ exports.FOOTER_LABEL_TARGETS = ['claim', 'cancel', 'submit', 'escalate', 'releas
 /**
  * The schema's footer label overrides, or an empty map when none are declared.
  * Reads only the known targets; a non-object `x-lt-labels`, unknown keys, and
- * blank or non-string values are dropped.
+ * blank or non-string values are dropped — except `cancel: false`, which is
+ * preserved as the hide instruction.
  */
 function readFooterLabels(schema) {
     const raw = schema?.[exports.X_LT_LABELS];
@@ -32,6 +38,8 @@ function readFooterLabels(schema) {
         return {};
     const source = raw;
     const labels = {};
+    if (source.cancel === false)
+        labels.cancel = false;
     for (const target of exports.FOOTER_LABEL_TARGETS) {
         const value = source[target];
         if (typeof value === 'string' && value.trim().length > 0) {

package/build/shared/form-validation/x-lt-require-any.d.ts

@@ -0,0 +1,22 @@
+/**
+ * x-lt-require-any — "at least one of this set" as a root-schema token. A
+ * form_schema declares groups of field names; a submission passes when every
+ * group has a value in at least one member. The canonical case: a Left
+ * quantity and a Right quantity where either satisfies, but blank-both fails.
+ *
+ *   x-lt-require-any   string[][] — e.g. [["left_quantity", "right_quantity"]]
+ *
+ * Visibility rules compose: a member hidden by its `x-lt-showIf` (or naming
+ * no schema property) can neither satisfy the group nor be demanded of the
+ * submitter, and a group whose members are ALL hidden is waived. `false` and
+ * `0` are answers; `''`, null, and undefined are not.
+ */
+export declare const X_LT_REQUIRE_ANY = "x-lt-require-any";
+/**
+ * The schema's require-any groups. Malformed declarations (non-array token,
+ * non-array groups, non-string members) read as no groups — a bad token never
+ * bricks submission.
+ */
+export declare function readRequireAnyGroups(schema: Record<string, unknown> | null | undefined): string[][];
+/** Present = an actual answer: `false` and `0` count; `''`/null/undefined do not. */
+export declare function hasRequireAnyValue(value: unknown): boolean;

package/build/shared/form-validation/x-lt-require-any.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * x-lt-require-any — "at least one of this set" as a root-schema token. A
+ * form_schema declares groups of field names; a submission passes when every
+ * group has a value in at least one member. The canonical case: a Left
+ * quantity and a Right quantity where either satisfies, but blank-both fails.
+ *
+ *   x-lt-require-any   string[][] — e.g. [["left_quantity", "right_quantity"]]
+ *
+ * Visibility rules compose: a member hidden by its `x-lt-showIf` (or naming
+ * no schema property) can neither satisfy the group nor be demanded of the
+ * submitter, and a group whose members are ALL hidden is waived. `false` and
+ * `0` are answers; `''`, null, and undefined are not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_REQUIRE_ANY = void 0;
+exports.readRequireAnyGroups = readRequireAnyGroups;
+exports.hasRequireAnyValue = hasRequireAnyValue;
+exports.X_LT_REQUIRE_ANY = 'x-lt-require-any';
+/**
+ * The schema's require-any groups. Malformed declarations (non-array token,
+ * non-array groups, non-string members) read as no groups — a bad token never
+ * bricks submission.
+ */
+function readRequireAnyGroups(schema) {
+    const raw = schema?.[exports.X_LT_REQUIRE_ANY];
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((group) => Array.isArray(group))
+        .map((group) => group.filter((m) => typeof m === 'string' && m.length > 0))
+        .filter((group) => group.length > 0);
+}
+/** Present = an actual answer: `false` and `0` count; `''`/null/undefined do not. */
+function hasRequireAnyValue(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    return true;
+}

package/build/start/workers.js

@@ -236,6 +236,7 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                         resolver_schema: c.resolverSchema ?? null,
                         cron_schedule: c.cronSchedule ?? null,
                         execute_as: c.executeAs ?? null,
+                        read_safe: c.readSafe ?? false,
                     };
                     try {
                         if ((0, apply_report_1.ownedByCode)(c.reset, configSource)) {
@@ -472,9 +473,8 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
             (0, apply_report_1.logSurfaceReport)('agents', agentReport);
         }
     }
-    // Register declared scan schemes (with their rules) — ownership per
-    // configSource / per-entry reset. A scheme and its rules are one ownership
-    // unit; the scheme applies first so rule validation sees its kind.
+    // Declared scan schemes + rules (one ownership unit, one reset). The scheme
+    // applies first — rule validation reads its kind.
     if (startConfig.scanSchemes?.length) {
         const { seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, listScanSchemes, listScanRules, } = await Promise.resolve().then(() => __importStar(require('../services/scan-code')));
         const scanReport = (0, apply_report_1.newSurfaceReport)();
@@ -492,7 +492,6 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
                     (0, apply_report_1.recordOutcome)(scanReport, `scheme ${scheme.version}`, outcome);
                     if (outcome === 'applied')
                         logger_1.loggerRegistry.info(`[long-tail] scan scheme applied: ${scheme.version}`);
-                    // Undeclared rules on a code-owned scheme are reported, never deleted.
                     const declaredCategories = new Set((rules ?? []).map((r) => r.category));
                     const existingRules = await listScanRules(scheme.version);
                     scanReport.orphans.push(...existingRules
@@ -514,7 +513,6 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
             }
         }
         if (codeOwnedBoot && !startConfig.examples) {
-            // Schemes in the DB not declared here (demo seeds own theirs under examples).
             const declaredVersions = new Set(startConfig.scanSchemes.map((s) => s.version));
             scanReport.orphans.push(...(await listScanSchemes())
                 .map((s) => s.version)

package/build/system/mcp-servers/admin/announcements.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Dashboard announcement tool — mirrors routes/announcements.ts. Publishing
+ * is a privileged surface (the HTTP route guards with requireRoleManager);
+ * targeting is display scoping only, so bodies must never carry secrets.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAnnouncementTools(server: McpServer): void;

package/build/system/mcp-servers/admin/announcements.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAnnouncementTools = registerAnnouncementTools;
+const zod_1 = require("zod");
+const api = __importStar(require("../../../api/announcements"));
+const publishAnnouncementSchema = zod_1.z.object({
+    body: zod_1.z.string().describe('Markdown body — the only required field.'),
+    title: zod_1.z.string().optional().describe('Headline shown on the collapsed banner.'),
+    layout: zod_1.z.string().optional().describe("Presentation form. Default: 'banner'."),
+    roles: zod_1.z.array(zod_1.z.string()).optional().describe('Target roles; omitted = everyone.'),
+    expires_at: zod_1.z.string().optional().describe('ISO timestamp; omitted = 24 hours from now.'),
+});
+function registerAnnouncementTools(server) {
+    // mirrors POST /api/announcements
+    server.registerTool('publish_announcement', {
+        title: 'Publish Announcement',
+        description: 'Publish a dashboard announcement — a banner every targeted user sees ' +
+            'live and on their next load until it expires or is dismissed. Only ' +
+            'the body is required; title, layout, role targeting, and expiry ' +
+            '(default 24h) are optional. Bodies broadcast to all authenticated ' +
+            'subscribers — never include secrets.',
+        inputSchema: publishAnnouncementSchema,
+    }, async (args) => {
+        const result = await api.createAnnouncement({
+            body: args.body,
+            title: args.title,
+            layout: args.layout,
+            roles: args.roles,
+            expiresAt: args.expires_at,
+        }, { userId: 'lt-system', role: 'superadmin' });
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+}

package/build/system/mcp-servers/admin/index.js

@@ -60,7 +60,8 @@ const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
 const scan_codes_1 = require("./scan-codes");
 const domain_context_1 = require("./domain-context");
-const TOOL_COUNT = 103;
+const announcements_1 = require("./announcements");
+const TOOL_COUNT = 105;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -73,7 +74,7 @@ async function createAdminServer(options) {
     (0, tasks_1.registerTaskTools)(instance); //  2 tools
     (0, escalations_1.registerEscalationTools)(instance); // 20 tools (RO + RW single + metadata + bulk)
     (0, workflow_config_1.registerWorkflowConfigTools)(instance); //  3 tools
-    (0, workflows_1.registerWorkflowTools)(instance); //  4 tools (+ terminate_workflow)
+    (0, workflows_1.registerWorkflowTools)(instance); //  5 tools (+ terminate_workflow, invoke_workflow_read_safe)
     (0, mcp_servers_1.registerMcpServerTools)(instance); //  4 tools
     (0, yaml_workflows_1.registerYamlWorkflowTools)(instance); //  5 tools
     (0, users_1.registerUserTools)(instance); // 10 tools (users + roles + role schemas)
@@ -91,7 +92,8 @@ async function createAdminServer(options) {
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
     (0, scan_codes_1.registerScanCodeTools)(instance); //  5 tools (scan schemes + rules + execute)
     (0, domain_context_1.registerDomainContextTools)(instance); //  1 tool  (get_domain_context)
-    // Total: 103
+    (0, announcements_1.registerAnnouncementTools)(instance); //  1 tool  (publish_announcement)
+    // Total: 105
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

package/build/system/mcp-servers/admin/workflows.js

@@ -109,6 +109,51 @@ function registerWorkflowTools(server) {
                 }],
         };
     });
+    // invoke_workflow gated to configs registered read-safe — the invocation
+    // surface exposed to read-scoped MCP callers. Any workflow may be attempted;
+    // one lacking the flag fails with a clear error.
+    server.registerTool('invoke_workflow_read_safe', {
+        title: 'Invoke Read-Safe Workflow',
+        description: 'Start a workflow registered read-safe (side-effect-free). Same contract ' +
+            'as invoke_workflow, gated to configs carrying read_safe=true — the ' +
+            'variant exposed to read-scoped MCP callers. A workflow without the ' +
+            'flag fails with a clear error.',
+        inputSchema: schemas_1.invokeWorkflowSchema,
+    }, async (args) => {
+        const config = await configService.getWorkflowConfig(args.workflow_type);
+        if (!config?.invocable) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `workflow ${args.workflow_type} is not invocable` }),
+                    }],
+                isError: true,
+            };
+        }
+        if (!config.read_safe) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `workflow ${args.workflow_type} is not registered read-safe` }),
+                    }],
+                isError: true,
+            };
+        }
+        const result = await (0, workflow_invocation_1.invokeWorkflow)({
+            workflowType: args.workflow_type,
+            data: args.data,
+            metadata: args.metadata,
+            executeAs: args.execute_as,
+            options: args.options,
+            auth: { userId: 'lt-system', role: 'superadmin' },
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ workflow_id: result.workflowId, message: 'Workflow started' }),
+                }],
+        };
+    });
     // mirrors GET /api/workflows/:workflowId/status + /result
     server.registerTool('get_workflow_status', {
         title: 'Get Workflow Status',