@hyperfixation/core 0.1.0

package/dist/workspace-views.d.ts

@@ -0,0 +1,143 @@
+/**
+ * What the workspace reads. Every function here is a control-plane read on the attached pool —
+ * plain unlocked SELECTs over the machinery tables and the app's own record table, no lock and
+ * no write — and every one is refused from inside a run for the reason `records.archive()`
+ * gives: a control-plane pool call made under a step's open transaction is a wait no deadlock
+ * detector can see.
+ *
+ * The views live here and not in `workspace.ts` because that file is the framework-light
+ * subpath the template imports: it stays pure and synchronous, and only the types cross over.
+ */
+import type { ApprovalDecisionKind, DecideResult } from "@hyperfixation/workflows";
+import type { Pool } from "pg";
+import { type ActivityRow } from "./activity.js";
+import { type LabelRow } from "./labels.js";
+import { type OutcomeRow } from "./outcomes.js";
+import { type RecordDefinition, type StageDefinition } from "./records.js";
+import type { Registry } from "./registry.js";
+import { type TaskRow } from "./tasks.js";
+import { DEFAULT_BOARD_LIMIT, type DraftField } from "./workspace.js";
+export { DEFAULT_BOARD_LIMIT };
+export declare const WORKSPACE_INBOX_OPERATION = "workspace.inbox";
+export declare const WORKSPACE_HOME_OPERATION = "workspace.home";
+export declare const WORKSPACE_BOARD_OPERATION = "workspace.board";
+export declare const WORKSPACE_RECORD_OPERATION = "workspace.record";
+/** The handles and registries every view reads through; `defineApp` supplies them. */
+export interface WorkspaceViewDeps {
+    pool: Pool;
+    records: Registry<RecordDefinition>;
+    /** True for an approval type with a registered draft schema — the only kind an edit reaches. */
+    hasSchema(type: string): boolean;
+}
+/** One pending approval, with its draft already flattened for whatever renders it. */
+export interface InboxItem {
+    approvalId: number;
+    runId: string;
+    flow: string;
+    key: string;
+    type: string;
+    recordType: string | null;
+    recordId: string | null;
+    /** The record's `displayColumn`; null when the approval names no record or the row is gone. */
+    recordTitle: string | null;
+    assigneeId: string | null;
+    createdAt: Date;
+    expiresAt: Date | null;
+    draft: unknown;
+    fields: DraftField[];
+    /** False when the approval's type registers no schema, which is what refuses every edit. */
+    editable: boolean;
+}
+export interface InboxOptions {
+    userId: string;
+    /** An admin sees every pending approval, not only their own and the unassigned ones. */
+    admin?: boolean;
+}
+export interface InboxView {
+    items: InboxItem[];
+    /** Counted over what this call returned, so an admin's counts are still their own. */
+    mine: number;
+    unassigned: number;
+}
+export interface HomeOptions {
+    userId: string;
+}
+export interface ReviewQueueCount {
+    source: string;
+    count: number;
+}
+export interface HomeView {
+    /** The user's own and the unassigned pending approvals — never someone else's. */
+    approvals: InboxItem[];
+    tasks: TaskRow[];
+    reviewQueue: ReviewQueueCount[];
+}
+export interface BoardOptions {
+    limit?: number;
+}
+export interface BoardCard {
+    id: string;
+    title: string | null;
+    stage: string | null;
+    score: number | null;
+    updatedAt: Date | null;
+}
+export interface BoardColumn {
+    stage: StageDefinition;
+    cards: BoardCard[];
+}
+export interface BoardView {
+    record: RecordDefinition;
+    columns: BoardColumn[];
+    /** Cards whose `stage` is null or names no registered stage. */
+    other: BoardCard[];
+    /** The limit this read used, whether the caller gave one or not. */
+    limit: number;
+    /** True when the table holds more unarchived rows than `limit` returned. */
+    truncated: boolean;
+}
+/** One run's writes on a record, in order. `runId` null is the manual group. */
+export interface TimelineGroup {
+    runId: string | null;
+    flow: string | null;
+    startedAt: Date | null;
+    entries: ActivityRow[];
+}
+export interface RecordView {
+    record: RecordDefinition;
+    id: string;
+    title: string | null;
+    /** The app table's own row, column names as the table spells them. */
+    row: Record<string, unknown>;
+    archivedAt: Date | null;
+    timeline: TimelineGroup[];
+    labels: LabelRow[];
+    outcomes: OutcomeRow[];
+    tasks: TaskRow[];
+    pendingApprovals: InboxItem[];
+}
+/** `DecideOptions` without `via`: the workspace is the web, and only the web. */
+export interface WorkspaceDecideOptions {
+    ids: number[];
+    decision: ApprovalDecisionKind;
+    /** Per-approval replacement drafts, parsed against the type's schema by `decide()`. */
+    edits?: Record<number, unknown>;
+    /** The client's own token, generated once per form mount, so a double submit replays. */
+    decisionKey: string;
+    userId?: string | null;
+    /** Whether the session holds the admin role; without it an assigned row refuses. */
+    admin?: boolean;
+}
+/** The reads `app.workspace` adds to the descriptors; all of them control-plane. */
+export interface WorkspaceViews {
+    inbox(options: InboxOptions): Promise<InboxView>;
+    home(options: HomeOptions): Promise<HomeView>;
+    board(recordType: string, options?: BoardOptions): Promise<BoardView>;
+    /** Undefined when the table holds no row with that id; an archived record still resolves. */
+    record(recordType: string, id: string | number): Promise<RecordView | undefined>;
+    decide(options: WorkspaceDecideOptions): Promise<DecideResult>;
+}
+export declare function workspaceInbox(deps: WorkspaceViewDeps, options: InboxOptions): Promise<InboxView>;
+export declare function workspaceHome(deps: WorkspaceViewDeps, options: HomeOptions): Promise<HomeView>;
+export declare function workspaceBoard(deps: WorkspaceViewDeps, recordType: string, options?: BoardOptions): Promise<BoardView>;
+export declare function workspaceRecord(deps: WorkspaceViewDeps, recordType: string, id: string | number): Promise<RecordView | undefined>;

