@teamscala/service-boot 0.23.319 → 0.23.320

package/src/fn-routers/tasks-router.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for task creation with initial comment.
+ * Extracted from @teamscala/orpc/fn-router — primitives tier must not
+ * contain application-specific work_items logic.
+ */
+import { type Context } from "./auth-router.ts";
+export declare const tasksRouter: {
+    createWithComment: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        success: boolean;
+        data: any;
+    }, {
+        success: boolean;
+        data: any;
+    }>, Record<never, never>, Record<never, never>>;
+};

package/src/fn-routers/user-preferences-router.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for a GENERIC per-user preference store backed by the
+ * `user_preferences` table. The user is resolved from the ORPC session context
+ * (`authed` middleware → `context.user.id`); the client supplies the org + key
+ * + value. This is the DB-durable, user-scoped key/value surface any feature
+ * can use — the AI browser-control focus (key `ai_ui_focus`) is the first
+ * consumer; it is NOT scala-projects-bespoke.
+ *
+ * Why this exists (over the generated `user_preferences` CRUD): the generated
+ * create/update do NOT resolve `user_id` server-side (only `organisation_id`
+ * from ctx.orgId), so a client cannot correctly write a per-user row through
+ * them. This proc stamps `user_id` from the authenticated caller, making the
+ * write safe + per-user. It also emits the `data_change` notify so the
+ * realtime surface (regions.watchDataChange) pushes updates to subscribed
+ * clients — the cross-region channel for the AI focus (the AiChat panel writes
+ * a focus here; the project-list-view in a different region subscribes +
+ * reacts, no shared React-context ancestor needed).
+ *
+ * Ownership is user_id: a caller reads/writes ONLY their own preferences. The
+ * org is part of the compound key (per-org isolation) but is client-supplied
+ * (the session carries the user, not the active org).
+ *
+ * DECISION — host-scoping of `user_preferences`: the table is NOT yet a shared
+ * `@teamscala/db` model (it lives in scala-projects's schema today), so this proc
+ * is genuinely host-scoped: it runs correctly on services whose Prisma client
+ * declares `user_preferences` (scala-projects is the first host) + is inert
+ * elsewhere. `Context.prisma` is `any`-typed, so the proc COMPILES workspace-
+ * wide (no type error on a model a host may not declare) — the `any` is the
+ * deliberate seam that lets one generic proc serve hosts incrementally as they
+ * adopt the table. Per-user preferences are platform-universal, so the tracked
+ * follow-on is to promote `user_preferences` to a shared `@teamscala/db` model
+ * (open-migration: `user_preferences→shared-model`, exit: every kind:ui host
+ * can mount this proc with no schema precondition) — at which point the proc is
+ * universally hostable + the `any` seam can tighten to the shared client. Until
+ * then the proc is opt-in per host (declare the table → get the capability).
+ */
+import * as v from "valibot";
+import { type Context } from "./auth-router.ts";
+export declare const userPreferencesRouter: {
+    upsert: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, v.ObjectSchema<{
+        readonly organisationId: v.StringSchema<undefined>;
+        /** The preference key (e.g. `ai_ui_focus`). Namespaced by feature. */
+        readonly key: v.StringSchema<undefined>;
+        /** The JSON value. Arbitrary per feature — typed by the caller. */
+        readonly value: v.AnySchema;
+    }, undefined>, import("@orpc/contract").Schema<{
+        success: boolean;
+    }, {
+        success: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+    get: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, v.ObjectSchema<{
+        readonly organisationId: v.StringSchema<undefined>;
+        readonly key: v.StringSchema<undefined>;
+    }, undefined>, import("@orpc/contract").Schema<{
+        value: any;
+        updatedAt: any;
+    }, {
+        value: any;
+        updatedAt: any;
+    }>, Record<never, never>, Record<never, never>>;
+};

package/src/fn-routers/work-items-router.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedure for safely deleting a work_item (initiative/project/task).
+ * Refuses the delete when the row still has child rows (parent_id = id), so a
+ * delete can NEVER orphan its descendants — the tree must be emptied bottom-up.
+ *
+ * Initiatives, projects and tasks are all rows of the ONE `work_items` table
+ * discriminated by `kind`, and `parent_id` carries no DB-level foreign key, so
+ * a plain `work_items.delete` leaves dangling children with no referential
+ * integrity to stop it. This one guard covers every level (you may only delete
+ * a leaf — a node with no children), which is exactly the "empty it first"
+ * behaviour the board wants.
+ */
+import { type Context } from "./auth-router.ts";
+export declare const workItemsRouter: {
+    /**
+     * Fired client-side right after a task's status is set to
+     * "pending_approval" (RaCI: the task's assignee is Responsible; the
+     * project's Accountable person is the approver). Walks parent_id up to
+     * the nearest project-kind ancestor, emails every accountable person on
+     * it. Never throws to the caller — a notification failure must not block
+     * the status change that already committed.
+     */
+    requestApproval: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        notified: number;
+    }, {
+        notified: number;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * Fired client-side right after a comment is created, when the comment
+     * text contains an @mention the client already resolved to a team-member
+     * id (client does the name matching against the people list it already
+     * has loaded; this handler only sends). Never throws to the caller for
+     * same reason as requestApproval -- a notification failure must not
+     * surface as a failed comment post.
+     */
+    notifyMentions: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        notified: number;
+    }, {
+        notified: number;
+    }>, Record<never, never>, Record<never, never>>;
+    /**
+     * Org-scoped member list for the task-comments panel — @mention matching AND
+     * comment-sender display (name + avatar). ChatPanel.tsx has no
+     * serverLoader/orgId prop (client-only overlay content), so it can't do the
+     * SSR raw-SQL org-scope join load-project-list-view.ts uses; this exposes
+     * the same result via a custom procedure instead of widening service_schema
+     * to the raw better_auth_member table.
+     *
+     * This is the SINGLE source of member display info for the comments panel:
+     * it coalesces BOTH name/email/avatar families on the user model into one
+     * shape (the `full_name`/`primary_email`/`avatar_url` family AND the
+     * better-auth `name`/`email`/`image` family). Returning avatar here lets the
+     * client resolve sender name+avatar from this one list and drop the separate
+     * `user.findMany` enrichment fetch it previously ran as a second waterfall
+     * hop after `comments.findMany` (loading-shape: one wave-parallel hit, not a
+     * dependent client-side round-trip chain).
+     */
+    orgMembers: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        id: string;
+        name: string;
+        email: string;
+        avatar: string | null;
+    }[], {
+        id: string;
+        name: string;
+        email: string;
+        avatar: string | null;
+    }[]>, Record<never, never>, Record<never, never>>;
+    deleteEmpty: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        success: boolean;
+    }, {
+        success: boolean;
+    }>, Record<never, never>, Record<never, never>>;
+};

