@homeflare/alchemy 0.59.0 → 0.60.0

package/src/scope/patch-check.ts

@@ -0,0 +1,118 @@
+/**
+ * A consuming stack's own `check` calls `checkAlchemyPatch` to assert it actually carries the
+ * duplicate-resource-id fix — not just that SOME version of `alchemy` is installed, but that
+ * THIS install carries the patch, for the alchemy version it was cut against.
+ *
+ * ★ WHY A BUMP CAN OTHERWISE DROP IT SILENTLY. `patchedDependencies` keys a patch to an EXACT
+ *   version string (`alchemy@2.0.0-beta.81`). `bun add alchemy@2.0.0-beta.82` leaves that key
+ *   pointing at a version nothing installs anymore — `bun install` neither errors nor warns,
+ *   it just stops applying the patch, and the stack is back to the original silent collision
+ *   with every other gate still green. This check is what turns that bump into a failing
+ *   `check`, the same way `tests/dist.test.ts` turns a build regression into a failing test
+ *   instead of a surprise three repos downstream (this package's own AGENTS.md, "the smoke
+ *   test is not optional").
+ * ★ A STATIC CHECK, mirroring `@homeflare/config/check`'s `checkCopy`/`checkOxfmt` — not a
+ *   functional probe that spins up a `Stack`/`Resource`/`Effect` harness on every `check` run.
+ *   The functional proof that the patch's LOGIC works lives in this package's own
+ *   `duplicate-id.test.ts`, against the exact pinned version; a consumer's `check` only needs
+ *   to know whether ITS install carries that same patch, applied — three file reads, no
+ *   `effect` runtime pulled into every repo's check step.
+ * ⛔ IT REPORTS, IT DOES NOT REPAIR, same as `checkProject` in `@homeflare/config/check` — this
+ *   never edits `package.json` or re-runs `bun install` for the caller.
+ */
+import { PATCHED_ALCHEMY_VERSION } from './duplicate-id.ts';
+
+/** One thing wrong with a consuming stack's alchemy patch, in the imperative. */
+export type PatchProblem = string;
+
+const patchKey = (version: string) => `alchemy@${version}`;
+
+/** Where THIS package's own shipped copy of the patch lives, however it was installed. */
+const shippedPatchPath = (version: string): string =>
+  new URL(`../../patches/${patchKey(version)}.patch`, import.meta.url).pathname;
+
+type PackageJson = {
+  readonly patchedDependencies?: Readonly<Record<string, string>>;
+};
+
+/**
+ * @param projectDir The consuming stack's OWN repo root (where its `package.json` and
+ *   `patches/` directory live) — never this kit's own.
+ * @param alchemyVersion The version to check for — defaults to the version this package's
+ *   own shipped patch targets ({@link PATCHED_ALCHEMY_VERSION}); a caller only overrides it to
+ *   test a different pin.
+ */
+export const checkAlchemyPatch = async (
+  projectDir: string,
+  alchemyVersion: string = PATCHED_ALCHEMY_VERSION,
+): Promise<readonly PatchProblem[]> => {
+  const problems: PatchProblem[] = [];
+  const key = patchKey(alchemyVersion);
+
+  const installedPkg = Bun.file(`${projectDir}/node_modules/alchemy/package.json`);
+  if (!(await installedPkg.exists())) {
+    problems.push('node_modules/alchemy: not installed — nothing to check the patch against');
+    return problems;
+  }
+  const installedVersion = ((await installedPkg.json()) as { version?: string }).version;
+  if (installedVersion !== alchemyVersion) {
+    problems.push(
+      `node_modules/alchemy is ${installedVersion ?? 'unknown'}, but the duplicate-resource-id ` +
+        `patch targets ${alchemyVersion} — bump the patch (@homeflare/alchemy's own ` +
+        'patches/) before bumping alchemy, or this install has no protection at all',
+    );
+    return problems;
+  }
+
+  const pkgFile = Bun.file(`${projectDir}/package.json`);
+  if (!(await pkgFile.exists())) {
+    problems.push('package.json: missing');
+    return problems;
+  }
+  const pkg = (await pkgFile.json()) as PackageJson;
+  const declaredPath = pkg.patchedDependencies?.[key];
+  if (declaredPath === undefined) {
+    problems.push(
+      `package.json: patchedDependencies has no entry for "${key}" — this stack has no ` +
+        'duplicate-resource-id protection at all; see @homeflare/alchemy/docs/duplicate-resource-id.md',
+    );
+    return problems;
+  }
+
+  const theirs = Bun.file(`${projectDir}/${declaredPath}`);
+  if (!(await theirs.exists())) {
+    problems.push(`package.json declares "${key}" at ${declaredPath}, but that file is missing`);
+    return problems;
+  }
+  const ours = Bun.file(shippedPatchPath(alchemyVersion));
+  if (!(await ours.exists())) {
+    // The kit's own tarball is missing its patch — a packaging bug, not the consumer's.
+    problems.push(`@homeflare/alchemy ships no patches/${key}.patch to compare against`);
+    return problems;
+  }
+  if ((await theirs.text()) !== (await ours.text())) {
+    problems.push(
+      `${declaredPath}: differs from @homeflare/alchemy's shipped patch — re-copy it, ` +
+        'or say why it differs',
+    );
+  }
+
+  // Declared and byte-identical is not yet APPLIED: a hand-edited patchedDependencies entry,
+  // or an install under a package manager that does not support bun's patch format, leaves
+  // node_modules unpatched with nothing above noticing. One cheap textual proof it landed.
+  const resourceSrc = Bun.file(`${projectDir}/node_modules/alchemy/src/Resource.ts`);
+  const resourceLib = Bun.file(`${projectDir}/node_modules/alchemy/lib/Resource.js`);
+  const marker = 'DuplicateResourceIdError';
+  const [srcText, libText] = await Promise.all([
+    resourceSrc.exists().then((ok) => (ok ? resourceSrc.text() : '')),
+    resourceLib.exists().then((ok) => (ok ? resourceLib.text() : '')),
+  ]);
+  if (!srcText.includes(marker) && !libText.includes(marker)) {
+    problems.push(
+      'node_modules/alchemy/{src/Resource.ts,lib/Resource.js}: neither contains the patch — ' +
+        'declared in package.json but not applied; re-run `bun install`',
+    );
+  }
+
+  return problems;
+};

