@starci/hfs 4.2.14 → 4.2.16

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.2.16 - 2026-10-14
+
+- Fixed: the `add api`, `add table` and `add webhook` templates render code the published canons (eslint-canon-be 3.2.17, eslint-canon-fe 8.2.16) accept, as examples/lite-app shows. The GraphQL error formatter spec builds its malformed-operation error from a code (`GRAPHQL_VALIDATION_FAILED`), not prose (`user-copy-through-catalog`); `platform/graphql`'s context factory types its parameter with the named `GraphqlContext` (`no-inline-param-type`); both webhook door spec templates register `HttpSecurityModule` with the module's own default and override `WebhookSignatureService` with the real verifier over a fake clock instead of a global `ClockModule` (`is-global-only-in-app`).
+- Fixed: two tables no longer render duplicate code (`HFS_DUPLICATE_CODE`). The table service template answers `Pick<Row, "id">` through a named result type, throws its not-found error from one module-level factory handed to `requireOwnedRow` (whose factory now receives the id) and maps the insert's rows with a module-level `createdRow`.
+- Fixed: `add table --fe` renders no dead or aliased operation types (`HFS_UNUSED_EXPORT`, `HFS_ALIAS_REEXPORT`): the operation files type their request with the generated variables, the types files export only the answer, which the SWR hooks name. `useQuery<X>Swr` answers the operation's GraphQLResponse as its data (as the ecommerce example does) and `useMutateCreate<X>Swr` primes that query with the response.
+
+## 4.2.15 - 2026-10-13
+
+- Changed: the heroicons family is the one application icon set (owner ruling 2026-10-13): the scaffold installs `@heroicons/react` 2.2.0 and `@starci/heroicons` 0.3.3 (fe-stack `icons`, tier core) in every product fe app in place of `@phosphor-icons/react`, and the `modules/toast` skeleton draws its status indicators with `@heroicons/react/24/outline` (CheckCircleIcon, XCircleIcon, ExclamationTriangleIcon, InformationCircleIcon). Carry the canon pins of eslint-canon-be 3.2.17, eslint-canon-fe 8.2.16 and CLI 1.2.15.
+
 ## 4.2.14 - 2026-10-13
 
 - Breaking: HFS manifest 3.0.0 (schema `starci/hfs-slots@3`, rule catalog `starci/hfs-rules@3` 3.0.0). Removing the front-end database slots and the Supabase realtime feature slot and narrowing `fe.route` change answers for existing apps, so the manifest takes a major: every app pins `"hfs": 3` (scaffold writes it), and an app still pinned to 2 is refused with `HFS_MANIFEST_MAJOR_MISMATCH`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.2.14",
+  "version": "4.2.16",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -14,8 +14,13 @@ purpose: >-
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
-  # @starci/heroicons has no pin since 1.0.0-alpha.13: the application icon set is @phosphor-icons/react (fe-stack.yaml
-  # icons) and eslint-canon-fe one-icon-set refuses every other glyph catalogue, so no product repository installs it.
+  '@starci/heroicons':
+    version: 0.3.4
+    group: starci
+    install: registry
+    side: fe
+    source: packages/heroicons/package.json
+    why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
     version: 0.9.14
     group: starci
@@ -24,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.2.16
+    version: 3.2.18
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.2.15
+    version: 8.2.17
     group: starci
     install: registry
     side: fe
@@ -71,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.2.14
+    version: 1.2.16
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.2.14
+    version: 4.2.16
     group: starci
     install: registry
     side: both
@@ -360,11 +365,11 @@ pins:
     group: framework
     side: fe
     why: 'the fan-out emitter behind the socket side-effect component (fe-stack realtime); version read from the starci-academy package-lock on 2026-10-13.'
-  '@phosphor-icons/react':
-    version: 2.1.10
+  '@heroicons/react':
+    version: 2.2.0
     group: ui
     side: fe
