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,4 @@
|
||||
* text=auto eol=lf
|
||||
*.png binary
|
||||
*.jpg binary
|
||||
*.ico binary
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
# dependencies
|
||||
node_modules/
|
||||
|
||||
# env files (never commit real secrets — .env.example files are fine)
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
|
||||
# build output
|
||||
dist/
|
||||
coverage/
|
||||
.next/
|
||||
|
||||
# logs
|
||||
npm-debug.log*
|
||||
*.log
|
||||
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
@@ -0,0 +1,13 @@
|
||||
# Changelog
|
||||
|
||||
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Monorepo
|
||||
|
||||
- Set up: npm workspaces (`packages/*`, `apps/*`), shared TypeScript, ESLint and Jest setup,
|
||||
and `npm run check` (lint, typecheck, tests and build).
|
||||
- `packages/contracts`: package set up with a dual CommonJS / ESM build (tsup) and the
|
||||
schema-name helpers every contract uses (`crosscode.<name>/<major>`).
|
||||
- `packages/ui`, `apps/accounts`, `apps/website`, `apps/app`: placeholders.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Cross Code platform
|
||||
|
||||
The monorepo for the Cross Code products that come after Cross Events, and the formats they share.
|
||||
The plan is in `hope-events/docs/ROADMAP-v3.md` (decided 2026-11-03).
|
||||
|
||||
| Folder | What | Status |
|
||||
|--------|------|--------|
|
||||
| `packages/contracts` | `@crosscode/contracts`: the shared JSON formats (zod schemas, JSON Schema, TypeScript types, sample payloads) used by every product, including Cross Events and the Hub | Phase 0, in progress |
|
||||
| `packages/ui` | `@crosscode/ui`: shared UI for the Website, App and Accounts | Placeholder, filled in during the Website phase |
|
||||
| `apps/accounts` | Accounts: the per-church sign-in (OpenID Connect) | Placeholder (phase 3) |
|
||||
| `apps/website` | Church Website | Placeholder (phase 4) |
|
||||
| `apps/app` | Church App (PWA) | Placeholder (phase 6) |
|
||||
|
||||
Cross Events (`joshua/hope-events`) and Cross Code Hub (`joshua/events-hub`) stay in their own
|
||||
repos and install `@crosscode/contracts` from Gitea's package registry.
|
||||
|
||||
## Rules (ROADMAP-v3 §1)
|
||||
|
||||
1. No shared databases, ever. Products only talk over HTTPS using the contracts.
|
||||
2. The Hub is never on the runtime path.
|
||||
3. One maintained codebase per product. Nothing is built specially for one church.
|
||||
4. The origin of a record owns it. Copies elsewhere are read-only and link back to the origin.
|
||||
|
||||
## Working on it
|
||||
|
||||
Node 20 or newer, npm workspaces.
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run check # lint + typecheck + tests + build, for every workspace
|
||||
npm run build # build every workspace
|
||||
npm test # test every workspace
|
||||
```
|
||||
|
||||
Work in a workspace with `npm run <script> -w packages/contracts`.
|
||||
|
||||
Stack (ROADMAP-v3 §8): TypeScript, zod, Jest, ESLint here; the apps add Next.js, Express,
|
||||
Prisma, PostgreSQL and pg-boss, as in Cross Events. PM2 and nginx, no Docker.
|
||||
|
||||
## Releasing
|
||||
|
||||
Each package and app is versioned and tagged on its own, as `<name>@<version>` (e.g.
|
||||
`contracts@1.0.0`). Branch → merge → tag → push, with a CHANGELOG entry. Run `npm run check` first.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Accounts
|
||||
|
||||
Placeholder: the per-church sign-in (OpenID Connect). Built in phase 3 of ROADMAP-v3 (see §3 there).
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"name": "@crosscode/accounts",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"description": "Placeholder: Accounts, built in phase 3 (ROADMAP-v3 §3)"
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Church App
|
||||
|
||||
Placeholder: the church-branded web app (PWA) with House of Prayer. Built in phase 6 of ROADMAP-v3 (see §7 there).
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"name": "@crosscode/app",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"description": "Placeholder: Church App, built in phase 6 (ROADMAP-v3 §7)"
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
# Church Website
|
||||
|
||||
Placeholder: the church's public website and its admin. Built in phase 4 of ROADMAP-v3 (see §6 there).
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"name": "@crosscode/website",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"description": "Placeholder: Church Website, built in phase 4 (ROADMAP-v3 §6)"
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
import { defineConfig, globalIgnores } from "eslint/config";
|
||||
import js from "@eslint/js";
|
||||
import tseslint from "typescript-eslint";
|
||||
|
||||
// One flat config for the whole monorepo. Run with `npm run lint` at the root.
|
||||
export default defineConfig([
|
||||
js.configs.recommended,
|
||||
...tseslint.configs.recommended,
|
||||
{
|
||||
files: ["**/*.cjs", "**/jest.config.js"],
|
||||
languageOptions: { sourceType: "commonjs", globals: { module: "writable", require: "readonly" } },
|
||||
rules: { "@typescript-eslint/no-require-imports": "off" },
|
||||
},
|
||||
{
|
||||
rules: {
|
||||
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
|
||||
"@typescript-eslint/consistent-type-imports": "error",
|
||||
},
|
||||
},
|
||||
globalIgnores(["**/node_modules/**", "**/dist/**", "**/coverage/**", "**/schemas/**"]),
|
||||
]);
|
||||
Generated
+7220
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,31 @@
|
||||
{
|
||||
"name": "crosscode-platform",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"description": "Cross Code platform monorepo: Accounts, Church Website, Church App and the shared contracts (see docs/ROADMAP-v3.md in hope-events)",
|
||||
"workspaces": [
|
||||
"packages/*",
|
||||
"apps/*"
|
||||
],
|
||||
"scripts": {
|
||||
"build": "npm run build --workspaces --if-present",
|
||||
"test": "npm test --workspaces --if-present",
|
||||
"typecheck": "npm run typecheck --workspaces --if-present",
|
||||
"lint": "eslint .",
|
||||
"check": "npm run lint && npm run typecheck && npm test && npm run build"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=20"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint/js": "^10.0.1",
|
||||
"@types/jest": "^30.0.0",
|
||||
"@types/node": "^20.19.43",
|
||||
"eslint": "^10.13.0",
|
||||
"jest": "^30.5.2",
|
||||
"ts-jest": "^29.4.15",
|
||||
"tsup": "^9.0.0",
|
||||
"typescript": "^5.9.3",
|
||||
"typescript-eslint": "^8.72.1"
|
||||
}
|
||||
}
|
||||
@@ -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)"
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
{
|
||||
// Shared by every package and app. Strict like the Cross Events backend's .ts files.
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"lib": ["ES2023"],
|
||||
"strict": true,
|
||||
"noImplicitOverride": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
"esModuleInterop": true,
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"declaration": true,
|
||||
"sourceMap": true
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user