@drkmttr/adhere 0.11.0 → 0.13.0

package/src/init.ts

@@ -12,15 +12,29 @@ export interface InitResult {
 }
 
 export type Install =
-  | { readonly status: "installed"; readonly packageManager: PackageManager }
+  | {
+      readonly status: "installed";
+      /** @drkmttr/adhere, added, or in a shared repo, package.json, installed. */
+      readonly what: string;
+      readonly packageManager: PackageManager;
+    }
   | { readonly status: "listed" }
   | { readonly status: "no-package-json" };
 
 export interface InitOptions {
   readonly force?: boolean;
+  /**
+   * `org/repo`: scaffold a repo whose rules other repos copy with `adhere
+   * install`, rather than one that lints itself.
+   */
+  readonly shared?: string;
+  /** Who can see the shared repo alchemy creates. Defaults to public. */
+  readonly visibility?: Visibility;
 }
 
-// adhere-ignore-file rules/import-written-files -- src/index.ts exports initProject, so a Bun text import here breaks loading the package on Node and in Vitest (checked 2026-09-26), and the compiled executable has no files beside it to read.
+export type Visibility = "public" | "private";
+
+// adhere-ignore-file import-written-files -- src/index.ts exports initProject, so a Bun text import here breaks loading the package on Node and in Vitest (checked 2026-09-26), and the compiled executable has no files beside it to read.
 const CONFIG = `import { defineConfig } from "@drkmttr/adhere";
 
 export default defineConfig({
@@ -29,10 +43,11 @@ export default defineConfig({
 `;
 
 /**
- * A project for the config alone. A tsconfig's globs skip dot directories, so
- * without it the editor opens `.adhere/config.ts` outside any project, where
- * it cannot resolve `@drkmttr/adhere`, whose types only `bundler`, `node16`,
- * and `nodenext` resolution reach.
+ * A project for the config and any rules written in TypeScript. A tsconfig's
+ * globs skip dot directories, so without it the editor opens
+ * `.adhere/config.ts` outside any project, where it cannot resolve
+ * `@drkmttr/adhere`, whose types only `bundler`, `node16`, and `nodenext`
+ * resolution reach.
  */
 const TSCONFIG = `{
   "compilerOptions": {
@@ -44,7 +59,7 @@ const TSCONFIG = `{
     "skipLibCheck": true,
     "allowImportingTsExtensions": true
   },
-  "include": ["config.ts"]
+  "include": ["**/*.ts"]
 }
 `;
 
@@ -100,18 +115,164 @@ export const handle = (id: string) =>
 \`\`\`
 `;
 