package/dist/scope/guard.d.ts

@@ -1,28 +0,0 @@
-/**
- * `guardDuplicateIds` — wrap a Resource class so every `("id", props)` call it makes first
- * claims that id through `duplicate-id.ts`'s per-stack registry, naming both resource types if
- * a second, different-typed resource already claimed it. See duplicate-id.ts's header for why
- * the check has to live HERE (at the moment of registration) rather than after the stack body
- * has finished running.
- *
- * Usage, in a resource's own file, right where it's exported today:
- *
- * ```ts
- * export const CaddyConfig = guardDuplicateIds(Resource<CaddyConfig>('Caddy.Config', { … }));
- * ```
- *
- * ★ A `Proxy` around the REAL class, not a reimplementation. `Resource()`'s return value is a
- *   callable object wearing an `Effectable.Prototype` (`Effect.isEffect(MyResource) === true`,
- *   for the bare-tag platform-resource pattern) plus `.ref`, `.Type`, `.Provider`, `.Self`,
- *   `.Aliases` — reconstructing that shape risks silently dropping one of them. A `Proxy` whose
- *   `get` trap is the default (`Reflect.get`) forwards every property read untouched; only the
- *   `apply` trap — the `MyResource("id", props)` call form — is new behaviour.
- * ⚠️ THE "REGISTER METHODS" OVERLOAD IS DELIBERATELY LEFT ALONE. `ResourceClass` is also callable
- *   with a single object argument to attach methods (`Resource()`'s own `typeof args[0] ===
- *   'object' ? Object.assign(...) : constructor(...)` branch) — that call mutates and returns the
- *   SAME class, carries no logical id, and has nothing to claim. Only a string first argument
- *   (the `(id, props)` form) goes through `claimResourceId`.
- */
-import type { ResourceClass, ResourceLike } from 'alchemy/Resource';
-export declare const guardDuplicateIds: <R extends ResourceLike>(resourceClass: ResourceClass<R>) => ResourceClass<R>;
-//# sourceMappingURL=guard.d.ts.map