package/src/gate-ttls.d.ts

@@ -0,0 +1,6 @@
+/** Populate the TTL cache from the registry rows. Idempotent; keeps defaults on
+ *  any miss so the gates ALWAYS render (protective-layers-fail-explicitly). */
+export declare function initGateTtls(): Promise<void>;
+export declare function agTtlMs(): number;
+export declare function propTtlMs(): number;
+export declare function gptTtlMs(): number;

package/src/gpt-gate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The PUBLIC GPT identity gate, expressed as config for the content-gate
+ * primitive (content-gate/). Unlike proposals/agreements this is NOT access
+ * control — every email is a valid visitor (lead capture). Its whole job is to
+ * make a returning visitor's identity known AT SSR so the GPT body renders the
+ * real conversation on first paint instead of server-rendering the capture gate
+ * and then swapping to the chat after hydration (the ssr-then-live-handoff +
+ * "know the visitor at SSR first paint" violation: building-applications).
+ *
+ * Flow: the capture form POSTs {gptId, email} to /api/gpt-access (openCapture →
+ * any email matches); the access endpoint sets a signed `gpt_token` cookie. On
+ * the next request runContentGate verifies that cookie for this agent and seeds
+ * resolved.initialVisitor — which the GPT body serverLoader (ssrGptSession) then
+ * uses to SSR-restore the conversation, and GptBodyBlock uses to skip the gate.
+ * onUnauthorized is a no-op: an un-gated (first-time) visitor sees the capture
+ * form the block renders itself when no visitor is known — that is correct, not
+ * a flash (they ARE anonymous), so there is nothing to withhold.
+ */
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+export declare const gptGateConfig: ContentGateConfig;
+export declare const gptAccessConfig: AccessConfig;

package/src/handlers/bun-stable-watch.d.ts

@@ -0,0 +1 @@
+export {};

package/src/handlers/pane-outbox-drain.d.ts

@@ -0,0 +1 @@
+export {};

package/src/handlers/projects-digest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The `projects-daily-digest` / `projects-weekly-digest` pg-boss handlers for
+ * scala-projects. Same fixed-query shape as prune-stale-data: no row-driven
+ * SQL, every query is a literal Prisma call against work_items; the
+ * scheduled_job row only carries the cron.
+ *
+ * Daily digest: per assignee, tasks assigned to them created in the last 24h.
+ * Weekly digest: per assignee, their overdue tasks + tasks due in the next 7
+ * days. Both group work_items by assignee_id so one org-wide query covers
+ * every member, then send one email per assignee via the
+ * projects-daily-digest / projects-weekly-digest email_template rows.
+ *
+ * Registered under `@teamscala/service-boot:projects-daily-digest` and
+ * `@teamscala/service-boot:projects-weekly-digest`.
+ */
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+export declare function sendDailyDigest(_ctx: {
+    config: ScheduledJobConfig;
+}): Promise<void>;
+export declare function sendWeeklyDigest(_ctx: {
+    config: ScheduledJobConfig;
+}): Promise<void>;

