@classytic/arc 2.20.0 → 2.22.0

package/skills/arc-module-publishing/references/package-manifest.md

@@ -0,0 +1,157 @@
+# package.json + tsdown reference
+
+Copy-paste manifest for an arc ecosystem package, plus the dependency-field rules and the
+optional-peer typing pattern. Values below are the real shapes shipped by
+`@classytic/arc-approval` — adapt names, keep the structure.
+
+---
+
+## package.json
+
+```jsonc
+{
+  "name": "@classytic/arc-<domain>",
+  "version": "0.1.0",
+  "description": "<one line — what this contributes to an arc host>",
+  "type": "module",
+
+  // Public entry. Add subpaths ("./adapter", "./testing") the same way if you split surfaces.
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+
+  "sideEffects": false,       // pure ESM, tree-shakable — no import-for-effect modules
+  "files": ["dist"],          // ship only build output; never src/, tests/, configs
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=22" },
+
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+
+  // CONTRACTS — what the host must provide. `>=`, never `^`.
+  // Floor >=2.21.0 if you use ResourceSeams / mergeResourceConfig / permissionMatrix /
+  // schedulesPlugin / errorMappers — declare the floor that matches the APIs you import.
+  "peerDependencies": {
+    "@classytic/arc": ">=2.21.0",
+    "@classytic/primitives": ">=0.9.0"
+  },
+
+  // Optional peers: declared here AND marked optional below. Host installs only if used.
+  // "peerDependencies": { ..., "zod": ">=3.23.0", "ioredis": ">=5.0.0" },
+  // "peerDependenciesMeta": {
+  //   "zod": { "optional": true },
+  //   "ioredis": { "optional": true }
+  // },
+
+  // TEST versions — pin with ^, floor >= each peer floor. Not shipped.
+  "devDependencies": {
+    "@classytic/arc": "^2.21.0",
+    "@classytic/primitives": "^0.9.1",
+    "@biomejs/biome": "^2.5.2",
+    "@types/node": "^22.19.21",
+    "tsdown": "^0.22.5",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.9"
+  },
+
+  "keywords": ["arc", "fastify", "<domain>", "classytic"],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": { "type": "git", "url": "https://github.com/classytic/arc-ecosystem.git", "directory": "packages/arc-<domain>" }
+}
+```
+
+In an **npm workspace**, devDeps common to all packages hoist to the root `package.json`; a
+package only lists devDeps unique to it. The peer-skew gate reads root + package devDeps
+together (see publishing-workflow.md).
+
+---
+
+## Dependency-field cheat sheet
+
+| Field | What goes here | Range style | Why |
+|---|---|---|---|
+| `dependencies` | (usually nothing) truly-private bundled helpers only | `^` | Ships with you; host can't override. Almost never needed. |
+| `peerDependencies` | arc, fastify, primitives, kits, zod, ioredis | **`>=`** | A contract/floor. Host resolves the real version; don't block their upgrades. |
+| `peerDependenciesMeta` | mark optional peers `{ optional: true }` | — | Host installs only if they use that path. |
+| `devDependencies` | concrete versions your tests run against | `^` | The version you actually exercise; floor must be `>=` peer floor. |
+
+**The trap:** putting `@classytic/arc` or `fastify` in `dependencies`, or writing a peer as
+`^2.20.0`. Both force the host into *your* version choice. A published arc package makes as
+few decisions for the host as possible — it states floors and gets out of the way.
+
+---
+
+## tsdown.config.ts
+
+```ts
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],   // add entries for extra subpaths: ["src/index.ts", "src/adapter.ts"]
+  format: ["esm"],           // ESM only — arc is ESM only
+  dts: true,                 // emit .d.mts
+  sourcemap: false,
+  clean: true,
+  treeshake: true,
+  target: "node22",
+  outDir: "dist",
+  deps: {
+    // Bundle NOTHING — same never-bundle contract as arc's own tsdown config.
+    skipNodeModulesBundle: true,
+    neverBundle: [/^@classytic\//],
+  },
+});
+```
+
+Why bundle nothing: if you inline `@classytic/arc` (or primitives, or a kit), the host ends up
+with two copies — yours frozen in `dist/`, theirs in `node_modules`. Arc's plugin registry,
+event transport, and scope decorators are identity-sensitive; two copies register twice and
+diverge. `neverBundle: [/^@classytic\//]` guarantees the host's single installed copy is the
+only one at runtime.
+
+---
+
+## Optional peers: keep their types out of your public surface
+
+If a peer is optional (a host might not install it), its types **must not** appear in your
+published `.d.mts` — otherwise a host without it gets a compile error importing your package.
+Use structural typing: describe the shape you need with a local interface, don't import the
+dependency's types into the public boundary.
+
+```ts
+// ❌ leaks zod into dist/index.d.mts — breaks hosts that didn't install zod
+import type { ZodType } from "zod";
+export function withValidation(schema: ZodType) { /* ... */ }
+
+// ✅ structural: the public signature owes nothing to zod's package
+export interface StandardSchemaLike<T> {
+  readonly "~standard": { validate: (v: unknown) => { value: T } | { issues: unknown[] } };
+}
+export function withValidation<T>(schema: StandardSchemaLike<T>) { /* ... */ }
+```
+
+For **shipped action/route schemas, use JSON Schema**, not zod objects. Arc converts JSON
+Schema natively; zod stays an *optional* convenience peer for hosts that prefer it. A package
+that hard-requires zod for its schemas has made zod a non-optional dependency by the back door.
+
+```ts
+schema: {
+  type: "object",
+  required: ["stepId", "decision"],
+  properties: {
+    stepId: { type: "string", minLength: 1 },
+    decision: { type: "string", enum: ["approved", "rejected"] },
+  },
+  additionalProperties: false,
+}
+```

