@aas-dev/stack 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Aas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# `@aas-dev/stack`
+
+The `aas` command. One toolchain: Vite+ (`vp`) for lint, format, test, and library build, and `@effect/tsgo` for the typecheck. The package version in this tree is `0.1.1`.
+
+Node `>=22.18` and pnpm `11.3.0`.
+
+## Install
+
+Put `pnpm-workspace.yaml` on disk before the first `pnpm install`. pnpm reads the overrides and `allowBuilds` while it builds the graph. `esbuild: true` lets the Vite+ install script run. Without it, pnpm `11.3.0` stops with `ERR_PNPM_IGNORED_BUILDS`. Extra `allowBuilds` keys are yours; `aas verify` does not call that drift.
+
+```yaml
+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
+```
+
+The `vite` override aliases Vite to `@voidzero-dev/vite-plus-core`. That package's own version is `1.4.0`, which is outside Vitest's `vite@^6 || ^7 || ^8` peer range. `peerDependencyRules` is what makes pnpm treat the aliased package as satisfying that peer. `allowAny` and `allowedVersions: "*"` are the pair Vite+ writes for this override.
+
+`minimumReleaseAge: 0` lets pnpm fetch the Effect and Vite+ versions this stack pins. A project with no `packages/` directory still installs: the glob matches nothing and the root package is the project.
+
+Depend on `effect`, `@effect/vitest`, and `@types/node` as well. The project imports them.
+
+```sh
+pnpm add -D @aas-dev/stack@0.1.1 effect@4.0.6 @effect/vitest@4.0.6 @types/node@22.20.5
+```
+
+From a packed tarball the file name is `aas-dev-stack-0.1.1.tgz`:
+
+```json
+{
+  "scripts": {
+    "verify": "aas verify"
+  },
+  "devDependencies": {
+    "@aas-dev/stack": "file:./aas-dev-stack-0.1.1.tgz",
+    "@effect/vitest": "4.0.6",
+    "@types/node": "22.20.5",
+    "effect": "4.0.6"
+  }
+}
+```
+
+## Init, the second install, verify
+
+```sh
+pnpm exec aas init
+pnpm exec aas verify
+```
+
+`aas init` writes the managed files and adds `"verify": "aas verify"` when that script is missing. When `pnpm-lock.yaml` already exists, init deletes `node_modules/.pnpm-workspace-state-v1.json` and runs `pnpm install`, so the lockfile overrides match the template. A second `pnpm install` that only prints "Already up to date" leaves those overrides stale, and the next `pnpm exec` fails with `ERR_PNPM_VERIFY_DEPS_BEFORE_RUN`.
+
+If `pnpm exec` is already failing with that error, run `pnpm install`. When the workspace file changed and install does not refresh, run `node node_modules/@aas-dev/stack/bin/aas.js init`.
+
+When `core.hooksPath` is already set, init prints the path and skips `vp hooks enable`. It does not take that path.
+
+`aas verify` prints nothing when it passes. A failure is `file:line: reason`.
+
+`aas explain` lists every ban and the approved alternative. `aas explain no-raw-io` is one rule. `aas doctor` checks the Node and pnpm pins, the hooks path, lockfile overrides, the patched `tsc`, and drift. It exits non-zero when a check fails.
+
+## Managed files
+
+| File                           | Role                                                                  |
+| ------------------------------ | --------------------------------------------------------------------- |
+| `.cursor/hooks.json`           | Cursor `beforeShellExecution` hook, `failClosed`                      |
+| `.vite-hooks/pre-commit`       | Runs `pnpm exec aas verify`                                           |
+| `pnpm-workspace.yaml`          | Pins, overrides, peer rules, `allowBuilds`. Extra build keys are kept |
+| `AGENTS.md`                    | The patterns the rules enforce                                        |
+| `.github/workflows/verify.yml` | CI runs `pnpm exec aas verify`                                        |
+| `vite.config.ts`               | `defineConfig()` from `@aas-dev/stack/config`                         |
+| `tsconfig.json`                | Extends `@aas-dev/stack/tsconfig.base.json`                           |
+
+`tsconfig.base.json` sets `noEmit`. `aas verify` runs `effect-tsgo patch` and then `tsc --noEmit`. That is the typecheck. Library output is `vp pack`, not `tsc`.
+
+`aas sync` rewrites the managed files and keeps `allowBuilds` keys that are not in the template.
+
+## Patterns the rules keep
+
+Errors are a `Schema.TaggedError`. Config is `Config` from `.env.schema`, or `Config.orElse(() => Config.succeed(...))` for a computed fallback such as a homedir path. `process.env` stays banned. Services extend `Context.Service`. IO goes through Effect, except `node:net` and `node:tls`, which are allowed only in a file named `*.adapter.ts`. Tests use `it.effect` from `@effect/vitest`. The full text is the generated `AGENTS.md`. `aas explain` prints the same alternatives.

package/dist/doctor.d.ts

@@ -0,0 +1,5 @@
+import { Effect, FileSystem } from "effect";
+export declare const doctor: (cwd: string) => Effect.Effect<{
+  ok: boolean;
+  text: string;
+}, import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem>;

package/dist/doctor.js

