@homeflare/alchemy 0.53.0 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/github/fork-pr-approval.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import {
+  type ForkPrApprovalClient,
+  type ForkPrApprovalPolicy,
+  ForkPrApprovalReadbackMismatch,
+  forkPrApprovalHandlers,
+} from './fork-pr-approval.ts';
+
+const fake = (initial: string, store = true) => {
+  const state = { policy: initial, puts: [] as string[] };
+  const client: ForkPrApprovalClient = {
+    get: () => Effect.succeed(state.policy),
+    put: (_o, _r, policy: ForkPrApprovalPolicy) =>
+      Effect.sync(() => {
+        state.puts.push(policy);
+        if (store) state.policy = policy;
+      }),
+  };
+  return { state, handlers: forkPrApprovalHandlers(() => client) };
+};
+
+const props = {
+  owner: 'taslabs-net',
+  repository: 'homeflare-kit',
+  approvalPolicy: 'all_external_contributors',
+} as const;
+// oxlint-disable-next-line typescript/no-explicit-any
+const run = <A>(e: Effect.Effect<A, unknown, any>) => Effect.runPromise(e as Effect.Effect<A>);
+// oxlint-disable-next-line typescript/no-explicit-any
+const h = (x: ReturnType<typeof fake>) => x.handlers as any;
+
+describe('GitHub.ForkPrApproval', () => {
+  test('reconcile PUTs a looser live policy up to the declared one and reads it back', async () => {
+    const f = fake('first_time_contributors');
+    const out = await run(h(f).reconcile({ news: props, output: undefined }));
+    expect(f.state.puts).toEqual(['all_external_contributors']);
+    expect(out).toEqual({ ...props, approvalPolicy: 'all_external_contributors' });
+  });
+
+  test('reconcile writes nothing when live already matches', async () => {
+    const f = fake('all_external_contributors');
+    await run(h(f).reconcile({ news: props, output: undefined }));
+    expect(f.state.puts).toEqual([]);
+  });
+
+  test('a PUT GitHub does not store fails the reconcile', async () => {
+    const f = fake('first_time_contributors', false);
+    const err = await run(h(f).reconcile({ news: props, output: undefined })).catch(
+      (e: unknown) => e,
+    );
+    expect(String(err)).toContain('read back first_time_contributors');
+    expect(ForkPrApprovalReadbackMismatch.name).toBe('ForkPrApprovalReadbackMismatch');
+  });
+
+  test('an unknown policy is refused before any write', async () => {
+    const f = fake('first_time_contributors');
+    const bad = { ...props, approvalPolicy: 'nobody' };
+    await expect(run(h(f).reconcile({ news: bad, output: undefined }))).rejects.toThrow('unknown');
+    expect(f.state.puts).toEqual([]);
+  });
+
+  test('delete never touches the live setting', async () => {
+    const f = fake('all_external_contributors');
+    await run(h(f).delete({ olds: props, output: props }));
+    expect(f.state.puts).toEqual([]);
+  });
+
+  test('read with no state reports the live value as unowned (adopt on purpose)', async () => {
+    const f = fake('first_time_contributors');
+    const r = await run(h(f).read({ olds: props, output: undefined }));
+    expect(JSON.stringify(r)).toContain('first_time_contributors');
+  });
+});

package/src/github/fork-pr-approval.ts

