@skyf0xx/hedgehog-core-full-stack-app 1.0.0

package/workspace/packages/config/eslint-base.js

@@ -0,0 +1,205 @@
+import nx from '@nx/eslint-plugin';
+
+/**
+ * Locked, shared ESLint flat config — extended by every app/lib in the
+ * workspace (via root `eslint.config.mjs`). Encodes Nx module boundaries
+ * (tags + depConstraints) as a build-time (`nx lint`) failure. See
+ * `.claude/skills/hedgehog-bootstrap` and `.claude/skills/hedgehog-loop`
+ * for the discipline this enforces.
+ *
+ * The constraints below describe the project shape `core.yaml`'s compiled
+ * layer sequence actually produces. One layer, `repository`, lands a
+ * module's port interface AND its Drizzle adapter in the same lib
+ * (`libs/<module>/repository`, tagged `type:adapter`) — there is no
+ * separate `type:port` project, so a tag constraint alone cannot say
+ * "import the interface, not the concrete class." The
+ * `no-restricted-imports` block below carries that half of port
+ * discipline; the tag graph carries the rest.
+ *
+ * Tag reference:
+ *   apps/api             -> scope:api
+ *   apps/worker           -> scope:worker
+ *   apps/web              -> scope:web
+ *   apps/mobile           -> scope:mobile
+ *   packages/db           -> scope:db,        type:adapter
+ *   packages/contracts    -> scope:contracts, type:contract
+ *   packages/hooks        -> scope:hooks,     type:hook
+ *   packages/auth         -> scope:auth,      type:adapter
+ *   packages/config       -> scope:config,    type:util
+ *   packages/shared       -> scope:shared,    type:util
+ *   libs/<module>/repository -> scope:<module>, type:adapter
+ *   libs/<module>/service    -> scope:<module>, type:service
+ */
+export default [
+  ...nx.configs['flat/base'],
+  ...nx.configs['flat/typescript'],
+  ...nx.configs['flat/javascript'],
+  {
+    ignores: ['**/dist', '**/out-tsc'],
+  },
+  {
+    files: [
+      '**/*.ts',
+      '**/*.tsx',
+      '**/*.js',
+      '**/*.jsx',
+      '**/*.cjs',
+      '**/*.mjs',
+    ],
+    rules: {
+      '@nx/enforce-module-boundaries': [
+        'error',
+        {
+          // `false`, not `true`: `packages/contracts` and `packages/hooks`
+          // are source-only by this core's design — they have no `build`
+          // target and are consumed as TypeScript sources. With this on,
+          // `apps/web` (a real Next build target) importing either one
+          // fails lint purely for that structural choice, not for any
+          // dependency that's actually wrong.
+          enforceBuildableLibDependency: false,
+          allow: ['^.*/eslint(\\.base)?\\.config\\.[cm]?[jt]s$'],
+          depConstraints: [
+            // domain services reach storage through their own module's
+            // repository lib, which holds the port interface alongside the
+            // Drizzle adapter (`type:adapter`). Which symbol a service may
+            // import out of that lib is the no-restricted-imports rule
+            // below, not something a tag can express.
+            {
+              sourceTag: 'type:service',
+              onlyDependOnLibsWithTags: [
+                'type:adapter',
+                'type:contract',
+                'type:util',
+              ],
+            },
+            // adapters (repositories, db client, auth config) depend on
+            // packages/db and shared utils — never reach across into
+            // another module's service
+            {
+              sourceTag: 'type:adapter',
+              onlyDependOnLibsWithTags: [
+                'type:adapter',
+                'type:contract',
+                'type:util',
+              ],
+            },
+            // the ts-rest/Zod contract is derived from the Drizzle schema
+            // (`drizzle-zod`), so it reaches packages/db and nothing else
+            {
+              sourceTag: 'type:contract',
+              onlyDependOnLibsWithTags: ['type:adapter', 'type:util'],
+            },
+            // TanStack Query hooks are typed by the contract they call
+            {
+              sourceTag: 'type:hook',
+              onlyDependOnLibsWithTags: ['type:contract', 'type:util'],
+            },
+            // shared utils (packages/config, packages/shared) depend on
+            // nothing else in the workspace — they're the floor
+            {
+              sourceTag: 'type:util',
+              onlyDependOnLibsWithTags: ['type:util'],
+            },
+            // web/mobile never import db or api internals — only contracts +
+            // hooks (+ shared util packages like packages/config, same as
+            // every other app in the workspace)
+            {
+              sourceTag: 'scope:web',
+              onlyDependOnLibsWithTags: [
+                'scope:contracts',
+                'scope:hooks',
+                'scope:shared',
+                'type:util',
+              ],
+            },
+            {
+              sourceTag: 'scope:mobile',
+              onlyDependOnLibsWithTags: [
+                'scope:contracts',
+                'scope:hooks',
+                'scope:shared',
+                'type:util',
+              ],
+            },
+            // worker reaches domain logic the same way api does
+            {
+              sourceTag: 'scope:worker',
+              onlyDependOnLibsWithTags: [
+                'type:adapter',
+                'type:service',
+                'type:contract',
+                'type:util',
+                'scope:shared',
+              ],
+            },
+            // api is the composition root: its NestJS module is the only
+            // place that constructs a module's concrete adapter and binds
+            // it to the port's DI token, so it reaches `type:adapter` by
+            // necessity. It also serves the ts-rest contract, hence
+            // `type:contract`. What it may NOT do is inject an adapter
+            // into a controller — that's the no-restricted-imports rule.
+            {
+              sourceTag: 'scope:api',
+              onlyDependOnLibsWithTags: [
+                'type:adapter',
+                'type:service',
+                'type:contract',
+                'type:util',
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    // Port discipline, the half tags can't express. A module's port
+    // interface and its Drizzle adapter live in the same lib, so
+    // `type:service -> type:adapter` has to be allowed above; this is what
+    // stops a service from importing the concrete adapter through it.
+    // Services see the port only. Deep paths are named rather than the
+    // package entry point, because the entry point is also how the port
+    // itself is imported.
+    files: ['libs/*/service/**/*.ts'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['**/*.adapter', '**/*.adapter.js', '**/*.adapter.ts'],
+              message:
+                'A service depends on its module\'s port interface, never the concrete adapter. Import the port from the repository lib\'s entry point and let apps/api bind the adapter to its DI token.',
+            },
+            {
+              group: ['@app/db', '@app/db/*', 'db', 'db/*', 'drizzle-orm', 'drizzle-orm/*'],
+              message:
+                'A service never talks to the database directly — that is the repository adapter\'s job, reached through the port.',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    // The same rule one layer up, minus the composition root. A NestJS
+    // module file (`*.module.ts`) is where the adapter is constructed and
+    // bound, so it is exempt; a controller injecting an adapter is not.
+    files: ['apps/api/**/*.ts'],
+    ignores: ['apps/api/**/*.module.ts'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['**/*.adapter', '**/*.adapter.js', '**/*.adapter.ts'],
+              message:
+                'Only a NestJS module (*.module.ts) constructs a concrete adapter. A controller depends on the service, or on the port token the module bound.',
+            },
+          ],
+        },
+      ],
+    },
+  },
+];

package/workspace/packages/config/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "config",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./prettier": "./prettier.js",
+    "./eslint-base": "./eslint-base.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@ts-rest/core": "3.53.0-rc.1"
+  },
+  "nx": {
+    "tags": [
+      "scope:config",
+      "type:util"
+    ]
+  }
+}

package/workspace/packages/config/prettier.js

@@ -0,0 +1,13 @@
+/**
+ * Locked, shared Prettier config — extended by every app/lib.
+ *
+ * Deliberately does NOT include `prettier-plugin-tailwindcss`: the plugin
+ * parses every file Prettier touches (not just files with Tailwind
+ * classes) and throws on any file when no Tailwind config is resolvable
+ * yet — true for every project from this step through `apps/web`'s own
+ * setup. Add the plugin to `apps/web`'s own Prettier config (extending
+ * this base) once Tailwind exists there, not here.
+ */
+export default {
+  singleQuote: true,
+};

package/workspace/packages/config/src/env.schema.spec.ts

@@ -0,0 +1,38 @@
+import { envSchema } from './env.schema';
+
+describe('envSchema', () => {
+  const valid = {
+    DATABASE_URL: 'postgresql://postgres:postgres@localhost:5432/app',
+    NODE_ENV: 'development',
+  };
+
+  it('accepts a fully valid env', () => {
+    const result = envSchema.safeParse(valid);
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects a missing DATABASE_URL', () => {
+    const rest: Record<string, string> = { ...valid };
+    delete rest['DATABASE_URL'];
+    const result = envSchema.safeParse(rest);
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an invalid NODE_ENV value', () => {
+    const result = envSchema.safeParse({ ...valid, NODE_ENV: 'staging' });
+    expect(result.success).toBe(false);
+  });
+
+  it('defaults WEB_ORIGIN when absent', () => {
+    const result = envSchema.safeParse(valid);
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.WEB_ORIGIN).toBe('http://localhost:3000');
+    }
+  });
+
+  it('rejects a non-URL WEB_ORIGIN', () => {
+    const result = envSchema.safeParse({ ...valid, WEB_ORIGIN: 'not-a-url' });
+    expect(result.success).toBe(false);
+  });
+});