@@ -0,0 +1,162 @@
+import { findBin, runTool, succeeded } from "./run.js";
+import { sameScalars, scalarEntries } from "./workspace.js";
+import { driftLines } from "./verify.js";
+import { Effect, FileSystem, Result, Schema } from "effect";
+// src/doctor.ts
+const Engines = Schema.Struct({
+	node: Schema.String,
+	pnpm: Schema.String
+});
+const Manifest = Schema.Struct({ engines: Engines });
+const StateSettings = Schema.Struct({ overrides: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)) });
+const WorkspaceState = Schema.Struct({ settings: Schema.optionalKey(StateSettings) });
+const decodeManifest = Schema.decodeResult(Schema.fromJsonString(Manifest));
+const decodeState = Schema.decodeResult(Schema.fromJsonString(WorkspaceState));
+const nodeEngine = /^>=(\d+)\.(\d+)\.(\d+)$/u;
+const exactVersion = /^v?(\d+)\.(\d+)\.(\d+)$/u;
+const versionOf = (text) => {
+	const matched = exactVersion.exec(text.trim());
+	const major = matched?.[1];
+	const minor = matched?.[2];
+	const patch = matched?.[3];
+	if (major === void 0 || minor === void 0 || patch === void 0) return;
+	return {
+		major: Number(major),
+		minor: Number(minor),
+		patch: Number(patch)
+	};
+};
+const atLeast = (actual, required) => {
+	if (actual.major !== required.major) return actual.major > required.major;
+	if (actual.minor !== required.minor) return actual.minor > required.minor;
+	return actual.patch >= required.patch;
+};
+const pair = (key, value) => [key, value];
+const recordPairs = (record) => {
+	const entries = [];
+	for (const [key, value] of Object.entries(record)) entries.push(pair(key, value));
+	return entries;
+};
+const typescriptPackage = (start) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const segments = start.split("/");
+	let index = segments.length;
+	while (index > 1) {
+		index -= 1;
+		const candidate = `${segments.slice(0, index).join("/")}/node_modules/typescript`;
+		if (yield* fs.exists(candidate)) return candidate;
+	}
+	return "";
+});
+const nativeBinary = (typescriptDir) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const name = `typescript-${process.platform}-${process.arch}`;
+	const binaryName = process.platform === "win32" ? "tsc.exe" : "tsc";
+	const parent = typescriptDir.split("/").slice(0, -1).join("/");
+	const links = [`${typescriptDir}/node_modules/@typescript/${name}`, `${parent}/@typescript/${name}`];
+	for (const link of links) if (yield* fs.exists(link)) return `${yield* fs.realPath(link)}/lib/${binaryName}`;
+	return "";
+});
+const patchedBinary = (tscBin) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const at = tscBin.lastIndexOf("/node_modules/.bin/");
+	if (at <= 0) return "";
+	const linked = yield* typescriptPackage(tscBin.slice(0, at));
+	if (linked === "") return "";
+	return yield* nativeBinary(yield* fs.realPath(linked));
+});
+const enginesCheck = () => Effect.gen(function* () {
+	const text = yield* (yield* FileSystem.FileSystem).readFileString(`${import.meta.dirname}/../package.json`);
+	const decoded = decodeManifest(text);
+	if (Result.isFailure(decoded)) return ["package.json:1: engines are missing"];
+	const nodeRequired = nodeEngine.exec(decoded.success.engines.node);
+	const nodeMajor = nodeRequired?.[1];
+	const nodeMinor = nodeRequired?.[2];
+	const nodePatch = nodeRequired?.[3];
+	const nodeActual = versionOf(process.version);
+	const lines = [];
+	if (nodeMajor === void 0 || nodeMinor === void 0 || nodePatch === void 0 || nodeActual === void 0 || !atLeast(nodeActual, {
+		major: Number(nodeMajor),
+		minor: Number(nodeMinor),
+		patch: Number(nodePatch)
+	})) lines.push(`node:1: ${process.version} does not satisfy ${decoded.success.engines.node}; install Node ${decoded.success.engines.node}`);
+	else lines.push(`node: ${process.version} matches ${decoded.success.engines.node}`);
+	const pnpm = yield* runTool({
+		bin: "pnpm",
+		args: ["--version"],
+		cwd: import.meta.dirname
+	});
+	const pnpmActual = succeeded(pnpm.exitCode) ? versionOf(pnpm.stdout) : void 0;
+	const pnpmRequired = versionOf(decoded.success.engines.pnpm);
+	if (pnpmActual === void 0 || pnpmRequired === void 0 || pnpmActual.major !== pnpmRequired.major || pnpmActual.minor !== pnpmRequired.minor || pnpmActual.patch !== pnpmRequired.patch) lines.push(`pnpm:1: ${pnpm.stdout.trim() || "missing"} does not match ${decoded.success.engines.pnpm}; install pnpm ${decoded.success.engines.pnpm}`);
+	else lines.push(`pnpm: ${pnpm.stdout.trim()} matches ${decoded.success.engines.pnpm}`);
+	return lines;
+});
+const hooksCheck = (cwd) => Effect.gen(function* () {
+	const git = yield* runTool({
+		bin: "git",
+		args: ["rev-parse", "--git-dir"],
+		cwd
+	});
+	if (!succeeded(git.exitCode)) return ["hooks: not a git repository; vp hooks enable skipped"];
+	const hooksPath = yield* runTool({
+		bin: "git",
+		args: [
+			"config",
+			"--get",
+			"core.hooksPath"
+		],
+		cwd
+	});
+	if (!succeeded(hooksPath.exitCode)) return ["git:1: core.hooksPath is unset; run pnpm exec vp hooks enable"];
+	const path = hooksPath.stdout.trim();
+	if (path === ".vite-hooks" || path === `${cwd}/.vite-hooks` || path.endsWith("/.vite-hooks")) return [`hooks: core.hooksPath is ${path}`];
+	return [`hooks: core.hooksPath is ${path}; vp hooks enable skipped`];
+});
+const lockCheck = (cwd) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const workspacePath = `${cwd}/pnpm-workspace.yaml`;
+	if (!(yield* fs.exists(workspacePath))) return ["pnpm-workspace.yaml:1: missing; run aas init"];
+	const workspace = yield* fs.readFileString(workspacePath);
+	const expected = scalarEntries(workspace, "overrides");
+	if (expected === void 0) return ["pnpm-workspace.yaml:1: overrides are missing; run aas sync"];
+	if (!(yield* fs.exists(`${cwd}/pnpm-lock.yaml`))) return ["pnpm-lock.yaml:1: missing lockfile; run pnpm install"];
+	const lock = yield* fs.readFileString(`${cwd}/pnpm-lock.yaml`);
+	const locked = scalarEntries(lock, "overrides");
+	if (locked === void 0 || !sameScalars(expected, locked)) return ["pnpm-lock.yaml:1: overrides are stale; run pnpm install"];
+	if (!(yield* fs.exists(`${cwd}/node_modules`))) return ["node_modules:1: missing; run pnpm install"];
+	const statePath = `${cwd}/node_modules/.pnpm-workspace-state-v1.json`;
+	if (!(yield* fs.exists(statePath))) return ["node_modules/.pnpm-workspace-state-v1.json:1: missing install state; run pnpm install"];
+	const stateText = yield* fs.readFileString(statePath);
+	const state = decodeState(stateText);
+	if (Result.isFailure(state)) return ["node_modules/.pnpm-workspace-state-v1.json:1: unreadable install state; run pnpm install"];
+	const overrides = state.success.settings?.overrides;
+	const installed = overrides === void 0 ? [] : recordPairs(overrides);
+	if (!sameScalars(expected, installed)) return ["node_modules/.pnpm-workspace-state-v1.json:1: overrides are stale; run pnpm install"];
+	return ["lockfile: overrides match pnpm-workspace.yaml"];
+});
+const tscCheck = () => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const tsc = yield* findBin("tsc").pipe(Effect.catchTag("CommandFailed", () => Effect.succeed("")));
+	if (tsc === "") return ["tsc:1: missing executable tsc"];
+	const binary = yield* patchedBinary(tsc);
+	if (binary === "" || !(yield* fs.exists(`${binary}.original`))) return ["tsc:1: TypeScript is not patched with @effect/tsgo; run pnpm exec effect-tsgo patch"];
+	return ["tsc: patched"];
+});
+const failed = (line) => /^\S+:\d+:/u.test(line);
+const doctor = (cwd) => Effect.gen(function* () {
+	const lines = [
+		...yield* enginesCheck(),
+		...yield* hooksCheck(cwd),
+		...yield* lockCheck(cwd),
+		...yield* tscCheck()
+	];
+	const drift = yield* driftLines(cwd);
+	if (drift.length === 0) lines.push("drift: managed files match the templates");
+	else lines.push(...drift);
+	return {
+		ok: lines.every((line) => !failed(line)),
+		text: lines.join("\n")
+	};
+});
+export { doctor };