package/dist/workspace.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The workspace's descriptors, and the reason they are a second entry point: the workspace is
+ * paths, nav items and flattened drafts — no component, no `react`, nothing the template cannot
+ * render its own way. Everything here is pure and synchronous; the guard is the template's, on
+ * the layout that renders these, because a workspace 404 and a workspace sign-in look the same
+ * to a stranger only if one guard covers every route.
+ */
+import type { ActivityRow } from "./activity.js";
+import type { LabelRow } from "./labels.js";
+import type { OutcomeRow } from "./outcomes.js";
+import type { PageDefinition } from "./pages.js";
+import type { RecordDefinition, StageDefinition } from "./records.js";
+import type { Registry } from "./registry.js";
+import type { TaskRow } from "./tasks.js";
+import type { WorkspaceViews } from "./workspace-views.js";
+export type { ActivityRow, LabelRow, OutcomeRow, PageDefinition, RecordDefinition, Registry, StageDefinition, TaskRow, };
+/**
+ * The reads themselves are `@hyperfixation/core`'s — they need the pool — but their types are
+ * the template's to name, so they are re-exported here with the descriptors.
+ */
+export type { BoardCard, BoardColumn, BoardOptions, BoardView, HomeOptions, HomeView, InboxItem, InboxOptions, InboxView, RecordView, ReviewQueueCount, TimelineGroup, WorkspaceDecideOptions, WorkspaceViews, } from "./workspace-views.js";
+/** Where the template mounts the workspace. Only the default; `route()` takes what it is given. */
+export declare const WORKSPACE_BASE_PATH = "/w";
+/**
+ * How many cards a board reads per record type before it stops. Declared here rather than beside
+ * `workspaceBoard` so a template can name the default it is about to override without importing
+ * the reads — `workspace-views.ts` re-exports it for `.`.
+ */
+export declare const DEFAULT_BOARD_LIMIT = 500;
+export type WorkspaceRoute = {
+    kind: "home";
+} | {
+    kind: "inbox";
+} | {
+    kind: "approval";
+    id: number;
+} | {
+    kind: "board";
+    record: RecordDefinition;
+} | {
+    kind: "record";
+    record: RecordDefinition;
+    id: string;
+} | {
+    kind: "page";
+    page: PageDefinition;
+};
+export interface WorkspaceNavItem {
+    readonly path: string;
+    readonly title: string;
+}
+/** The two registries the workspace reads. `defineApp` passes its own. */
+export interface WorkspaceRegistries {
+    readonly records: Registry<RecordDefinition>;
+    readonly pages: Registry<PageDefinition>;
+}
+export interface AppWorkspace extends WorkspaceViews {
+    /**
+     * The catch-all's body: the segments below the mount point, resolved. `undefined` is a path the
+     * workspace does not serve. No guard and no `await` — unlike the admin's `route()`, this one
+     * resolves a path and nothing else.
+     */
+    route(path?: string | readonly string[]): WorkspaceRoute | undefined;
+    nav(): WorkspaceNavItem[];
+}
+export declare function approvalPath(id: number): string;
+export declare function workspaceRoute(registries: WorkspaceRegistries, path?: string | readonly string[]): WorkspaceRoute | undefined;
+export declare function workspaceNav(registries: WorkspaceRegistries): WorkspaceNavItem[];
+/** One row of a draft, ready to be shown or edited. `path` is also an edit form's field name. */
+export interface DraftField {
+    /** Dotted through objects and bracketed through arrays: `contacts[0].email`. */
+    readonly path: string;
+    /**
+     * The walk from the draft root: object keys verbatim, array indexes as numbers. `path` is a
+     * display string and two different leaves can share one — `{"a.b": 1}` and `{a: {b: 2}}` both
+     * read `a.b` — so anything writing a value back follows this instead. Empty for a bare scalar
+     * draft, which is its own root.
+     */
+    readonly segments: readonly (string | number)[];
+    readonly label: string;
+    readonly value: string;
+}
+/**
+ * A draft — an approval's `payload`, model output — flattened to rows. The values are the draft's
+ * own text, unescaped and unmarked-up: escaping belongs to whatever renders them, and a draft
+ * holding `<img src=x>` must reach the renderer as that literal string rather than as something
+ * this function decided was safe.
+ *
+ * A container contributes no row of its own, so an empty object or array flattens to nothing.
+ */
+export declare function draftFields(draft: unknown): DraftField[];