package/src/handlers/prune-stale-data.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The `db-prune-stale-data` pg-boss handler. Reads the `retention` map from the
+ * `scheduled_job` row config and prunes stale rows per entry.
+ *
+ * Writes use Prisma ORM methods (deleteMany/updateMany) via the prisma-registry
+ * client — NEVER raw SQL. The `@teamscala/db` client carries the `blockRawSqlWrites`
+ * audit extension: `$executeRaw`/`$executeRawUnsafe` are blocked so every write
+ * is audited; ORM methods are the canonical audited path.
+ *
+ * SAFETY — identifier allowlist: each retention key selects a FIXED, hardcoded
+ * Prisma model + field (table/field names are literal in code, never derived
+ * from the row); the row's value (a duration string) is parsed to a cutoff Date.
+ * A row can therefore never inject arbitrary SQL or address an unvetted model.
+ * Keys not in the allowlist are skipped + logged.
+ *
+ * `audit_trail.*` is INTENTIONALLY EXCLUDED: `audit-trail-permanent` (critical)
+ * forbids any DELETE FROM audit_trail. The legacy row's
+ * `audit_trail.sync_entities: "delete all"` entry is stale drift from before
+ * the 2026-06-19 hardening — surfaced (skipped + warned), never executed.
+ *
+ * Registered under slug `@teamscala/service-boot:prune-stale-data`.
+ */
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+export declare function pruneStaleData({ config, }: {
+    config: ScheduledJobConfig;
+}): Promise<void>;

package/src/handlers/registry-stale-inactive-sweep.d.ts

@@ -0,0 +1 @@
+export {};

package/src/handlers/scala-tools-currency-watch.d.ts

@@ -0,0 +1 @@
+export {};

package/src/handlers/singleton-tools-currency-watch.d.ts

@@ -0,0 +1 @@
+export {};

package/src/handlers/singleton-tools-currency-watch.ts

@@ -30,40 +30,11 @@ import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { spawn } from "@teamscala/os/spawn";
 import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
 
