Summary

Memora no tiene todavía ni una línea de código de producto: esta tarea entrega el terreno de trabajo y nada de producto. Un monorepo pnpm + Turborepo cuyo package.json raíz es la única puerta de entrada; apps/web con TanStack Start + Tailwind + shadcn (new-york / neutral) mostrando un «Hola Mundo» que demuestra que la cadena de estilos aplica de punta a punta; MongoDB 8 en Docker Compose (sin credenciales, volumen nombrado, solo para local) con los scripts db:up / db:down / db:reset; packages/db como único sitio del repositorio que resuelve MONGODB_URI y construye el cliente de Mongo; y console-runner en la raíz (por petición explícita) con un menú interactivo de mantenimiento que comprueba la conexión, limpia la base de datos tras una confirmación explícita e imprime un TODO en la opción de datos de prueba — un hueco señalizado, nunca trabajo fingido. La calidad la sostienen tsc --noEmit y Prettier, sin linter por decisión explícita, con un workflow de GitHub Actions que ejecuta typecheck, format:check, test y build en cada PR para que el gate de merge del harness tenga un verde real que leer. El criterio de éxito es operativo: quien clona el repositorio levanta la base de datos, arranca el front y ejecuta el runner con comandos de la raíz — y eso se verifica a mano (db:up → runner → dev → la página carga), porque la suite de tests es hermética y no cubre la infra real.

Requirements — Infraestructura y estructura base del monorepo

Source PRD: docs/prds/infra-monorepo-2026-10-17.md
Task: #1 — branch harness/1-infra-monorepo

Scope note: this delivery is infrastructure only. No product surface, no domain
model, no auth. The success criterion is operational: a fresh clone can bring up the
database, start the front and run the maintenance runner from root package.json
scripts, and the PR passes the mechanical gates.

A. Monorepo root — one install, one entry point (US1)

