@drkmttr/adhere 0.2.1 → 0.2.2

package/{adhere.config.ts → .adhere/config.ts}

@@ -1,4 +1,4 @@
-import type { Config } from "./src/index.ts";
+import type { Config } from "../src/index.ts";
 
 // Type-only import: erased at runtime, so the compiled binary loads this file
 // without resolving the package (see README, "Configuration").

package/.github/workflows/ci.yaml

@@ -16,4 +16,12 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run typecheck
       - run: bun run test
-      - run: bun run build
+      - run: bun run build:npm
+      - name: Run the launcher against the linux-x64 package
+        run: |
+          # Outside the checkout, where the launcher has no source to fall back to.
+          launcher="$RUNNER_TEMP/launcher"
+          mkdir -p "$launcher/node_modules/@drkmttr"
+          cp -r bin "$launcher/bin"
+          ln -s "$PWD/dist/npm/linux-x64" "$launcher/node_modules/@drkmttr/adhere-linux-x64"
+          node "$launcher/bin/adhere.js" --version

package/.github/workflows/publish.yaml

@@ -1,8 +1,18 @@
 name: Publish
 
 on:
-  release:
-    types: [published]
+  workflow_call:
+    inputs:
+      tag_name:
+        description: "Release tag to publish, for example v0.3.0."
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: "Release tag to publish, for example v0.3.0."
+        required: true
+        type: string
 
 permissions:
   id-token: write
@@ -23,15 +33,36 @@ jobs:
           node-version: "24"
           registry-url: "https://registry.npmjs.org"
       - name: Verify release tag matches package version
+        env:
+          TAG_NAME: ${{ inputs.tag_name }}
         run: |