package/dist/scope/guard.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/scope/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIpE,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,YAAY,iBACvC,aAAa,CAAC,CAAC,CAAC,KAC9B,aAAa,CAAC,CAAC,CAiBM,CAAC"}

package/src/scope/guard.test.ts

@@ -1,128 +0,0 @@
-/**
- * `guardDuplicateIds` driven through a REAL `Alchemy.Stack(...)` body with real `Resource()`
- * classes — the same shape `litellm/fake-stack.ts` and `github/repo-apply-order-fake-stack.ts`
- * use for the same reason their own headers give: a check built only against this module's own
- * logic (duplicate-id.test.ts) proves the registry works, not that wiring it onto a resource
- * class via a `Proxy` actually intercepts the call Alchemy itself makes when a stack body
- * `yield*`s it.
- *
- * ⚠️ `dup-experiment.ts` (this PR's own throwaway script, not checked in) first measured the
- *   UNGUARDED failure mode this guards against: two different `Resource()` classes sharing a
- *   logical id compile a stack whose only entry at that fqn is the FIRST type, with no trace the
- *   second one ever ran. These tests are the regression guard for exactly that, once wrapped.
- */
-import { describe, expect, test } from 'bun:test';
-import * as Alchemy from 'alchemy';
-import { push as pushNamespace } from 'alchemy/Namespace';
-import type { Resource, ResourceLike } from 'alchemy/Resource';
-import * as Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-import { guardDuplicateIds } from './guard.ts';
-
-interface Props {
-  readonly value: number;
-}
-interface TestResource extends Resource<string, Props, object> {}
-
-/** A plain `Resource()` class, wrapped, for a given vendor-style type string. */
-const guarded = (type: string) => guardDuplicateIds(Alchemy.Resource<TestResource>(type));
-
-type StackBody = Effect.Effect<unknown, unknown, unknown>;
-
-/** Same cast-at-the-typed-boundary shape as `litellm/fake-stack.ts`; see that file's own header. */
-const runStack = (body: StackBody) => {
-  const state = Alchemy.inMemoryState();
-  const stack = Alchemy.Stack as unknown as (
-    stackName: string,
-    options: { providers: Layer.Layer<never>; state: typeof state },
-    body: StackBody,
-  ) => Effect.Effect<
-    { readonly resources: Readonly<Record<string, ResourceLike>> },
-    unknown,
-    never
-  >;
-  return Effect.runPromiseExit(
-    stack('GuardTestStack', { providers: Layer.empty, state }, body).pipe(
-      Effect.provideService(Alchemy.Stage, 'test'),
-      Effect.scoped,
-    ),
-  );
-};
-
-describe('guardDuplicateIds, through a real stack', () => {
-  test('distinct ids both register', async () => {
-    const A = guarded('Test.A');
-    const B = guarded('Test.B');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* A('one', { value: 1 });
-        yield* B('two', { value: 2 });
-      }),
-    );
-    expect(exit._tag).toBe('Success');
-    if (exit._tag !== 'Success') return;
-    expect(Object.keys(exit.value.resources).sort()).toEqual(['one', 'two']);
-  });
-
-  test('the same guarded type re-registering its own id stays a noop, not a death', async () => {
-    const A = guarded('Test.A');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* A('shared', { value: 1 });
-        yield* A('shared', { value: 1 });
-      }),
-    );
-    expect(exit._tag).toBe('Success');
-  });
-
-  test('two different guarded types sharing an id die naming both, before either resource "wins"', async () => {
-    const Retirement = guarded('Nix.JobRetirement');
-    const Caddy = guarded('Caddy.Config');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* Retirement('caddy', { value: 1 });
-        yield* Caddy('caddy', { value: 2 });
-      }),
-    );
-    expect(exit._tag).toBe('Failure');
-    if (exit._tag !== 'Failure') return;
-    const reasons = (exit.cause as { reasons: readonly { _tag: string; defect?: unknown }[] })
-      .reasons;
-    const reason = reasons[0];
-    expect(reason === undefined ? undefined : reason._tag).toBe('Die');
-    const defect = reason === undefined ? undefined : (reason.defect as Error | undefined);
-    expect(defect === undefined ? '' : String(defect.message)).toContain(
-      'REFUSING: duplicate resource id "caddy" in scope (root): ' +
-        'first declared by Nix.JobRetirement, again by Caddy.Config',
-    );
-  });
-
-  test('one guarded, one unguarded type sharing an id still dies (the guarded side still claims it)', async () => {
-    const Guarded = guarded('Test.Guarded');
-    const Unguarded = Alchemy.Resource<TestResource>('Test.Unguarded');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* Guarded('shared', { value: 1 });
-        yield* Unguarded('shared', { value: 2 });
-      }),
-    );
-    // The unguarded side never calls `claimResourceId`, so Alchemy's own idempotent-registration
-    // branch runs instead (Resource.ts) and this SUCCEEDS as a silent noop — exactly the gap this
-    // PR documents as out of scope for a kit-only fix (docs/duplicate-resource-id.md). Asserting
-    // the current behaviour, not endorsing it: `guardDuplicateIds` only protects pairs where BOTH
-    // sides are wrapped.
-    expect(exit._tag).toBe('Success');
-  });
-
-  test('the same id in a nested namespace is a different scope', async () => {
-    const Retirement = guarded('Nix.JobRetirement');
-    const Caddy = guarded('Caddy.Config');
-    const exit = await runStack(
-      Effect.gen(function* () {
-        yield* Retirement('caddy', { value: 1 });
-        yield* pushNamespace('child', Caddy('caddy', { value: 2 }));
-      }),
-    );
-    expect(exit._tag).toBe('Success');
-  });
-});

