@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/templates/default/src/config/modules.ts

@@ -0,0 +1,23 @@
+/**
+ * Module wiring — placeholder.
+ *
+ * Today, wire modules in `src/index.ts`: that's the type-safe seam for the
+ * `hc()` typed client. Each module exposes `buildXxxApp(deps)` — its own
+ * bounded sub-app — which you mount on the root with `root.route("/", ...)`.
+ * Mounting bounded sub-apps (rather than threading one shared app through
+ * every module) keeps each route-type instantiation bounded so the typed
+ * client scales. For example, after `ship-api add accounts`:
+ *
+ *   // src/index.ts
+ *   import { buildAccountsApp, AccountService } from "./modules/accounts/index.js";
+ *   const { db } = createDb({ config: { connectionString: env.DATABASE_URL }, schema });
+ *   const root = createApp({ cors });
+ *   const app = root.route("/", buildAccountsApp({ service: new AccountService(db), provider }));
+ *   export type ShipApiClient = typeof app;
+ *
+ * This file is reserved for a planned `ship-api` auto-wiring step that will
+ * generate explicit, type-preserving wiring from your installed modules. Until
+ * then it intentionally exports nothing — wire in `index.ts`.
+ */
+
+export {};

package/templates/default/src/db/schema.ts

@@ -0,0 +1,26 @@
+/**
+ * Composed database schema — single source of truth for both:
+ *   1. The runtime via `createDb({ config, schema })` in `src/index.ts`.
+ *   2. The migration tooling via `drizzle.config.ts` (`schema:
+ *      "./src/db/schema.ts"`).
+ *
+ * The framework ships no default tables — identity/RBAC lives in the
+ * `accounts` module (add it with `ship-api add accounts`). Compose each
+ * module's exported schema fragment here, then add your own module tables.
+ * For example, after `ship-api add accounts`:
+ *
+ *   import { accountsSchema } from "../modules/accounts/index.js";
+ *   export const schema = { ...accountsSchema, ...yourTables };
+ */
+
+// Compose module schema fragments as you add them:
+// import { accountsSchema } from "../modules/accounts/index.js"; // ship-api add accounts
+// import { posts, postsRelations } from "../modules/posts/schema.js"; // ship-api g resource posts
+
+export const schema = {
+  // ...accountsSchema,
+  // posts,
+  // postsRelations,
+};
+
+export type Schema = typeof schema;

package/templates/default/src/environment.ts

@@ -0,0 +1,81 @@
+import { defineEnv } from "@sixthsummit/ship-api";
+import { z } from "zod";
+
+/**
+ * Runtime configuration boundary. `defineEnv` validates
+ * `process.env` against the Zod schema below at boot — fail-fast
+ * with a structured "missing/invalid: KEY" error instead of letting
+ * bad config produce silent runtime failures.
+ *
+ * Convention enforced by the project's eslint config: this file is the only
+ * application-config boundary for `process.env`. The dependency-free
+ * `instrumentation.ts` bootstrap is the intentional early exception. Module
+ * and handler code route through the typed `env` object exported below.
+ */
+export const env = defineEnv(
+  z.object({
+    // ─── Server ────────────────────────────────────────────────────
+    PORT: z.coerce.number().int().positive().default(3000),
+    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+    LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info"),
+    /**
+     * Comma-separated CORS allowlist. The framework wires `hono/cors`
+     * with `credentials: true` against this list at `createApp()`.
+     * Browsers reject `origin: '*'` + `credentials: true`; the
+     * framework refuses to construct an app under that combination.
+     *
+     * Example: `CORS_ORIGINS=https://app.example.com,https://admin.example.com`
+     */
+    CORS_ORIGINS: z
+      .string()
+      .optional()
+      .transform((value) =>
+        value
+          ? value
+              .split(",")
+              .map((entry) => entry.trim())
+              .filter((entry) => entry.length > 0)
+          : undefined,
+      ),
+
+    // ─── Database ──────────────────────────────────────────────────
+    DATABASE_URL: z.string().url(),
+
+    // ─── Auth ──────────────────────────────────────────────────────
+    OAUTH_STATE_SECRET: z.string().min(32),
+    JWT_SIGNING_KEY: z.string().optional(),
+    JWT_VERIFICATION_KEYS: z.string().optional(),
+
+    // ─── Redis (optional in dev, required for rate-limit + jobs) ───
+    REDIS_URL: z.string().url().optional(),
+
+    // ─── Admin (Bull-Board dashboard etc.) ─────────────────────────
+    // Required when mounting the Bull-Board admin UI via
+    // `createBullBoardApp({ apiKey: env.ADMIN_API_KEY })`. ≥32 random
+    // bytes; rotate independently of JWT keys. The dashboard is
+    // dev/staging-only — don't expose it on a public hostname even
+    // with the key set.
+    ADMIN_API_KEY: z.string().min(32).optional(),
+
+    // ─── Observability ─────────────────────────────────────────────
+    OTEL_SDK_DISABLED: z.string().optional(),
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().url().optional(),
+    OTEL_SERVICE_NAME: z.string().default("ship-api-app"),
+    ENVIRONMENT_NAME: z.string().default("development"),
+    METRICS_ENABLED: z.string().optional(),
+    METRICS_PORT: z.coerce.number().int().positive().default(9464),
+
+    // ─── Firebase (default AuthProvider; swap for Better-Auth/etc.) ─
+    FIREBASE_CREDENTIALS: z.string().optional(),
+
+    // ─── OAuth providers (declare only what you support) ───────────
+    OAUTH_GOOGLE_CLIENT_ID: z.string().optional(),
+    OAUTH_GOOGLE_CLIENT_SECRET: z.string().optional(),
+    OAUTH_GOOGLE_REDIRECT_URI: z.string().url().optional(),
+    OAUTH_MICROSOFT_CLIENT_ID: z.string().optional(),
+    OAUTH_MICROSOFT_CLIENT_SECRET: z.string().optional(),
+    OAUTH_MICROSOFT_REDIRECT_URI: z.string().url().optional(),
+  }),
+);
+
+export type Env = typeof env;

