@beignet/core 0.0.20 → 0.0.21

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @beignet/core
 
+## 0.0.21
+
+### Patch Changes
+
+- Ship TanStack Intent agent skills with Beignet packages and scaffold generated apps with Intent skill-loading guidance.
+
 ## 0.0.20
 
 ## 0.0.19

package/README.md

@@ -30,6 +30,13 @@ npm install arktype
 
 This package requires TypeScript 5.0 or higher for proper type inference.
 
+## Agent skills
+
+This package ships a TanStack Intent skill for coding agents:
+`@beignet/core#app-architecture`. Load it when adding or fixing Beignet
+schemas, contracts, use cases, app errors, ports, policies, app context,
+providers, workflow primitives, or core subpath imports.
+
 ## Subpaths
 
 Install `@beignet/core` once, then import the framework area you need. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/core",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "description": "Core framework primitives for Beignet",
   "exports": {
@@ -150,6 +150,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.test-d.ts",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -167,7 +168,8 @@
     "api",
     "typescript",
     "standard-schema",
-    "validation"
+    "validation",
+    "tanstack-intent"
   ],
   "license": "MIT",
   "repository": {

package/skills/app-architecture/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: app-architecture
+description: "Build Beignet app feature slices with @beignet/core primitives: schemas, contracts, use cases, app errors, ports, policies, context, providers, jobs, schedules, tasks, outbox, mail, uploads, and tests. Use when adding or fixing Beignet application behavior, dependency boundaries, app-facing ports, authorization, workflow primitives, or core subpath imports."
+---
+
+# Beignet App Architecture
+
+Use this skill when working in an app that depends on `@beignet/core`.
+Read the app's `AGENTS.md`, `beignet.config.*`, and closest existing feature
+slice before changing code.
+
+## Source Order
+
+1. Follow local app instructions and configured paths.
+2. Reuse the nearest feature slice's naming and helper exports.
+3. Inspect installed `@beignet/core/*` exports and types when an API is unclear.
+4. Read narrow Beignet docs only for the concept being changed.
+
+## Feature Slice
+
+Normal feature code belongs here:
+
+```txt
+features/<feature>/
+  contracts.ts
+  schemas.ts
+  routes.ts
+  use-cases/
+  ports.ts
+  policy.ts
+  client/
+  components/
+  tests/
+    factories/
+```
+
+Small features do not need every file. Add folders when the concern exists.
+
+## Core Boundaries
+
+- Contracts and schemas must be import-safe for clients and OpenAPI.
+- Use cases own business workflows and depend on `ctx.ports`, not infra.
+- Domain and use-case code must not import React, routes, providers, server
+  runtime, or concrete adapters.
+- Infra implements ports and may import provider packages, SDKs, and database
+  clients.
+- UI and feature client modules call server behavior through contracts and a
+  typed client, not by importing use cases.
+
+## Contracts And Schemas
+
+Use `@beignet/core/contracts` and keep shared DTOs in `schemas.ts`.
+
+```ts
+import { defineContractGroup } from "@beignet/core/contracts";
+import { z } from "zod";
+import { errors } from "@/features/shared/errors";
+
+export const projectSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+});
+
+const projects = defineContractGroup()
+  .namespace("projects")
+  .prefix("/api/projects");
+
+export const getProject = projects
+  .get("/:id")
+  .pathParams(z.object({ id: z.string().uuid() }))
+  .errors({ ProjectNotFound: errors.ProjectNotFound })
+  .responses({ 200: projectSchema });
+```
+
+If a route-backed use case throws `appError("ProjectNotFound")`, the matching
+contract should declare `ProjectNotFound` with `.errors(...)`.
+
+## Use Cases
+
+Use the app-bound `useCase` builder from `lib/use-case.ts`.
+
+```ts
+import { requireUserId } from "@beignet/core/ports";
+import { appError } from "@/features/shared/errors";
+import { projectIdInputSchema, projectSchema } from "@/features/projects/schemas";
+import { useCase } from "@/lib/use-case";
+
+export const getProjectUseCase = useCase
+  .query("projects.get")
+  .input(projectIdInputSchema)
+  .output(projectSchema)
+  .run(async ({ ctx, input }) => {
+    const userId = requireUserId(ctx);
+    const project = await ctx.ports.projects.findById(input.id);
+    if (!project) throw appError("ProjectNotFound", { details: input });
+
+    await ctx.gate.authorize("projects.read", project);
+    return project;
+  });
+```
+
+Use `ctx.ports.uow.transaction(...)` when writes, audit entries, events, jobs,
+or outbox records must commit together.
+
+## Errors And Policies
+
+- Generated apps usually place the error catalog in `features/shared/errors.ts`.
+  Some apps centralize it elsewhere; reuse the existing catalog.
+- Business authorization belongs in use cases or feature policies, not only
+  route metadata.
+- Put a policy in the feature that owns the authorized resource. Cross-feature
+  abilities may still live there when they inspect that resource.
+
+## Ports And Providers
+
+- Feature-specific ports usually live in `features/<feature>/ports.ts`.
+- App-wide ports live in `ports/`.
+- Default wiring belongs in `infra/app-ports.ts`.
+- `bound` ports are app-owned at boot, such as gates, config, clocks, IDs, or
+  no-op reporters.
+- `deferred` ports are supplied by providers at startup, such as auth,
+  database, mail, logger, jobs, repositories, idempotency, and rate limits.
+
+Do not import provider packages from contracts, use cases, routes, UI, or
+feature client modules.
+
+## Workflows
+
+Feature-owned workflow definitions belong under the feature:
+
+```txt
+features/<feature>/jobs/
+features/<feature>/schedules/
+features/<feature>/notifications/
+features/<feature>/tasks/
+features/<feature>/uploads/
+```
+
+Small existing apps may use feature-root `jobs.ts` or `schedules.ts`; follow
+local style unless migrating deliberately. Central registries and service
+contexts live under `server/`.
+
+Providers should not start unbounded background loops on server boot. Expose
+cron routes, worker entrypoints, task runners, schedule runners, or outbox
+drains instead.
+
+## Validation
+
+After core app-architecture changes, run from the app root:
+
+```bash
+beignet lint
+beignet doctor --strict
+bun run test
+bun run typecheck
+```
+
+Use the app's package manager and scripts. If package-manager shims are not on
+PATH, use local binaries such as `./node_modules/.bin/beignet lint`.