package/dist/explain.d.ts

@@ -0,0 +1,4 @@
+import { CommandFailed } from "./errors.js";
+import { Effect } from "effect";
+export declare const explanation: (names: ReadonlyArray<string>, rule: string | undefined) => string;
+export declare const explain: (rule: string | undefined) => Effect.Effect<undefined, CommandFailed | import("effect/PlatformError").PlatformError, import("effect/Stdio").Stdio>;

package/dist/explain.js

@@ -0,0 +1,48 @@
+import { CommandFailed } from "./errors.js";
+import { writeStdout } from "./run.js";
+import { ruleNames } from "./plugin/aas.js";
+import { Effect } from "effect";
+// src/explain.ts
+const texts = {
+	"effect-tests": "Imports from vitest and focused, skipped, or todo tests hide failures from the gate. Import assert, describe, and it from @effect/vitest and run it.effect.",
+	"no-bypass-comment": "A directive comment can silence the diagnostic it sits on. Delete @ts-ignore, @ts-expect-error, @ts-nocheck, eslint-disable, eslint-enable, oxlint-disable, and oxlint-enable. Fix the code.",
+	"no-comments": "Comments rot next to the code they describe. Use a clearer name, or write the explanation in AGENTS.md, an ADR, or the README. A shebang is not a comment.",
+	"no-effect-run": "Effect.runPromise, Effect.runSync, Effect.runFork, and Effect.runPromiseExit leave the Effect channel. Stay inside Effect. Tests use it.effect. NodeRuntime.runMain is the process boundary.",
+	"no-error-class": "new Error and the other built-in error constructors are untyped failures. Define a Schema.TaggedError and pass the brand parameter.",
+	"no-explicit-any": "any turns the checker off. Keep the value unknown until a Schema decodes it.",
+	"no-module-let": "Module-scope let and var are shared mutable state. Keep that state on a Context.Service. A binding inside a function is fine.",
+	"no-non-null-assertion": "A non-null assertion hides a missing value. Narrow the value, or decode it with Schema.",
+	"no-plain-class": "A plain class is a second object style. Extend Schema.TaggedError or Context.Service.",
+	"no-process-env": "process.env, process[\"env\"], and process?.env skip the config boundary. Declare a supplied value in .env.schema and read it with Config. A computed fallback, such as a homedir path, is Config.String(key).pipe(Config.orElse(() => Config.succeed(value))). That fallback is not Config.withDefault, and the key does not have to be in .env.schema. process.env stays banned.",
+	"no-raw-io": "Node fs, http, https, child_process, global fetch, and console bypass Effect's services. Use FileSystem, HttpClient, ChildProcess, and Console. node:net, net, node:tls, and tls have no Effect client in Effect 4.0.6, so those four specifiers are allowed only in a file whose name ends with .adapter.ts. That file is the Node TCP and TLS entry. The same file still bans every other raw import. No command grants an exception.",
+	"no-throw": "throw leaves the Effect channel. Yield a Schema.TaggedError.",
+	"no-try": "try and catch leave the Effect channel. Failures stay on the Effect error channel.",
+	"no-type-assertion": "A type assertion, including as const and an angle-bracket assertion, invents a type. Parse with Schema, or keep a tuple with a const type parameter."
+};
+const formatRule = (name) => {
+	const text = texts[name];
+	if (text === void 0) return "";
+	return `aas/${name}\n${text}`;
+};
+const explanation = (names, rule) => {
+	if (rule === void 0 || rule === "") {
+		const blocks = [];
+		for (const name of names) {
+			const block = formatRule(name);
+			if (block === "") return "";
+			blocks.push(block);
+		}
+		return blocks.join("\n\n");
+	}
+	const name = rule.startsWith("aas/") ? rule.slice(4) : rule;
+	return formatRule(name);
+};
+const explain = (rule) => Effect.gen(function* () {
+	const text = explanation(ruleNames, rule);
+	if (text === "") {
+		const line = rule === void 0 || rule === "" ? "explain:1: missing text for a rule" : `explain:1: unknown rule ${rule}`;
+		return yield* new CommandFailed({ lines: [line] });
+	}
+	yield* writeStdout(text);
+});
+export { explain, explanation };

package/dist/package-script.d.ts

@@ -0,0 +1,3 @@
+import { CommandFailed } from "./errors.js";
+import { Effect, FileSystem } from "effect";
+export declare const ensureVerifyScript: (cwd: string) => Effect.Effect<undefined, CommandFailed | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem>;

package/dist/package-script.js

@@ -0,0 +1,42 @@
+import { CommandFailed } from "./errors.js";
+import { findBin, runTool, succeeded } from "./run.js";
+import { Effect, FileSystem, Result, Schema } from "effect";
+// src/package-script.ts
+const Manifest = Schema.Record(Schema.String, Schema.Unknown);
+const Scripts = Schema.Record(Schema.String, Schema.String);
+const decodeManifest = Schema.decodeResult(Schema.fromJsonString(Manifest));
+const decodeScripts = Schema.decodeUnknownResult(Scripts);
+const verifyScript = "aas verify";
+const readScripts = (value) => Effect.gen(function* () {
+	if (value === void 0) return {};
+	const parsed = decodeScripts(value);
+	if (Result.isFailure(parsed)) return yield* new CommandFailed({ lines: ["package.json:1: scripts must be a map of strings"] });
+	return parsed.success;
+});
+const ensureVerifyScript = (cwd) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = `${cwd}/package.json`;
+	if (!(yield* fs.exists(path))) return;
+	const text = yield* fs.readFileString(path);
+	const decoded = decodeManifest(text);
+	if (Result.isFailure(decoded)) return yield* new CommandFailed({ lines: ["package.json:1: package.json is not an object"] });
+	const manifest = decoded.success;
+	const scripts = yield* readScripts(manifest["scripts"]);
+	if (scripts["verify"] !== void 0) return;
+	const next = {
+		...manifest,
+		scripts: {
+			...scripts,
+			verify: verifyScript
+		}
+	};
+	yield* fs.writeFileString(path, `${JSON.stringify(next, null, 2)}\n`);
+	const vp = yield* findBin("vp");
+	const formatted = yield* runTool({
+		bin: vp,
+		args: ["fmt", "package.json"],
+		cwd
+	});
+	if (!succeeded(formatted.exitCode)) return yield* new CommandFailed({ lines: ["package.json:1: format"] });
+});
+export { ensureVerifyScript };