package/templates/default/src/index.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Sample test — exercises `createApp` end-to-end without booting a server.
+ * Hono apps are testable via `app.request(path, init)` which returns a
+ * standard `Response`. No supertest, no port binding, no test containers.
+ *
+ * Replace this file with real coverage as you add modules. Pattern to follow:
+ *   - service unit tests at `modules/<name>/services/<Name>Service.test.ts`
+ *     (fake-DB; cover service logic + lifecycle hooks)
+ *   - route integration tests at `modules/<name>/routes.test.ts`
+ *     (full requireAuth → requirePermission → validate → handler chain)
+ *   - mirror the harness from `modules/accounts/routes.test.ts` in the
+ *     framework monorepo for canonical structure.
+ */
+
+import { describe, it, expect } from "vitest";
+import { createApp, registerErrorHandlers } from "@sixthsummit/ship-api";
+
+describe("createApp", () => {
+  it("returns a Hono app that handles routes", async () => {
+    const app = createApp({});
+    app.get("/sample", (c) => c.json({ ok: true }));
+
+    const res = await app.request("/sample");
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it("serves /livez and /readyz with no extra wiring", async () => {
+    const app = createApp({});
+
+    const live = await app.request("/livez");
+    expect(live.status).toBe(200);
+    expect(await live.json()).toEqual({ ok: true });
+
+    const ready = await app.request("/readyz");
+    expect(ready.status).toBe(200);
+  });
+
+  it("shapes thrown errors via registerErrorHandlers", async () => {
+    const app = createApp({});
+    registerErrorHandlers(app);
+    app.get("/boom", () => {
+      throw new Error("kaboom");
+    });
+
+    const res = await app.request("/boom");
+
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error?: { message?: string } };
+    expect(body.error).toBeDefined();
+  });
+});

package/templates/default/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Process bootstrap. Instrumentation is the only static runtime import:
+ * ESM evaluates every static dependency before running this body, so loading
+ * the application here would make auto-instrumentation too late.
+ */
+import "./instrumentation.js";
+
+await import("./server.js");
+
+// Type-only exports are erased and therefore do not load `server.js` early.
+export type { ShipApiClient } from "./server.js";

package/templates/default/src/instrumentation.ts

@@ -0,0 +1,13 @@
+/**
+ * Telemetry bootstrap boundary. Keep this module independent from application
+ * code so the SDK starts before HTTP, database, Redis, or logging libraries
+ * are loaded. Direct environment reads are intentional at this early boundary:
+ * importing the application's validated environment would load the framework.
+ */
+import { startOtel } from "@sixthsummit/ship-observability-otel/sdk";
+
+startOtel({
+  serviceName: process.env.OTEL_SERVICE_NAME ?? "ship-api-app",
+  serviceVersion: process.env.npm_package_version,
+  environmentName: process.env.ENVIRONMENT_NAME ?? process.env.NODE_ENV,
+});

package/templates/default/src/server.ts

@@ -0,0 +1,90 @@
+/**
+ * Application composition root. `src/index.ts` starts OpenTelemetry and then
+ * loads this module dynamically so its dependencies can be instrumented.
+ *
+ *   1. validates env via `defineEnv` (already done in
+ *      `./environment.ts` — importing it triggers validation).
+ *   2. composes the root app (`createApp({ cors })`) and mounts each
+ *      module's sub-app via `root.route("/", buildXxxApp(deps))`.
+ *   3. wires the auth provider (Firebase by default; swap for
+ *      Better-Auth/Clerk/WorkOS/Auth.js when those adapters land).
+ *   4. starts the HTTP server.
+ *
+ * The END of the route chain is exported as `ShipApiClient` so client
+ * consumers (web, mobile, microservices) can `hc<ShipApiClient>()`
+ * end-to-end-typed without codegen — see the v4 cross-framework
+ * contract in AGENTS.md. Hono's RPC types live on the RETURN VALUE of
+ * each chained `.get()`/`.post()` call — routes register at runtime
+ * either way, but a discarded return (or a `typeof app` taken from the
+ * bare `createApp()` result) produces a typed client with zero routes.
+ */
+
+import { serve } from "@hono/node-server";
+import { createApp, registerErrorHandlers, httpLogger } from "@sixthsummit/ship-api";
+import { logger } from "@sixthsummit/ship-api/observability/logger";
+import { env } from "./environment.js";
+// DB wiring (when you add modules): compose the schema via
+//   const { db } = createDb({ config: { connectionString: env.DATABASE_URL }, schema });
+// import { createDb } from "@sixthsummit/ship-api/app/db/client";
+// import { schema } from "./db/schema.js";
+
+// ─── Compose the app ──────────────────────────────────────────────────
+
+const app = createApp({
+  // CORS — driven by the `CORS_ORIGINS` env var (a comma-separated
+  // allowlist of origins). When unset the framework attaches no CORS
+  // middleware; cookies stay same-origin only.
+  cors: env.CORS_ORIGINS ? { origin: env.CORS_ORIGINS, credentials: true } : undefined,
+  // Health routes: `createApp` already mounts unauthenticated `GET /livez`
+  // and `GET /readyz`, ahead of every middleware below — no wiring needed.
+  // `createDb(...)` adds a `db.primary` readiness check once you add a
+  // database. Configure with `health: { prefix, readyzTimeoutMs }`, or opt
+  // out with `health: false`. Don't add `/healthz`: Cloud Run's front end
+  // intercepts that path before it reaches the container.
+});
+
+registerErrorHandlers(app);
+app.use("*", httpLogger());
+
+// Capture the chained return — `routes` carries this route's RPC type;
+// a bare `app.get(...)` statement would register it but lose the type.
+const routes = app.get("/", (c) => c.json({ ok: true, framework: "ship-api", version: "v4" }));
+
+// ─── Wire your modules ────────────────────────────────────────────────
+//
+// Modules are copied into your app (e.g. `ship-api add accounts`), so you
+// import them from your local `./modules/<name>`, not from the framework.
+//
+// Each module exposes `buildXxxApp(deps)` — its own bounded sub-app. Mount
+// each onto the root with `.route("/", ...)`; modules keep their absolute
+// paths, so the client stays flat (`api.accounts.$get`). Chain the mounts and
+// point `ShipApiClient` at the end so every route's RPC type survives:
+//
+// import { buildAccountsApp, AccountService } from "./modules/accounts/index.js";
+// import { createDb } from "@sixthsummit/ship-api/app/db/client";
+// import { firebaseAuth } from "@sixthsummit/ship-api/app/auth/adapters/firebase";
+// import { schema } from "./db/schema.js";
+//
+// const { db } = createDb({ config: { connectionString: env.DATABASE_URL }, schema });
+// const accountService = new AccountService(db);
+// const provider = firebaseAuth({ findAccount: (uid) => accountService.findByFirebaseUid(uid) });
+// const routedApp = routes
+//   .route("/", buildAccountsApp({ service: accountService, provider }));
+// export type ShipApiClient = typeof routedApp;   // ← replaces the export below
+//
+// Mounting each module as its own sub-app (rather than threading one app
+// through every `defineXxxRoutes`) keeps each route-type instantiation
+// bounded, so the typed client scales to many modules without `tsc` overflow.
+// ⚠️ Keep `registerErrorHandlers` + `httpLogger` + cors on the ROOT only —
+// never set `onError`/`use("*")` inside a module sub-app (it would shadow the
+// uniform AppError shape and per-request logging).
+
+// ─── Export the App type for typed-client consumers ──────────────────
+
+export type ShipApiClient = typeof routes;
+
+// ─── Boot ─────────────────────────────────────────────────────────────
+
+serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+  logger.info({ port: info.port, environment: env.ENVIRONMENT_NAME }, "ship-api up");
+});

package/templates/default/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*", "drizzle.config.ts", "ship-api.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}