package/skills/arc-module-publishing/references/publishing-workflow.md

@@ -0,0 +1,182 @@
+# Publishing workflow
+
+Monorepo layout, the release gates, and the classytic bot-identity publish steps.
+
+---
+
+## Monorepo layout (npm workspaces)
+
+Prefer **one workspace holding many small packages** over one repo per package — they release
+together and share tooling. The `@classytic/arc-ecosystem` layout:
+
+```
+arc-ecosystem/
+  package.json                 # workspaces: ["packages/*"], shared devDeps, verify script
+  scripts/
+    check-peer-skew.mjs        # gate: every peer floor covered by a devDep floor
+    prepublish-gate.mjs        # per-package publish gate
+  packages/
+    arc-approval/              # @classytic/arc-approval — one package, one surface
+      package.json
+      tsdown.config.ts
+      src/index.ts
+    arc-involvement/
+    arc-notifications/
+```
+
+Root `package.json` scripts:
+
+```jsonc
+{
+  "workspaces": ["packages/*"],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "typecheck": "npm run typecheck --workspaces",
+    "lint": "biome check packages/",
+    "test": "vitest run",
+    "check:peer-skew": "node scripts/check-peer-skew.mjs",
+    "verify": "npm run check:peer-skew && npm run typecheck && npm run lint && npm run test && npm run build"
+  }
+}
+```
+
+Shared devDeps (arc, primitives, biome, tsdown, typescript, vitest, fastify, @types/node) live
+in the **root** `package.json` so every package tests against one aligned set. During
+pre-publish development the root can carry `"@classytic/arc": "file:../arc"` to test against
+unreleased arc; **switch it to the published range (`"^2.20.0"`) once arc ships** and reinstall
+so packages resolve arc from the registry tarball, not the local symlink.
+
+**pnpm + turborepo + changesets** is the heavier-duty alternative to npm workspaces once the
+package count grows: turbo gives cached, topo-ordered builds (`dependsOn: ["^build"]`);
+changesets drive versioning + changelogs (`access: "public"`, `updateInternalDependencies:
+"patch"`). Wire the peer-skew gate into the release path so it can't be skipped — e.g.
+`"release": "pnpm run check:peer-skew && turbo typecheck test build && changeset publish"`.
+Local workspace links use `workspace:*` (pnpm) instead of `file:`; the peer-skew gate treats
+`workspace:` / `link:` / `file:` as covering any floor (the checked-out source *is* the version
+under development).
+
+### Supply-chain hygiene (.npmrc / pnpm-workspace.yaml)
+
+Belt-and-suspenders settings worth adopting for a published ecosystem:
+
+```ini
+# .npmrc
+auto-install-peers=false     # peers are the HOST's duty — never silently fetch them
+save-workspace-protocol=rolled
+```
+
+```yaml
+# pnpm-workspace.yaml
+onlyBuiltDependencies:       # allowlist packages permitted to run install scripts
+  - esbuild
+  - mongodb-memory-server
+minimumReleaseAgeExclude:    # cooldown on brand-new registry versions, with explicit escapes
+  - '@classytic/repo-core@0.7.0'
+```
+
+- `auto-install-peers=false` enforces the contract mechanically: if a host forgets a peer, they
+  get an error, not a silently-resolved wrong version. It also stops your *dev* environment from
+  masking a missing peer declaration.
+- `onlyBuiltDependencies` is a lifecycle-script allowlist — nothing runs `postinstall` unless you
+  named it. A cheap, real guard against a compromised transitive dep executing on `pnpm install`.
+- A `minimumReleaseAge` cooldown blunts the "malicious version published minutes ago" attack;
+  the `Exclude` list is your escape hatch for versions you've vetted.
+
+---
+
+## Gate 1 — peer-skew (monorepo)
+
+`scripts/check-peer-skew.mjs` fails the build if any package declares a peer floor higher than
+the devDep floor it actually tests against. Without it, a package can claim `">=2.20.0"` while
+its suite runs against 2.18 — a lie that ships. The gate reads root + package devDeps together
+(`file:` links count as covering any floor, since the link *is* the version under development).
+
+```js
+// Core check, per package, per peer:
+//   devFloor = floorOf(devDeps[name])         // from root + package devDeps merged
+//   peerFloor = floorOf(peers[name])
+//   if (devFloor < peerFloor) FAIL            // suite tests below what you promise
+// Optional peers (peerDependenciesMeta.optional) with no devDep are allowed to be absent.
+```
+
+Run it first in `verify` so a skew fails fast before the slower typecheck/test/build.
+
+---
+
+## Gate 2 — prepublish (per package)
+
+No package publishes without a green gate. No `--no-verify`, ever.
+
+- **Solo package:** `"prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"`.
+- **Workspace:** a shared `scripts/prepublish-gate.mjs` invoked from each package's
+  `prepublishOnly`, running the full workspace `verify` (peer-skew + typecheck + lint + test +
+  build) so no package ships against a skewed or broken tree.
+
+The gate is the contract with consumers: if it's green, the published `dist/` was typechecked,
+linted, tested, and built from the source in the same commit.
+
+---
+
+## Release — classytic packages (bot identity)
+
+Every commit in a classytic package is authored as **`classytic-bot[bot]`** — the maintainer
+identity, never an individual. **Per-invocation git env vars only; never `git config
+--global`; no `Co-Authored-By` trailers.**
+
+```bash
+GIT_AUTHOR_NAME="classytic-bot[bot]" \
+GIT_AUTHOR_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
+GIT_COMMITTER_NAME="classytic-bot[bot]" \
+GIT_COMMITTER_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
+git commit -m "feat(arc-x): …"
+```
+
+Push through `@classytic/dev-tools` so the commit and pusher both carry the `[bot]` badge (it
+mints a short-lived GitHub App installation token, pushes, and never persists it):
+
+```bash
+npm run push -- main         # push current work to main
+```
+
+Publish to **public npm** (`publishConfig.access: "public"` is already set):
+
+```bash
+npm publish -w @classytic/arc-<domain>   # prepublishOnly gate runs automatically
+```
+
+Third-party (non-classytic) packages: normal git identity, same gates and same
+public/scoped-npm publish — only the bot identity and `classytic-push` are classytic-specific.
+
+---
+
+## Versioning a public export
+
+SemVer the **contract**, not the internals:
+
+| Change | Bump |
+|---|---|
+| New optional config field, new exported helper, new action | **minor** |
+| Raising a peer floor (e.g. now requires arc ≥2.21) | **minor** (it narrows the host set) |
+| Changing an exported function signature, removing an export, renaming an action/field | **major** |
+| Internal refactor, dep bump within range, doc/test-only | **patch** |
+
+The `ArcModule` shape you return, your exported function signatures, and your action/schema
+surface are the contract consumers pin against. Internals (private helpers, how the engine is
+built) are free to change under a patch.
+
+---
+
+## Common publish failures (and the fix)
+
+- **Peer written as `^` instead of `>=`** → blocks hosts on a newer major that still satisfies
+  your API. Fix: `">=X.Y.0"`.
+- **arc/fastify in `dependencies`** → host gets a bundled duplicate; plugin registry splits.
+  Fix: move to `peerDependencies`.
+- **Optional-peer types in `dist/*.d.mts`** → hosts without that peer fail to compile your
+  package. Fix: structural typing at the public boundary (see package-manifest.md).
+- **Deep import (`@classytic/arc/src/...`)** → breaks on any arc internal reorg. Fix: use a
+  public subpath, or file the missing export against arc.
+- **A back-edge: arc depending on your package** → un-publishable cycle. Fix: the abstraction
+  belongs in arc as a port/hook, not as a dependency on you.
+- **Skewed devDep below peer floor** → suite tests a version you claim to support but don't.
+  Fix: raise the devDep, reinstall, re-run peer-skew.