+const sharedReadme = (org: string, repo: string) => `# ${repo}
+
+Shared [adhere](https://github.com/darkmatter/adhere) rules for ${org}'s
+repositories. Each rule is a directory in \`.adhere/rules/\` that holds a
+\`RULE.md\`, or a \`RULE.ts\`, and a repo that copies it in has Jev judge its
+files against it when it runs \`adhere lint\`.
+
+## Use these rules
+
+List the rules, then copy them into a repo, all of them or one topic or rule:
+
+\`\`\`sh
+adhere list ${org}/${repo}
+adhere install ${org}/${repo}
+adhere install ${org}/${repo}/style
+adhere install ${org}/${repo}/style/prefer-small-files
+\`\`\`
+
+The copies land in \`.adhere/rules/${org}/${repo}/\` and are that repo's own from then
+on, to edit or to start other rules from. To take a later version of a rule,
+install it again with \`--force\`, which overwrites local edits.
+
+## Add a rule
+
+Add a directory under \`.adhere/rules/<topic>/\` with the rule in a \`RULE.md\`;
+its path is the rule's id. See
+[Rules as Markdown files](https://github.com/darkmatter/adhere#rules-as-markdown-files)
+and the [rule writing tips](https://github.com/darkmatter/adhere#rule-writing-tips).
+\`adhere validate\` checks each rule's wording and asks Jev whether any two
+contradict. CI runs it on every push to main and every pull request.
+
+## Setup
+
+\`alchemy.run.ts\` creates this repository on GitHub, or adopts it when it
+exists, and sets the \`TYPESAFE_API_KEY\` secret CI's \`adhere validate\` needs.
+Install, which init already did, deploy once, then push:
+
+\`\`\`sh
+npm install
+TYPESAFE_API_KEY=... npx alchemy deploy
+git init && git add -A && git commit -m "Add shared adhere rules"
+git remote add origin git@github.com:${org}/${repo}.git && git push -u origin main
+\`\`\`
+
+Deploying again updates the secret, as after rotating the key.
+`;
+
+const SHARED_WORKFLOW = `name: adhere
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx --yes @drkmttr/adhere validate
+        env:
+          TYPESAFE_API_KEY: \${{ secrets.TYPESAFE_API_KEY }}
+`;
+
+const sharedStack = (
+  org: string,
+  repo: string,
+  visibility: Visibility,
+) => `import * as Alchemy from "alchemy";
+import * as GitHub from "alchemy/GitHub";
+import * as Output from "alchemy/Output";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+
+const owner = "${org}";
+
+export default Alchemy.Stack(
+  "${repo}",
+  { providers: GitHub.providers(), state: Alchemy.localState() },
+  Effect.gen(function* () {
+    const repository = yield* GitHub.Repository("rules", {
+      owner,
+      name: "${repo}",
+      description: "Shared adhere rules",
+      visibility: "${visibility}",
+    });
+    // CI's adhere validate asks Jev whether any two rules contradict. Naming
+    // the repository by its output makes alchemy create it before the secret.
+    yield* GitHub.Secret("typesafe-api-key", {
+      owner,
+      repository: Output.map(repository.fullName, (fullName) => fullName.split("/")[1] ?? ""),
+      name: "TYPESAFE_API_KEY",
+      value: yield* Config.Redacted("TYPESAFE_API_KEY"),
+    });
+    return { url: repository.htmlUrl };
+  }).pipe(Effect.orDie),
+);
+`;
+
+/**
+ * alchemy's CLI runs on effect and its Node platform. They are pinned, as is
+ * the platform's own dependency, since a range of prereleases takes the newest:
+ * effect 4.0.0-rc.118 moved modules alchemy 2.0.0-beta.79 imports (checked
+ * 2026-09-28).
+ */
+const sharedPackage = (repo: string) =>
+  `${JSON.stringify(
+    {
+      name: repo,
+      private: true,
+      type: "module",
+      devDependencies: {
+        "@effect/platform-node": "4.0.0-rc.117",
+        alchemy: "2.0.0-beta.79",
+        effect: "4.0.0-rc.117",
+      },
+      overrides: { "@effect/platform-node-shared": "4.0.0-rc.117" },
+    },
+    null,
+    2,
+  )}\n`;
+
+const SHARED_GITIGNORE = `node_modules/
+.alchemy/
+`;
+
 const CONFIG_PATH = CONFIG_FILES[0];
 
-/** The config's own project, which only a config at `.adhere/config.ts` needs. */
+/** The project of the config at `.adhere/config.ts`, and of the rules written in TypeScript beside it. */
 const CONFIG_PROJECT = ".adhere/tsconfig.json";
 