package/src/scope/guard.ts

@@ -1,49 +0,0 @@
-/**
- * `guardDuplicateIds` — wrap a Resource class so every `("id", props)` call it makes first
- * claims that id through `duplicate-id.ts`'s per-stack registry, naming both resource types if
- * a second, different-typed resource already claimed it. See duplicate-id.ts's header for why
- * the check has to live HERE (at the moment of registration) rather than after the stack body
- * has finished running.
- *
- * Usage, in a resource's own file, right where it's exported today:
- *
- * ```ts
- * export const CaddyConfig = guardDuplicateIds(Resource<CaddyConfig>('Caddy.Config', { … }));
- * ```
- *
- * ★ A `Proxy` around the REAL class, not a reimplementation. `Resource()`'s return value is a
- *   callable object wearing an `Effectable.Prototype` (`Effect.isEffect(MyResource) === true`,
- *   for the bare-tag platform-resource pattern) plus `.ref`, `.Type`, `.Provider`, `.Self`,
- *   `.Aliases` — reconstructing that shape risks silently dropping one of them. A `Proxy` whose
- *   `get` trap is the default (`Reflect.get`) forwards every property read untouched; only the
- *   `apply` trap — the `MyResource("id", props)` call form — is new behaviour.
- * ⚠️ THE "REGISTER METHODS" OVERLOAD IS DELIBERATELY LEFT ALONE. `ResourceClass` is also callable
- *   with a single object argument to attach methods (`Resource()`'s own `typeof args[0] ===
- *   'object' ? Object.assign(...) : constructor(...)` branch) — that call mutates and returns the
- *   SAME class, carries no logical id, and has nothing to claim. Only a string first argument
- *   (the `(id, props)` form) goes through `claimResourceId`.
- */
-import type { ResourceClass, ResourceLike } from 'alchemy/Resource';
-import * as Effect from 'effect/Effect';
-import { claimResourceId } from './duplicate-id.ts';
-
-export const guardDuplicateIds = <R extends ResourceLike>(
-  resourceClass: ResourceClass<R>,
-): ResourceClass<R> =>
-  new Proxy(resourceClass, {
-    apply(target, thisArg, args: unknown[]) {
-      const id = args[0];
-      if (typeof id !== 'string') {
-        // The "attach methods" overload — not a registration, nothing to claim.
-        return Reflect.apply(target as (...a: unknown[]) => unknown, thisArg, args);
-      }
-      return Effect.gen(function* () {
-        yield* claimResourceId(resourceClass.Type, id);
-        return yield* Reflect.apply(
-          target as (...a: unknown[]) => unknown,
-          thisArg,
-          args,
-        ) as Effect.Effect<R>;
-      });
-    },
-  }) as ResourceClass<R>;