-    why: 'the one application icon set (fe-stack icons); version read from the starci-academy package-lock on 2026-10-13.'
+    why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-canon-fe (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
   'next-themes':
     version: 0.4.6
     group: ui

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -99,11 +99,14 @@ concerns:
     why: the grammar renderers over HeroUI and Tailwind; no second UI kit and no CSS-in-JS.
   - id: icons
     tier: core
-    packages: ['@phosphor-icons/react']
+    packages: ['@heroicons/react', '@starci/heroicons']
     home: [fe.components]
     pattern: FE-ICON
-    forbids: [react-icons, lucide-react, '@iconify/react', '@gravity-ui/icons', '@tabler/icons-react', '@fortawesome/react-fontawesome']
-    why: one application icon set.
+    forbids: ['@phosphor-icons/react', react-icons, lucide-react, '@iconify/react', '@gravity-ui/icons', '@tabler/icons-react', '@fortawesome/react-fontawesome']
+    why: >-
+      one application icon set, the heroicons family (owner ruling 2026-10-13), on the 24/outline and 16/solid cuts. @heroicons/react
+      is the base set and is used first; @starci/heroicons holds only the glyphs heroicons lacks (brand or domain glyphs drawn in
+      heroicons style), never duplicates a heroicons glyph, and a missing glyph is added to it.
   - id: theme
     tier: core
     packages: [next-themes]

package/runtime/knowledge/hfs/rules.yaml

@@ -987,13 +987,13 @@ rules:
       - {kind: eslint-fe, id: component-purity}
   - id: R93
     code: "FE_VENDOR_BOUNDARY"
-    law: "Vendor primitives and icons reach components only through their named owner: the one icon set of knowledge/hfs/fe-stack.yaml through the icon leaf at the glyph scale, every vendor primitive behind a named owner; the Grammar package is imported only through its selected code and style entry and keeps its declared contract."
+    law: "Vendor primitives and icons reach components only through their named owner: the one icon set of knowledge/hfs/fe-stack.yaml (the heroicons family) through the icon leaf at the glyph scale, every vendor primitive behind a named owner; the Grammar package is imported only through its selected code and style entry and keeps its declared contract."
     kinds: [lint, codemod]
     gates: [pre-commit, pre-push, settle, land, ci]
     failureCodes: ["FE_VENDOR_BOUNDARY", "ARCH_GRAMMAR_CONTRACT_INVALID", "ARCH_GRAMMAR_EXPORT_BYPASS"]
     enforcers:
       - {kind: eslint-fe, id: no-vendor-icon-outside-icon-leaf}
-      - {kind: eslint-fe, id: one-icon-set}
+      - {kind: eslint-fe, id: heroicons-is-the-glyph-vendor}
       - {kind: eslint-fe, id: no-off-scale-glyph-size}
       - {kind: eslint-fe, id: no-decorative-icon-in-metric-cell}
       - {kind: eslint-fe, id: vendor-primitive-has-named-owner}

package/runtime/modules/kernel/removed-vocabulary.yaml

@@ -309,8 +309,3 @@ removed:
     name: anonymousActions
     use: 'the front end holds no Server Action (R243 FE_SERVER_ACTION_FORBIDDEN), so no slot lists anonymous ones'
     since: 1.0.0-alpha.13
-  - id: lint-heroicons-is-the-glyph-vendor
-    kind: vocabulary
-    name: heroicons-is-the-glyph-vendor
-    use: 'the eslint-fe rule is one-icon-set: the application icon set is @phosphor-icons/react (knowledge/hfs/fe-stack.yaml icons), imported only by the Icon leaf; the grammar Icon takes whatever glyph the app supplies'
-    since: 1.0.0-alpha.13

package/runtime/scripts/hfs/architecture/dead-exports.mjs

@@ -9,7 +9,10 @@
  *
  * Owner = every graph.ownerRoots unit whose tier is not `app` and whose public entry file is in the graph (index.ts or
  * index.tsx, a package's src/index.ts). The `entries` its slot declares (slot data: a second public entry file of the owner) are further
- * public entries of the same owner, judged exactly like the entry. The exported names of an entry are its named exports, `export { a as b }`,
+ * public entries of the same owner, judged like the entry, with one addition: a name another declared entry of the owner
+ * imports (not re-exports) is used, because it is part of that entry's public signature (an operation file
+ * `graphql/queries/query-<x>.ts` typing its request and answer with `graphql/queries/types/<x>.ts`). A barrel or any other
+ * non-entry file of the owner still does not count. The exported names of an entry are its named exports, `export { a as b }`,
  * `export { x } from`, declarations with `export`, and `default` for `export default`. `export *` is refused by owners.mjs
  * and contributes no name here.
  *
@@ -330,11 +333,22 @@ const unusedExportViolation = (publicEntry, name, line, owner) => ({
   message: `${publicEntry} exports ${name}, but no production file outside ${owner.root || 'the repository root'} imports it; remove the export (only a unit role spec, a fixture builder, a test world file, or an integration spec of this integration's own provider folder counts besides production files).`,
 });
 
-/** The unused-export violations and the export count of one public entry of an owner. */
-const publicEntryExports = (context, key, owner, publicEntry) => {
+/** Adds to `used` what another declared entry of the same owner imports from `publicEntry`: that entry's signature makes it public. */
+const addSiblingEntryUses = (context, publicEntry, declared, used) => {
+  for (const edge of context.edgesTo.get(publicEntry) ?? []) {
+    if (edge.reexport || edge.from === publicEntry || !declared.has(edge.from)) continue;
+    const bindings = bindingsOf(context.ts, edge.edge.declaration);
+    if (bindings.all) used.all = true;
+    for (const pair of bindings.pairs) used.names.add(pair.imported);
+  }
+};
+
+/** The unused-export violations and the export count of one public entry of an owner (`declared`: its slot's extra entries). */
+const publicEntryExports = (context, key, owner, publicEntry, declared) => {
   const names = exportedNames(context.ts, context.graph.files.get(publicEntry).sourceFile);
   const used = consumedNames(context, publicEntry, key, 0, new Set([publicEntry]));
   addReexportedUses(context, key, publicEntry, used);
+  if (declared.has(publicEntry)) addSiblingEntryUses(context, publicEntry, declared, used);
   const violations = [...names]
     .filter(([name]) => !(used.all || used.names.has(name)))
     .map(([name, line]) => unusedExportViolation(publicEntry, name, line, owner));
@@ -351,8 +365,9 @@ const ownerExportFindings = (context, config) => {
     const entry = entryOf(graph, config, key, owner);
     if (!entry) continue;
     owners += 1;
-    for (const publicEntry of [entry, ...extraEntries(graph, entry)]) {
-      const found = publicEntryExports(context, key, owner, publicEntry);
+    const declared = new Set(extraEntries(graph, entry));
+    for (const publicEntry of [entry, ...declared]) {
+      const found = publicEntryExports(context, key, owner, publicEntry, declared);
       exports += found.exports;
       violations.push(...found.violations);
     }

package/templates/be/inbox/webhook-door.spec.ts.tpl

@@ -4,9 +4,9 @@ import type { RawBodyRequest } from "@nestjs/common"
 import { Test } from "@nestjs/testing"
 import type { Request } from "express"
 import { @@Provider@@InboxService } from "@modules/domain/@@provider@@-inbox"
-import { CLOCK, ClockModule } from "@modules/platform/clock"
 import { Secret } from "@modules/platform/config"
-import { HttpSecurityModule } from "@modules/platform/http-security"
+import { HttpSecurityModule, WebhookSignatureService } from "@modules/platform/http-security"
+import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import { @@Event@@Request } from "./dto/@@event@@.request"
 import { @@Provider@@Webhook } from "./@@provider@@.webhook"
 
@@ -26,26 +26,25 @@ const DELIVERY = deliveryOf()
 const RAW_BODY = Buffer.from(JSON.stringify(DELIVERY))
 const REQUEST = mock<RawBodyRequest<Request>>({ rawBody: RAW_BODY })
 
+const OPTIONS: HttpSecurityOptions = {
+    allowedOrigins: [],
+    rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
+    webhooks: { "@@provider@@": { secret: new Secret(SECRET), toleranceMs: 300_000 } },
+}
+
 const sign = (rawBody: Buffer, timestamp: string): string =>
     `sha256=${createHmac("sha256", SECRET).update(`${timestamp}.`).update(rawBody).digest("hex")}`
 
 const build = async (deliveries: @@Provider@@InboxService) => {
     const moduleRef = await Test.createTestingModule({
-        imports: [
-            ClockModule.register({ isGlobal: true }),
-            HttpSecurityModule.register({
-                allowedOrigins: [],
-                rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
-                webhooks: { "@@provider@@": { secret: new Secret(SECRET), toleranceMs: 300_000 } },
-            }),
-        ],
+        imports: [HttpSecurityModule.register(OPTIONS)],
         controllers: [@@Provider@@Webhook],
         providers: [
             { provide: @@Provider@@InboxService, useValue: deliveries },
         ],
     })
-        .overrideProvider(CLOCK)
-        .useValue(new FakeClock(AT))
+        .overrideProvider(WebhookSignatureService)
+        .useValue(new WebhookSignatureService(OPTIONS, new FakeClock(AT)))
         .compile()
     return moduleRef.get(@@Provider@@Webhook)
 }

package/templates/be/patterns/webhooks/webhook.door.spec.ts.tpl

@@ -4,9 +4,9 @@ import type { RawBodyRequest } from "@nestjs/common"
 import { Test } from "@nestjs/testing"
 import type { Request } from "express"
 import { @@service@@ } from "@@serviceModule@@"
-import { CLOCK, ClockModule } from "@modules/platform/clock"
 import { Secret } from "@modules/platform/config"
-import { HttpSecurityModule } from "@modules/platform/http-security"
+import { HttpSecurityModule, WebhookSignatureService } from "@modules/platform/http-security"
+import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import { @@Event@@Request } from "./dto/@@event@@.request"
 import { @@Provider@@Webhook } from "./@@provider@@.webhook"
 
@@ -25,26 +25,25 @@ const DELIVERY = deliveryOf()
 const RAW_BODY = Buffer.from(JSON.stringify(DELIVERY))
 const REQUEST = mock<RawBodyRequest<Request>>({ rawBody: RAW_BODY })
 
+const OPTIONS: HttpSecurityOptions = {
+    allowedOrigins: [],
+    rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
+    webhooks: { "@@provider@@": { secret: new Secret(SECRET), toleranceMs: 300_000 } },
+}
+
 const sign = (rawBody: Buffer, timestamp: string): string =>
     `sha256=${createHmac("sha256", SECRET).update(`${timestamp}.`).update(rawBody).digest("hex")}`
 
 const build = async (deliveries: @@service@@) => {
     const moduleRef = await Test.createTestingModule({
-        imports: [
-            ClockModule.register({ isGlobal: true }),
-            HttpSecurityModule.register({
-                allowedOrigins: [],
-                rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
-                webhooks: { "@@provider@@": { secret: new Secret(SECRET), toleranceMs: 300_000 } },
-            }),
-        ],
+        imports: [HttpSecurityModule.register(OPTIONS)],
         controllers: [@@Provider@@Webhook],
         providers: [
             { provide: @@service@@, useValue: deliveries },
         ],
     })
-        .overrideProvider(CLOCK)
-        .useValue(new FakeClock(AT))
+        .overrideProvider(WebhookSignatureService)
+        .useValue(new WebhookSignatureService(OPTIONS, new FakeClock(AT)))
         .compile()
     return moduleRef.get(@@Provider@@Webhook)
 }

package/templates/be/platform/errors-graphql/graphql-error.mapper.spec.ts

@@ -9,7 +9,7 @@ describe("formatGraphqlError", () => {
     it("keeps the message of a malformed operation and marks it invalid without describing it", () => {
         const errors = mock<ErrorsService>()
 
-        expect(formatGraphqlError(errors, formatted, new GraphQLError("Cannot query field"))).toEqual({
+        expect(formatGraphqlError(errors, formatted, new GraphQLError("GRAPHQL_VALIDATION_FAILED"))).toEqual({
             message: "raw",
             path: ["item"],
             locations: [{ line: 1, column: 3 }],

package/templates/be/platform/graphql/graphql.module.ts

@@ -3,7 +3,6 @@ import type { ApolloDriverConfig } from "@nestjs/apollo"
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { GraphQLModule as NestGraphQLModule } from "@nestjs/graphql"
-import type { Request, Response } from "express"
 import { ERRORS_SERVICE, formatGraphqlError } from "@modules/platform/errors"
 import type { ErrorsService } from "@modules/platform/errors"
 import { REQUEST_LOCALE } from "@modules/platform/i18n"
@@ -37,7 +36,7 @@ export class GraphqlModule extends ConfigurableModuleClass {
                         path: "/graphql",
                         playground: false,
                         introspection: true,
-                        context: ({ req, res }: { req: Request; res: Response }): GraphqlContext => ({ req, res }),
+                        context: ({ req, res }: GraphqlContext): GraphqlContext => ({ req, res }),
                         formatError: (formatted, error) => formatGraphqlError(errors, formatted, error),
                         validationRules: [depthLimitRule(GRAPHQL_DEPTH_MAX)],
                         plugins: [localizeErrorsPlugin(errors, requestLocale)],

package/templates/be/skeleton-lite/src/modules/platform/database/database.sql.ts

@@ -33,9 +33,9 @@ function assertSqlIdent(_value: string): asserts _value is SqlIdent {
 /** Checks a dynamic identifier against the names the caller allows and brands it. */
 {{> be/common/sql-ident.ts.partial}}
 
-type NotFoundFactory = () => never
+type NotFoundFactory = (id: string) => never
 
-/** Requires the row selected by an id-and-owner statement and lets the capability own its typed not-found error. */
+/** Requires the row selected by an id-and-owner statement and lets the capability own its typed not-found error of that id. */
 export const requireOwnedRow = async <T>(
     entityManager: EntityManager,
     statement: SqlText,
@@ -44,6 +44,6 @@ export const requireOwnedRow = async <T>(
     notFound: NotFoundFactory,
 ): Promise<T> => {
     const row = (await entityManager.query<Array<T>>(statement, [id, ownerId]))[0]
-    if (row === undefined) return notFound()
+    if (row === undefined) return notFound(id)
     return row
 }

package/templates/be/table/service.api.ts.tpl

@@ -5,8 +5,18 @@ import { {{Name}}Error, {{Name}}ErrorCode } from "./errors/{{name}}.error"
 import type { {{Name}}Row } from "./persistence/{{name}}.rows"
 import { FIND_{{upper}}, INSERT_{{upper}} } from "./persistence/{{name}}.sql"
 
-interface {{Name}}Result {
-    readonly id: string
+/** What the capability answers for one row: its id. */
+type {{Name}}Result = Pick<{{Name}}Row, "id">
+
+/** Throws the typed not-found error of one id: absent and denied rows share it. */
+const notFound = (id: string): never => {
+    throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotFound, params: { id } })
+}
+
+/** The row an insert answered; an insert that answered none throws the typed not-created error. */
+const createdRow = ([row]: ReadonlyArray<{{Name}}Result>): {{Name}}Result => {
+    if (row === undefined) throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotCreated })
+    return row
 }
 
 @Injectable()
@@ -16,15 +26,11 @@ export class {{Name}}Service {
 
     /** Answers one row owned by the authenticated principal; absent and denied rows share one typed not-found result. */
     {{nameCamel}}(principalId: string, id: string): Promise<{{Name}}Result> {
-        return requireOwnedRow<Pick<{{Name}}Row, "id">>(this.entityManager, FIND_{{upper}}, id, principalId, () => {
-            throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotFound, params: { id } })
-        })
+        return requireOwnedRow<{{Name}}Result>(this.entityManager, FIND_{{upper}}, id, principalId, notFound)
     }
 
     /** Creates one row owned by the authenticated principal and answers its id. */
-    async create{{Singular}}(principalId: string): Promise<{{Name}}Result> {
-        const [row] = await this.entityManager.query<Array<Pick<{{Name}}Row, "id">>>(INSERT_{{upper}}, [principalId])
-        if (row === undefined) throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotCreated })
-        return { id: row.id }
+    create{{Singular}}(principalId: string): Promise<{{Name}}Result> {
+        return this.entityManager.query<Array<{{Name}}Result>>(INSERT_{{upper}}, [principalId]).then(createdRow)
     }
 }

package/templates/be/table/service.ts.tpl

@@ -5,8 +5,12 @@ import { {{Name}}Error, {{Name}}ErrorCode } from "./errors/{{name}}.error"
 import type { {{Name}}Row } from "./persistence/{{name}}.rows"
 import { FIND_{{upper}} } from "./persistence/{{name}}.sql"
 
-interface {{Name}}Result {
-    readonly id: string
+/** What the capability answers for one row: its id. */
+type {{Name}}Result = Pick<{{Name}}Row, "id">
+
+/** Throws the typed not-found error of one id: absent and denied rows share it. */
+const notFound = (id: string): never => {
+    throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotFound, params: { id } })
 }
 
 @Injectable()
@@ -16,8 +20,6 @@ export class {{Name}}Service {
 
     /** Answers one row owned by the authenticated principal; absent and denied rows share one typed not-found result. */
     {{nameCamel}}(principalId: string, id: string): Promise<{{Name}}Result> {
-        return requireOwnedRow<Pick<{{Name}}Row, "id">>(this.entityManager, FIND_{{upper}}, id, principalId, () => {
-            throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotFound, params: { id } })
-        })
+        return requireOwnedRow<{{Name}}Result>(this.entityManager, FIND_{{upper}}, id, principalId, notFound)
     }
 }

package/templates/fe/skeleton/apps/__app__/src/modules/toast/toast.tsx

@@ -1,5 +1,10 @@
+import {
+    CheckCircleIcon,
+    ExclamationTriangleIcon,
+    InformationCircleIcon,
+    XCircleIcon,
+} from "@heroicons/react/24/outline"
 import { toast as heroToast } from "@heroui/react"
-import { CheckCircleIcon, InfoIcon, WarningIcon, XCircleIcon } from "@phosphor-icons/react"
 import type { ReactNode } from "react"
 
 /** The options a status toast takes: HeroUI's, minus the variant the status already names. */
@@ -9,8 +14,8 @@ type StatusToastOptions = Parameters<typeof heroToast.success>[1]
 const INDICATOR: Record<"success" | "danger" | "warning" | "info", ReactNode> = {
     success: <CheckCircleIcon className="size-6 text-success-soft-foreground" />,
     danger: <XCircleIcon className="size-6 text-danger-soft-foreground" />,
-    warning: <WarningIcon className="size-6 text-warning-soft-foreground" />,
-    info: <InfoIcon className="size-6 text-accent" />,
+    warning: <ExclamationTriangleIcon className="size-6 text-warning-soft-foreground" />,
+    info: <InformationCircleIcon className="size-6 text-accent" />,
 }
 
 /** The app's toast: HeroUI's imperative toast with the status indicator injected; the region is mounted by the providers. */

package/templates/fe/table/graphql/mutation.ts.tpl

@@ -3,7 +3,7 @@ import type { TypedDocumentNode } from "@apollo/client"
 import type { Create{{Singular}}Mutation, Create{{Singular}}MutationVariables } from "../__generated__/graphql"
 import { createAuthApolloClient, graphqlResponseOf } from "../clients"
 import type { GraphQLResponse, OperationParams } from "../types"
-import type { MutateCreate{{Singular}}Data, MutateCreate{{Singular}}Request } from "./types/create-{{singular}}"
+import type { MutateCreate{{Singular}}Data } from "./types/create-{{singular}}"
 
 /** The `create{{Singular}}` mutation of the back end (be/src/features/api/{{name}}, create-{{singular}}). */
 const MUTATION_CREATE_{{singularUpper}}: TypedDocumentNode<Create{{Singular}}Mutation, Create{{Singular}}MutationVariables> = gql`
@@ -18,7 +18,7 @@ const MUTATION_CREATE_{{singularUpper}}: TypedDocumentNode<Create{{Singular}}Mut
 export const mutateCreate{{Singular}} = async ({
     request,
     signal,
-}: OperationParams<MutateCreate{{Singular}}Request>): Promise<GraphQLResponse<MutateCreate{{Singular}}Data>> =>
+}: OperationParams<Create{{Singular}}MutationVariables>): Promise<GraphQLResponse<MutateCreate{{Singular}}Data>> =>
     graphqlResponseOf(
         await createAuthApolloClient({ signal }).mutate({ mutation: MUTATION_CREATE_{{singularUpper}}, variables: request }),
         (data) => data.create{{Singular}},

package/templates/fe/table/graphql/mutation.types.ts.tpl

@@ -1,7 +1,4 @@
-import type { Create{{Singular}}Mutation, Create{{Singular}}MutationVariables } from "../../__generated__/graphql"
+import type { Create{{Singular}}Mutation } from "../../__generated__/graphql"
 
-/** What mutateCreate{{Singular}} takes: the variables of the `create{{Singular}}` mutation (none: the caller owns the row). */
-export type MutateCreate{{Singular}}Request = Create{{Singular}}MutationVariables
-
-/** What mutateCreate{{Singular}} answers: the `create{{Singular}}` field. */
+/** What mutateCreate{{Singular}} answers: the `create{{Singular}}` field (generated from the back end's contract). */
 export type MutateCreate{{Singular}}Data = Create{{Singular}}Mutation["create{{Singular}}"]

package/templates/fe/table/graphql/query.ts.tpl

@@ -3,7 +3,7 @@ import type { TypedDocumentNode } from "@apollo/client"
 import type { {{Singular}}Query, {{Singular}}QueryVariables } from "../__generated__/graphql"
 import { createAuthApolloClient, graphqlResponseOf } from "../clients"
 import type { GraphQLResponse, OperationParams } from "../types"
-import type { Query{{Singular}}Data, Query{{Singular}}Request } from "./types/{{singular}}"
+import type { Query{{Singular}}Data } from "./types/{{singular}}"
 
 /** The `{{singularCamel}}` query of the back end (be/src/features/api/{{name}}, get-{{singular}}). */
 const QUERY_{{singularUpper}}: TypedDocumentNode<{{Singular}}Query, {{Singular}}QueryVariables> = gql`
@@ -18,7 +18,7 @@ const QUERY_{{singularUpper}}: TypedDocumentNode<{{Singular}}Query, {{Singular}}
 export const query{{Singular}} = async ({
     request,
     signal,
-}: OperationParams<Query{{Singular}}Request>): Promise<GraphQLResponse<Query{{Singular}}Data>> =>
+}: OperationParams<{{Singular}}QueryVariables["input"]>): Promise<GraphQLResponse<Query{{Singular}}Data>> =>
     graphqlResponseOf(
         await createAuthApolloClient({ signal }).query({ query: QUERY_{{singularUpper}}, variables: { input: request } }),
         (data) => data.{{singularCamel}},

package/templates/fe/table/graphql/query.types.ts.tpl

@@ -1,7 +1,4 @@
-import type { {{Singular}}Query, {{Singular}}QueryVariables } from "../../__generated__/graphql"
+import type { {{Singular}}Query } from "../../__generated__/graphql"
 
-/** What query{{Singular}} takes: the input of the `{{singularCamel}}` query (generated from the back end's contract). */
-export type Query{{Singular}}Request = {{Singular}}QueryVariables["input"]
-
-/** What query{{Singular}} answers: the `{{singularCamel}}` field. */
+/** What query{{Singular}} answers: the `{{singularCamel}}` field (generated from the back end's contract). */
 export type Query{{Singular}}Data = {{Singular}}Query["{{singularCamel}}"]

package/templates/fe/table/graphql/useMutateSwr.ts.tpl

@@ -1,6 +1,8 @@
 import { useSWRConfig } from "swr"
 import useSWRMutation from "swr/mutation"
+import type { GraphQLResponse } from "@/modules/api"
 import { mutateCreate{{Singular}} } from "@/modules/api/graphql/mutations/mutation-create-{{singular}}"
+import type { MutateCreate{{Singular}}Data } from "@/modules/api/graphql/mutations/types/create-{{singular}}"
 import { QUERY_{{singularUpper}}_SWR_KEY } from "../queries/useQuery{{Singular}}Swr"
 
 /** The SWR key of the create-{{singular}} mutation. */
@@ -8,14 +10,13 @@ export const MUTATE_CREATE_{{singularUpper}}_SWR_KEY = "MUTATE_CREATE_{{singular
 
 /**
  * Creates one {{singular}} row; answers the GraphQLResponse so the caller reports it through modules/toast
- * (useGraphQLWithToast). A success primes the {{singular}} query of the new row, the resource the mutation is tied to.
+ * (useGraphQLWithToast). A success primes the {{singular}} query of the new row with that response.
  */
 export const useMutateCreate{{Singular}}Swr = () => {
     const { mutate } = useSWRConfig()
     return useSWRMutation(MUTATE_CREATE_{{singularUpper}}_SWR_KEY, async () => {
-        const response = await mutateCreate{{Singular}}({ request: {} })
-        if (response.success)
-            await mutate([QUERY_{{singularUpper}}_SWR_KEY, response.data.id], response.data, { revalidate: false })
+        const response: GraphQLResponse<MutateCreate{{Singular}}Data> = await mutateCreate{{Singular}}({ request: {} })
+        if (response.success) await mutate([QUERY_{{singularUpper}}_SWR_KEY, response.data.id], response, { revalidate: false })
         return response
     })
 }

package/templates/fe/table/graphql/useQuerySwr.ts.tpl

@@ -1,17 +1,14 @@
 import useSWR from "swr"
+import type { GraphQLResponse } from "@/modules/api"
 import { query{{Singular}} } from "@/modules/api/graphql/queries/query-{{singular}}"
 import type { Query{{Singular}}Data } from "@/modules/api/graphql/queries/types/{{singular}}"
 
 /** The SWR key of the {{singular}} query; the full key carries the row id, the identity of its result. */
 export const QUERY_{{singularUpper}}_SWR_KEY = "QUERY_{{singularUpper}}_SWR"
 
-/** One {{singular}} row of the signed-in reader by id; no id, no request. A failure is thrown as the GraphQLResponse's message. */
+/** One {{singular}} row of the signed-in reader by id, as its GraphQLResponse; no id, no request. */
 export const useQuery{{Singular}}Swr = (id: string | undefined) =>
     useSWR(
         id === undefined ? null : ([QUERY_{{singularUpper}}_SWR_KEY, id] as const),
-        async ([, rowId]): Promise<Query{{Singular}}Data> => {
-            const response = await query{{Singular}}({ request: { id: rowId } })
-            if (!response.success) throw new Error(response.message, { cause: response })
-            return response.data
-        },
+        ([, rowId]): Promise<GraphQLResponse<Query{{Singular}}Data>> => query{{Singular}}({ request: { id: rowId } }),
     )