-const files = [
-  [CONFIG_PATH, CONFIG],
-  [CONFIG_PROJECT, TSCONFIG],
-  [".adhere/style/prefer-small-files.md", SMALL_FILES],
-  [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
+const EXAMPLES = [
+  [".adhere/rules/style/prefer-small-files/RULE.md", SMALL_FILES],
+  [".adhere/rules/style/name-domain-actions/RULE.md", NAME_EFFECTS],
 ] as const;
 
+/**
+ * A shared repo has no config: \`adhere install\` copies only rules, and
+ * \`validate\` reads \`.adhere/rules/\` without one.
+ */
+const filesFor = (
+  shared: string | undefined,
+  visibility: Visibility,
+): ReadonlyArray<readonly [string, string]> => {
+  if (shared === undefined) {
+    return [[CONFIG_PATH, CONFIG], [CONFIG_PROJECT, TSCONFIG], ...EXAMPLES];
+  }
+  const [org = "", repo = ""] = shared.split("/");
+  return [
+    ["README.md", sharedReadme(org, repo)],
+    [".github/workflows/adhere.yaml", SHARED_WORKFLOW],
+    ["alchemy.run.ts", sharedStack(org, repo, visibility)],
+    ["package.json", sharedPackage(repo)],
+    [".gitignore", SHARED_GITIGNORE],
+    ...EXAMPLES,
+  ];
+};
+
 const exists = (path: string): Promise<boolean> =>
   access(path).then(
     () => true,
@@ -165,31 +326,36 @@ const packageManagerAt = async (root: string): Promise<PackageManager> => {
 
 /**
  * pnpm refuses to add to a workspace root without a flag. `-w` fails outside a
- * workspace, so the first one, which works in both, stands in for it. pnpm 11
- * also fails on msgpackr-extract's unapproved build script. It comes with
- * effect, and adhere never calls msgpackr, so the second flag lets pnpm skip
- * the build with a warning.
+ * workspace, so this one, which works in both, stands in for it.
  */
 const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
   bun: [],
-  pnpm: ["--ignore-workspace-root-check", "--config.strict-dep-builds=false"],
+  pnpm: ["--ignore-workspace-root-check"],
   yarn: [],
   npm: [],
 };
 
-/** Adds adhere to devDependencies, so the config's `import type` resolves. */
-const installAdhere = (root: string) =>
+/**
+ * Adds adhere to devDependencies, so the config's `import type` resolves. A
+ * shared repo's package.json, which init writes, lists what it needs already,
+ * so there it installs that instead.
+ */
+const installPackages = (root: string, shared: boolean) =>
   Effect.tryPromise({
     try: async (): Promise<Install> => {
       const manifest = await readFile(join(root, "package.json"), "utf8").catch(() => undefined);
       if (manifest === undefined) return { status: "no-package-json" };
       const { dependencies, devDependencies } = JSON.parse(manifest);
-      if (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined) {
+      if (
+        !shared &&
+        (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined)
+      ) {
         return { status: "listed" };
       }
       const packageManager = await packageManagerAt(root);
+      const args = shared ? ["install"] : ["add", "-D", PACKAGE, ...addFlags[packageManager]];
       await new Promise<void>((resolve, reject) => {
-        spawn(packageManager, ["add", "-D", PACKAGE, ...addFlags[packageManager]], {
+        spawn(packageManager, args, {
           cwd: root,
           stdio: "inherit",
         })
@@ -198,11 +364,11 @@ const installAdhere = (root: string) =>
             code === 0 ? resolve() : reject(new Error(`${packageManager} exited with ${code}`)),
           );
       });
-      return { status: "installed", packageManager };
+      return { status: "installed", what: shared ? "package.json" : PACKAGE, packageManager };
     },
     catch: (cause) =>
       new Error(
-        `Could not add ${PACKAGE} to package.json: ${cause instanceof Error ? cause.message : String(cause)}`,
+        `Could not install ${shared ? "package.json" : PACKAGE}: ${cause instanceof Error ? cause.message : String(cause)}`,
       ),
   });
 
@@ -213,8 +379,8 @@ 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) {
+    const existing = options.shared === undefined ? yield* otherConfig(root) : undefined;
+    for (const [path, contents] of filesFor(options.shared, options.visibility ?? "public")) {
       if (path === CONFIG_PATH && existing !== undefined) {
         skipped.push(existing);
         continue;
@@ -228,6 +394,6 @@ export const initProject = (
         skipped.push(relative(root, join(root, path)));
       }
     }
-    const install = yield* installAdhere(root);
+    const install = yield* installPackages(root, options.shared !== undefined);
     return { created, skipped, install };
   });

package/src/install.ts

@@ -0,0 +1,158 @@
+import { spawn } from "node:child_process";
+import { access, cp, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { RULES_DIRECTORY, type RuleId } from "#config.ts";
+import { parseRuleMarkdown } from "#markdown.ts";
+import { Effect } from "effect";
+
+/**
+ * A GitHub repo whose `.adhere/rules/` another repo copies: `org/repo`, then
+ * optionally a topic or a rule's id, then optionally `#` and a branch or tag,
+ * as in `darkmatter/standards/data/brand-ports#v3`.
+ */
+export interface Source {
+  readonly repo: string;
+  /** A rule id or a topic, `data/brand-ports` or `data`; empty for every rule. */
+  readonly rule: string;
+  readonly ref?: string;
+}
+
+export const parseSource = (spec: string): Source | undefined => {
+  const [path = "", ref] = spec.split("#");
+  const [org, repo, ...rule] = path.split("/").filter((segment) => segment.length > 0);
+  if (org === undefined || repo === undefined || ref === "") return undefined;
+  return { repo: `${org}/${repo}`, rule: rule.join("/"), ...(ref === undefined ? {} : { ref }) };
+};
+
+const failed = (what: string) => (cause: unknown) =>
+  new Error(`${what}: ${cause instanceof Error ? cause.message : String(cause)}`);
+
+/**
+ * A shallow clone in a temporary directory, deleted when the scope closes.
+ * git, rather than GitHub's API, so a private repo is reached with whatever
+ * credentials git already has, and `url.<base>.insteadOf` can point
+ * github.com elsewhere, such as at SSH.
+ */
+const cloned = (source: Source) =>
+  Effect.acquireRelease(
+    Effect.tryPromise({
+      try: async () => {
+        const directory = await mkdtemp(join(tmpdir(), "adhere-install-"));
+        const branch = source.ref === undefined ? [] : ["--branch", source.ref];
+        const url = `https://github.com/${source.repo}.git`;
+        await new Promise<void>((resolve, reject) => {
+          let stderr = "";
+          spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
+            stdio: ["inherit", "ignore", "pipe"],
+          })
+            .on("error", reject)
+            .on("exit", (code) =>
+              code === 0
+                ? resolve()
+                : reject(new Error(stderr.trim() || `git exited with ${code}`)),
+            )
+            .stderr?.on("data", (chunk) => {
+              stderr += chunk;
+            });
+        });
+        return directory;
+      },
+      catch: failed(`Could not clone ${source.repo}`),
+    }),
+    (directory) => Effect.promise(() => rm(directory, { recursive: true, force: true })),
+  );
+
+/**
+ * The repo's rules in its root `.adhere/rules/`, as lint reads them there:
+ * each directory that holds a RULE.md or a RULE.ts, by its path, with that file.
+ */
+const rulesIn = (source: Source, clone: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const directory = join(clone, RULES_DIRECTORY);
+      const entries = await readdir(directory, { recursive: true }).catch(() => []);
+      const rules = entries
+        .flatMap((entry) => {
+          const [, id, name] = /^(.+)\/(RULE\.(?:md|ts))$/.exec(entry.split(sep).join("/")) ?? [];
+          return id === undefined || name === undefined ? [] : [{ id: id as RuleId, name }];
+        })
+        .filter(
+          ({ id }) => source.rule === "" || id === source.rule || id.startsWith(`${source.rule}/`),
+        )
+        .sort((a, b) => a.id.localeCompare(b.id));
+      if (rules.length === 0) {
+        throw new Error(
+          source.rule === ""
+            ? `it has no rules in ${RULES_DIRECTORY}/`
+            : `it has no rule or topic ${source.rule} in ${RULES_DIRECTORY}/`,
+        );
+      }
+      return rules.map(({ id, name }) => ({ id, name, directory: join(directory, id) }));
+    },
+    catch: failed(`Nothing to copy from ${source.repo}`),
+  });
+
+/**
+ * Each rule a source names, with its description. A rule written in
+ * TypeScript is listed without one: reading it would run the repo's code.
+ */
+export const listRules = (source: Source) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const rules = yield* rulesIn(source, yield* cloned(source));
+      return yield* Effect.forEach(rules, ({ id, name, directory }) =>
+        Effect.gen(function* () {
+          if (name === "RULE.ts") return { id, description: "(TypeScript, which list does not run)" };
+          const text = yield* Effect.tryPromise({
+            try: () => readFile(join(directory, name), "utf8"),
+            catch: failed(`Could not read ${id}`),
+          });
+          const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}/${name}`);
+          return { id, description: rule.description };
+        }),
+      );
+    }),
+  );
+
+export interface InstallResult {
+  readonly created: ReadonlyArray<string>;
+  readonly skipped: ReadonlyArray<string>;
+}
+
+/**
+ * Copies the rules a source names, each its whole directory, helpers and all,
+ * into `root`'s `.adhere/rules/` under the source's org and repo, so
+ * `data/ports` from acme/rules is the rule `acme/rules/data/ports`, and two
+ * sources' rules never collide. They are the project's own rules from then
+ * on, and a copied RULE.ts runs whenever lint does. As with init, a rule
+ * already there is skipped, unless `force` replaces its directory.
+ */
+export const installRules = (root: string, source: Source, options: { readonly force?: boolean }) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const rules = yield* rulesIn(source, yield* cloned(source));
+      const created: Array<string> = [];
+      const skipped: Array<string> = [];
+      for (const { id, directory } of rules) {
+        const path = `${RULES_DIRECTORY}/${source.repo}/${id}/`;
+        const target = join(root, path);
+        const copied = yield* Effect.tryPromise({
+          try: async () => {
+            const exists = await access(target).then(
+              () => true,
+              () => false,
+            );
+            if (exists && options.force !== true) return false;
+            await rm(target, { recursive: true, force: true });
+            await mkdir(dirname(target), { recursive: true });
+            await cp(directory, target, { recursive: true });
+            return true;
+          },
+          catch: failed(`Could not write ${path}`),
+        });
+        (copied ? created : skipped).push(path);
+      }
+      return { created, skipped } satisfies InstallResult;
+    }),
+  );

package/src/main.ts

@@ -5,7 +5,7 @@ import { version } from "#version.ts";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { plugin } from "bun";
 import { Cause, Effect, Layer, Logger, References, Runtime } from "effect";
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 
 // A config file may import `@drkmttr/adhere`, for `defineConfig`. The compiled
 // executable resolves no packages from disk, so it answers that import with