@aas-dev/stack 0.0.0-stage → 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

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# `@aas-dev/stack`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/bin/aas.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/bin.js"

package/dist/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin.js

@@ -0,0 +1,15 @@
+import { main } from "./program.js";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Exit } from "effect";
+// src/bin.ts
+const teardown = (exit, onExit) => {
+	onExit(Exit.match(exit, {
+		onFailure: () => 1,
+		onSuccess: (code) => typeof code === "number" ? code : 1
+	}));
+};
+NodeRuntime.runMain(main(process.cwd()).pipe(Effect.provide(NodeServices.layer)), {
+	disableErrorReporting: true,
+	teardown
+});
+export {};

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import { UserConfig } from "vite-plus";
+export type AasConfig = UserConfig;
+export declare const defineConfig: (options?: {
+  readonly ignorePatterns?: ReadonlyArray<string>;
+}) => AasConfig;

package/dist/config.js

@@ -0,0 +1,75 @@
+import { defineConfig as defineConfig$1 } from "vite-plus";
+// src/config.ts
+const pluginPath = `${import.meta.dirname}/../plugin/aas.mjs`;
+const errors = (rules) => rules;
+const rules = errors({
+	"aas/no-throw": "error",
+	"aas/no-try": "error",
+	"aas/no-error-class": "error",
+	"aas/no-process-env": "error",
+	"aas/no-type-assertion": "error",
+	"aas/no-explicit-any": "error",
+	"aas/no-non-null-assertion": "error",
+	"aas/no-bypass-comment": "error",
+	"aas/no-comments": "error",
+	"aas/effect-tests": "error",
+	"aas/no-raw-io": "error",
+	"aas/no-effect-run": "error",
+	"aas/no-module-let": "error",
+	"aas/no-plain-class": "error"
+});
+const defaultIgnore = [
+	"dist",
+	"vendor",
+	"node_modules",
+	"coverage",
+	".vite-hooks/_",
+	"packages/fence/fixtures"
+];
+const defineConfig = (options) => defineConfig$1({
+	lint: {
+		jsPlugins: [pluginPath],
+		options: {
+			denyWarnings: true,
+			respectEslintDisableDirectives: false
+		},
+		ignorePatterns: [...options?.ignorePatterns ?? defaultIgnore],
+		rules
+	},
+	fmt: {
+		printWidth: 100,
+		semi: false,
+		ignorePatterns: [
+			"node_modules",
+			"dist",
+			"vendor",
+			"coverage",
+			".vitest",
+			".vite-hooks/_"
+		]
+	},
+	test: {
+		include: ["**/*.test.ts"],
+		exclude: [
+			"**/node_modules/**",
+			"**/dist/**",
+			"**/fixtures/**",
+			"**/vendor/**"
+		],
+		passWithNoTests: false,
+		server: { deps: { inline: ["@effect/vitest"] } }
+	},
+	pack: {
+		entry: ["src/**/*.ts", "!src/**/*.test.ts"],
+		dts: true,
+		unbundle: true,
+		fixedExtension: false,
+		hash: false,
+		clean: true,
+		logLevel: "error",
+		failOnWarn: false,
+		report: false,
+		deps: { neverBundle: true }
+	}
+});
+export { defineConfig };

package/dist/cursor-hook.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cursor-hook.js

@@ -0,0 +1,28 @@
+import { BadHookInput } from "./errors.js";
+import { writeStdout } from "./run.js";
+import { commandBypassesVerify } from "./policy.js";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Result, Schema, Stream } from "effect";
+import { Stdio } from "effect/Stdio";
+// src/cursor-hook.ts
+const HookInput = Schema.Struct({ command: Schema.optionalKey(Schema.String) });
+const deny = JSON.stringify({
+	permission: "deny",
+	user_message: "pnpm verify cannot be skipped.",
+	agent_message: "Run pnpm verify. Do not pass --no-verify, a short -n on commit, LEFTHOOK=0, HUSKY=0, VP_GIT_HOOKS=0, VITE_GIT_HOOKS=0, or vp hooks disable."
+});
+const allow = JSON.stringify({ permission: "allow" });
+const hook = Effect.gen(function* () {
+	const stdio = yield* Stdio;
+	const input = yield* Stream.mkString(Stream.decodeText(stdio.stdin));
+	const decoded = Schema.decodeResult(Schema.fromJsonString(HookInput))(input);
+	if (Result.isFailure(decoded)) return yield* new BadHookInput({});
+	const command = decoded.success.command ?? "";
+	if (command === "" || commandBypassesVerify(command)) {
+		yield* writeStdout(deny);
+		return;
+	}
+	yield* writeStdout(allow);
+});
+NodeRuntime.runMain(hook.pipe(Effect.provide(NodeServices.layer)), { disableErrorReporting: true });
+export {};

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/errors.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+declare const CommandFailed_base: Schema.Class<CommandFailed, Schema.TaggedStruct<"CommandFailed", {
+  readonly lines: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class CommandFailed extends CommandFailed_base {}
+declare const BadHookInput_base: Schema.Class<BadHookInput, Schema.TaggedStruct<"BadHookInput", {}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class BadHookInput extends BadHookInput_base {}
+export {};

package/dist/errors.js

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+// src/errors.ts
+var CommandFailed = class extends Schema.TaggedError()("CommandFailed", { lines: Schema.Array(Schema.String) }) {};
+var BadHookInput = class extends Schema.TaggedError()("BadHookInput", {}) {};
+export { BadHookInput, CommandFailed };

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/index.d.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from "./config.js";
+import { commandBypassesVerify } from "./policy.js";
+export { commandBypassesVerify, defineConfig };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { defineConfig } from "./config.js";
+import { commandBypassesVerify } from "./policy.js";
+export { commandBypassesVerify, defineConfig };

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 };