package/workspace/packages/config/src/env.schema.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+export const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+  WEB_ORIGIN: z.string().url().default('http://localhost:3000'),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+export function loadEnv(): Env {
+  const parsed = envSchema.safeParse(process.env);
+  if (!parsed.success) {
+    console.error(parsed.error.format());
+    process.exit(1);
+  }
+  return parsed.data;
+}

package/workspace/packages/config/src/index.ts

@@ -0,0 +1 @@
+export * from './env.schema';

package/workspace/packages/config/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/workspace/packages/config/tsconfig.lib.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo",
+    "emitDeclarationOnly": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "references": [],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/workspace/packages/config/tsconfig.spec.json

@@ -0,0 +1,34 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ],
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/workspace/packages/config/vitest.config.mts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/packages/config',
+  test: {
+    name: 'config',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));

package/workspace/packages/db/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "db",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "pg": "^8.22.0",
+    "config": "workspace:*"
+  },
+  "nx": {
+    "tags": [
+      "scope:db",
+      "type:adapter"
+    ]
+  }
+}

package/workspace/packages/db/src/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/db';
+export * from './schema/index';

package/workspace/packages/db/src/lib/db.spec.ts

@@ -0,0 +1,48 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('db', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env.DATABASE_URL =
+      'postgres://postgres:postgres@localhost:5432/app';
+    process.env.NODE_ENV = 'test';
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('lazily constructs a single shared pool', async () => {
+    const { getPool, closeDb } = await import('./db');
+    const first = getPool();
+    const second = getPool();
+    expect(first).toBe(second);
+    await closeDb();
+  });
+
+  it('returns a drizzle client bound to the shared pool', async () => {
+    const { getDb, closeDb } = await import('./db');
+    const db = getDb();
+    expect(db).toBeDefined();
+    await closeDb();
+  });
+
+  it('exits fast when DATABASE_URL is missing or malformed', async () => {
+    process.env.DATABASE_URL = 'not-a-url';
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit called');
+    });
+    const errorSpy = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+
+    const { getPool } = await import('./db');
+    expect(() => getPool()).toThrow('process.exit called');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

package/workspace/packages/db/src/lib/db.ts

@@ -0,0 +1,54 @@
+import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import { loadEnv } from 'config';
+
+/**
+ * Shared Drizzle client (Postgres via `pg`). Reads `DATABASE_URL` through
+ * `loadEnv()` — boot fails fast on a missing/malformed connection string
+ * rather than surfacing as a runtime connection error.
+ *
+ * No domain schema is registered here — each module's own schema lives in
+ * `libs/<module>/repository` (Phase A) and is passed in via `withSchema`
+ * (or attached at the call site), keeping this package schema-agnostic
+ * infra rather than a place domain modules reach into directly.
+ */
+
+let pool: Pool | undefined;
+let client: NodePgDatabase | undefined;
+
+export function getPool(): Pool {
+  if (!pool) {
+    const env = loadEnv();
+    pool = new Pool({
+      connectionString: env.DATABASE_URL,
+      // A wedged connection surfaces as a query error rather than a hang.
+      connectionTimeoutMillis: 10_000,
+      idleTimeoutMillis: 30_000,
+    });
+    // `pg` emits 'error' on the pool when an *idle* client's connection dies
+    // (Postgres restart, failover, laptop sleep). Node terminates the process
+    // on an unhandled 'error' event, so without this listener a routine
+    // database blip crashes the API. `pg` has already discarded the bad
+    // client by the time this fires: the next query opens a fresh connection,
+    // so logging and swallowing is the recovery.
+    pool.on('error', (err) => {
+      console.error('idle postgres client error', err);
+    });
+  }
+  return pool;
+}
+
+export function getDb(): NodePgDatabase {
+  if (!client) {
+    client = drizzle(getPool());
+  }
+  return client;
+}
+
+export async function closeDb(): Promise<void> {
+  if (pool) {
+    await pool.end();
+    pool = undefined;
+    client = undefined;
+  }
+}

package/workspace/packages/db/src/schema/index.ts

@@ -0,0 +1,4 @@
+// Barrel-of-barrels: one re-export line per module, added by that module's
+// own schema layer (in scope — see core.yaml's schema layer). Keeps
+// packages/db/src/index.ts itself static after bootstrap.
+export {};

package/workspace/packages/db/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/workspace/packages/db/tsconfig.lib.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo",
+    "emitDeclarationOnly": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../config/tsconfig.lib.json" }],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/workspace/packages/db/tsconfig.spec.json

@@ -0,0 +1,34 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ],
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/workspace/packages/db/vitest.config.mts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig(() => ({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/packages/db',
+  test: {
+    name: 'db',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8' as const,
+    },
+  },
+}));