package/dist/plugin/aas.js

@@ -0,0 +1,379 @@
+// plugin/aas.mjs
+const markers = [
+	"@ts-ignore",
+	"@ts-expect-error",
+	"@ts-nocheck",
+	"eslint-disable",
+	"eslint-enable",
+	"oxlint-disable",
+	"oxlint-enable"
+];
+const errorNames = /* @__PURE__ */ new Set([
+	"Error",
+	"AggregateError",
+	"EvalError",
+	"RangeError",
+	"ReferenceError",
+	"SyntaxError",
+	"TypeError",
+	"URIError"
+]);
+const rawSpecifiers = /* @__PURE__ */ new Set([
+	"child_process",
+	"fs",
+	"http",
+	"https",
+	"node:child_process",
+	"node:fs",
+	"node:fs/promises",
+	"node:http",
+	"node:https"
+]);
+const socketSpecifiers = /* @__PURE__ */ new Set([
+	"net",
+	"node:net",
+	"node:tls",
+	"tls"
+]);
+const consoleMethods = /* @__PURE__ */ new Set([
+	"debug",
+	"error",
+	"info",
+	"log",
+	"warn"
+]);
+const effectRunMethods = /* @__PURE__ */ new Set([
+	"runFork",
+	"runPromise",
+	"runPromiseExit",
+	"runSync"
+]);
+const bannedTestMembers = /* @__PURE__ */ new Set([
+	"only",
+	"skip",
+	"skipIf",
+	"todo"
+]);
+const testAliases = /* @__PURE__ */ new Set([
+	"fdescribe",
+	"fit",
+	"ftest",
+	"xdescribe",
+	"xit",
+	"xtest"
+]);
+const report = (context, node, message) => {
+	context.report({
+		node,
+		message
+	});
+};
+const literalName = (property, computed) => {
+	if (!computed && property.type === "Identifier") return property.name;
+	if (computed && (property.type === "Literal" || property.type === "StringLiteral") && typeof property.value === "string") return property.value;
+	return "";
+};
+const isProcessEnv = (node) => {
+	if (node.type !== "MemberExpression") return false;
+	return node.object.type === "Identifier" && node.object.name === "process" && literalName(node.property, node.computed) === "env";
+};
+const hasName = (node, name) => {
+	if (node === null || node === void 0 || typeof node !== "object") return false;
+	if (node.type === "Identifier" && node.name === name) return true;
+	return hasName(node.callee, name) || hasName(node.object, name) || hasName(node.property, name) || hasName(node.expression, name);
+};
+const blessedSuper = (node) => hasName(node, "TaggedError") || hasName(node, "Service");
+const specifier = (node) => {
+	if (node === null || node === void 0) return "";
+	if ((node.type === "Literal" || node.type === "StringLiteral") && typeof node.value === "string") return node.value;
+	return "";
+};
+const chainParts = (callee) => {
+	const parts = [];
+	let current = callee;
+	while (current.type === "MemberExpression" || current.type === "ChainExpression") {
+		if (current.type === "ChainExpression") {
+			current = current.expression;
+			continue;
+		}
+		if (current.computed || current.property.type !== "Identifier") return [];
+		parts.push(current.property.name);
+		current = current.object;
+	}
+	if (current.type !== "Identifier") return [];
+	parts.push(current.name);
+	parts.reverse();
+	return parts;
+};
+const isItEffect = (parts) => {
+	if (parts[0] !== "it" || parts[1] !== "effect") return false;
+	let index = 2;
+	while (index < parts.length) {
+		const part = parts[index];
+		if (part !== void 0 && bannedTestMembers.has(part)) return false;
+		index += 1;
+	}
+	return true;
+};
+const flagModuleBinding = (context, statement) => {
+	if (statement === null || statement === void 0) return;
+	if (statement.type === "VariableDeclaration" && statement.kind !== "const") report(context, statement, "module-scope let and var are banned; keep state in a Context.Service");
+	const binding = statement.init ?? statement.left;
+	if ((statement.type === "ForStatement" || statement.type === "ForInStatement" || statement.type === "ForOfStatement") && binding !== null && binding !== void 0 && binding.type === "VariableDeclaration" && binding.kind !== "const") report(context, binding, "module-scope let and var are banned; keep state in a Context.Service");
+};
+const noThrow = {
+	meta: { type: "problem" },
+	create(context) {
+		return { ThrowStatement(node) {
+			report(context, node, "throw is banned; yield a Schema.TaggedError");
+		} };
+	}
+};
+const noTry = {
+	meta: { type: "problem" },
+	create(context) {
+		return { TryStatement(node) {
+			report(context, node, "try is banned; failures stay on the Effect channel");
+		} };
+	}
+};
+const noErrorClass = {
+	meta: { type: "problem" },
+	create(context) {
+		return { NewExpression(node) {
+			const callee = node.callee;
+			const name = callee.type === "Identifier" ? callee.name : callee.type === "MemberExpression" ? literalName(callee.property, callee.computed) : "";
+			if (errorNames.has(name)) report(context, node, "new Error is banned; define a Schema.TaggedError");
+		} };
+	}
+};
+const noProcessEnv = {
+	meta: { type: "problem" },
+	create(context) {
+		return { MemberExpression(node) {
+			if (isProcessEnv(node)) report(context, node, "process.env is banned; declare the variable in .env.schema and read it with Config");
+		} };
+	}
+};
+const noTypeAssertion = {
+	meta: { type: "problem" },
+	create(context) {
+		return {
+			TSAsExpression(node) {
+				report(context, node, "type assertions are banned, including as const; parse with Schema or use a const type parameter");
+			},
+			TSTypeAssertion(node) {
+				report(context, node, "angle-bracket assertions are banned; parse with Schema or use a const type parameter");
+			}
+		};
+	}
+};
+const noExplicitAny = {
+	meta: { type: "problem" },
+	create(context) {
+		return { TSAnyKeyword(node) {
+			report(context, node, "any is banned; use unknown and decode it with Schema");
+		} };
+	}
+};
+const noNonNullAssertion = {
+	meta: { type: "problem" },
+	create(context) {
+		return { TSNonNullExpression(node) {
+			report(context, node, "non-null assertions are banned; narrow the value or decode it with Schema");
+		} };
+	}
+};
+const textOf = (context) => {
+	const source = context.sourceCode;
+	if (typeof source.text === "string") return source.text;
+	if (typeof source.getText === "function") return source.getText();
+	return "";
+};
+const commentStart = (comment) => {
+	const range = comment.range;
+	if (Array.isArray(range)) {
+		const start = range[0];
+		return typeof start === "number" ? start : -1;
+	}
+	if (range !== null && range !== void 0 && typeof range.start === "number") return range.start;
+	if (typeof comment.start === "number") return comment.start;
+	return -1;
+};
+const isShebang = (comment, text) => {
+	if (comment.type === "Shebang" || comment.type === "Hashbang") return true;
+	return text.startsWith("#!") && commentStart(comment) === 0;
+};
+const noComments = {
+	meta: { type: "problem" },
+	create(context) {
+		const text = textOf(context);
+		return { Program(node) {
+			for (const comment of context.sourceCode.getAllComments()) {
+				if (isShebang(comment, text)) continue;
+				const message = "comments are banned; use clearer names or docs";
+				if (comment.loc === void 0 || comment.loc === null) report(context, node, message);
+				else context.report({
+					loc: comment.loc,
+					message
+				});
+			}
+		} };
+	}
+};
+const noBypassComment = {
+	meta: { type: "problem" },
+	create(context) {
+		return { Program(node) {
+			for (const comment of context.sourceCode.getAllComments()) {
+				let matched = "";
+				for (const marker of markers) if (comment.value.includes(marker)) {
+					matched = marker;
+					break;
+				}
+				if (matched === "") continue;
+				const message = `directive comments are banned (${matched})`;
+				if (comment.loc === void 0 || comment.loc === null) report(context, node, message);
+				else context.report({
+					loc: comment.loc,
+					message
+				});
+			}
+		} };
+	}
+};
+const effectTests = {
+	meta: { type: "problem" },
+	create(context) {
+		const filename = typeof context.filename === "string" ? context.filename : "";
+		const isTest = filename.endsWith(".test.ts");
+		return {
+			ImportDeclaration(node) {
+				const source = specifier(node.source);
+				if (source === "vitest/config") {
+					if (!filename.endsWith("/vitest.config.ts") && !filename.endsWith("\\vitest.config.ts")) report(context, node, "import tests from @effect/vitest");
+					return;
+				}
+				if (source === "vitest" || source.startsWith("vitest/") || source.startsWith("@vitest/")) report(context, node, "import tests from @effect/vitest");
+			},
+			CallExpression(node) {
+				if (!isTest) return;
+				const parts = chainParts(node.callee);
+				const root = parts[0];
+				if (root === void 0) {
+					if (node.callee.type === "Identifier" && (node.callee.name === "it" || node.callee.name === "test" || testAliases.has(node.callee.name))) report(context, node, "tests use it.effect from @effect/vitest");
+					return;
+				}
+				if (isItEffect(parts)) return;
+				if (root === "it" || root === "test" || testAliases.has(root)) {
+					report(context, node, "tests use it.effect from @effect/vitest");
+					return;
+				}
+				if (root === "describe") {
+					let index = 1;
+					while (index < parts.length) {
+						const part = parts[index];
+						if (part !== void 0 && bannedTestMembers.has(part)) {
+							report(context, node, "skipped, focused, and todo tests are banned");
+							return;
+						}
+						index += 1;
+					}
+				}
+			}
+		};
+	}
+};
+const isAdapterFile = (context) => {
+	return (typeof context.filename === "string" ? context.filename : "").endsWith(".adapter.ts");
+};
+const rawMessage = (source) => {
+	if (socketSpecifiers.has(source)) return "node:net and node:tls belong in a .adapter.ts file; other raw IO stays banned";
+	return "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess";
+};
+const bannedRaw = (context, node, source) => {
+	if (socketSpecifiers.has(source)) {
+		if (isAdapterFile(context)) return;
+		report(context, node, rawMessage(source));
+		return;
+	}
+	if (rawSpecifiers.has(source)) report(context, node, rawMessage(source));
+};
+const ruleNames = Object.keys({
+	"effect-tests": effectTests,
+	"no-bypass-comment": noBypassComment,
+	"no-comments": noComments,
+	"no-effect-run": {
+		meta: { type: "problem" },
+		create(context) {
+			return { CallExpression(node) {
+				const callee = node.callee;
+				if (callee.type !== "MemberExpression") return;
+				if (callee.object.type === "Identifier" && callee.object.name === "Effect" && effectRunMethods.has(literalName(callee.property, callee.computed))) report(context, node, "Effect.run* is banned; stay inside Effect and use it.effect in tests");
+			} };
+		}
+	},
+	"no-error-class": noErrorClass,
+	"no-explicit-any": noExplicitAny,
+	"no-module-let": {
+		meta: { type: "problem" },
+		create(context) {
+			return { Program(node) {
+				for (const statement of node.body) {
+					const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+					flagModuleBinding(context, declaration);
+				}
+			} };
+		}
+	},
+	"no-non-null-assertion": noNonNullAssertion,
+	"no-plain-class": {
+		meta: { type: "problem" },
+		create(context) {
+			return {
+				ClassDeclaration(node) {
+					if (!blessedSuper(node.superClass)) report(context, node, "plain classes are banned; extend Schema.TaggedError or Context.Service");
+				},
+				ClassExpression(node) {
+					if (!blessedSuper(node.superClass)) report(context, node, "plain classes are banned; extend Schema.TaggedError or Context.Service");
+				}
+			};
+		}
+	},
+	"no-process-env": noProcessEnv,
+	"no-raw-io": {
+		meta: { type: "problem" },
+		create(context) {
+			return {
+				ImportDeclaration(node) {
+					bannedRaw(context, node, specifier(node.source));
+				},
+				ImportExpression(node) {
+					bannedRaw(context, node, specifier(node.source));
+				},
+				CallExpression(node) {
+					const callee = node.callee;
+					if (callee.type === "Identifier" && callee.name === "fetch") {
+						report(context, node, "global fetch is banned; use Effect HttpClient");
+						return;
+					}
+					if (callee.type === "Identifier" && callee.name === "require") {
+						bannedRaw(context, node, specifier(node.arguments[0]));
+						return;
+					}
+					if (callee.type !== "MemberExpression") return;
+					const name = literalName(callee.property, callee.computed);
+					if (callee.object.type === "Identifier" && callee.object.name === "console" && consoleMethods.has(name)) {
+						report(context, node, "console is banned; use Effect Console");
+						return;
+					}
+					if (callee.object.type === "Identifier" && (callee.object.name === "globalThis" || callee.object.name === "global" || callee.object.name === "window") && name === "fetch") report(context, node, "global fetch is banned; use Effect HttpClient");
+				}
+			};
+		}
+	},
+	"no-throw": noThrow,
+	"no-try": noTry,
+	"no-type-assertion": noTypeAssertion
+});
+export { ruleNames };