-          version="${GITHUB_REF_NAME#v}"
+          version="${TAG_NAME#v}"
+          if [[ "$version" == "$TAG_NAME" || ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-.+][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Release tags must look like vX.Y.Z, optionally with a prerelease/build suffix." >&2
+            exit 1
+          fi
           package_version="$(node -p "require('./package.json').version")"
           if [ "$version" != "$package_version" ]; then
-            echo "Release tag $GITHUB_REF_NAME does not match package.json version $package_version." >&2
+            echo "Release tag $TAG_NAME does not match package.json version $package_version." >&2
             exit 1
           fi
       - run: bun install --frozen-lockfile
       - run: bun run typecheck
       - run: bun run test
-      - run: bun run build
-      - run: npm publish --access public --provenance
+      - run: bun run build:npm
+      - name: Publish the platform packages
+        run: |
+          for directory in dist/npm/*/; do
+            name="$(node -p "require('./${directory}package.json').name")"
+            version="$(node -p "require('./${directory}package.json').version")"
+            # A rerun after a partial publish skips the versions already on npm.
+            if npm view "$name@$version" version >/dev/null 2>&1; then
+              echo "$name@$version is already published."
+            else
+              npm publish "$directory" --access public --provenance
+            fi
+          done
+      - name: Publish @drkmttr/adhere with the platform packages as optional dependencies
+        run: |
+          bun scripts/npm-packages.ts pin
+          npm publish --access public --provenance

package/.github/workflows/release.yaml

@@ -55,8 +55,17 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run typecheck
       - run: bun run test
-      - run: bun run build
+      - run: bun run build:npm
       - name: Create GitHub release
         run: bun run release -- --ci "${{ steps.release.outputs.version }}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    uses: ./.github/workflows/publish.yaml
+    permissions:
+      contents: read
+      id-token: write
+    with:
+      tag_name: ${{ github.ref_name }}

package/README.md

@@ -14,8 +14,8 @@ Deterministic rules (substring matches, type checks) belong in a normal linter.
 A config file in the working directory of the repo being audited, at one of
 these paths (keep one):
 
+- `.adhere/config.ts`, the default, next to the rules
 - `adhere.config.ts`
-- `.adhere/config.ts`
 - `.adhere.config.ts`
 
 ```ts
@@ -46,17 +46,26 @@ package installed, `defineConfig({...})` does the same thing.
 
 ### Rules as Markdown files
 
-A repo's own rules live in `.adhere/`, one `*.md` file per rule. The path
-without `.md` is the rule id, so `.adhere/data/brand-ports.md` is
-`data/brand-ports`. When that directory exists, it is read without any config.
-A repo that already has a `docs/` directory may prefer `docs/adhere/`, so the
-rules sit with the rest of its documentation; point `rules` at it:
+A repo's own rules live in `.adhere/`, one `*.md` file per rule, next to the
+config and the cache (neither is read as a rule). The path without `.md` is the
+rule id, so `.adhere/data/brand-ports.md` is `data/brand-ports`. When that
+directory exists, it is read without any config.
+
+`.adhere/` is the default rather than `docs/adhere/` because it keeps
+everything adhere owns in one directory: the config and the cache are tool
+state, not documentation, and would stay in `.adhere/` anyway. A nested
+`.adhere/` also scopes its rules to the directory that contains it (below). The
+cost is visibility: a dot directory is hidden from `ls`, and from `rg` without
+`--hidden`. A repo that would rather keep its rules with the rest of its
+documentation can point `rules` at `docs/adhere/`:
 
 ```ts
 export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
 ```
 
-A config is otherwise needed only to name presets or set thresholds.
+Rules read through `rules` apply project-wide; nested `.adhere/` directories
+are not read then. A config is otherwise needed only to name presets or set
+thresholds.
 
 Nested `.adhere/` directories are also discovered. A rule in
 `packages/api/.adhere/data/brand-ports.md` has the same id,
@@ -100,7 +109,7 @@ A preset has the shape of a config without `presets`: `rules`, and optionally
 [effect-solutions](https://github.com/kitlangton/effect-solutions) docs and the
 [effect/platform](https://effect.website/docs/platform/introduction/) docs.
 Name it in the config, or on the command line with `--preset effect`, in which
-case `adhere.config.ts` is optional.
+case the config file is optional.
 
 ### Precedence
 
@@ -109,6 +118,19 @@ order (a later preset wins), then the defaults `jev-latest` and `0.7`. A rule
 in `rules` replaces a preset rule with the same id. A rule's own `threshold`
 beats all of the above for that rule.
 
+## Install
+
+```sh
+npm install --global @drkmttr/adhere   # or: bun add --global @drkmttr/adhere
+```
+
+`adhere` is the native executable (below), compiled for macOS and Linux on
+arm64 and x64 and for Windows on x64. Each platform's is its own package,
+`@drkmttr/adhere-<platform>-<arch>`, and an optional dependency of
+`@drkmttr/adhere` that the install fetches only on that platform. The package's
+`bin/adhere.js` runs it with Node, so neither Bun nor adhere's runtime
+dependencies are needed.
+
 ## Run
 
 From a checkout, with Bun:
@@ -119,6 +141,9 @@ bun link          # puts `adhere` on PATH
 adhere --preset effect
 ```
 
+In a checkout no platform package is installed, so `bin/adhere.js` runs
+`src/main.ts` with Bun instead.
+
 `adhere` audits the working directory. When that directory contains `agents/`,
 `apps/`, or `packages/`, only those trees are read. Exit code 1 when there is
 at least one finding.
@@ -151,7 +176,9 @@ are treated as intentional shadowing rather than contradictions.
 [`--compile`](https://bun.sh/docs/bundler/executables) with
 `--asset ./presets`. It runs without Bun or `node_modules` on the target
 machine and still loads the repo's `config.ts` and Markdown rules from disk.
-For another platform, add `--target`, for example `bun-darwin-arm64`.
+`bun run build:npm` compiles it for every published platform instead, each
+into its package under `dist/npm/`
+([`scripts/npm-packages.ts`](./scripts/npm-packages.ts)).
 
 ## Release
 
@@ -168,10 +195,18 @@ derives `0.3.0` from `v0.3.0`, and runs `bun run release -- --ci 0.3.0`.
 Release-it bumps `package.json`, commits `chore: release v0.3.0` back to
 `main`, skips npm publish, and creates the GitHub Release for the existing tag.
 
-Publishing stays in `.github/workflows/publish.yaml`: the published GitHub
-Release triggers the OIDC trusted-publisher job, which verifies that
-`package.json` matches the release tag and then runs
-`npm publish --access public --provenance`. No npm token is used.
+Publishing stays in `.github/workflows/publish.yaml`: after release-it
+finishes, `.github/workflows/release.yaml` calls the reusable publish workflow
+directly, avoiding a chained GitHub Release event created by `GITHUB_TOKEN`.
+The publish workflow verifies that `package.json` matches the release tag,
+builds the platform packages, and publishes each of them before
+`@drkmttr/adhere`, which it first lists them in as `optionalDependencies` at
+the same version. Every publish is `npm publish --access public --provenance`.
+No npm token is used, so a new platform package has to be published once by
+hand and given the trusted publisher on npmjs.com before the job can publish
+it. The publish workflow can also be run manually for an already-created
+release tag if a publish needs to be retried; it skips platform packages whose
+version is already on npm.
 
 ## How a file is judged
 

package/bin/adhere.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * `adhere` on PATH. Runs the executable compiled for this machine, which the
+ * install fetched as the optional dependency `@drkmttr/adhere-<platform>-<arch>`
+ * (see scripts/npm-packages.ts). A checkout has none installed, so there it
+ * runs src/main.ts with Bun instead.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const platform = `${process.platform}-${process.arch}`;
+const platformPackage = `@drkmttr/adhere-${platform}`;
+const executable = process.platform === "win32" ? "adhere.exe" : "adhere";
+const args = process.argv.slice(2);
+
+const resolveExecutable = () => {
+  try {
+    return createRequire(import.meta.url).resolve(`${platformPackage}/bin/${executable}`);
+  } catch {
+    return undefined;
+  }
+};
+
+const run = (command, commandArgs) => {
+  const result = spawnSync(command, commandArgs, { stdio: "inherit" });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+};
+
+const prebuilt = resolveExecutable();
+if (prebuilt) run(prebuilt, args);
+else if (existsSync(new URL("../.git", import.meta.url)))
+  run("bun", [fileURLToPath(new URL("../src/main.ts", import.meta.url)), ...args]);
+else {
+  console.error(
+    `adhere: ${platformPackage} is not installed, so there is no executable for ${platform}.` +
+      " It is an optional dependency of @drkmttr/adhere: reinstall without --omit=optional or --no-optional." +
+      " If it is still missing, adhere does not ship an executable for this platform.",
+  );
+  process.exitCode = 1;
+}

package/bun.lock

@@ -5,10 +5,10 @@
     "": {
       "name": "@drkmttr/adhere",
       "dependencies": {
-        "@effect/platform-bun": "4.0.0-rc.112",
         "effect": "4.0.0-rc.112",
       },
       "devDependencies": {
+        "@effect/platform-bun": "4.0.0-rc.112",
         "@types/bun": "^1.4.2",
         "@types/node": "^24.13.6",
         "release-it": "^21.1.0",

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
-  "description": "Lints a repository against reference code in adhere.config.ts, judged by Jev.",
+  "description": "Lints a repository against reference code in .adhere/, judged by Jev.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/darkmatter/adhere.git"
   },
   "bin": {
-    "adhere": "src/main.ts"
+    "adhere": "bin/adhere.js"
   },
   "type": "module",
   "imports": {
@@ -26,13 +26,14 @@
     "test": "vp test",
     "typecheck": "tsc --noEmit && bun run lint",
     "build": "bun build --compile --minify --sourcemap src/main.ts --asset ./presets --outfile dist/adhere",
+    "build:npm": "bun scripts/npm-packages.ts build",
     "release": "release-it"
   },
   "dependencies": {
-    "@effect/platform-bun": "4.0.0-rc.112",
     "effect": "4.0.0-rc.112"
   },
   "devDependencies": {
+    "@effect/platform-bun": "4.0.0-rc.112",
     "@types/bun": "^1.4.2",
     "@types/node": "^24.13.6",
     "release-it": "^21.1.0",
@@ -58,5 +59,12 @@
       "allowSameVersion": true,
       "publish": false
     }
+  },
+  "optionalDependencies": {
+    "@drkmttr/adhere-darwin-arm64": "0.2.2",
+    "@drkmttr/adhere-darwin-x64": "0.2.2",
+    "@drkmttr/adhere-linux-arm64": "0.2.2",
+    "@drkmttr/adhere-linux-x64": "0.2.2",
+    "@drkmttr/adhere-win32-x64": "0.2.2"
   }
 }

package/scripts/npm-packages.ts

@@ -0,0 +1,68 @@
+/**
+ * The npm packages that carry the compiled executable, one per platform. Each
+ * is an optional dependency of `@drkmttr/adhere` limited by `os` and `cpu`, so
+ * an install fetches only its own machine's, and `bin/adhere.js` runs it.
+ *
+ *   bun scripts/npm-packages.ts build   compile every platform into dist/npm/
+ *   bun scripts/npm-packages.ts pin     list them in package.json at its version
+ *
+ * Only the publish job runs `pin`. The committed package.json leaves them out
+ * because a version is not on npm until that job has published it.
+ */
+import packageJson from "../package.json";
+import { $ } from "bun";
+import { rm } from "node:fs/promises";
+
+process.chdir(new URL("../", import.meta.url).pathname);
+
+/** `os` and `cpu` are Node's `process.platform` and `process.arch`, which the launcher names the package from. */
+const platforms = [
+  { os: "darwin", cpu: "arm64", target: "bun-darwin-arm64" },
+  { os: "darwin", cpu: "x64", target: "bun-darwin-x64" },
+  { os: "linux", cpu: "arm64", target: "bun-linux-arm64" },
+  { os: "linux", cpu: "x64", target: "bun-linux-x64" },
+  { os: "win32", cpu: "x64", target: "bun-windows-x64" },
+] as const;
+
+type Platform = (typeof platforms)[number];
+
+const packageName = ({ os, cpu }: Platform) => `${packageJson.name}-${os}-${cpu}`;
+
+const writeJson = (path: string, value: unknown) =>
+  Bun.write(path, `${JSON.stringify(value, null, 2)}\n`);
+
+const build = async () => {
+  for (const platform of platforms) {
+    const directory = `dist/npm/${platform.os}-${platform.cpu}`;
+    const executable = platform.os === "win32" ? "adhere.exe" : "adhere";
+    await rm(directory, { recursive: true, force: true });
+    await $`bun build --compile --minify --sourcemap --target=${platform.target} src/main.ts --asset ./presets --outfile ${directory}/bin/${executable}`;
+    await writeJson(`${directory}/package.json`, {
+      name: packageName(platform),
+      version: packageJson.version,
+      description: `The adhere executable for ${platform.os}-${platform.cpu}. Install ${packageJson.name}, which depends on it.`,
+      repository: packageJson.repository,
+      os: [platform.os],
+      cpu: [platform.cpu],
+      files: [`bin/${executable}`],
+      preferUnplugged: true,
+      publishConfig: packageJson.publishConfig,
+    });
+  }
+};
+
+const pin = () =>
+  writeJson("package.json", {
+    ...packageJson,
+    optionalDependencies: Object.fromEntries(
+      platforms.map((platform) => [packageName(platform), packageJson.version]),
+    ),
+  });
+
+const command = Bun.argv[2];
+if (command === "build") await build();
+else if (command === "pin") await pin();
+else {
+  console.error("usage: bun scripts/npm-packages.ts build|pin");
+  process.exit(2);
+}

package/skills/adhere/SKILL.md

@@ -44,9 +44,11 @@ Skip rules a preset already covers. Run `adhere --help` and read
 
 ## 3. Write each rule as a file
 
-Default location `.adhere/<topic>/<slug>.md`. If the repo already has `docs/`,
-use `docs/adhere/<topic>/<slug>.md` and set `rules: "./docs/adhere"` in the
-config. The path without `.md` is the rule id.
+Default location `.adhere/<topic>/<slug>.md`, next to the config and the
+cache. Use `docs/adhere/<topic>/<slug>.md` with `rules: "./docs/adhere"` in the
+config only when the user wants rules kept with the repo's docs; rules read
+that way apply project-wide, and nested `.adhere/` directories are not read.
+The path without `.md` is the rule id.
 
 ````md
 ---
@@ -73,10 +75,10 @@ Rules for the rule:
 
 ## 4. Configure
 
-Pick one config location: `adhere.config.ts`, `.adhere/config.ts`, or
-`.adhere.config.ts`. A config is optional when `.adhere/` exists or a preset is
-passed on the command line. Use a type-only import so the file also loads
-under the native binary:
+Put the config at `.adhere/config.ts`. `adhere.config.ts` and
+`.adhere.config.ts` also load; keep one. A config is optional when `.adhere/`
+exists or a preset is passed on the command line. Use a type-only import so
+the file also loads under the native binary:
 
 ```ts
 import type { Config } from "@drkmttr/adhere";

package/src/cli.ts

@@ -48,7 +48,7 @@ class UsageReported extends Schema.TaggedError<UsageReported>()(
 
 const preset = Flag.choice("preset", presetNames).pipe(
   Flag.optional,
-  Flag.withDescription("Add a built-in rule set. With a preset, adhere.config.ts is optional."),
+  Flag.withDescription("Add a built-in rule set. With a preset, .adhere/config.ts is optional."),
 );
 
 const threshold = Flag.float("threshold").pipe(
@@ -86,7 +86,7 @@ const audit = Command.make("adhere", { preset, threshold }, () =>
   }),
 ).pipe(
   Command.withDescription(
-    "Audit the working directory against reference code from adhere.config.ts or a preset, judged by Jev.",
+    "Audit the working directory against reference code from .adhere/config.ts or a preset, judged by Jev.",
   ),
   Command.provide((input) =>
     auditLayer({
@@ -98,7 +98,7 @@ const audit = Command.make("adhere", { preset, threshold }, () =>
 
 const INIT_HELP = `Usage: adhere init [--force]
 
-Scaffold adhere.config.ts and example Markdown rules.
+Scaffold .adhere/config.ts and example Markdown rules.
 
 Options:
   --force   Overwrite existing scaffold files

package/src/config.ts

@@ -32,6 +32,12 @@ export const AdhereConfig = Schema.Struct({
 /** Where a repo keeps its rule files by default. The cache lives under it. */
 export const ADHERE_DIRECTORY = ".adhere";
 export const CACHE_DIRECTORY = `${ADHERE_DIRECTORY}/cache`;
+/** Where a config may live, relative to the working directory. Exactly one may exist. */
+export const CONFIG_FILES = [
+  `${ADHERE_DIRECTORY}/config.ts`,
+  "adhere.config.ts",
+  ".adhere.config.ts",
+] as const;
 export interface AdhereConfig extends Schema.Schema.Type<typeof AdhereConfig> {}
 
 /** The shape a config file default-exports. */

package/src/init.ts

@@ -1,5 +1,6 @@
 import { access, mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
+import { CONFIG_FILES } from "#config.ts";
 import { Effect } from "effect";
 
 export interface InitResult {
@@ -44,8 +45,10 @@ export const loadCustomerProfile = (customerId: CustomerId) =>
 \`\`\`
 `;
 
+const CONFIG_PATH = CONFIG_FILES[0];
+
 const files = [
-  ["adhere.config.ts", CONFIG],
+  [CONFIG_PATH, CONFIG],
   [".adhere/style/prefer-small-files.md", SMALL_FILES],
   [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
 ] as const;
@@ -56,6 +59,15 @@ const exists = (path: string): Promise<boolean> =>
     () => false,
   );
 
+/** A config at another accepted path. Scaffolding a second one would refuse every run. */
+const otherConfig = (root: string) =>
+  Effect.promise(async () => {
+    for (const file of CONFIG_FILES) {
+      if (file !== CONFIG_PATH && (await exists(join(root, file)))) return file;
+    }
+    return undefined;
+  });
+
 const writeScaffoldFile = (root: string, path: string, contents: string, options: InitOptions) =>
   Effect.tryPromise({
     try: async () => {
@@ -79,7 +91,12 @@ export const initProject = (
   Effect.gen(function* () {
     const created: Array<string> = [];
     const skipped: Array<string> = [];
+    const existing = yield* otherConfig(root);
     for (const [path, contents] of files) {
+      if (path === CONFIG_PATH && existing !== undefined) {
+        skipped.push(existing);
+        continue;
+      }
       const status = yield* writeScaffoldFile(root, path, contents, options);
       if (status === "created") {
         created.push(relative(root, join(root, path)));

package/src/services/AdhereConfig.ts

@@ -1,6 +1,7 @@
 import {
   ADHERE_DIRECTORY,
   type AdhereConfig as Decoded,
+  CONFIG_FILES,
   ConfigUnavailable,
   decodeConfig,
   type Loaded,
@@ -20,9 +21,6 @@ import {
 } from "#rules.ts";
 import { Context, Effect, FileSystem, Layer, Path, Record } from "effect";
 
-/** Where a config may live, relative to the working directory. Exactly one may exist. */
-export const CONFIG_FILES = ["adhere.config.ts", ".adhere/config.ts", ".adhere.config.ts"] as const;
-
 export class AdhereConfig extends Context.Service<
   AdhereConfig,
   ResolvedConfig

package/test/audit.test.ts

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Crypto, Effect, FileSystem, Layer, Path, Record } from "effect";
@@ -433,7 +433,7 @@ describe("init", () => {
   it("scaffolds config and example rules without clobbering existing files", async () => {
     const root = join(tmpdir(), `adhere-init-${Date.now()}`);
     await Effect.runPromise(initProject(root));
-    const config = await readFile(join(root, "adhere.config.ts"), "utf8");
+    const config = await readFile(join(root, ".adhere", "config.ts"), "utf8");
     const rule = await readFile(join(root, ".adhere", "style", "prefer-small-files.md"), "utf8");
 
     expect(config).toContain("satisfies Config");
@@ -441,9 +441,21 @@ describe("init", () => {
 
     const second = await Effect.runPromise(initProject(root));
     expect(second.created).toEqual([]);
-    expect(second.skipped).toContain("adhere.config.ts");
+    expect(second.skipped).toContain(".adhere/config.ts");
     expect(second.skipped).toContain(".adhere/style/prefer-small-files.md");
   });
+
+  it("keeps a config at another accepted path instead of adding a second one", async () => {
+    const root = join(tmpdir(), `adhere-init-existing-${Date.now()}`);
+    await mkdir(root, { recursive: true });
+    await writeFile(join(root, "adhere.config.ts"), "export default {};\n", "utf8");
+
+    const result = await Effect.runPromise(initProject(root, { force: true }));
+
+    expect(result.skipped).toContain("adhere.config.ts");
+    expect(result.created).not.toContain(".adhere/config.ts");
+    await expect(access(join(root, ".adhere", "config.ts"))).rejects.toThrow();
+  });
 });
 
 describe("pipeline", () => {

package/tsconfig.json

@@ -21,6 +21,6 @@
       "#*": ["./src/*"]
     }
   },
-  "include": ["src/**/*.ts", "test/**/*.ts", "adhere.config.ts"],
+  "include": ["src/**/*.ts", "test/**/*.ts", "scripts/**/*.ts", ".adhere/config.ts"],
   "exclude": ["dist", "node_modules"]
 }