@aas-dev/stack 0.0.0-stage → 0.1.1

package/templates/AGENTS.md

@@ -0,0 +1,147 @@
+# AGENTS.md
+
+This project uses `@aas-dev/stack`. The command is `aas`. The ideal is one way to do each thing, and `pnpm verify` is the score. A check that cannot run in this environment gets changed until it can. A check that passes while a bypass still works is too lax.
+
+`aas verify` is the gate. `pnpm verify` calls it. On success it prints nothing. On failure it prints `file:line` diagnostics.
+
+## The loop
+
+`aas verify` runs, in order:
+
+1. A drift check. `.cursor/hooks.json`, `.vite-hooks/pre-commit`, `AGENTS.md`, `.github/workflows/verify.yml`, `vite.config.ts`, and `tsconfig.json` must match the templates from `aas init` byte for byte. `pnpm-workspace.yaml` must carry the same pins. Extra `allowBuilds` keys are allowed on that file only. `aas sync` rewrites the managed files and keeps those extra keys.
+2. `varlock load`, when `.env.schema` is present, so the schema is valid.
+3. `vp fmt --check` (Oxfmt, through Vite+).
+4. `vp lint` (Oxlint, through Vite+, with the `aas` rules below).
+5. `vp pack` (tsdown, through Vite+) for each library.
+6. `effect-tsgo patch`, then `tsc --noEmit` with the `@effect/tsgo` language service.
+7. `vp test` (`@effect/vitest` on the Vitest that ships with Vite+).
+
+Vite+ does not replace the Effect typecheck. `vp check`'s type checker is tsgolint and does not run `@effect/language-service`. The patched `tsc` does.
+
+The Cursor `beforeShellExecution` hook, the Vite+ pre-commit hook, and GitHub Actions all call this same gate. The hook is `failClosed`. CI does not set `continue-on-error`.
+
+`NodeRuntime.runMain` is the process boundary. Everywhere else, stay inside Effect.
+
+`tsconfig.json` extends `@aas-dev/stack/tsconfig.base.json`, which sets `noEmit`. `tsc` typechecks. A library build is `vp pack`, not `tsc` emit.
+
+## Commands
+
+`aas init` writes the managed files, adds a `verify` script of `aas verify` when `package.json` has none, and runs `pnpm install` when `pnpm-lock.yaml` already exists so the lockfile picks up the template overrides. When `core.hooksPath` is already set, init prints that path and does not run `vp hooks enable`.
+
+`aas sync` rewrites the managed files from the templates.
+
+`aas explain` lists every rule. `aas explain <rule>` prints why that ban exists and the approved alternative. A rule id is `aas/no-throw` or `no-throw`.
+
+`aas doctor` checks the Node and pnpm pins, the hooks path, lockfile override freshness, the patched `tsc`, and managed-file drift. It prints each check. It exits non-zero when one fails, and the line says what to run.
+
+## Blessed patterns
+
+One pattern per concern. The lint rule is what makes the other patterns unavailable.
+
+### Errors
+
+Yield a `Schema.TaggedError`. Pass the brand parameter `@effect/tsgo` requires.
+
+```ts
+export class EmptyText extends Schema.TaggedError<EmptyText, { readonly brand: unique symbol }>()(
+  "EmptyText",
+  {},
+) {}
+
+yield * new EmptyText({})
+```
+
+`aas/no-throw`, `aas/no-try`, and `aas/no-error-class` reject `throw`, `try`, and `new Error` (including the other built-in error constructors).
+
+### Config
+
+Read values with `Config`. A value the project has to supply is declared in `.env.schema`, and that schema is the only place a literal default lives. Do not call `Config.withDefault`.
+
+A computed runtime fallback does not belong in `.env.schema` and does not read `process.env`. `Config.orElse` runs the next `Config` when the key is absent. `Config.succeed` inside that callback builds the value when it is needed:
+
+```ts
+import { homedir } from "node:os"
+import { Config } from "effect"
+
+export const dataDir = Config.String("DATA_DIR").pipe(
+  Config.orElse(() => Config.succeed(`${homedir()}/.aas`)),
+)
+```
+
+`aas/no-process-env` rejects `process.env`, `process["env"]`, and `process?.env`.
+
+Keep a string tuple without a type assertion:
+
+```ts
+const literals = <const Values extends readonly string[]>(...values: Values): Values => values
+
+export const AppEnv = Config.Literals(literals("development", "test", "production"), "APP_ENV")
+```
+
+### Services
+
+Extend `Context.Service` and provide a `Layer`.
+
+```ts
+export class AppConfig extends Context.Service<
+  AppConfig,
+  { readonly env: "development" | "test" | "production" }
+>()("aas/AppConfig") {
+  static readonly layer = Layer.effect(
+    AppConfig,
+    Effect.gen(function* () {
+      const env = yield* AppEnv
+      return AppConfig.of({ env })
+    }),
+  )
+}
+```
+
+`aas/no-plain-class` rejects a class whose superclass is not `Schema.TaggedError` or `Context.Service`. `aas/no-module-let` rejects module-scope `let` and `var`. A binding inside a function is fine. State that outlives a call belongs on a service.
+
+### IO
+
+Use Effect's `FileSystem`, `HttpClient`, `ChildProcess`, and `Console`. Stay inside Effect. Tests use `it.effect` instead of running the boundary.
+
+`aas/no-raw-io` rejects `node:fs`, `node:fs/promises`, `fs`, `node:child_process`, `child_process`, `node:http`, `http`, `node:https`, `https`, `require` of those modules, dynamic `import` of those modules, global `fetch`, and `console.log` / `error` / `warn` / `info` / `debug`.
+
+Effect 4.0.6 has no TCP or TLS client. `node:net`, `net`, `node:tls`, and `tls` are allowed only in a file whose name ends with `.adapter.ts`. That file is the Node entry for those sockets. `node:fs`, HTTP, child processes, `fetch`, and `console` stay banned there too. No command, flag, or comment grants the exception.
+
+`aas/no-effect-run` rejects `Effect.runPromise`, `Effect.runSync`, `Effect.runFork`, and `Effect.runPromiseExit`.
+
+### Tests
+
+```ts
+import { assert, describe, it } from "@effect/vitest"
+
+it.effect("counts code points", () =>
+  Effect.gen(function* () {
+    const counted = yield* countText("👋")
+    assert.strictEqual(counted.characters, 1)
+  }),
+)
+```
+
+`aas/effect-tests` rejects imports from `vitest` or `@vitest/*`, plain `it()` / `test()`, `it.skip` / `it.only` / `it.todo` / `it.skipIf` / `it.live`, `describe.only`, and the aliases `fit`, `fdescribe`, `ftest`, `xit`, `xdescribe`, `xtest`. `it.effect` (and `it.effect.each` / `it.effect.prop`) is the runner. `describe` without a focus or skip modifier is fine.
+
+Assert observable behavior. Do not mock the capability. A test that needs a process or the filesystem uses the Node `ChildProcess` and `FileSystem` layers and really runs them.
+
+### Types
+
+`aas/no-explicit-any` rejects `any`. `aas/no-type-assertion` rejects `as` and angle-bracket assertions, including `as const`. `aas/no-non-null-assertion` rejects `!`. An import alias (`import { readFile as read }`) is not a type assertion.
+
+External data is `unknown` until a `Schema` decodes it. Discriminate unions and exhaust them. Brand a value by parsing it. A `Schema.TaggedError` passes `{ readonly brand: unique symbol }` as its brand parameter. `@effect/tsgo` errors on leaked requirements, floating effects, global `Date` / `fetch` / `console`, Node built-in imports, and `instanceof` on a schema type (`Schema.is` is the check). `unstableApiUsage` is off because the Effect v4 APIs this stack requires are still marked unstable.
+
+## Comments
+
+`aas/no-comments` rejects a line comment, a block comment, and a JSDoc comment. The diagnostic tells the author to use clearer names or docs. A shebang line is not a comment. `/// <reference>` is a line comment, and `aas/no-bypass-comment` does not list it. `@ts-ignore`, `@ts-expect-error`, and `@ts-nocheck` are already `aas/no-bypass-comment` hits; `aas/no-comments` reports those comments as well. `@ts-check` is not a bypass marker.
+
+## Bypasses the fence catches
+
+`aas/no-bypass-comment` rejects comments that contain `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, `eslint-disable`, `eslint-enable`, `oxlint-disable`, or `oxlint-enable`. A disable comment can silence the statement it covers, so the fence test also scans source text. A block comment that hides every oxlint diagnostic still fails that scan. The fixtures in `packages/fence/fixtures` are ignored by the normal lint so they can exist; `packages/fence` runs `vp lint` on them and asserts each rule id and count. Blessed fixtures must produce zero diagnostics.
+
+Git cannot delete `--no-verify`. The agent hook rejects it anyway, including inside `bash -c "..."`. It also rejects a short option cluster that contains `n` on `commit`, `merge`, `rebase`, `cherry-pick`, `am`, and `pull` (`-n`, `-nm`, `-an`), and it rejects `LEFTHOOK=0`, `HUSKY=0`, `VP_GIT_HOOKS=0`, `VITE_GIT_HOOKS=0`, `vp hooks disable`, and `vp.hooks.disabled`. `git log -n 5`, `git push -n`, `git commit -m "hello -n"`, `vp hooks enable`, and `vp hooks status` stay allowed: `-n` is only special on the subcommands above, and a quoted message is not a flag. Unreadable hook input crashes the process, and `failClosed` turns that crash into a deny. The Vite+ pre-commit hook runs `pnpm exec aas verify` for a human commit. CI runs the same command even if the hook was skipped.
+
+## Ideal
+
+One capability, one error style, one config source, one service style, one IO style, one test style. Blank text fails with a `Schema.TaggedError`. A counted value reports Unicode code points, whitespace-separated words, and `\n`-separated lines. `Config` and `Context.Service` are the config and service shapes. Climb toward more capabilities in that shape. Do not add a second pattern because the first one is inconvenient.

package/templates/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "node ./node_modules/@aas-dev/stack/dist/cursor-hook.js",
+        "failClosed": true
+      }
+    ]
+  }
+}

package/templates/pnpm-workspace.yaml

@@ -0,0 +1,23 @@
+packages:
+  - "packages/*"
+
+verifyDepsBeforeRun: error
+
+# Exact versions are the pin. The release-age gate would refuse the Effect 4
+# and oxlint versions this stack just chose, so it stays off.
+minimumReleaseAge: 0
+
+overrides:
+  "vite@*": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+  "vitest@*": "5.0.5"
+
+peerDependencyRules:
+  allowAny:
+    - vite
+    - vitest
+  allowedVersions:
+    vite: "*"
+    vitest: "*"
+
+allowBuilds:
+  esbuild: true

package/templates/pre-commit

@@ -0,0 +1,3 @@
+#!/bin/sh
+# The commit hook is the same gate as CI. Skipping the hook does not skip CI.
+pnpm exec aas verify

package/templates/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@aas-dev/stack/tsconfig.base.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["dist", "node_modules", "vendor", "packages/fence/fixtures"]
+}

package/templates/verify.yml

@@ -0,0 +1,20 @@
+name: verify
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11.3.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec aas verify

package/templates/vite.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "@aas-dev/stack/config"
+
+export default defineConfig()

package/tsconfig.base.json

@@ -0,0 +1,71 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "moduleDetection": "force",
+    "esModuleInterop": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true,
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "namespaceImportPackages": ["effect"],
+        "diagnosticSeverity": {
+          "anyUnknownInErrorContext": "error",
+          "unsafeEffectTypeAssertion": "error",
+          "floatingEffect": "error",
+          "floatingEffectInVitest": "error",
+          "missingEffectContext": "error",
+          "missingEffectError": "error",
+          "missingLayerContext": "error",
+          "leakingRequirements": "error",
+          "globalErrorInEffectCatch": "error",
+          "globalErrorInEffectFailure": "error",
+          "unknownInEffectCatch": "error",
+          "tryCatchInEffectGen": "error",
+          "returnEffectInGen": "error",
+          "runEffectInsideEffect": "error",
+          "schemaSyncInEffect": "error",
+          "instanceOfSchema": "error",
+          "newPromise": "error",
+          "asyncFunction": "error",
+          "globalConsole": "error",
+          "globalConsoleInEffect": "error",
+          "globalDate": "error",
+          "globalDateInEffect": "error",
+          "globalFetch": "error",
+          "globalFetchInEffect": "error",
+          "globalRandom": "error",
+          "globalRandomInEffect": "error",
+          "globalTimers": "error",
+          "globalTimersInEffect": "error",
+          "cryptoRandomUUID": "error",
+          "cryptoRandomUUIDInEffect": "error",
+          "nodeBuiltinImport": "error",
+          "strictEffectProvide": "off",
+          "lazyEffect": "off",
+          "strictBooleanExpressions": "off",
+          "unstableApiUsage": "off"
+        }
+      }
+    ]
+  }
+}