@drkmttr/adhere 0.11.0 → 0.12.0

package/README.md

@@ -139,6 +139,9 @@ adhere lint --deny-warnings    # fail on warnings as well as errors
 adhere lint --log-level debug  # log each request to Jev on stderr
 adhere validate                # check the rules' wording; ask Jev whether any contradict
 adhere init [--force]          # scaffold .adhere/config.ts and two example rules
+adhere init --shared org/repo  # scaffold a repo of rules other repos install
+adhere list org/repo           # list the rules in another repo's .adhere/
+adhere install org/repo        # copy them into this repo's .adhere/org/repo/
 adhere login                   # save a TypeSafe AI API key for later runs
 adhere logout                  # delete the saved key
 adhere skill                   # print the agent skill (below)
@@ -307,6 +310,52 @@ msgpackr-extract, an optional native add-on that comes with `effect` and that
 adhere never uses, with a warning instead of failing.
 It skips the install when `package.json` already lists adhere.
 
+`adhere init --shared org/repo` scaffolds a repo whose rules other repos copy
+in with `adhere install` (see [Sharing rules](#sharing-rules)) instead of one
+that lints itself. It writes the two example rules and no config, since
+install copies only rule files, and with them:
+
+- `README.md`, which says what the repo is for, how to install its rules, and
+  how to add one.
+- `.github/workflows/adhere.yaml`, which runs `adhere validate` on every push
+  to main and every pull request, with the `TYPESAFE_API_KEY` secret. A pull
+  request from a fork gets no secrets, so validate refuses there.
+- `alchemy.run.ts`, an [alchemy](https://alchemy.run) stack that creates the
+  private GitHub repo, or adopts it, and sets that secret from
+  `TYPESAFE_API_KEY` when deployed with `npx alchemy deploy`.
+- `package.json`, with alchemy and effect pinned to versions that work
+  together, which init installs, and a `.gitignore` for them and alchemy's
+  state.
+
+### Sharing rules
+
+An organization's rules can live in one repo's `.adhere/`, and other repos
+copy them in. `adhere list org/repo` prints each rule there with its
+description. `adhere install org/repo` copies every rule into this repo's
+`.adhere/org/repo/`, so `data/brand-ports` from darkmatter/standards is
+`.adhere/darkmatter/standards/data/brand-ports.md`, the rule
+`darkmatter/standards/data/brand-ports`, and two repos' rules never collide.
+A topic or a rule after the repo copies only that part, and `#` picks a branch
+or tag:
+
+```sh
+adhere install darkmatter/standards/data                # the data topic
+adhere install darkmatter/standards/data/brand-ports    # one rule
+adhere install darkmatter/standards#v3                  # every rule, as tagged v3
+```
+
+The copies are the repo's own rules from then on: commit them, edit them, or
+start new rules from them. Nothing tracks where they came from, so a later
+install skips a file already there, as init does, and `--force` overwrites it,
+edits and all. Only Markdown rule files are copied; the source's config, its
+inline rules, and its cache are not. A config with inline `rules` replaces
+the `.adhere/` rule files, so it replaces copied ones too.
+
+The source is cloned with `git` from `https://github.com/org/repo.git`, so a
+private repo needs git's credentials for GitHub, as `gh auth setup-git` sets
+up. To clone over SSH instead, let git rewrite the URL:
+`git config --global url.git@github.com:.insteadOf https://github.com/`.
+
 ### Validate
 
 `adhere validate` loads the config, rule files, and presets the way `lint`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.11.0",
-    "@drkmttr/adhere-darwin-x64": "0.11.0",
-    "@drkmttr/adhere-linux-arm64": "0.11.0",
-    "@drkmttr/adhere-linux-x64": "0.11.0",
-    "@drkmttr/adhere-win32-x64": "0.11.0"
+    "@drkmttr/adhere-darwin-arm64": "0.12.0",
+    "@drkmttr/adhere-darwin-x64": "0.12.0",
+    "@drkmttr/adhere-linux-arm64": "0.12.0",
+    "@drkmttr/adhere-linux-x64": "0.12.0",
+    "@drkmttr/adhere-win32-x64": "0.12.0"
   }
 }

package/src/cli.ts

@@ -23,6 +23,7 @@ import {
 import type { Flags } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
 import { type Install, initProject } from "#init.ts";
+import { installRules, listRules, parseSource } from "#install.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
@@ -326,7 +327,7 @@ export const validateCommand = Command.make("validate", { preset }, () =>
 const installLine = (install: Install): string => {
   switch (install.status) {
     case "installed":
-      return `installed: @drkmttr/adhere with ${install.packageManager}`;
+      return `installed: ${install.what} with ${install.packageManager}`;
     case "listed":
       return "installed: none, @drkmttr/adhere is already in package.json";
     case "no-package-json":
@@ -334,11 +335,25 @@ const installLine = (install: Install): string => {
   }
 };
 
+const shared = Flag.string("shared").pipe(
+  Flag.filter(
+    (repo) => /^[\w.-]+\/[\w.-]+$/.test(repo),
+    (repo) => `--shared names a GitHub repo as org/repo, not ${repo}.`,
+  ),
+  Flag.optional,
+  Flag.withDescription(
+    "Scaffold a repo of rules other repos copy with adhere install, named org/repo on GitHub: example rules, a README, a CI workflow that runs adhere validate, and an alchemy.run.ts that creates the repo and its TYPESAFE_API_KEY secret.",
+  ),
+);
+
 /** `adhere init`: the scaffold. */
-export const initCommand = Command.make("init", { force }, (input) =>
+export const initCommand = Command.make("init", { force, shared }, (input) =>
   Effect.gen(function* () {
     const path = yield* Path.Path;
-    const result = yield* initProject(path.resolve(), { force: input.force });
+    const result = yield* initProject(path.resolve(), {
+      force: input.force,
+      ...Option.match(input.shared, { onNone: () => ({}), onSome: (repo) => ({ shared: repo }) }),
+    });
     const lines = [
       result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
       result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
@@ -352,6 +367,58 @@ export const initCommand = Command.make("init", { force }, (input) =>
   ),
 );
 
+const source = Argument.string("source").pipe(
+  Argument.filterMap(
+    (spec) => Option.fromNullishOr(parseSource(spec)),
+    (spec) => `org/repo, then optionally a topic or rule and #ref, not ${spec}`,
+  ),
+  Argument.withDescription(
+    "A GitHub repo with rules in .adhere/, as org/repo, optionally followed by a topic or a rule, as in org/repo/data/brand-ports, and by #branch or #tag.",
+  ),
+);
+
+/** `adhere list org/repo`: the rules another repo's `.adhere/` holds. */
+export const listCommand = Command.make("list", { source }, (input) =>
+  Effect.gen(function* () {
+    const rules = yield* listRules(input.source);
+    const width = Math.max(...rules.map(({ id }) => id.length));
+    yield* Console.log(
+      rules.map(({ id, description }) => `${id.padEnd(width)}  ${description}`).join("\n"),
+    );
+  }),
+).pipe(
+  Command.withDescription(
+    "List the rules in a GitHub repo's .adhere/, each with its description, for adhere install. Clones with git, so a private repo needs git's credentials for it.",
+  ),
+);
+
+/** `adhere install org/repo`: another repo's rules, copied into this one's `.adhere/`. */
+export const installCommand = Command.make(
+  "install",
+  {
+    source,
+    force: Flag.boolean("force").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription("Overwrite rule files already in .adhere/."),
+    ),
+  },
+  (input) =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const result = yield* installRules(path.resolve(), input.source, { force: input.force });
+      yield* Console.log(
+        [
+          result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
+          result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
+        ].join("\n"),
+      );
+    }),
+).pipe(
+  Command.withDescription(
+    "Copy the rules in a GitHub repo's .adhere/, or one topic or rule of them, into this repo's .adhere/<org>/<repo>/. They are this repo's own rules from then on, to edit or keep in step by hand. Existing files are skipped unless --force.",
+  ),
+);
+
 /**
  * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
  * Whitespace around it, like the newline a pipe ends with, is dropped.
@@ -439,6 +506,10 @@ export const cli = Command.make("adhere").pipe(
     },
     { command: "adhere login", description: "Save your TypeSafe AI API key for later runs" },
     { command: "adhere lint", description: "Audit the working directory" },
+    {
+      command: "adhere install org/repo",
+      description: "Copy another repo's .adhere/ rules into this one",
+    },
     {
       command: "adhere lint --preset effect",
       description: "Audit against the built-in Effect rules",
@@ -448,6 +519,8 @@ export const cli = Command.make("adhere").pipe(
     lintCommand,
     validateCommand,
     initCommand,
+    listCommand,
+    installCommand,
     loginCommand,
     logoutCommand,
     skillCommand,

package/src/init.ts

@@ -12,12 +12,22 @@ 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;
 }
 
 // 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.
@@ -100,18 +110,155 @@ 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 Markdown file in \`.adhere/\`, 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/${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 Markdown file under \`.adhere/<topic>/\`; its path is its 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) => `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: "private",
+    });
+    // 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. */
 const CONFIG_PROJECT = ".adhere/tsconfig.json";
 
-const files = [
-  [CONFIG_PATH, CONFIG],
-  [CONFIG_PROJECT, TSCONFIG],
+const EXAMPLES = [
   [".adhere/style/prefer-small-files.md", SMALL_FILES],
   [".adhere/style/name-domain-actions.md", NAME_EFFECTS],
 ] as const;
 
+/**
+ * A shared repo has no config: \`adhere install\` copies only rule files, and
+ * \`validate\` reads \`.adhere/\` without one.
+ */
+const filesFor = (shared: string | undefined): 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)],
+    ["package.json", sharedPackage(repo)],
+    [".gitignore", SHARED_GITIGNORE],
+    ...EXAMPLES,
+  ];
+};
+
 const exists = (path: string): Promise<boolean> =>
   access(path).then(
     () => true,
@@ -177,19 +324,27 @@ const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
   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 +353,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 +368,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)) {
       if (path === CONFIG_PATH && existing !== undefined) {
         skipped.push(existing);
         continue;
@@ -228,6 +383,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,147 @@
+import { spawn } from "node:child_process";
+import { access, copyFile, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { ADHERE_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 root `.adhere/` rule files by id, as lint reads them there: every `*.md` outside `cache/`. */
+const rulesIn = (source: Source, clone: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const directory = join(clone, ADHERE_DIRECTORY);
+      const entries = await readdir(directory, { recursive: true }).catch(() => []);
+      const ids = entries
+        .filter((entry) => entry.endsWith(".md") && !entry.startsWith(`cache${sep}`))
+        .map((entry): RuleId => entry.slice(0, -".md".length).split(sep).join("/"))
+        .filter(
+          (id) => source.rule === "" || id === source.rule || id.startsWith(`${source.rule}/`),
+        )
+        .sort();
+      if (ids.length === 0) {
+        throw new Error(
+          source.rule === ""
+            ? `it has no rules in ${ADHERE_DIRECTORY}/`
+            : `it has no rule or topic ${source.rule} in ${ADHERE_DIRECTORY}/`,
+        );
+      }
+      return ids.map((id) => ({ id, file: join(directory, `${id}.md`) }));
+    },
+    catch: failed(`Nothing to copy from ${source.repo}`),
+  });
+
+/** Each rule a source names, with its description. */
+export const listRules = (source: Source) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const rules = yield* rulesIn(source, yield* cloned(source));
+      return yield* Effect.forEach(rules, ({ id, file }) =>
+        Effect.gen(function* () {
+          const text = yield* Effect.tryPromise({
+            try: () => readFile(file, "utf8"),
+            catch: failed(`Could not read ${id}`),
+          });
+          const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}.md`);
+          return { id, description: rule.description };
+        }),
+      );
+    }),
+  );
+
+export interface InstallResult {
+  readonly created: ReadonlyArray<string>;
+  readonly skipped: ReadonlyArray<string>;
+}
+
+/**
+ * Copies the rules a source names into `root`'s `.adhere/` 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. As with init, a file already there is
+ * skipped unless `force`.
+ */
+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, file } of rules) {
+        const path = `${ADHERE_DIRECTORY}/${source.repo}/${id}.md`;
+        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 mkdir(dirname(target), { recursive: true });
+            await copyFile(file, target);
+            return true;
+          },
+          catch: failed(`Could not write ${path}`),
+        });
+        (copied ? created : skipped).push(path);
+      }
+      return { created, skipped } satisfies InstallResult;
+    }),
+  );