-/**
- * Where a tool's "latest" comes from.
- *
- * A DISCRIMINATED UNION, deliberately, rather than an optional `repo` field
- * hanging off one shape: an unhandled variant then fails to compile instead of
- * silently taking the npm branch. The previous single-member form
- * (`type: "npm_package"`) made a GitHub-released binary UNREPRESENTABLE, not
- * merely unregistered — which is why codex and zerostack are absent from
- * `config/scala-singleton-tools` entirely. Both are standalone ELF binaries in
- * ~/.local/bin and neither is npm-managed, so neither could be described at all.
- *
- * Their LOCATION is correct and must not be "fixed": `bun-bin-is-unstable`
- * designates ${HOME}/.local/bin as the home for operator CLIs precisely so they
- * never shadow a /usr/local/bin singleton wrapper. The gap was currency
- * tracking, never placement.
- */
-type VersionSource =
-	| {
-			type: "npm_package";
-			name: string;
-			dist_tag: string;
-	  }
-	| {
-			/** A GitHub release asset — the shape codex and zerostack ship as. */
-			type: "github_release";
-			/** "owner/repo". */
-			repo: string;
-			/**
-			 * Regex matched against each release asset's name to pick the download.
-			 * Required: a repo publishing several platform builds has no safe default,
-			 * and guessing one installs the wrong architecture silently.
-			 */
-			asset_pattern: string;
-	  };
+interface VersionSource {
+	type: "npm_package";
+	name: string;
+	dist_tag: string;
+}
 
 interface SingletonTool {
 	name: string;
@@ -127,13 +98,9 @@ function semverLt(a: string, b: string): boolean {
 /** Read the installed version from a tool's real_path (symlink-resolved binary). */
 async function readInstalledVersion(tool: SingletonTool): Promise<string | null> {
 	try {
-		const vs = tool.version_source;
-		// The package.json path only exists for an npm-sourced JS tool. A
-		// github_release tool has no node_modules entry, so it falls through to the
-		// `--version` probe below like any other binary.
-		if (tool.kind === "js" && tool.install_dir && vs?.type === "npm_package") {
+		if (tool.kind === "js" && tool.install_dir) {
 			// JS tools: read the installed package's package.json
-			const pkgJsonPath = `${tool.install_dir}/node_modules/${vs.name}/package.json`;
+			const pkgJsonPath = `${tool.install_dir}/node_modules/${tool.version_source!.name}/package.json`;
 			const pkg = await Bun.file(pkgJsonPath).json() as { version: string };
 			return pkg.version;
 		}
@@ -152,30 +119,6 @@ async function readInstalledVersion(tool: SingletonTool): Promise<string | null>
 	}
 }
 
-/**
- * Latest published version for a GitHub-released tool.
- *
- * Reads the repo's latest release tag rather than enumerating assets, because
- * the tag is what carries the VERSION; the asset pattern only decides which
- * build to download at install time. A leading "v" is stripped so the value
- * compares against `readInstalledVersion` output under the same semver parser.
- */
-async function fetchLatestGithubRelease(repo: string): Promise<string | null> {
-	try {
-		const res = await fetch(
-			`https://api.github.com/repos/${repo}/releases/latest`,
-			{ headers: { accept: "application/vnd.github+json" } },
-		);
-		if (!res.ok) return null;
-		const release = (await res.json()) as { tag_name?: string };
-		const tag = (release.tag_name ?? "").trim().replace(/^v/, "");
-		if (!tag || !parseSemver(tag)) return null;
-		return tag;
-	} catch {
-		return null;
-	}
-}
-
 /** Fetch the latest version from npm for a given package + dist-tag. */
 async function fetchLatestVersion(pkg: string, distTag: string): Promise<string | null> {
 	try {
@@ -210,35 +153,7 @@ async function fetchLatestVersion(pkg: string, distTag: string): Promise<string
 /** Reinstall a stale tool to the latest version. */
 async function reinstallTool(tool: SingletonTool, latest: string): Promise<boolean> {
 	const log = getAppLogger();
-	const vs = tool.version_source;
-	if (!vs) return false;
-
-	if (vs.type === "github_release") {
-		// A GitHub-released binary is NOT installed by a package manager, so there
-		// is no "reinstall" verb to call — it would have to be downloaded, verified,
-		// made executable and swapped atomically over a file that may be RUNNING.
-		// That is a real install path with real failure modes (partial download,
-		// wrong architecture, replacing a binary mid-execution), and doing it badly
-		// is worse than not doing it: a half-written CLI is a broken CLI.
-		//
-		// So this reports the drift and stops. Detection is live from today; the
-		// automated swap is a separate, deliberate change. Reporting a version the
-		// watcher cannot actually install is honest — silently claiming currency
-		// would not be.
-		log.warn(
-			`[singleton-tools-currency] ${tool.name}: STALE, latest ${latest} from ${vs.repo}. Automated github_release install is not implemented — update it manually.`,
-		);
-		recordEvent({
-			kind: "singleton-tools.currency.tick",
-			payload: {
-				tool: tool.name,
-				latest,
-				status: "stale-manual-update-required",
-				repo: vs.repo,
-			},
-		});
-		return false;
-	}
+	const vs = tool.version_source!;
 
 	if (tool.kind === "js" && tool.install_dir) {
 		// JS tool: bun add in the install_dir
@@ -297,21 +212,8 @@ async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig })
 
 	for (const tool of config.tools) {
 		const vs = tool.version_source;
-		if (!vs) {
-			// A tool with no version_source is NOT tracked, and that must be loud.
-			// This previously `continue`d silently as "not yet inside the mechanism",
-			// which is how a gap becomes permanent: nothing distinguishes a tool
-			// nobody has declared from one that is up to date, so the watcher reports
-			// a clean tick while the tool rots. That is the exact shape of
-			// `a-component-may-not-report-a-state-it-has-not-verified` — the run
-			// advertises coverage it never performed.
-			log.warn(
-				`[singleton-tools-currency] ${tool.name}: NO version_source — not tracked, cannot be kept current. Add one to config/scala-singleton-tools.`,
-			);
-			recordEvent({
-				kind: "singleton-tools.currency.tick",
-				payload: { tool: tool.name, status: "no-version-source" },
-			});
+		if (!vs || vs.type !== "npm_package") {
+			// No version_source declared — skip (the tool is not yet inside the mechanism)
 			continue;
 		}
 
@@ -334,12 +236,7 @@ async function singletonToolsCurrencyWatch(_ctx: { config: ScheduledJobConfig })
 			continue;
 		}
 
-		// Branch on the discriminant, never on a field's presence — an unhandled
-		// variant is a compile error here rather than a silent fall-through to npm.
-		const latest =
-			vs.type === "npm_package"
-				? await fetchLatestVersion(vs.name, vs.dist_tag)
-				: await fetchLatestGithubRelease(vs.repo);
+		const latest = await fetchLatestVersion(vs.name, vs.dist_tag);
 		if (!latest) {
 			log.warn(`[singleton-tools-currency] ${tool.name}: cannot fetch latest — skip`);
 			recordEvent({

package/src/handlers/sweep-event-log.d.ts

@@ -0,0 +1 @@
+export {};

package/src/handlers/sweep-host-cache.d.ts

@@ -0,0 +1 @@
+export {};