• R1 (ubiquitous): The repository root shall be a private pnpm workspace whose
  pnpm-workspace.yaml declares apps/*, packages/* and console-runner as
  workspace packages.
• R2 (ubiquitous): The root package.json shall pin the package manager with
  packageManager: "pnpm@10.19.0" and declare the supported Node version in engines
  (node: ">=24.16.0 <25"), matched by a committed .nvmrc holding 24.16.0.
• R3 (event): When pnpm install is run at the repository root, the system shall
  install and link every workspace package's dependencies in a single command, with no
  further manual configuration.
• R4 (ubiquitous): After the migration the repository shall contain exactly one
  lockfile — pnpm-lock.yaml — and no package-lock.json.
• R5 (ubiquitous): The harness CLI shall stay resolvable at
  <repo-root>/node_modules/.bin/lemony after a pnpm install, because
  .claude/hooks/lib/lemony.sh resolves that exact path.
• R6 (ubiquitous): The root package.json shall be the only entry point and expose
  exactly these scripts: dev, build, test, typecheck, format, format:check,
  db:up, db:down, db:reset, runner.
• R7 (event): When one of the workspace-spanning root scripts (dev, build,
  test, typecheck) is run, the system shall delegate the work to Turborepo through
  turbo.json, not to a hand-written loop over directories.
• R8 (ubiquitous): Every workspace package shall compile under TypeScript strict
  mode (strict: true) from a shared root tsconfig.base.json.
• R9 (event): When pnpm typecheck is run, the system shall run tsc --noEmit for
  every workspace and exit non-zero if any workspace reports a type error.
• R10 (event): When pnpm format:check is run, the system shall verify Prettier
  formatting across the project's own tracked files and exit non-zero if any file is
  unformatted.
• R11 (ubiquitous): The Prettier scope shall exclude vendor and generated paths —
  node_modules, .claude/, pnpm-lock.yaml, build outputs and caches — so a harness
  vendor update can never fail the format gate.
• R12 (event): When pnpm build, pnpm test or pnpm dev has been run,
  git status --porcelain shall report no new untracked and no modified tracked files
  (every build output and cache is gitignored).

Acceptance criteria

• A fresh clone + pnpm install + pnpm typecheck + pnpm test + pnpm build
  succeeds with no step outside the root package.json.
• pnpm-lock.yaml is committed; package-lock.json is gone from the worktree and
  from the index.
• .claude/hooks/lib/lemony.sh emit … still works after the install (the launcher
  finds the local bin).
• git status --porcelain is empty after a full build + test + a dev session.

B. Front end — «Hola Mundo» proving the TanStack Start → Tailwind → shadcn chain (US4)

• R13 (ubiquitous): apps/web shall be a TanStack Start application in TypeScript
  strict mode, with Tailwind configured and shadcn initialised with style new-york
  and base colour neutral.
• R14 (event): When pnpm dev is run, the system shall serve apps/web on a local
  port and its root route shall render the «Hola Mundo» page.
• R15 (ubiquitous): The «Hola Mundo» route shall render its content inside a shadcn
  Card and shall include a shadcn Button, so the styling chain is demonstrably
  applied end to end.
• R16 (ubiquitous): The page shall use the shadcn/Tailwind default tokens only — no
  theme switcher, no dark-mode toggle, no custom palette (deferred by the PRD).
• R17 (event): When pnpm build is run, the system shall produce a production build
  of apps/web and exit zero.
• R18 (ubiquitous): The repository shall contain no file, route, asset, script or
  dependency left behind by a scaffolding CLI that is not used by the «Hola Mundo»
  page, the tests, the gates or the build.
• R19 (event): When the front smoke test runs, it shall render the «Hola Mundo»
  route component and assert both the greeting text and the presence of the shadcn
  Button, without Docker, a live Mongo or network access.
• R20 (ubiquitous): The front end shall perform no database access in this delivery,
  and apps/web shall declare no dependency on @memora/db.
• R21 (unwanted): If the current shadcn release is incompatible with the Tailwind
  version TanStack Start installs, then the implementation shall pin the exact
  combination that works and state the pinned versions in progress.md and the PR
  description, instead of leaving a broken or half-working styling chain.

Acceptance criteria

• pnpm dev serves a page showing the greeting inside a Card with a styled
  Button (Tailwind classes visibly applied).
• pnpm test runs the smoke test green with Docker stopped and no network.
• apps/web/package.json lists no unused dependency and no @memora/db.

C. MongoDB in Docker — reproducible local database (US2, US3)

• R22 (ubiquitous): docker-compose.yml at the repository root shall define a
  single service built from image mongo:8, publishing port 27017, with no
  credentials, a named volume mounted at /data/db, and a healthcheck that reports
  the server as ready.
• R23 (ubiquitous): docker-compose.yml shall carry a header comment stating it is
  for local development only — no credentials, never for an externally reachable
  environment.
• R24 (event): When pnpm db:up is run, the system shall start the Mongo container
  detached and return only once the container reports healthy.
• R25 (event): When pnpm db:down is run, the system shall stop and remove the
  container while preserving the named volume, so the data survives.
• R26 (event): When pnpm db:reset is run, the system shall remove the container
  and its named volume and then start a fresh healthy container, so the database
  comes back empty.
• R27 (unwanted): If the Docker daemon is not running, or port 27017 is already
  bound, then the db:* script shall surface Docker's own error message unchanged and
  exit non-zero — no masking, no retry loop, no silent success.
• R28 (ubiquitous): The database name shall be memora and the canonical local URI
  mongodb://localhost:27017/memora.

Acceptance criteria

• pnpm db:up → docker compose ps shows the service healthy.
• Data written between db:up and db:down is still there after db:up again.
• After pnpm db:reset the memora database is empty.
• With Docker stopped, pnpm db:up exits non-zero and prints Docker's error.

D. packages/db — the only place that knows how to reach Mongo (technical decision)

• R29 (ubiquitous): packages/db, published in the workspace as @memora/db, shall
  be the only location in the repository that resolves MONGODB_URI or constructs a
  Mongo client; no other workspace shall import the mongodb driver directly.
• R30 (ubiquitous): @memora/db shall expose a pure resolver
  (resolveMongoUri(env)) that returns the configured URI for a given environment
  record, without reading global state itself.
• R31 (unwanted): If MONGODB_URI is absent, empty or whitespace-only in the given
  environment, then the resolver shall throw an explicit error naming the variable and
  pointing at .env.example, and shall not fall back to any default URI.
• R32 (ubiquitous): @memora/db shall expose a client factory
  (createMongoClient(uri)) that applies a server-selection timeout of at most
  5000 ms, so an unreachable server fails fast instead of hanging on the driver's
  default.
• R33 (ubiquitous): @memora/db shall expose the two maintenance primitives the
  runner needs — a connectivity check (ping) and a database drop — operating on the
  database encoded in the URI, with no hard-coded database name.
• R34 (ubiquitous): .env.example shall be versioned at the repository root with
  MONGODB_URI=mongodb://localhost:27017/memora, and .env shall be gitignored.
• R35 (event): When an entry point starts, the system shall load the
  repository-root .env into the process environment if the file exists, and shall not
  fail when it is absent — the missing-variable failure of R31 is the only
  configuration failure path.
• R36 (ubiquitous): @memora/db shall be consumed as TypeScript source (no build
  step, no emitted dist/) and shall typecheck on its own via pnpm typecheck.
• R37 (ubiquitous): The driver shall be the official mongodb package with generic
  collection typing; no ODM (no Mongoose, no Prisma) shall be added.

Acceptance criteria

• A unit test proves resolveMongoUri returns the value when present.
• A unit test proves the absent/empty variable throws, and the message names
  MONGODB_URI.
• grep for from 'mongodb' outside packages/db returns nothing.

E. Console runner — discoverable maintenance menu (US5, US7)

• R38 (event): When pnpm runner is run, the system shall display an interactive
  arrow-key menu offering exactly: check Mongo connection, clean database, load seed
  data, exit — requiring no command-line flags.
• R39 (event): When an operation finishes, the system shall return to the menu, and
  when exit is chosen it shall close any open Mongo client and exit with code 0,
  leaving no hanging process.
• R40 (event): When «check connection» is chosen, the system shall connect with the
  resolved URI, issue a ping, and report success naming the host and database it
  reached.
• R41 (unwanted): If the connection or ping fails (server down, timeout), then the
  system shall report the failure with the driver's message plus a hint to run
  pnpm db:up, return to the menu, and not crash with an unhandled-exception stack
  trace.
• R42 (unwanted): If MONGODB_URI cannot be resolved when an operation needs it,
  then the runner shall print that explicit configuration error (R31) and return to the
  menu without attempting a connection.
• R43 (event): When «load seed data» is chosen, the system shall print a message
  marking the operation as pending (TODO), perform no database access, and return
  a pending result marker — it shall never report work it did not do.
• R44 (unwanted): If the user interrupts a prompt (Ctrl+C), then the runner shall
  terminate quietly — no unhandled-exception stack trace — closing any open client.
• R45 (ubiquitous): Each runner operation shall be a function independent of the
  prompt layer, receiving its Mongo client/db as a parameter, so it can be tested
  against a double.
• R46 (ubiquitous): The runner shall be executed with tsx directly over
  TypeScript, with no build step.

Acceptance criteria

• pnpm runner shows the four-entry menu and navigates with arrow keys.
• With Mongo down, «check connection» reports the failure and the menu is still
  usable.
• «Load seed data» prints a TODO and the test proves no client method was called.
• Unit tests cover every operation function against a Mongo double.

F. Clean database — the destructive operation (US6)

• R47 (event): When «clean database» is chosen, the system shall first ask for an
  explicit confirmation that names the target database, before touching anything.
• R48 (ubiquitous): The confirmation prompt shall default to no, so proceeding
  requires a deliberate keystroke.
• R49 (state+event): While the confirmation has been accepted, the system shall call
  dropDatabase on the database resolved from the URI and report the outcome.
• R50 (unwanted): If the confirmation is declined, then the system shall perform no
  write of any kind — dropDatabase shall not be called — and shall return a cancelled
  marker.
• R51 (unwanted): If dropDatabase fails, then the system shall report the error
  and return to the menu, leaving the runner usable.

Acceptance criteria

• A unit test proves accepted confirmation ⇒ dropDatabase called exactly once.
• A unit test proves declined confirmation ⇒ no method called on the double, result
  marked cancelled.
• Manual check: cleaning the real local database actually empties it.

G. CI and declared gates (US8)

• R52 (event): When a pull request targeting main is opened or updated, GitHub
  Actions shall run a workflow that installs with pnpm (--frozen-lockfile, with the
  pnpm store cached) and then runs typecheck, format:check, test and build.
• R53 (unwanted): If any of those four commands exits non-zero, then the workflow
  shall fail — no continue-on-error, no step allowed to swallow a red gate.
• R54 (ubiquitous): The workflow shall take the Node version from .nvmrc and the
  pnpm version from the root packageManager field, so CI and local use the same
  versions.
• R55 (ubiquitous): harness.config.yml shall declare gates: as exactly
  typecheck, format:check, test, build, and shall leave merge.allow_no_checks
  at its default false.
• R56 (ubiquitous): The whole test suite shall be hermetic — no test shall require
  Docker, a live Mongo instance or network access.
• R57 (ubiquitous): README.md shall document the quickstart for a fresh clone:
  install, db:up / db:down / db:reset, dev, runner, and the gate commands.

Acceptance criteria

• The PR for this task shows a green GitHub Actions check with the four gate steps.
• A deliberately broken type (locally) turns the typecheck step red.
• harness.config.yml lists the four gates under gates:.

H. Definition of done — manual real-run verification

• R58 (event): When the implementation is signalled done, progress.md shall record
  the outcome of the manual real-run sequence, executed in this order: pnpm db:up →
  pnpm runner → «check connection» reports success → pnpm dev → the «Hola Mundo»
  page loads in a browser → pnpm db:down.
• R59 (ubiquitous): This manual sequence shall be treated as part of done; the
  hermetic suite does not cover it, and a green suite alone shall not be read as
  evidence that the infrastructure runs.

Acceptance criteria

• progress.md contains the six-step verification with its result.

Design

See .claude/state/tasks/1/spec/design.md.

Tasks

See .claude/state/tasks/1/spec/tasks.md.