Monorepo set up: workspaces, contracts package, placeholders

npm workspaces (packages/*, apps/*) with shared TypeScript, ESLint and
Jest setup and `npm run check`. @crosscode/contracts builds to CommonJS
and ESM (tsup) with the crosscode.<name>/<major> schema-name helpers.
packages/ui and apps/{accounts,website,app} are placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-04 09:36:42 +02:00
co-authored by Claude Opus 5.5
commit 19f79dfb17
24 changed files with 7609 additions and 0 deletions
+36
View File
@@ -0,0 +1,36 @@
# @crosscode/contracts
Everything that crosses between Cross Code products is defined once, here (ROADMAP-v3 §2):
zod schemas, generated JSON Schema, TypeScript types and sample payloads. Every product, including
Cross Events and the Hub, uses it, so the key fields are the same in every product's JSON.
| Contract | Used for | Status |
|----------|----------|--------|
| `crosscode.event/1` | The event feed every product publishes and reads | To do |
| `crosscode.church/1` | The church profile: name, logo, colours, campuses, service times, contact details | To do |
| `crosscode.identity/1` | Accounts' sign-in token claims and back-channel calls (`user.updated`, `user.deleted`, `user.export`) | To do |
| Hub protocol v3 | Register, heartbeat, licence token, AI calls, for every product | To do |
## Versioning
- Every payload carries its `schema` name: `crosscode.<name>/<major>`.
- Adding an **optional** field keeps the version. Consumers ignore fields they don't know.
- Removing or renaming a field, or changing its meaning, needs a new major (`/2`). The old one
is served alongside it until every install has updated.
```ts
import { parseSchemaName, isSchema } from "@crosscode/contracts";
parseSchemaName("crosscode.event/1"); // { name: "event", major: 1 }
isSchema(payload.schema, "event", 1); // true / false
```
## Installing
Published to Gitea's package registry. In the consuming repo's `.npmrc`:
```
@crosscode:registry=https://c-git.crosscode.co.za/api/packages/joshua/npm/
```
Works with both `require` (Cross Events backend, Hub) and `import` (Next.js apps).
+7
View File
@@ -0,0 +1,7 @@
module.exports = {
testEnvironment: "node",
testMatch: ["<rootDir>/tests/**/*.test.ts"],
transform: { "^.+\\.ts$": ["ts-jest", { tsconfig: { module: "commonjs", moduleResolution: "node", isolatedModules: true } }] },
moduleFileExtensions: ["ts", "js", "json"],
modulePathIgnorePatterns: ["<rootDir>/dist/"],
};
+46
View File
@@ -0,0 +1,46 @@
{
"name": "@crosscode/contracts",
"version": "0.1.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED",
"type": "commonjs",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"require": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"./package.json": "./package.json"
},
"files": [
"dist",
"schemas",
"samples",
"README.md"
],
"sideEffects": false,
"scripts": {
"build": "tsup",
"typecheck": "tsc -p tsconfig.json --noEmit",
"test": "jest"
},
"dependencies": {
"zod": "^4.6.7"
},
"publishConfig": {
"registry": "https://c-git.crosscode.co.za/api/packages/joshua/npm/"
},
"repository": {
"type": "git",
"url": "https://c-git.crosscode.co.za/joshua/crosscode-platform.git",
"directory": "packages/contracts"
}
}
+7
View File
@@ -0,0 +1,7 @@
/**
* @crosscode/contracts — the shared JSON formats used by every Cross Code product
* (ROADMAP-v3 §2). Contracts to come in 1.0.0: `crosscode.event/1`, `crosscode.church/1`,
* `crosscode.identity/1` and Hub protocol v3.
*/
export { schemaName, parseSchemaName, isSchema } from "./schema-name";
export type { SchemaName } from "./schema-name";
+37
View File
@@ -0,0 +1,37 @@
/**
* Every payload that crosses between products carries its `schema` name, so a consumer always
* knows what it's reading (ROADMAP-v3 §2): `crosscode.<name>/<major>`, e.g. `crosscode.event/1`.
*
* Versioning:
* - Adding an optional field keeps the major version. Consumers ignore fields they don't know.
* - Removing or renaming a field, or changing its meaning, needs the next major (`/2`), served
* alongside the old one until every install has updated.
*/
const SCHEMA_NAME = /^crosscode\.([a-z][a-z0-9-]*)\/([1-9][0-9]*)$/;
export interface SchemaName {
name: string;
major: number;
}
/** Builds a schema name: `schemaName("event", 1)` → `"crosscode.event/1"`. */
export function schemaName<N extends string, M extends number>(name: N, major: M): `crosscode.${N}/${M}` {
const result = `crosscode.${name}/${major}` as const;
if (!SCHEMA_NAME.test(result)) throw new Error(`Invalid schema name: ${result}`);
return result;
}
/** Splits a schema name into its name and major version, or returns `null` if it isn't one. */
export function parseSchemaName(value: unknown): SchemaName | null {
if (typeof value !== "string") return null;
const match = SCHEMA_NAME.exec(value);
if (!match) return null;
return { name: match[1]!, major: Number(match[2]) };
}
/** True when `value` is a payload's `schema` for the given name and major version. */
export function isSchema(value: unknown, name: string, major: number): boolean {
const parsed = parseSchemaName(value);
return parsed !== null && parsed.name === name && parsed.major === major;
}
@@ -0,0 +1,38 @@
import { isSchema, parseSchemaName, schemaName } from "../src";
describe("schemaName", () => {
it("builds crosscode.<name>/<major>", () => {
expect(schemaName("event", 1)).toBe("crosscode.event/1");
expect(schemaName("church", 2)).toBe("crosscode.church/2");
});
it("refuses names and versions that don't fit the pattern", () => {
expect(() => schemaName("Event", 1)).toThrow();
expect(() => schemaName("event", 0)).toThrow();
expect(() => schemaName("event", 1.5)).toThrow();
expect(() => schemaName("", 1)).toThrow();
});
});
describe("parseSchemaName", () => {
it("splits a schema name", () => {
expect(parseSchemaName("crosscode.event/1")).toEqual({ name: "event", major: 1 });
expect(parseSchemaName("crosscode.hub-protocol/3")).toEqual({ name: "hub-protocol", major: 3 });
});
it.each([undefined, null, 1, "", "crosscode.event", "crosscode.event/0", "crosscode.event/01", "other.event/1", "crosscode.event/1 ", "crosscode.Event/1"])(
"returns null for %p",
(value) => {
expect(parseSchemaName(value)).toBeNull();
},
);
});
describe("isSchema", () => {
it("matches name and major", () => {
expect(isSchema("crosscode.event/1", "event", 1)).toBe(true);
expect(isSchema("crosscode.event/2", "event", 1)).toBe(false);
expect(isSchema("crosscode.church/1", "event", 1)).toBe(false);
expect(isSchema(undefined, "event", 1)).toBe(false);
});
});
+8
View File
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": ".",
"types": ["node", "jest"]
},
"include": ["src", "tests", "tsup.config.ts"]
}
+13
View File
@@ -0,0 +1,13 @@
import { defineConfig } from "tsup";
// Dual build: CommonJS for the Cross Events backend and the Hub (they `require`), ESM for the
// Next.js apps. Types for both.
export default defineConfig({
entry: ["src/index.ts"],
format: ["cjs", "esm"],
dts: true,
sourcemap: true,
clean: true,
target: "es2022",
outExtension: ({ format }) => ({ js: format === "esm" ? ".mjs" : ".js" }),
});
+5
View File
@@ -0,0 +1,5 @@
# @crosscode/ui
Placeholder. Shared UI (church branding from `crosscode.church/1`, layout, forms, the sign-in
pages' look) for Accounts, the Church Website and the Church App. Filled in during the Website
phase (ROADMAP-v3 §9, phase 4).
+6
View File
@@ -0,0 +1,6 @@
{
"name": "@crosscode/ui",
"version": "0.0.0",
"private": true,
"description": "Placeholder: shared UI for the Website, App and Accounts, filled in during the Website phase (ROADMAP-v3 §9, phase 4)"
}