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:
@@ -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).
|
||||
@@ -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/"],
|
||||
};
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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";
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": ".",
|
||||
"types": ["node", "jest"]
|
||||
},
|
||||
"include": ["src", "tests", "tsup.config.ts"]
|
||||
}
|
||||
@@ -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" }),
|
||||
});
|
||||
@@ -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).
|
||||
@@ -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)"
|
||||
}
|
||||
Reference in New Issue
Block a user