@homeflare/alchemy 0.37.7 → 0.38.0

package/src/linux/unit-form.ts

@@ -12,8 +12,11 @@
  * ⛔ `content` IS NEVER A SECRET. Props sit unencrypted in Alchemy state and the unit file is
  *   world-readable at 0644; a unit that needs a secret takes `EnvironmentFile=` pointing at a file
  *   a secret renderer maintains.
+ * ★ THE TEXT-SHAPE CHECKS (comments/blank lines before [Section], [Install] key lookup) live in
+ *   `unit-text.ts`, split out to keep this file under the house line cap.
  */
 import { sha256Hex } from '../launchd/job-form.ts';
+import { hasInstallSection, textProblems } from './unit-text.ts';
 
 export type UnitSection = {
   /** `Unit`, `Service`, `Timer`, `Install`, … — verbatim, including its capitalisation. */
@@ -172,8 +175,6 @@ const TYPES = new Set([
   'timer',
 ]);
 
-const INSTALL_KEYS = new Set(['WantedBy', 'RequiredBy', 'UpsertedBy', 'Also', 'Alias']);
-
 /**
  * Every refusal at once, so one plan shows the whole list.
  * ⛔ THE TWO STRUCTURAL RULES, both proven by systemd's own output rather than assumed:
@@ -206,7 +207,7 @@ export const unitProblems = (props: SystemdUnitProps, expect?: string): string[]
         `${directory} is not one of them. Move it, or declare enabled: false.`,
     );
   }
-  if (props.enabled !== false && !hasInstall(props)) {
+  if (props.enabled !== false && !hasInstallSection(unitText(props))) {
     found.push(
       'enabled units need an [Install] section with WantedBy/RequiredBy/Also/Alias; without one ' +
         'systemd calls the unit "static" and `systemctl enable` has nothing to link. Add one, or ' +
@@ -218,18 +219,3 @@ export const unitProblems = (props: SystemdUnitProps, expect?: string): string[]
   }
   return found;
 };
-
-const hasInstall = (props: SystemdUnitProps): boolean => {
-  const text = unitText(props);
-  if (!text.includes('[Install]')) return false;
-  const after = text.slice(text.indexOf('[Install]'));
-  return [...INSTALL_KEYS].some((key) => new RegExp(`^${key}=`, 'm').test(after));
-};
-
-const textProblems = (text: string): string[] => {
-  const found: string[] = [];
-  if (text.trim() === '') found.push('the unit file is empty');
-  if (text.includes('\u0000')) found.push('the unit file contains NUL');
-  if (!/^\s*\[[A-Za-z]+]/.test(text)) found.push('a unit file must begin with a [Section]');
-  return found;
-};

package/src/linux/unit-text.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `unit-text.ts`'s own tests — the INI text-shape checks, on their own, separate from
+ * `unit-lifecycle.test.ts`'s end-to-end fake-host behaviour.
+ */
+import { describe, expect, test } from 'bun:test';
+import { hasInstallSection, textProblems } from './unit-text.ts';
+
+// 🔴 REGRESSION, CT100 deploy 2026-09-26 00:11Z: `assertValid` refused this EXACT content — "a
+//   unit file must begin with a [Section]" — even though it is byte-identical to what systemd
+//   already loads on CT100 (sha256 verified against the live host). Leading lines copied
+//   verbatim from homeflare-ct100's src/openbao-agent/files/openbao-agent.service.
+const CT100_OPENBAO_AGENT = [
+  "# CT100's openbao-agent.",
+  '#',
+  "# THIS FILE WAS RECOVERED FROM THE RUNNING BOX, NOT PUSHED TO IT. The repo's copy was STALE",
+  '#   and would have REMOVED `Environment=BAO_NAMESPACE=homeflare` -- without which the agent',
+  '#   authenticates into the root namespace, every template 403s, and the failure reads as a',
+  '#   missing grant rather than a missing variable. That is the exact shape the vault policies',
+  '#   README warns about: a deploy converging a stale copy over a working live one.',
+  '# So the FIRST run of deploy-ct100.sh was a --dry-run, and this is what it was for.',
+  '[Unit]',
+  'Description=OpenBao agent',
+  'After=network-online.target',
+  'Wants=network-online.target',
+  '[Service]',
+  'Environment=BAO_NAMESPACE=homeflare',
+  'ExecStart=/usr/bin/bao agent -config=/etc/openbao/agent.hcl',
+  'RuntimeDirectory=openbao',
+  'Restart=on-failure',
+  'RestartSec=10',
+  '[Install]',
+  'WantedBy=multi-user.target',
+  '',
+].join('\n');
+
+describe('textProblems', () => {
+  test('the CT100 openbao-agent.service fixture validates — comments may precede [Unit]', () => {
+    expect(textProblems(CT100_OPENBAO_AGENT)).toEqual([]);
+  });
+
+  test('blank lines alone may also precede the first section', () => {
+    expect(textProblems('\n\n[Unit]\nDescription=x\n')).toEqual([]);
+  });
+
+  test('a ; comment is accepted the same as a #  comment', () => {
+    expect(textProblems('; a semicolon comment\n[Unit]\nDescription=x\n')).toEqual([]);
+  });
+
+  test('a genuine key=value before any section still refuses — comments are not a blanket exemption', () => {
+    expect(textProblems('Description=no section at all\n[Unit]\n').join(' ')).toMatch(
+      /must begin with a \[Section\]/,
+    );
+  });
+
+  test('an empty file and one with NUL are still refused', () => {
+    expect(textProblems('   \n').join(' ')).toMatch(/is empty/);
+    expect(textProblems('[Unit]\nDescription=a\u0000b\n').join(' ')).toMatch(/contains NUL/);
+  });
+});
+
+describe('hasInstallSection', () => {
+  test('true only once an [Install] key actually appears after the header', () => {
+    expect(hasInstallSection('[Unit]\n[Install]\nWantedBy=multi-user.target\n')).toBe(true);
+    expect(hasInstallSection('[Unit]\nDescription=x\n')).toBe(false);
+    expect(hasInstallSection('[Unit]\n[Install]\n')).toBe(false);
+  });
+});

package/src/linux/unit-text.ts

@@ -0,0 +1,58 @@
+/**
+ * The parts of `unit-form.ts`'s validation that inspect the unit file's TEXT rather than its
+ * props struct — split out so unit-form.ts stays under the file cap, and because these are one
+ * coherent concern: is this INI shape something systemd would actually load. Takes plain strings,
+ * never `SystemdUnitProps`, so it never needs to import back from unit-form.ts.
+ *
+ * ⛔ `[Install]` KEYS ARE `unit-form.ts`'s OWN LIST, NOT SYSTEMD'S FULL VOCABULARY — WantedBy,
+ *   RequiredBy, UpsertedBy, Also, Alias, per `systemd.unit(5)` §[Install]. `container-form.ts`'s
+ *   own header notes it deliberately does NOT reuse this set: a `.container` file's `[Install]`
+ *   supports only Alias/WantedBy/RequiredBy (`podman-systemd.unit(5)`), narrower than this.
+ */
+
+export const INSTALL_KEYS = new Set(['WantedBy', 'RequiredBy', 'UpsertedBy', 'Also', 'Alias']);
+
+/** Whether `text` has an `[Install]` section carrying at least one key systemd actually links on. */
+export const hasInstallSection = (text: string): boolean => {
+  if (!text.includes('[Install]')) return false;
+  const after = text.slice(text.indexOf('[Install]'));
+  return [...INSTALL_KEYS].some((key) => new RegExp(`^${key}=`, 'm').test(after));
+};
+
+/**
+ * The first line that is neither blank nor a comment — the line whose shape actually decides
+ * whether the file "begins with a [Section]", per `textProblems` below.
+ * ★ systemd.syntax(7): "Empty lines and lines starting with '#' or ';' are ignored", with no
+ *   carve-out for the position before the first section — a comment header is ordinary content
+ *   there, same as anywhere else in the file.
+ */
+export const firstSubstantiveLine = (text: string): string | undefined =>
+  text
+    .split('\n')
+    .find((line) => !(line.trim() === '' || line.startsWith('#') || line.startsWith(';')));
+
+/**
+ * 🔴 MEASURED FALSE, CT100 deploy 2026-09-26 00:11Z: the openbao-agent.service asset's first eight
+ *   lines are `#`-comments recording where the file was recovered from (verbatim from the live
+ *   host — homeflare-ct100's `src/openbao-agent/files/openbao-agent.service`), and the file is
+ *   byte-identical to what systemd already loads there. The old check tested the WHOLE text
+ *   against `/^\s*\[[A-Za-z]+]/` — `\s*` skips blank lines and indentation, never a `#`/`;`
+ *   comment — so a leading comment line failed it outright. This checks only the first
+ *   SUBSTANTIVE line, so any number of leading blank lines and comments are fine and a genuine
+ *   `key=value` before any section — the one real error this exists to catch — still fails, since
+ *   that line is neither blank nor a comment either.
+ */
+export const textProblems = (text: string): string[] => {
+  const found: string[] = [];
+  if (text.trim() === '') found.push('the unit file is empty');
+  if (text.includes('\u0000')) found.push('the unit file contains NUL');
+  const first = firstSubstantiveLine(text);
+  // ★ `\s*` kept from the original regex — leading indentation on the SECTION line itself was
+  //   already tolerated before this fix and stays that way; only the leading-comment shape changes.
+  if (first === undefined || !/^\s*\[[A-Za-z]+]/.test(first)) {
+    found.push(
+      'a unit file must begin with a [Section] (blank lines and #/; comments before it are fine)',
+    );
+  }
+  return found;
+};