@@ -0,0 +1,174 @@
+/**
+ * `GitHub.ForkPrApproval` — a repository's "approval for running fork pull request workflows
+ * from contributors" setting, as a declared resource.
+ *
+ * ★ WHY IT EXISTS (Tim, 2026-10-14 01:28 ET). `PUBLIC_ONLY_UNDECLARABLE` (repo-baseline-data.ts)
+ *   listed this setting as something no resource could express. homeflare-kit moved onto the
+ *   self-hosted pve pool, and homeflare-mini's ci-runner serves a public repo only while this
+ *   setting is `all_external_contributors` (its `PUBLIC_RUNNER_REPOS`, fail-closed) — a fork's
+ *   code must not reach the LAN runner without a maintainer's click. So the setting is now code.
+ *
+ * ⚠️ ONE ENDPOINT PAIR, NOTHING ELSE. `GET`/`PUT /repos/{owner}/{repo}/actions/permissions/
+ *   fork-pr-contributor-approval`. The setting always exists, so there is no create and no delete:
+ *   `reconcile` PUTs the declared policy and reads it back; `delete` leaves the live setting as it
+ *   is (the default removal policy is `retain`, and dropping a declaration must never loosen it).
+ * ⛔ ADOPT, NEVER CLAIM SILENTLY. With no prior state `read` returns the live value as `Unowned`,
+ *   so a stack has to `adopt(true)` it on purpose — the same convention as `RepositoryRuleset`.
+ * ⛔ READ BACK. A PUT that GitHub accepts but does not store is reported, not trusted: the
+ *   reconcile re-reads and fails on a mismatch.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import { GitHubCredentials } from 'alchemy/GitHub';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+
+/** GitHub's three values, most to least permissive. */
+export const FORK_PR_APPROVAL_POLICIES = [
+  'first_time_contributors_new_to_github',
+  'first_time_contributors',
+  'all_external_contributors',
+] as const;
+
+export type ForkPrApprovalPolicy = (typeof FORK_PR_APPROVAL_POLICIES)[number];
+
+export interface ForkPrApprovalProps {
+  readonly owner: string;
+  readonly repository: string;
+  readonly approvalPolicy: ForkPrApprovalPolicy;
+  /** GitHub Enterprise API base; omit for github.com. */
+  readonly baseUrl?: string;
+}
+
+export interface ForkPrApprovalAttributes {
+  readonly owner: string;
+  readonly repository: string;
+  readonly approvalPolicy: string;
+}
+
+export interface ForkPrApproval extends Resource<
+  'GitHub.ForkPrApproval',
+  ForkPrApprovalProps,
+  ForkPrApprovalAttributes,
+  never
+> {}
+
+export const ForkPrApproval = Resource<ForkPrApproval>('GitHub.ForkPrApproval', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** The two calls this resource makes, so tests can hand it a fake. */
+export interface ForkPrApprovalClient<R = never> {
+  readonly get: (owner: string, repo: string) => Effect.Effect<string, Error, R>;
+  readonly put: (
+    owner: string,
+    repo: string,
+    policy: ForkPrApprovalPolicy,
+  ) => Effect.Effect<void, Error, R>;
+}
+
+/** A PUT GitHub accepted but did not store. */
+export class ForkPrApprovalReadbackMismatch extends Error {
+  readonly _tag = 'ForkPrApprovalReadbackMismatch';
+}
+
+const asError = (e: unknown): Error => (e instanceof Error ? e : new Error(String(e)));
+const PATH = 'actions/permissions/fork-pr-contributor-approval';
+
+export const octokitForkPrApprovalClient = (
+  baseUrl: string | undefined,
+): ForkPrApprovalClient<GitHubCredentials> => {
+  const octokit = Effect.gen(function* () {
+    const creds = yield* yield* GitHubCredentials;
+    return baseUrl === undefined ? creds.octokit() : creds.octokit({ baseUrl });
+  }).pipe(Effect.mapError(asError));
+  return {
+    get: (owner, repo) =>
+      Effect.gen(function* () {
+        const o = yield* octokit;
+        const res = yield* Effect.tryPromise({
+          try: () => o.request(`GET /repos/{owner}/{repo}/${PATH}`, { owner, repo }),
+          catch: asError,
+        });
+        return String((res.data as { approval_policy?: unknown }).approval_policy);
+      }),
+    put: (owner, repo, policy) =>
+      Effect.gen(function* () {
+        const o = yield* octokit;
+        yield* Effect.tryPromise({
+          try: () =>
+            o.request(`PUT /repos/{owner}/{repo}/${PATH}`, {
+              owner,
+              repo,
+              approval_policy: policy,
+            }),
+          catch: asError,
+        });
+      }),
+  };
+};
+
+const attrs = (
+  owner: string,
+  repository: string,
+  approvalPolicy: string,
+): ForkPrApprovalAttributes => ({
+  owner,
+  repository,
+  approvalPolicy,
+});
+
+/** The provider's handlers over any client — the real one below, a fake in tests. */
+export const forkPrApprovalHandlers = <R>(
+  clientFor: (baseUrl: string | undefined) => ForkPrApprovalClient<R>,
+) =>
+  ForkPrApproval.Provider.of({
+    list: () => Effect.succeed([]),
+    nuke: { skip: true },
+
+    read: ({ output, olds }) =>
+      Effect.gen(function* () {
+        const live = yield* clientFor(olds.baseUrl).get(olds.owner, olds.repository);
+        const found = attrs(olds.owner, olds.repository, live);
+        return output === undefined ? Unowned(found) : found;
+      }),
+
+    diff: ({ news, olds }) =>
+      Effect.succeed(
+        isResolved(news) &&
+          olds !== undefined &&
+          (news.owner !== olds.owner || news.repository !== olds.repository)
+          ? ({ action: 'replace' } as const)
+          : undefined,
+      ),
+
+    reconcile: ({ news }) =>
+      Effect.gen(function* () {
+        if (!(FORK_PR_APPROVAL_POLICIES as readonly string[]).includes(news.approvalPolicy)) {
+          return yield* Effect.fail(
+            new Error(`unknown fork-PR approval policy: ${String(news.approvalPolicy)}`),
+          );
+        }
+        const client = clientFor(news.baseUrl);
+        const before = yield* client.get(news.owner, news.repository);
+        if (before !== news.approvalPolicy) {
+          yield* client.put(news.owner, news.repository, news.approvalPolicy);
+        }
+        const after = yield* client.get(news.owner, news.repository);
+        if (after !== news.approvalPolicy) {
+          return yield* Effect.fail(
+            new ForkPrApprovalReadbackMismatch(
+              `${news.owner}/${news.repository}: PUT ${news.approvalPolicy}, read back ${after}`,
+            ),
+          );
+        }
+        return attrs(news.owner, news.repository, after);
+      }),
+
+    // ⛔ Retain: removing the declaration never loosens the live setting.
+    delete: () => Effect.void,
+  });
+
+export const ForkPrApprovalProvider = () =>
+  Provider.succeed(ForkPrApproval, forkPrApprovalHandlers(octokitForkPrApprovalClient));

package/src/github/index.ts

@@ -45,6 +45,15 @@ export {
   type RepositoryRulesetRules,
   type RepositoryRulesetStatusChecksRule,
 } from './repository-ruleset.ts';
+export {
+  FORK_PR_APPROVAL_POLICIES,
+  ForkPrApproval,
+  type ForkPrApprovalAttributes,
+  type ForkPrApprovalPolicy,
+  type ForkPrApprovalProps,
+  ForkPrApprovalProvider,
+  ForkPrApprovalReadbackMismatch,
+} from './fork-pr-approval.ts';
 export { repoPolicyProviders } from './repository-ruleset-providers.ts';
 export { RULE_TYPE_COVERAGE, type RepositoryRuleType } from './repository-ruleset-constraints.ts';
 export {

package/src/github/repo-baseline-data.ts

@@ -86,10 +86,10 @@ export function repoBaselineRuleset(input: RepoBaselineInput) {
 /** Public-only settings this baseline asserts but cannot express through either resource above
  * at `alchemy@2.0.0-beta.79` — recorded for the wave-3 handoff artifact (plan section 2), not
  * declared anywhere. Both already measured ON for `kit` (LIVE SURVEY 2026-09-23); `builds` is
- * the gap. */
+ * the gap. Fork-PR approval left this list on 2026-10-14: `ForkPrApproval` (fork-pr-approval.ts)
+ * declares it. */
 export const PUBLIC_ONLY_UNDECLARABLE = [
   'secret_scanning: enabled',
   'secret_scanning_push_protection: enabled',
   'private_vulnerability_reporting: enabled',
-  "fork-PR approval: 'first_time_contributors'",
 ] as const;

package/src/github/repository-ruleset-providers.ts

@@ -38,9 +38,14 @@
  */
 import * as GitHub from 'alchemy/GitHub';
 import * as Layer from 'effect/Layer';
+import { ForkPrApprovalProvider } from './fork-pr-approval.ts';
 import { RepositoryRulesetProvider } from './repository-ruleset.ts';
 
 export const repoPolicyProviders = (options?: GitHub.ProvidersOptions) => {
   const github = GitHub.providers(options);
-  return Layer.mergeAll(github, RepositoryRulesetProvider().pipe(Layer.provideMerge(github)));
+  return Layer.mergeAll(
+    github,
+    RepositoryRulesetProvider().pipe(Layer.provideMerge(github)),
+    ForkPrApprovalProvider().pipe(Layer.provideMerge(github)),
+  );
 };

package/src/linux/container-env-quote.test.ts

@@ -15,6 +15,7 @@ import {
   QuadletEnvironmentValueError,
   environmentLines,
   environmentValueProblems,
+  needsQuoting,
   quoteEnvironmentValue,
 } from './container-env-quote.ts';
 import { containerProblems, renderContainerFile } from './container-form.ts';
@@ -62,13 +63,64 @@ describe('the rendered text', () => {
 
   test('keys are sorted, so the render is stable for an unordered plain object', () => {
     expect(environmentLines({ B: '2', A: '1' })).toEqual([
-      ['Environment', '"A=1"'],
-      ['Environment', '"B=2"'],
+      ['Environment', 'A=1'],
+      ['Environment', 'B=2'],
     ]);
     expect(environmentLines({})).toEqual([]);
   });
 });
 
+describe('quoted only when needed (0.53.1)', () => {
+  test('plain values render bare, byte-identical to the 0.51/0.52 renderer', () => {
+    expect(
+      environmentLines({
+        CADDY_CONFIG: '/etc/caddy/Caddyfile',
+        EMPTY: '',
+        URL: 'https://grafana.example/login?a=1&b=2#frag',
+        MIXED: 'a-b_c.d:e/f,g;h@i+j=k(l)[m]{n}*~!|<>?`',
+      }).map(([key, value]) => `${key}=${value}`),
+    ).toEqual([
+      'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
+      'Environment=EMPTY=',
+      'Environment=MIXED=a-b_c.d:e/f,g;h@i+j=k(l)[m]{n}*~!|<>?`',
+      'Environment=URL=https://grafana.example/login?a=1&b=2#frag',
+    ]);
+  });
+
+  test.each([
+    ['space', 'a b'],
+    ['tab', 'a\tb'],
+    ['double quote', 'say "hi"'],
+    ['single quote', "it's"],
+    ['percent', '50%off'],
+    ['dollar', 'pa$word'],
+    ['backslash', 'C:\\path'],
+  ])('a value with a %s is quoted', (_name, value) => {
+    expect(needsQuoting(`K=${value}`)).toBe(true);
+    const rendered = quoteEnvironmentValue('K', value);
+    expect(rendered.startsWith('"K=')).toBe(true);
+    expect(rendered.endsWith('"')).toBe(true);
+  });
+
+  test('a single quote alone triggers the full quoted form', () => {
+    expect(quoteEnvironmentValue('K', "it's")).toBe(`"K=it's"`);
+  });
+
+  test('a special character in the KEY also triggers quoting', () => {
+    expect(quoteEnvironmentValue('A%B', '1')).toBe('"A%%B=1"');
+  });
+
+  test('plain values never need quoting', () => {
+    expect(needsQuoting('A=1')).toBe(false);
+    expect(needsQuoting('K=')).toBe(false);
+    expect(quoteEnvironmentValue('A', '1')).toBe('A=1');
+  });
+
+  test('newlines are still refused before the bare/quoted decision', () => {
+    expect(() => quoteEnvironmentValue('K', 'plain\nplain')).toThrow(QuadletEnvironmentValueError);
+  });
+});
+
 describe('newlines are refused, not encoded', () => {
   test('a newline in a value is a typed error naming the key, never the value', () => {
     expect(() => quoteEnvironmentValue('WEBHOOK_URL', 'https://x\nSECRET-TAIL')).toThrow(

package/src/linux/container-env-quote.ts

@@ -65,6 +65,17 @@ export class QuadletEnvironmentValueError extends Data.TaggedError('QuadletEnvir
   }
 }
 
+/**
+ * The characters that make a bare `KEY=value` unsafe: whitespace (quadlet's splitter ends the
+ * assignment there), `"` and `'` (start/end a quoted region), `\\` (C-escape, which can fail the
+ * whole line), `%` (systemd specifier) and `$` (systemd variable expansion). Anything else passes
+ * quadlet, podman's re-emission and systemd's ExecStart parsing unchanged.
+ */
+const SPECIAL = /[\s"'\\%$]/u;
+
+/** True when `assignment` must be wrapped and escaped to survive the three parsers. */
+export const needsQuoting = (assignment: string): boolean => SPECIAL.test(assignment);
+
 /**
  * `Environment="KEY=value"` — the whole assignment double-quoted, with `\`, `"`, `%` and `$`
  * escaped (in that order, over the joined `KEY=value`), so the wrapping quotes this function adds
@@ -76,6 +87,10 @@ export class QuadletEnvironmentValueError extends Data.TaggedError('QuadletEnvir
  */
 export const quoteEnvironmentValue = (key: string, value: string): string => {
   if (key.includes('\n') || value.includes('\n')) throw new QuadletEnvironmentValueError({ key });
+  // ★ QUOTE ONLY WHEN NEEDED (0.53.1): a `KEY=value` with none of the characters any of the three
+  //   parsers treats specially passes all of them verbatim, so it renders bare — byte-identical to
+  //   the 0.51/0.52 renderer, so units holding only plain values do not change (and do not restart).
+  if (!needsQuoting(`${key}=${value}`)) return `${key}=${value}`;
   // ⛔ THE `$` REPLACEMENT MUST BE A FUNCTION — measured 2026-10-12: `replaceAll`'s replacement
   //   STRING runs its own `$`-pattern mini-language (same fold as systemd: `$$` in it IS one
   //   literal `$`, and `$&` is the match), so a plain `'$$'` replacement silently no-ops and the

package/src/linux/container-fixture.test.ts

@@ -66,9 +66,9 @@ test('renders every directive CT100’s live caddy.container carries', () => {
     'ContainerName=caddy',
     'Network=host',
     'EnvironmentFile=/etc/caddy/cf-token.env',
-    // ⛔ Quoted, like every Environment= value now (container-env-quote.ts) — the caddy value has
-    //   no spaces, but uniform quoting is the rule; container-env-quote.test.ts has the story.
-    'Environment="CADDY_CONFIG=/etc/caddy/Caddyfile"',
+    // ★ Bare again since 0.53.1: the value holds nothing any parser treats specially, so it renders
+    //   exactly as the live file (and 0.51/0.52) has it — container-env-quote.ts quotes only when needed.
+    'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
     'Volume=/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
     'Volume=/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
     'Volume=/etc/caddy/cf-token.env:/run/cf/token.env:ro',