package/dist/workspace.js

@@ -0,0 +1,136 @@
+/**
+ * The workspace's descriptors, and the reason they are a second entry point: the workspace is
+ * paths, nav items and flattened drafts — no component, no `react`, nothing the template cannot
+ * render its own way. Everything here is pure and synchronous; the guard is the template's, on
+ * the layout that renders these, because a workspace 404 and a workspace sign-in look the same
+ * to a stranger only if one guard covers every route.
+ */
+/** Where the template mounts the workspace. Only the default; `route()` takes what it is given. */
+export const WORKSPACE_BASE_PATH = "/w";
+/**
+ * How many cards a board reads per record type before it stops. Declared here rather than beside
+ * `workspaceBoard` so a template can name the default it is about to override without importing
+ * the reads — `workspace-views.ts` re-exports it for `.`.
+ */
+export const DEFAULT_BOARD_LIMIT = 500;
+export function approvalPath(id) {
+    return `${WORKSPACE_BASE_PATH}/approvals/${id}`;
+}
+function segmentsOf(path) {
+    // A catch-all already hands back the segments below the mount, so an array is taken as-is — a
+    // record type named `w` stays reachable. Only a whole pathname has the mount on the front.
+    if (typeof path !== "string")
+        return (path ?? []).filter((segment) => segment.length > 0);
+    const segments = path.split("/").filter((segment) => segment.length > 0);
+    return segments[0] === WORKSPACE_BASE_PATH.slice(1) ? segments.slice(1) : segments;
+}
+/** `hf_approval.id` is a bigint identity, so anything else in the slot is not an approval. */
+function approvalIdOf(segment) {
+    if (!/^[1-9][0-9]*$/.test(segment))
+        return undefined;
+    const id = Number(segment);
+    return Number.isSafeInteger(id) ? id : undefined;
+}
+export function workspaceRoute(registries, path) {
+    const segments = segmentsOf(path);
+    if (segments.length === 0)
+        return { kind: "home" };
+    if (segments[0] === "approvals") {
+        if (segments.length === 1)
+            return { kind: "inbox" };
+        if (segments.length > 2)
+            return undefined;
+        const id = approvalIdOf(segments[1]);
+        return id === undefined ? undefined : { kind: "approval", id };
+    }
+    if (segments.length <= 2) {
+        const record = registries.records.get(segments[0]);
+        if (record !== undefined) {
+            const id = segments[1];
+            return id === undefined ? { kind: "board", record } : { kind: "record", record, id };
+        }
+    }
+    // Pages are keyed by their whole path, which is also the `href` `nav()` hands the template, so
+    // the lookup puts the mount back on the front of the segments it was given.
+    const page = registries.pages.get([WORKSPACE_BASE_PATH, ...segments].join("/"));
+    return page === undefined ? undefined : { kind: "page", page };
+}
+export function workspaceNav(registries) {
+    return [
+        { path: WORKSPACE_BASE_PATH, title: "Home" },
+        { path: `${WORKSPACE_BASE_PATH}/approvals`, title: "Inbox" },
+        ...registries.records.all().map((record) => ({
+            path: `${WORKSPACE_BASE_PATH}/${record.recordType}`,
+            title: record.title ?? record.recordType,
+        })),
+        ...registries.pages
+            .all()
+            .filter((page) => page.nav === true)
+            .map((page) => ({ path: page.path, title: page.title })),
+    ];
+}
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * A leaf is always text, never `null` or a number: the template renders these as strings and an
+ * edit form posts them back as strings, so the conversion happens once, here.
+ */
+function leafText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null || value === undefined)
+        return "";
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+        return String(value);
+    }
+    // A function, a symbol or an exotic object: nothing a JSON draft holds, and nothing worth
+    // guessing a rendering for.
+    return "";
+}
+function labelOf(key) {
+    const words = key
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[\s_-]+/)
+        .filter((word) => word.length > 0)
+        .map((word) => word.toLowerCase());
+    const sentence = words.join(" ");
+    return sentence.length === 0 ? key : sentence[0].toUpperCase() + sentence.slice(1);
+}
+function flatten(value, path, segments, label, into) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            flatten(item, `${path}[${index}]`, [...segments, index], `${label} ${index + 1}`, into);
+        });
+        return;
+    }
+    if (isPlainRecord(value)) {
+        for (const [key, nested] of Object.entries(value)) {
+            flatten(nested, path === "" ? key : `${path}.${key}`, [...segments, key], labelOf(key), into);
+        }
+        return;
+    }
+    into.push({ path, segments, label, value: leafText(value) });
+}
+/**
+ * A draft — an approval's `payload`, model output — flattened to rows. The values are the draft's
+ * own text, unescaped and unmarked-up: escaping belongs to whatever renders them, and a draft
+ * holding `<img src=x>` must reach the renderer as that literal string rather than as something
+ * this function decided was safe.
+ *
+ * A container contributes no row of its own, so an empty object or array flattens to nothing.
+ */
+export function draftFields(draft) {
+    if (Array.isArray(draft) || isPlainRecord(draft)) {
+        const fields = [];
+        flatten(draft, "", [], "Value", fields);
+        return fields;
+    }
+    // A bare scalar draft has no key to name it, and `value` is the field name a form would post.
+    return [{ path: "value", segments: [], label: "Value", value: leafText(draft) }];
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hyperfixation/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "defineApp, registries, resolution, records, activity, tasks, labels, outcomes, and the status endpoint",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grahamlutz/hyperfixation-core.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./workspace": {
+      "types": "./dist/workspace.d.ts",
+      "default": "./dist/workspace.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "dependencies": {
+    "@dbos-inc/dbos-sdk": "4.27.6",
+    "@hyperfixation/db": "0.1.0",
+    "@hyperfixation/workflows": "0.1.0",
+    "pg": "^8.23.0"
+  },
+  "devDependencies": {
+    "@hyperfixation/eslint-config": "0.1.0",
+    "@hyperfixation/testing": "0.1.0",
+    "@microsoft/api-extractor": "^7.59.1",
+    "@types/pg": "^8.23.1",
+    "eslint": "^10.10.0",
+    "zod": "4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src",
+    "api-extractor": "api-extractor run && api-extractor run -c api-extractor.workspace.json",
+    "api-extractor:update": "api-extractor run --local && api-extractor run --local -c api-extractor.workspace.json",
+    "test": "vitest run --passWithNoTests"
+  }
+}