package/dist/program.js

@@ -1,14 +1,18 @@
 import { CommandFailed } from "./errors.js";
 import { writeStdout } from "./run.js";
-import { init, sync } from "./scaffold.js";
 import { verify } from "./verify.js";
+import { doctor } from "./doctor.js";
+import { explain } from "./explain.js";
+import { init, sync } from "./scaffold.js";
 import { Cause, Effect } from "effect";
 import { Stdio } from "effect/Stdio";
 // src/program.ts
-const usage = "usage: aas verify | aas init | aas sync";
+const usage = "usage: aas verify | aas init | aas sync | aas explain [rule] | aas doctor";
 const main = (cwd) => Effect.gen(function* () {
-	const command = (yield* (yield* Stdio).args)[0];
-	return yield* dispatch(command, cwd).pipe(Effect.catchTag("CommandFailed", (error) => Effect.gen(function* () {
+	const args = yield* (yield* Stdio).args;
+	const command = args[0];
+	const rule = args[1];
+	return yield* dispatch(command, rule, cwd).pipe(Effect.catchTag("CommandFailed", (error) => Effect.gen(function* () {
 		yield* writeStdout(error.lines.join("\n"));
 		return 1;
 	})), Effect.catchCause((cause) => Effect.gen(function* () {
@@ -16,7 +20,7 @@ const main = (cwd) => Effect.gen(function* () {
 		return 1;
 	})));
 });
-const dispatch = (command, cwd) => Effect.gen(function* () {
+const dispatch = (command, rule, cwd) => Effect.gen(function* () {
 	if (command === "verify") {
 		yield* verify(cwd);
 		return 0;
@@ -29,6 +33,16 @@ const dispatch = (command, cwd) => Effect.gen(function* () {
 		yield* sync(cwd);
 		return 0;
 	}
+	if (command === "explain") {
+		yield* explain(rule);
+		return 0;
+	}
+	if (command === "doctor") {
+		const report = yield* doctor(cwd);
+		yield* writeStdout(report.text);
+		if (!report.ok) return yield* new CommandFailed({ lines: [] });
+		return 0;
+	}
 	yield* writeStdout(usage);
 	return yield* new CommandFailed({ lines: [] });
 });

package/dist/scaffold.d.ts

@@ -1,5 +1,5 @@
 import { CommandFailed } from "./errors.js";
 import { Effect, FileSystem } from "effect";
 export declare const writeTemplates: (cwd: string) => Effect.Effect<void, import("effect/PlatformError").PlatformError, FileSystem.FileSystem>;
-export declare const init: (cwd: string) => Effect.Effect<void, CommandFailed | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem>;
+export declare const init: (cwd: string) => Effect.Effect<void, CommandFailed | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Stdio").Stdio>;
 export declare const sync: typeof writeTemplates;

package/dist/scaffold.js

@@ -1,6 +1,8 @@
 import { CommandFailed } from "./errors.js";
-import { findBin, runTool, succeeded } from "./run.js";
+import { failLines, findBin, runTool, succeeded, writeStdout } from "./run.js";
 import { managedFiles, readTemplate } from "./templates.js";
+import { mergeAllowBuilds } from "./workspace.js";
+import { ensureVerifyScript } from "./package-script.js";
 import { Effect, FileSystem } from "effect";
 // src/scaffold.ts
 const parentOf = (path) => {
@@ -11,10 +13,12 @@ const parentOf = (path) => {
 const writeTemplates = (cwd) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	for (const file of managedFiles) {
-		const text = yield* readTemplate(file.template);
+		const template = yield* readTemplate(file.template);
 		const target = `${cwd}/${file.path}`;
 		const parent = parentOf(target);
 		if (parent !== "") yield* fs.makeDirectory(parent, { recursive: true });
+		const previous = (yield* fs.exists(target)) ? yield* fs.readFileString(target) : "";
+		const text = file.template === "pnpm-workspace.yaml" && previous !== "" ? mergeAllowBuilds(template, previous) : template;
 		yield* fs.writeFileString(target, text);
 	}
 });
@@ -34,7 +38,10 @@ const installHooks = (cwd) => Effect.gen(function* () {
 		],
 		cwd
 	});
-	if (succeeded(hooksPath.exitCode)) return;
+	if (succeeded(hooksPath.exitCode)) {
+		yield* writeStdout(`core.hooksPath is ${hooksPath.stdout.trim()}; vp hooks enable skipped`);
+		return;
+	}
 	const vp = yield* findBin("vp");
 	const installed = yield* runTool({
 		bin: vp,
@@ -47,9 +54,23 @@ const failOr = (stdout, stderr) => {
 	const text = `${stdout}\n${stderr}`.trim();
 	return [`vp:1: ${text === "" ? "vp hooks enable failed" : text.split("\n")[0] ?? "failed"}`];
 };
+const refreshLockfile = (cwd) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	if (!(yield* fs.exists(`${cwd}/pnpm-lock.yaml`))) return;
+	const state = `${cwd}/node_modules/.pnpm-workspace-state-v1.json`;
+	if (yield* fs.exists(state)) yield* fs.remove(state);
+	const installed = yield* runTool({
+		bin: "pnpm",
+		args: ["install"],
+		cwd
+	});
+	if (!succeeded(installed.exitCode)) return yield* new CommandFailed({ lines: failLines("pnpm", `${installed.stdout}\n${installed.stderr}`) });
+});
 const init = (cwd) => Effect.gen(function* () {
 	yield* writeTemplates(cwd);
+	yield* ensureVerifyScript(cwd);
 	yield* installHooks(cwd);
+	yield* refreshLockfile(cwd);
 });
 const sync = writeTemplates;
 export { init, sync, writeTemplates };

package/dist/verify.d.ts

@@ -1,3 +1,4 @@
 import { CommandFailed } from "./errors.js";
 import { Effect, FileSystem } from "effect";
+export declare const driftLines: (cwd: string) => Effect.Effect<string[], import("effect/PlatformError").PlatformError, FileSystem.FileSystem>;
 export declare const verify: (cwd: string) => Effect.Effect<undefined, CommandFailed | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem>;

package/dist/verify.js

@@ -1,9 +1,10 @@
 import { CommandFailed } from "./errors.js";
 import { diagnosticsFrom, failLines, findBin, runTool, succeeded } from "./run.js";
 import { managedFiles, readTemplate } from "./templates.js";
+import { workspaceDrift } from "./workspace.js";
 import { Effect, FileSystem, Result, Schema } from "effect";
 // src/verify.ts
-const checkDrift = (cwd) => Effect.gen(function* () {
+const driftLines = (cwd) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const lines = [];
 	for (const file of managedFiles) {
@@ -11,10 +12,30 @@ const checkDrift = (cwd) => Effect.gen(function* () {
 		const target = `${cwd}/${file.path}`;
 		const present = yield* fs.exists(target);
 		const actual = present ? yield* fs.readFileString(target) : "";
+		if (file.template === "pnpm-workspace.yaml") {
+			const reason = present ? workspaceDrift(expected, actual) : "drifted from the aas template; run aas sync";
+			if (reason !== "") lines.push(`${file.path}:1: ${reason}`);
+			continue;
+		}
 		if (!present || actual !== expected) lines.push(`${file.path}:1: drifted from the aas template; run aas sync`);
 	}
+	return lines;
+});
+const checkDrift = (cwd) => Effect.gen(function* () {
+	const lines = yield* driftLines(cwd);
 	if (lines.length > 0) return yield* new CommandFailed({ lines });
 });
+const patchTypeScript = (tsc) => Effect.gen(function* () {
+	const at = tsc.lastIndexOf("/node_modules/.bin/");
+	if (at <= 0) return yield* new CommandFailed({ lines: [`tsc:1: unable to locate the typescript package for ${tsc}`] });
+	const effectTsgo = yield* findBin("effect-tsgo");
+	yield* runChecked({
+		bin: effectTsgo,
+		args: ["patch", "--typescript"],
+		cwd: tsc.slice(0, at),
+		label: "effect-tsgo"
+	});
+});
 const runChecked = (input) => Effect.gen(function* () {
 	const result = yield* runTool(input);
 	if (succeeded(result.exitCode)) return;
@@ -83,18 +104,21 @@ const verify = (cwd) => Effect.gen(function* () {
 		cwd: target,
 		label: "pack"
 	});
-	if (yield* fs.exists(`${cwd}/tsconfig.json`)) yield* runChecked({
-		bin: tsc,
-		args: [
-			"--noEmit",
-			"--pretty",
-			"false",
-			"-p",
-			"tsconfig.json"
-		],
-		cwd,
-		label: "tsc"
-	});
+	if (yield* fs.exists(`${cwd}/tsconfig.json`)) {
+		yield* patchTypeScript(tsc);
+		yield* runChecked({
+			bin: tsc,
+			args: [
+				"--noEmit",
+				"--pretty",
+				"false",
+				"-p",
+				"tsconfig.json"
+			],
+			cwd,
+			label: "tsc"
+		});
+	}
 	const reportPath = `${cwd}/.vitest/aas-report.json`;
 	const tested = yield* runTool({
 		bin: vp,
@@ -163,4 +187,4 @@ const testFailures = (text, cwd) => {
 	}
 	return lines;
 };
-export { verify };
+export { driftLines, verify };

package/dist/workspace.d.ts

@@ -0,0 +1,4 @@
+export declare const scalarEntries: (text: string, key: string) => (readonly [string, string])[] | undefined;
+export declare const workspaceDrift: (template: string, actual: string) => "" | "drifted from the aas template; run aas sync";
+export declare const mergeAllowBuilds: (template: string, previous: string) => string;
+export declare const sameScalars: (left: ReadonlyArray<readonly [string, string]>, right: ReadonlyArray<readonly [string, string]>) => boolean;

package/dist/workspace.js

@@ -0,0 +1,76 @@
+// src/workspace.ts
+const unquote = (raw) => {
+	const trimmed = raw.trim();
+	if (trimmed.length >= 2 && (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'"))) return trimmed.slice(1, -1);
+	return trimmed;
+};
+const linesOf = (text) => text.split("\n");
+const sectionRange = (lines, key) => {
+	const start = lines.findIndex((line) => line === `${key}:`);
+	if (start < 0) return;
+	let end = start + 1;
+	while (end < lines.length) {
+		const line = lines[end] ?? "";
+		if (line === "" || line.startsWith(" ") || line.startsWith("#")) {
+			end += 1;
+			continue;
+		}
+		break;
+	}
+	return {
+		start,
+		end
+	};
+};
+const sectionBody = (text, key) => {
+	const lines = linesOf(text);
+	const range = sectionRange(lines, key);
+	if (range === void 0) return;
+	return lines.slice(range.start + 1, range.end).join("\n");
+};
+const remainder = (text, key) => {
+	const lines = linesOf(text);
+	const range = sectionRange(lines, key);
+	if (range === void 0) return text;
+	return [...lines.slice(0, range.start), ...lines.slice(range.end)].join("\n");
+};
+const entryPattern = /^("?)([A-Za-z0-9@/_.+*-]+)\1:\s*(.+)$/u;
+const scalarEntries = (text, key) => {
+	const body = sectionBody(text, key);
+	if (body === void 0) return;
+	const entries = [];
+	for (const line of body.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		if (trimmed.startsWith("-")) return;
+		const matched = entryPattern.exec(trimmed);
+		const name = matched?.[2];
+		const value = matched?.[3];
+		if (name === void 0 || value === void 0) return;
+		entries.push([name, unquote(value)]);
+	}
+	return entries;
+};
+const drift = "drifted from the aas template; run aas sync";
+const workspaceDrift = (template, actual) => {
+	if (remainder(template, "allowBuilds") !== remainder(actual, "allowBuilds")) return drift;
+	const expected = scalarEntries(template, "allowBuilds");
+	const found = scalarEntries(actual, "allowBuilds");
+	if (expected === void 0 || found === void 0) return drift;
+	for (const [key, value] of expected) {
+		const match = found.find((entry) => entry[0] === key);
+		if (match === void 0 || match[1] !== value) return drift;
+	}
+	return "";
+};
+const mergeAllowBuilds = (template, previous) => {
+	const expected = scalarEntries(template, "allowBuilds");
+	const found = scalarEntries(previous, "allowBuilds");
+	if (expected === void 0 || found === void 0) return template;
+	const extras = found.filter((entry) => !expected.some((required) => required[0] === entry[0])).sort((left, right) => left[0] < right[0] ? -1 : left[0] > right[0] ? 1 : 0);
+	if (extras.length === 0) return template;
+	return `${template.endsWith("\n") ? template.slice(0, -1) : template}\n${extras.map(([key, value]) => `  ${key}: ${value}`).join("\n")}\n`;
+};
+const pairText = (entries) => entries.map(([key, value]) => `${key}=${value}`).sort().join("\n");
+const sameScalars = (left, right) => pairText(left) === pairText(right);
+export { mergeAllowBuilds, sameScalars, scalarEntries, workspaceDrift };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aas-dev/stack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The aas command. One installable toolchain: Vite+, Effect tsgo, and the fence.",
   "license": "MIT",
   "repository": {

package/plugin/aas.mjs

@@ -24,15 +24,15 @@ const rawSpecifiers = new Set([
   "fs",
   "http",
   "https",
-  "net",
   "node:child_process",
   "node:fs",
   "node:fs/promises",
   "node:http",
   "node:https",
-  "node:net",
 ])
 
+const socketSpecifiers = new Set(["net", "node:net", "node:tls", "tls"])
+
 const consoleMethods = new Set(["debug", "error", "info", "log", "warn"])
 
 const effectRunMethods = new Set(["runFork", "runPromise", "runPromiseExit", "runSync"])
@@ -410,27 +410,40 @@ const effectTests = {
   },
 }
 
+const isAdapterFile = (context) => {
+  const filename = typeof context.filename === "string" ? context.filename : ""
+  return filename.endsWith(".adapter.ts")
+}
+
+const rawMessage = (source) => {
+  if (socketSpecifiers.has(source)) {
+    return "node:net and node:tls belong in a .adapter.ts file; other raw IO stays banned"
+  }
+  return "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess"
+}
+
+const bannedRaw = (context, node, source) => {
+  if (socketSpecifiers.has(source)) {
+    if (isAdapterFile(context)) {
+      return
+    }
+    report(context, node, rawMessage(source))
+    return
+  }
+  if (rawSpecifiers.has(source)) {
+    report(context, node, rawMessage(source))
+  }
+}
+
 const noRawIo = {
   meta: { type: "problem" },
   create(context) {
     return {
       ImportDeclaration(node) {
-        if (rawSpecifiers.has(specifier(node.source))) {
-          report(
-            context,
-            node,
-            "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess",
-          )
-        }
+        bannedRaw(context, node, specifier(node.source))
       },
       ImportExpression(node) {
-        if (rawSpecifiers.has(specifier(node.source))) {
-          report(
-            context,
-            node,
-            "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess",
-          )
-        }
+        bannedRaw(context, node, specifier(node.source))
       },
       CallExpression(node) {
         const callee = node.callee
@@ -438,16 +451,8 @@ const noRawIo = {
           report(context, node, "global fetch is banned; use Effect HttpClient")
           return
         }
-        if (
-          callee.type === "Identifier" &&
-          callee.name === "require" &&
-          rawSpecifiers.has(specifier(node.arguments[0]))
-        ) {
-          report(
-            context,
-            node,
-            "raw IO imports are banned; use Effect FileSystem, HttpClient, or ChildProcess",
-          )
+        if (callee.type === "Identifier" && callee.name === "require") {
+          bannedRaw(context, node, specifier(node.arguments[0]))
           return
         }
         if (callee.type !== "MemberExpression") {

package/templates/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This project uses aas-stack. 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.
+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.
 
@@ -8,19 +8,31 @@ This project uses aas-stack. The ideal is one way to do each thing, and `pnpm ve
 
 `aas verify` runs, in order:
 
-1. A drift check. `.cursor/hooks.json`, `.vite-hooks/pre-commit`, `pnpm-workspace.yaml`, `AGENTS.md`, `.github/workflows/verify.yml`, `vite.config.ts`, and `tsconfig.json` must match the templates from `aas init`. `aas sync` rewrites them.
+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. `tsc --noEmit` with the `@effect/tsgo` language service.
+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` in `packages/cli/src/bin.ts` and `packages/cli/src/cursor-hook.ts` is the process boundary. Everywhere else, stay inside Effect.
+`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
 
@@ -43,7 +55,18 @@ yield * new EmptyText({})
 
 ### Config
 
-Declare every variable in `.env.schema`. Read it with `Config`. The schema is the only place a default lives. Do not also call `Config.withDefault`.
+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`.
 
@@ -80,7 +103,9 @@ export class AppConfig extends Context.Service<
 
 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`, `node:net`, `net`, `require` of those modules, dynamic `import` of those modules, global `fetch`, and `console.log` / `error` / `warn` / `info` / `debug`.
+`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`.
 
@@ -109,7 +134,7 @@ External data is `unknown` until a `Schema` decodes it. Discriminate unions and
 
 ## 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. The fence test scans source text, skipping a leading shebang and quoted spans, so a comment the linter did not report still fails.
+`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
 
@@ -119,14 +144,4 @@ Git cannot delete `--no-verify`. The agent hook rejects it anyway, including ins
 
 ## Ideal
 
-One capability, one error style, one config source, one service style, one IO style, one test style. `@aas-stack/core` is that shape for one capability, `countText`: blank text fails with `EmptyText`, and a counted value reports Unicode code points, whitespace-separated words, and `\n`-separated lines. `AppEnv` and `AppConfig` are the config and service examples. Climb toward more capabilities in that shape. Do not add a second pattern because the first one is inconvenient.
-
-## Vendored Effect
-
-`pnpm vendor:agent-sources` clones the Effect version pinned by `@aas-stack/core` into `vendor/effect`. The clone is gitignored. `pnpm verify` does not clone.
-
-## Not in this commit
-
-HTTP with OpenAPI, MCP, and the Executor app adapter are next. The runtime constraint those adapters have to meet is already written in `docs/executor-runtime.md`. `kristoffer-aas/roborock-mcp` is the planned first consumer.
-
-rat-stack and pstack are the inspiration for the fence and the TypeScript rules. This repo does not vendor their code, and it does not use XState or Alchemy.
+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/pnpm-workspace.yaml

@@ -10,3 +10,14 @@ 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