@hitch42/applet 0.1.1-beta.1

package/scaffold/.agents/skills/hitch-applets/references/client.md

@@ -0,0 +1,73 @@
+# Client routes and interface
+
+Read this file before you change client routes, navigation, page layout, forms, or controls.
+
+## Choose the client half
+
+- Use a client-only applet for a user interface that uses the current user's Hitch access.
+- Add a server only for secrets, external services, schedules, or imperative server work.
+- Do not add a server proxy for normal Hitch data access.
+
+## Define routes
+
+Hitch mounts each applet below `/<code>`. Include the applet code in every route path.
+
+Use these file and path pairs:
+
+| File                                   | Route path          |
+| -------------------------------------- | ------------------- |
+| `src/client/routes/index.tsx`          | `/<code>/`          |
+| `src/client/routes/about.tsx`          | `/<code>/about`     |
+| `src/client/routes/settings/index.tsx` | `/<code>/settings/` |
+
+Define a page with `createFileRoute`:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/<code>/about")({
+  component: AboutPage,
+});
+
+function AboutPage() {
+  return <main>About</main>;
+}
+```
+
+- Keep the generated route path type as the source of truth.
+- If TypeScript rejects a route, check its file name and `/<code>` prefix.
+- Do not use a cast to bypass a route error.
+
+## Add navigation
+
+Use TanStack Router's `Link` for a normal internal link:
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+<Link to="/<code>/about">About</Link>;
+```
+
+Use the bundled `LinkButton` for a button-style link:
+
+```tsx
+import { LinkButton } from "@/client/components/ui/button";
+
+<LinkButton href="/<code>/about">About</LinkButton>;
+```
+
+- Use a full path that starts with the applet code.
+- Use `LinkButton` for button-style navigation. Use `Button` for an action.
+- Do not add extra navigation that the user did not request.
+
+## Use the interface components
+
+- Use components in `src/client/components/ui` before raw HTML controls.
+- Inspect a component export before you use it.
+- Browse the [shadcn component catalog](https://ui.shadcn.com/docs/components) before you create a control.
+- Prefer a shadcn React Aria component when the catalog has a suitable component.
+- Run `pnpm exec shadcn add <component>` from the applet directory to add a missing component.
+- Keep installed components unchanged when possible.
+- Copy a component outside the `ui` directory before a product-specific change.
+- Use `cn` from `@/client/lib/utils` for class names.
+- Keep global styles in `src/client/styles/globals.css`.

package/scaffold/.agents/skills/hitch-applets/references/files.md

@@ -0,0 +1,109 @@
+# Files
+
+Use the file API to upload bytes, read file metadata, and link files to records.
+
+## Upload a file
+
+- Import `hitch` from the client or server SDK.
+- Call `hitch.files.upload(file)` with a web `File`.
+- Use the same upload call in the client and server halves.
+- Receive the complete file row plus a `downloadUrl` when the call resolves: storage has the bytes.
+- A failed upload throws an `Error` and leaves no usable id. Call `upload(file)` again to retry — the abandoned row is harmless.
+
+```ts
+import { hitch } from "@hitch42/applet/client";
+
+const uploaded = await hitch.files.upload(file);
+```
+
+Show progress or allow cancellation with the options argument:
+
+```ts
+const controller = new AbortController();
+
+const uploaded = await hitch.files.upload(file, {
+  signal: controller.signal,
+  onProgress: ({ loaded, total }) => setPercent(Math.round((100 * loaded) / total)),
+});
+```
+
+- `onProgress` reports uploaded bytes in the browser. The server half uploads without progress.
+- Abort the signal to cancel; the call rejects with an abort error.
+
+Use a TanStack mutation in a React component:
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const upload = useMutation({
+  mutationFn: (file: File) => hitch.files.upload(file),
+});
+
+upload.mutate(file);
+```
+
+Use the server SDK for an imperative upload:
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const uploaded = await hitch.files.upload(file);
+```
+
+## Set the content type
+
+The browser sets `file.type` for picked files. On the server, set the type when you construct the `File`:
+
+```ts
+const file = new File([csvBytes], "report.csv", { type: "text/csv" });
+```
+
+An empty `file.type` uploads as `application/octet-stream`.
+
+## Read a file
+
+Use `download` when a component needs one fresh link without query state:
+
+```ts
+const file = await hitch.files.download(id);
+file.downloadUrl; // a download link, valid for one hour
+```
+
+Use the `get` query utilities when React needs file metadata as query state.
+
+`get` returns `{ data, downloadUrl }`. Every file you can fetch is complete: `upload` resolves only after storage confirms the bytes. A file whose upload never finished answers 404 with code `file_not_arrived` — treat that id as dead and upload again.
+
+```ts
+const fileQuery = useQuery(
+  hitch.files.get.queryOptions({
+    input: { params: { id } },
+  }),
+);
+
+if (fileQuery.data) {
+  const { data: row, downloadUrl } = fileQuery.data;
+  row.filename; // "report.csv"
+  row.contentType; // "text/csv"
+  row.sizeBytes; // 1024
+  downloadUrl; // a download link, valid for one hour
+}
+```
+
+A `downloadUrl` expires after one hour. Call `get` again for a fresh link instead of storing one.
+
+## Link a file to a record
+
+Store `uploaded.id` as the value of an attachment attribute. A multi-value attachment attribute takes an array of ids.
+
+```ts
+const uploaded = await hitch.files.upload(file);
+
+await hitch.records.claims.update.call({
+  params: { id: claimId },
+  body: { receipt_id: uploaded.id }, // multi-value: [uploaded.id]
+});
+```
+
+- Upload the file before the record write: the write rejects a missing id ("file not found") and a pending id ("file has not arrived").
+- Store the file id, never a URL — URLs expire.

package/scaffold/.agents/skills/hitch-applets/references/manifest.md

@@ -0,0 +1,171 @@
+# Applet manifest
+
+Define the applet manifest in `applet.manifest.ts`.
+
+The authored definition omits `org`.
+The applet tool reads `org` from `hitch.config.ts` in the workspace root.
+
+## Use top-level fields
+
+- `org` identifies the Hitch organization.
+- `name` gives the applet a display name.
+- `code` gives the applet its stable code and URL prefix.
+- `objects` declares record objects and attribute access.
+- `variables` optionally declares runtime variables.
+- `schedules` optionally declares scheduled server calls.
+- `dependencies` optionally declares applet runtime packages.
+- `devDependencies` optionally declares applet build packages.
+
+The manifest and applet definition reject unknown fields.
+
+## Set `org`
+
+- Use a non-empty organization code.
+- Start the code with a lowercase letter.
+- End the code with a lowercase letter or number.
+- Use only lowercase letters, numbers, and non-consecutive hyphens.
+- Do not put `org` in `applet.manifest.ts`.
+- Set it in the root `hitch.config.ts` file.
+
+## Set `name`
+
+- Use a string with 1 through 120 characters after trimming.
+- Use the name as the applet display name.
+
+## Set `code`
+
+- Start the code with a lowercase letter.
+- End the code with a lowercase letter or number.
+- Use only lowercase letters, numbers, and non-consecutive underscores.
+- Make the applet directory name equal to the code.
+- Rename the directory or change the code when they differ.
+- Expect the Vite base path to be `/<code>/`.
+- Include the code in each client route path.
+
+## Declare objects
+
+Add one entry for each object that the applet needs.
+
+```ts
+objects: [
+  {
+    code: "deals",
+    canCreate: true,
+    canDelete: false,
+    readOnly: ["created_by"],
+    readWrite: ["stage", "amount"],
+  },
+],
+```
+
+Each object entry has five required fields.
+
+- `code` identifies the Hitch object.
+- `canCreate` is a boolean that controls the generated `create` method.
+- `canDelete` is a boolean that controls the generated `delete` method.
+- `readOnly` lists attribute codes that the applet can read but cannot write.
+- `readWrite` lists attribute codes that the applet can read and write.
+
+- Use the applet code format for each object code.
+- Do not declare the same object code more than once.
+- Use the applet code format for each attribute code.
+- Do not list `id`, `name`, or `expected_version` as an attribute code.
+- Do not repeat an attribute code in one list.
+- Do not put one attribute code in both lists.
+
+The object declaration caps record access for the applet identity.
+
+- Declare only the objects that scheduled applet work needs.
+- Declare only the attributes that scheduled applet work needs.
+- Use `readOnly` for attributes that the applet identity must not change.
+- Use `readWrite` for attributes that the applet identity can change.
+- Set `canCreate` and `canDelete` to the required values.
+- The generated contract omits undeclared objects.
+- The generated contract removes `create` when `canCreate` is false.
+- The generated contract removes `delete` when `canDelete` is false.
+- Regenerate after an object grant changes.
+- Do not restore a removed object or method with a cast.
+
+Client requests use the current user's identity and access.
+Scheduled requests use the applet identity and its manifest cap.
+
+## Declare variables
+
+Declare variable names and policies without values.
+
+```ts
+variables: {
+  API_URL: {},
+  API_TOKEN: { secret: true },
+  REPORT_CHANNEL: { optional: true },
+},
+```
+
+- Start each key with a letter or underscore.
+- Use only letters, numbers, and underscores after the first character.
+- Use at most 128 characters.
+- Do not use a key that starts with `HITCH_`, without regard to letter case.
+- Set `secret` to a boolean to mark how the platform stores the value.
+- Set `optional` to a boolean to control whether the value is required.
+- Omit `optional` or set it to false for a required variable.
+- Set variable values on the platform.
+- Do not put variable values in the manifest or source code.
+- Read declared variables from `env` in server code.
+- Expect an optional variable to have type `string | undefined`.
+- Expect a required variable to have type `string`.
+
+## Declare schedules
+
+Each schedule calls one registered server procedure.
+
+```ts
+schedules: [
+  {
+    code: "refresh_cache",
+    name: "Refresh cache",
+    cron: "*/5 * * * *",
+    path: "/refreshCache",
+  },
+],
+```
+
+- `code` gives the schedule a stable code.
+- `name` gives the schedule a display name.
+- `cron` sets its run times.
+- `path` selects a server router procedure.
+
+Apply these validation rules.
+
+- Use the applet code format for each schedule code.
+- Do not declare the same schedule code more than once.
+- Use a name with 1 through 120 characters after trimming.
+- Use a valid five-field cron expression.
+- Put fields in minute, hour, day-of-month, month, and day-of-week order.
+- Start `path` with one `/`.
+- Do not start `path` with `//`.
+- Do not put whitespace in `path`.
+- Keep `src/server/main.ts` when the manifest has a schedule.
+
+Generation registers the server router type.
+After generation, `path` accepts only paths from that registered router.
+Before router registration, the path type falls back to `string`.
+
+## Declare packages
+
+Add direct package requirements to the manifest.
+
+```ts
+dependencies: {
+  "date-fns": "^4.1.0",
+},
+devDependencies: {
+  "@types/example": "^1.0.0",
+},
+```
+
+- Put runtime imports in `dependencies`.
+- Put build and test tools in `devDependencies`.
+- Do not add a package that the applet CLI already supplies.
+- Do not put one package in both dependency groups.
+- Use package ranges that pnpm accepts.
+- Run `applet generate`, `applet build`, or `applet deploy` to update generated package files.

package/scaffold/.agents/skills/hitch-applets/references/markdown.md

@@ -0,0 +1,37 @@
+# Markdown
+
+Use the SDK components to edit and render markdown with Hitch file images.
+
+## Edit markdown
+
+`MarkdownEditor` is a controlled Tiptap WYSIWYG editor. Store its markdown value in your form state. Pass `hitch.files` for image paste and drop.
+
+The editor supports GFM tables and task lists. A plain table serializes as GFM. A table with block content in a cell (for example a list) serializes as inline HTML, which the `Markdown` renderer also renders.
+
+```tsx
+import { hitch } from "@hitch42/applet/client";
+import { MarkdownEditor } from "@hitch42/applet/react";
+
+<MarkdownEditor value={value} onChange={setValue} files={hitch.files} />;
+```
+
+The editor uploads pasted or dropped images. It stores each image as `![name](hitch-file://<file-id>)`.
+
+The `files` value must supply both `upload(file)` and `download(id)`. The editor uses `download(id)` to show stored Hitch images.
+
+While an upload runs, the editor shows the image from a temporary local URL and blocks native form submission, so a form cannot save a half-done upload. A failed upload removes the image and calls `onUploadError` if you pass one; without it, the editor logs the error and continues with the next file.
+
+## Render markdown
+
+Pass the same files surface to `Markdown`:
+
+```tsx
+import { hitch } from "@hitch42/applet/client";
+import { Markdown } from "@hitch42/applet/react";
+
+<Markdown files={hitch.files}>{value}</Markdown>;
+```
+
+`Markdown` calls `hitch.files.download(id)` to replace each Hitch file id with a fresh download link.
+
+Store markdown with `hitch-file://` file ids. Never store a presigned download URL because it expires.

package/scaffold/.agents/skills/hitch-applets/references/records.md

@@ -0,0 +1,152 @@
+# Records
+
+Use the generated Hitch contract as the typed data plane.
+
+- Import `hitch` from `@hitch42/applet/client` in client code.
+- Import `hitch` from `@hitch42/applet/server` in server code.
+- Read object codes, attribute codes, inputs, and outputs from the generated types.
+- Use only the target applet's `.hitch` types as schema evidence.
+- Never copy or infer types from a sibling applet.
+- If the target applet has no generated types, resolve generation before you write record code.
+- Do not add local copies of generated types.
+- Do not use a cast to restore a missing object, field, or operation.
+
+## Use record verbs
+
+- `list` sends `GET /v1/<objectCode>` and lists records with query parameters.
+- `create` sends `POST /v1/<objectCode>` and creates one record.
+- `get` sends `GET /v1/<objectCode>/{id}` and gets one record.
+- `update` sends `PATCH /v1/<objectCode>/{id}` and updates one record.
+- `delete` sends `DELETE /v1/<objectCode>/{id}` and deletes one record.
+- `query` sends `POST /v1/<objectCode>/query` and lists records with a structured body.
+- `updateWhere` sends `POST /v1/<objectCode>/update` and updates matching records.
+- `aggregate` sends `POST /v1/<objectCode>/aggregate` and calculates aggregate values.
+
+- Pass an object ID in `params.id` for `get`, `update`, and `delete`.
+- Pass record fields in `body` for `create` and `update`.
+- Pass structured query data in `body` for `query`.
+
+## Call records from the client
+
+Use TanStack Query options from each generated procedure.
+
+```ts
+import { useQuery } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const deals = useQuery(
+  hitch.records.deals.query.queryOptions({
+    input: {
+      body: { filter: { stage: { $eq: "open" } }, limit: 25 },
+    },
+  }),
+);
+```
+
+```ts
+import { useMutation } from "@tanstack/react-query";
+import { hitch } from "@hitch42/applet/client";
+
+const createDeal = useMutation(hitch.records.deals.create.mutationOptions());
+
+createDeal.mutate({ body: { name: "New deal" } });
+```
+
+- Use `.queryOptions(...)` for reads and `.mutationOptions(...)` for writes.
+- The client uses the current user's identity and access.
+- Do not add a server proxy for normal access control or filtering.
+
+## Call records from the server
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const deals = await hitch.records.deals.query({
+  body: { filter: { stage: { $eq: "open" } }, limit: 25 },
+});
+
+const deal = await hitch.records.deals.get({
+  params: { id: dealId },
+});
+```
+
+- Do not use `.queryOptions(...)` or `.mutationOptions(...)` on the server.
+- Use the server SDK for imperative data access, secrets, or external services.
+
+## Build a query
+
+The `query` body accepts `filter`, `sort`, `limit`, `cursor`, and `include`.
+
+```ts
+const page = await hitch.records.deals.query({
+  body: {
+    filter: {
+      $and: [{ stage: { $in: ["open", "won"] } }, { amount: { $gte: 1000 } }],
+    },
+    sort: { attribute: "amount", direction: "desc" },
+    limit: 50,
+    cursor,
+    include: ["company"],
+  },
+});
+```
+
+- Use `$and` or `$or` with a non-empty array of filter nodes.
+- Use `$not` with one filter node.
+- Put more than one field in a node to combine those fields with AND.
+- Use a direct field value as shorthand for `$eq`.
+- Use `$eq`, `$in`, or `$not_empty` for identity fields.
+- Use `$eq` or `$not_empty` for checkbox fields.
+- Use only `$not_empty` for attachment fields.
+- Use `$eq`, `$in`, `$not_empty`, `$contains`, `$starts_with`, or `$ends_with` for text fields.
+- Use `$eq`, `$in`, `$not_empty`, `$lt`, `$lte`, `$gt`, or `$gte` for ordered fields.
+- Pass `true` to `$not_empty`.
+- Pass an array to `$in`.
+- Pass a string to `$contains`, `$starts_with`, and `$ends_with`.
+- Sort with `{ attribute, direction }`.
+- Use `asc` or `desc` as the sort direction.
+- Do not sort by multi-value, reference, user, or attachment attributes.
+- Omit `sort` to sort by `createdAt` in descending order.
+- Use a positive integer for `limit`.
+- The service caps `limit` at 200 and uses 50 by default.
+- Pass the returned pagination cursor back as `cursor`.
+- Pass one attribute code or an array of attribute codes as `include`.
+
+## Aggregate records
+
+Pass `filter`, `aggregates`, and `groupBy` in the aggregate body.
+An aggregate or group attribute can name one reference step and a target attribute, for example `company_id.industry`.
+Each aggregate can have its own `filter` with the same syntax as the top-level `filter`, including nested reference filters.
+`groupBy` accepts an array of up to two dimensions.
+The array form returns `keys` and `labels` arrays per group.
+The object form orders category groups by an aggregate value (top-N by value).
+The array form orders each dimension by key; `limit` selects the first N distinct keys in that order. It does not support top-N by value.
+
+```ts
+const totals = await hitch.records.deals.aggregate({
+  body: { filter, aggregates, groupBy },
+});
+```
+
+## Update matching records
+
+Pass `filter`, `set`, optional `expect`, and optional `limit` to `updateWhere`.
+
+```ts
+const result = await hitch.records.deals.updateWhere({
+  body: { filter, set: { stage: "closed" }, expect: 3 },
+});
+```
+
+- Use a nonnegative integer for `expect`.
+- Use generated types for query, aggregate, group, set, and limit values.
+
+## Fix a missing method
+
+The generated contract contains only objects declared in the manifest.
+
+- The contract removes `create` when `canCreate` is false.
+- The contract removes `delete` when `canDelete` is false.
+- Treat a missing method as a missing manifest grant, and edit the manifest when required.
+- Run generation after a manifest or Hitch schema change.
+- Do not bypass the contract with a cast.

package/scaffold/.agents/skills/hitch-applets/references/schedules.md

@@ -0,0 +1,86 @@
+# Scheduled runs
+
+Use a schedule to call an applet server procedure from a cron expression.
+
+## Define the target procedure
+
+- Add the target to the applet's server router.
+- Use `os.handler` to define the procedure.
+- Default-export `{ router }`.
+
+```ts
+import { os } from "@orpc/server";
+
+const router = {
+  refresh: os.handler(async () => {
+    // Run the scheduled work.
+  }),
+};
+
+export default { router };
+```
+
+## Declare the schedule
+
+- Add a `schedules` entry to the applet manifest.
+- Give each schedule a unique `code`.
+- Give each schedule a non-empty `name`.
+- Use a valid five-field cron expression.
+- Set `path` to the server procedure path.
+- Start the path with `/`.
+- Do not add whitespace to the path.
+
+```ts
+schedules: [
+  {
+    code: "refresh",
+    name: "Refresh data",
+    cron: "*/5 * * * *",
+    path: "/refresh",
+  },
+],
+```
+
+- The five fields are minute, hour, day of month, month, and day of week.
+- The registered router type checks the path after type generation.
+- A nested procedure uses its nested router path.
+- The scheduler invokes the named router procedure with no input.
+
+## Understand the run identity
+
+- A scheduled run acts as the applet.
+- It has no current user.
+- Hitch data calls use the applet's manifest grants.
+- The manifest grants set the maximum data access.
+- User-only endpoints return HTTP 403.
+- Admin-only endpoints return HTTP 403.
+
+## Keep work within the run limits
+
+- Each run has a 30,000 millisecond CPU limit.
+- Each run has a 1,000 subrequest limit.
+- Keep the procedure within both limits.
+- The scheduler prevents overlap for 16 minutes after an active run starts.
+- A later due run can start after that overlap window.
+
+## Upload files from a run
+
+- Import `hitch` from `@hitch42/applet/server`.
+- Call `hitch.files.upload(file)` with a web `File`.
+- The upload uses the scheduled run's applet identity.
+- The file bytes go directly to storage through a presigned URL.
+
+```ts
+import { hitch } from "@hitch42/applet/server";
+
+const uploaded = await hitch.files.upload(file);
+```
+
+## Diagnose a failed run
+
+- Check the applet invocation history first.
+- Read the stored status, path, HTTP status, and error details.
+- Check the applet logs for procedure details.
+- Follow the log commands in the main Hitch applet skill.
+- Include `--level log` during diagnosis.
+- Do not log secrets, tokens, or personal data.