package/dist/preloadResources-CHw3_oA_.mjs

@@ -1,45 +0,0 @@
-//#region src/testing/preloadResources.ts
-/**
-* Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
-*
-* Accepts either:
-* - `{ import: 'default' }` form: values are the resource directly
-* - default form: values are the full module — picks first export with `toPlugin()`
-*
-* Throws if any module doesn't yield a valid `ResourceLike`.
-*/
-function preloadResources(globResult) {
-	const resources = [];
-	for (const [path, value] of Object.entries(globResult)) {
-		const resource = pickResource(value);
-		if (!resource) throw new Error(`preloadResources: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		resources.push(resource);
-	}
-	return resources.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
-}
-/**
-* Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
-*
-* Use this when resources depend on prior bootstrap (e.g., engine init) and
-* cannot be evaluated at import time of the preload file.
-*/
-async function preloadResourcesAsync(globResult) {
-	return (await Promise.all(Object.entries(globResult).map(async ([path, loader]) => {
-		const resource = pickResource(await loader());
-		if (!resource) throw new Error(`preloadResourcesAsync: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		return resource;
-	}))).sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
-}
-function pickResource(value) {
-	if (!value || typeof value !== "object") return void 0;
-	if (typeof value.toPlugin === "function") return value;
-	const mod = value;
-	const candidates = [
-		mod.default,
-		mod.resource,
-		...Object.values(mod)
-	];
-	for (const c of candidates) if (c && typeof c === "object" && typeof c.toPlugin === "function") return c;
-}
-//#endregion
-export { preloadResourcesAsync as n, preloadResources as t };

package/dist/schemaConverter-U0MnO9vd.mjs

@@ -1,110 +0,0 @@
-//#region src/utils/schemaConverter.ts
-/** Default target for Fastify-consumed schemas (matches Fastify v5's default AJV draft). */
-const DEFAULT_FASTIFY_TARGET = "draft-7";
-/** Default target for OpenAPI document generation (matches arc's emitted OpenAPI version). */
-const DEFAULT_OPENAPI_TARGET = "openapi-3.0";
-let _toJSONSchema = null;
-import("zod").then(({ z }) => {
-	if (typeof z?.toJSONSchema === "function") _toJSONSchema = (schema, opts) => z.toJSONSchema(schema, opts);
-}).catch(() => {});
-/**
-* Check if an object is already a plain JSON Schema.
-* Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
-* `allOf`, `anyOf`, `oneOf`, `items`, `enum`) and does NOT have Zod markers.
-*/
-function isJsonSchema(input) {
-	if (input === null || typeof input !== "object") return false;
-	const obj = input;
-	if ("_def" in obj || "_zod" in obj) return false;
-	return "type" in obj || "properties" in obj || "$ref" in obj || "allOf" in obj || "anyOf" in obj || "oneOf" in obj || "items" in obj || "enum" in obj;
-}
-/**
-* Check if an object is a Zod schema (has `_zod` marker from Zod v4).
-*/
-function isZodSchema(input) {
-	return input !== null && typeof input === "object" && "_zod" in input;
-}
-/**
-* Convert any schema input to JSON Schema.
-*
-* Detection order:
-* 1. `null`/`undefined` → `undefined`
-* 2. Already JSON Schema → pass through as-is (zero overhead)
-* 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
-* 4. Unrecognized object → return as-is (treat as opaque schema)
-*
-* @param input Schema (Zod, plain JSON Schema, or opaque object)
-* @param target Output target — defaults to `draft-7` for Fastify compatibility.
-*               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
-*/
-function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET) {
-	if (input == null) return void 0;
-	if (typeof input !== "object") return void 0;
-	if (isJsonSchema(input)) return input;
-	if (isZodSchema(input)) {
-		if (!_toJSONSchema) return input;
-		try {
-			const converted = _toJSONSchema(input, { target });
-			if ("$schema" in converted) delete converted.$schema;
-			return converted;
-		} catch {
-			return { type: "object" };
-		}
-	}
-	return input;
-}
-/**
-* Convert all schema fields in an OpenApiSchemas object.
-* JSON Schema values pass through unchanged. Only Zod schemas are converted.
-*
-* Defaults to the `openapi-3.0` target since this function feeds OpenAPI doc
-* generation, not Fastify route validation.
-*/
-function convertOpenApiSchemas(schemas, target = DEFAULT_OPENAPI_TARGET) {
-	const result = {};
-	const schemaFields = [
-		"entity",
-		"createBody",
-		"updateBody",
-		"params",
-		"listQuery",
-		"response"
-	];
-	for (const field of schemaFields) {
-		const value = schemas[field];
-		if (value !== void 0) result[field] = toJsonSchema(value, target) ?? value;
-	}
-	for (const [key, value] of Object.entries(schemas)) if (!schemaFields.includes(key)) result[key] = value;
-	return result;
-}
-/**
-* Convert schema values in a Fastify route schema record.
-*
-* Handles `body`, `querystring`, `params`, `headers` (top-level conversion)
-* and `response` (iterates by status code — each value converted individually).
-*
-* JSON Schema values pass through unchanged. Only Zod schemas are converted.
-*
-* Used for both custom routes and customSchemas (CRUD overrides).
-*
-* Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
-* Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.
-*/
-function convertRouteSchema(schema, target = DEFAULT_FASTIFY_TARGET) {
-	const result = { ...schema };
-	for (const field of [
-		"body",
-		"querystring",
-		"params",
-		"headers"
-	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field], target) ?? result[field];
-	if (result.response !== void 0 && typeof result.response === "object" && result.response !== null) {
-		const responseObj = result.response;
-		const convertedResponse = {};
-		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema, target) ?? responseSchema;
-		result.response = convertedResponse;
-	}
-	return result;
-}
-//#endregion
-export { toJsonSchema as a, isZodSchema as i, convertRouteSchema as n, isJsonSchema as r, convertOpenApiSchemas as t };