@homeflare/alchemy 0.14.0 → 0.19.0

package/README.md

@@ -142,6 +142,28 @@ one is logged (argv only, never content) before it runs. A plan never calls sudo
   could not read back, and another user's `gui/<uid>`. A plan that will write runs the same checks.
 - Full list, sudoers cautions and limits: [docs/launchd-sudo.md](./docs/launchd-sudo.md).
 
+## Linux hosts — `@homeflare/alchemy/linux`
+
+The same `HostRunner` seam, over ssh, plus the three families the launchd subpath had no Linux twin
+for: `HostDirectory` (because no file resource creates a parent), `RemoteFile` (a whole file, or one
+**managed block** inside a file somebody else owns) and `SystemdUnit` / `SystemdTimer`.
+`linuxProviders(await sshRunner({ host }))` provides all four.
+
+```ts
+RemoteFile('block', { path: '/etc/example.conf', region: { name: 'homeflare' }, content: 'a line\n' });
+SystemdUnit('thing', { name: 'thing.service', sections: [...], restartOn: [config.sha256] });
+```
+
+- ⛔ **A deploy never mass-restarts.** A unit restarts only when its own file changed, when state or
+  systemd says the loaded copy is stale, or when a digest the declaration listed changed. An adopted
+  unit that already matches is not restarted, reloaded or started.
+- ⛔ **Every byte outside a managed region is identical**, and a delete removes only the block.
+- ⛔ **Fail closed over ssh:** `BatchMode=yes`, host verification untouched, and a remote result
+  without its framing marker is an Error — never "nothing is there".
+- ⛔ **No silent sudo:** a root-owned path needs a root ssh destination or your own privileged runner.
+- ⛔ **The directive set is systemd's:** unit files render verbatim; nothing here invents a schema.
+- Guide, the measured `systemctl` shapes and the limits: [docs/linux-host.md](./docs/linux-host.md).
+
 ## Caddy — `@homeflare/alchemy/caddy`
 
 `CaddyConfig` declares a running Caddy's config as Caddyfile text, applied through Caddy's own admin
@@ -162,6 +184,13 @@ with `HostFile`; `caddyProviders()` provides the transport, `http://127.0.0.1:20
 PVE and PBS objects over the PVE API, `ProxmoxLxc` for containers, and the provisioning baseline
 every cluster needs first. What it never does to a guest, and why: [docs/proxmox.md](./docs/proxmox.md).
 
+## NetBox — `@homeflare/alchemy/netbox`
+
+`Netbox.Prefix` declares one IP prefix and the decision recorded against it — including
+`status: 'deprecated'`, which is how a retired range stops being folklore. Every write is checked
+against a table generated from NetBox's own OpenAPI document before the request is built.
+⛔ Adopt-first, `retain` on removal, and read/write shapes that differ: [docs/netbox.md](./docs/netbox.md).
+
 ## GitHub — `@homeflare/alchemy/github`
 
 `declareRepoPolicy` declares one repository's merge policy and its default-branch ruleset in a

package/dist/linux/directory-lifecycle.d.ts

@@ -0,0 +1,50 @@
+/**
+ * HostDirectory's props, validation and lifecycle over a HostRunner.
+ *
+ * ★ WHY IT EXISTS AT ALL. `Host.File` and `Remote.File` both refuse to create a parent directory,
+ *   on purpose — creating one would invent an owner and a mode nobody declared. The consequence is
+ *   that a first deploy into a new tree fails on its first file. This resource is the declaration
+ *   that was missing, not a convenience flag on the file.
+ * ⛔ ONE DIRECTORY, NEVER A CHAIN. A missing parent is a refusal that names it, so a tree is a
+ *   chain of declarations whose modes and owners are all visible in the plan. `mkdir -p` would
+ *   create the intermediate levels at whatever umask the deploy happened to run with.
+ * ⛔ DELETE IS `rmdir`, NEVER RECURSIVE. A directory that still holds files is a refusal: removing
+ *   a declaration must not be able to remove data the declaration never mentioned.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { type HostRunner } from '../launchd/runner.ts';
+export interface HostDirectoryProps {
+    /** Absolute path. ⚠️ Its parent must already exist — declare it as another HostDirectory. */
+    path: string;
+    /** Permission bits. @default 0o755 */
+    mode?: number;
+    /** User name or numeric uid. Omitted: whoever the runner writes as. */
+    owner?: string | number;
+    /** Group name or numeric gid. Omitted: the parent's default group. */
+    group?: string | number;
+}
+export interface HostDirectoryAttributes {
+    path: string;
+    mode: number;
+    uid: number;
+    gid: number;
+}
+export declare const DEFAULT_DIR_MODE = 493;
+export declare const refuse: (path: string, message: string) => Error;
+export declare const directoryProblems: (props: HostDirectoryProps) => string[];
+export declare const readDirectory: (runner: HostRunner, path: string) => Promise<HostDirectoryAttributes | undefined>;
+/**
+ * Create it when absent, then bring mode and ownership to the declaration and read back.
+ * ⚠️ `mkdir -m` sets the mode with chmod(2) after mkdir(2), so it is exact — plain `mkdir` would
+ *   mask the declared bits through the deploying shell's umask and the drift would return forever.
+ */
+export declare const reconcileDirectory: (runner: HostRunner, props: HostDirectoryProps, output?: HostDirectoryAttributes, adopt?: boolean) => Promise<HostDirectoryAttributes>;
+/**
+ * ★ A plan that will write asks the runner first (`checkWrite`, when it has one) — a directory is
+ *   created and chmod'd through `exec`, but a runner that refuses to touch the path at all should
+ *   say so at plan time rather than mid-apply.
+ */
+export declare const diffDirectory: (runner: HostRunner, news: HostDirectoryProps, output: HostDirectoryAttributes) => Promise<Diff>;
+/** Remove it. ⛔ `rmdir`: a directory that still holds anything is a refusal, never a recursion. */
+export declare const deleteDirectory: (runner: HostRunner, output: HostDirectoryAttributes) => Promise<void>;
+//# sourceMappingURL=directory-lifecycle.d.ts.map

package/dist/linux/directory-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-lifecycle.d.ts","sourceRoot":"","sources":["../../src/linux/directory-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,sBAAsB,CAAC;AAErE,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAEtC,eAAO,MAAM,MAAM,SAAU,MAAM,WAAW,MAAM,KAAG,KACN,CAAC;AAYlD,eAAO,MAAM,iBAAiB,UAAW,kBAAkB,KAAG,MAAM,EAMnE,CAAC;AA2BF,eAAO,MAAM,aAAa,WAChB,UAAU,QACZ,MAAM,KACX,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAI7C,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WACrB,UAAU,SACX,kBAAkB,WAChB,uBAAuB,sBAE/B,OAAO,CAAC,uBAAuB,CAwDjC,CAAC;AAYF;;;;GAIG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,QACZ,kBAAkB,UAChB,uBAAuB,KAC9B,OAAO,CAAC,IAAI,CAed,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,eAAe,WAClB,UAAU,UACV,uBAAuB,KAC9B,OAAO,CAAC,IAAI,CAMd,CAAC"}

package/dist/linux/directory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `Host.Directory` — one directory on the host, declared: path, mode, owner, group.
+ *
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`: a directory already at the path reads as `Unowned`, and
+ *   where the plan never asked, reconcile honours the same flag (docs/ownership.md).
+ * ★ IT IS NOT LINUX-ONLY. `mkdir`, `chmod`, `chown` and `rmdir` are the same argv on macOS, so this
+ *   resource works through any HostRunner; it lives in the linux subpath because the gap it closes
+ *   was found there (a first deploy into a new tree, which every file resource refuses to create).
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { HostRunnerService } from '../launchd/runner.ts';
+import type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+export type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+export interface HostDirectory extends Resource<'Host.Directory', HostDirectoryProps, HostDirectoryAttributes> {
+}
+export declare const HostDirectory: import("alchemy").ResourceClass<HostDirectory>;
+export declare const HostDirectoryProvider: () => import("effect/Layer").Layer<Provider.Provider<HostDirectory>, never, HostRunnerService>;
+//# sourceMappingURL=directory.d.ts.map

package/dist/linux/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/linux/directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAQ5F,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE5F,MAAM,WAAW,aAAc,SAAQ,QAAQ,CAC7C,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,CACxB;CAAG;AAEJ,eAAO,MAAM,aAAa,gDAA4C,CAAC;AAEvE,eAAO,MAAM,qBAAqB,gGAkC/B,CAAC"}

package/dist/linux/fake-linux-host.d.ts

@@ -0,0 +1,35 @@
+import { type UnitState } from './fake-systemd.ts';
+import type { FileStat, HostRunner, HostUser } from '../launchd/runner.ts';
+type Entry = {
+    bytes: Uint8Array;
+    mode: number;
+    uid: number;
+    gid: number;
+    kind: FileStat['kind'];
+};
+export type FakeLinuxOptions = {
+    euid?: number;
+    privileged?: boolean;
+    /** Directories that exist, and their owner uid. Every level above one of these exists as root. */
+    dirs?: Record<string, number>;
+    users?: Record<string, HostUser>;
+    groups?: Record<string, number>;
+    /** ⛔ Make every `systemctl show` fail, to prove a failed READ refuses instead of writing. */
+    failShow?: boolean;
+};
+export declare const fakeLinuxHost: (options?: FakeLinuxOptions) => {
+    calls: string[][];
+    dirs: Map<string, number>;
+    expectUnit: (path: string) => void;
+    files: Map<string, Entry>;
+    modes: Map<string, {
+        mode: number;
+        uid: number;
+        gid: number;
+    }>;
+    placeUnit: (path: string, text: string, state?: Partial<UnitState>) => void;
+    runner: HostRunner;
+    units: Map<string, UnitState>;
+};
+export {};
+//# sourceMappingURL=fake-linux-host.d.ts.map

package/dist/linux/fake-linux-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-linux-host.d.ts","sourceRoot":"","sources":["../../src/linux/fake-linux-host.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAEV,QAAQ,EACR,UAAU,EACV,QAAQ,EAET,MAAM,sBAAsB,CAAC;AAE9B,KAAK,KAAK,GAAG;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC;AAEnG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAUF,eAAO,MAAM,aAAa,aAAa,gBAAgB;;;uBAoJ3B,MAAM;;;cAlIM,MAAM;aAAO,MAAM;aAAO,MAAM;;sBA8G7C,MAAM,QAAQ,MAAM,UAAS,OAAO,CAAC,SAAS,CAAC;;;CAyBzE,CAAC"}

package/dist/linux/fake-systemd.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The systemd half of the fake Linux host: a `systemctl` that behaves the way systemctl.ts measured
+ * the real one behaving. ⛔ TEST-ONLY, and not on the barrel.
+ *
+ * ★ THE ONE BEHAVIOUR EVERYTHING ELSE RESTS ON: `show` of a unit that does not exist EXITS 0 and
+ *   answers `LoadState=not-found`. A fake that returned an error there would let a provider bug
+ *   through that reads the exit code instead of the load state — which is the bug the real host's
+ *   measurement exists to prevent.
+ */
+import type { ExecResult } from '../launchd/runner.ts';
+export type UnitState = {
+    /** What systemd has loaded; `undefined` once it has been unloaded. */
+    loadedSha: string | undefined;
+    active: boolean;
+    enabled: boolean;
+    masked?: boolean;
+};
+export type FakeSystemdDeps = {
+    readonly units: Map<string, UnitState>;
+    /** Every unit-file path the host holds, so a reload can notice a new one. */
+    readonly files: {
+        keys: () => Iterable<string>;
+    };
+    /** The text of a unit's file, or `undefined` when it has none. */
+    readonly fileFor: (name: string) => string | undefined;
+    /** The text at one path, for the reload sweep. */
+    readonly fileAt: (path: string) => string | undefined;
+    readonly pathOf: (name: string) => string;
+    readonly digest: (text: string) => string;
+    /** ⛔ Make every `show` fail, to prove a failed READ refuses instead of writing. */
+    readonly failShow: boolean;
+};
+export declare const fakeSystemd: (deps: FakeSystemdDeps) => (args: readonly string[]) => ExecResult;
+//# sourceMappingURL=fake-systemd.d.ts.map

package/dist/linux/fake-systemd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-systemd.d.ts","sourceRoot":"","sources":["../../src/linux/fake-systemd.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,MAAM,SAAS,GAAG;IACtB,sEAAsE;IACtE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IACjD,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACvD,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B,CAAC;AAKF,eAAO,MAAM,WAAW,SAAU,eAAe,YACjC,SAAS,MAAM,EAAE,KAAG,UAiEnC,CAAC"}

package/dist/linux/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Linux host providers for Alchemy — a host's directories, its files (whole, or one managed block
+ * inside somebody else's file) and its systemd units, over the SAME HostRunner seam the launchd
+ * subpath drives a Mac through.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The lifecycle
+ *   files, the systemctl parsers and the fake host are internals; an `export *` would publish them
+ *   as API and make the next refactor a breaking change.
+ * ⛔ A DEPLOY NEVER MASS-RESTARTS: a unit is restarted only when its own file changed, or a digest
+ *   the declaration listed changed. See docs/linux-host.md.
+ * ★ THE SEAM IS SHARED, NOT COPIED. `HostRunner` is re-exported here so a Linux stack never has to
+ *   import from the launchd subpath to type its own runner.
+ */
+export type { HostDirectoryAttributes, HostDirectoryProps } from './directory-lifecycle.ts';
+export { HostDirectory, HostDirectoryProvider } from './directory.ts';
+export { linuxProviders } from './providers.ts';
+export type { RegionSpec } from './region.ts';
+export type { RemoteFileAttributes, RemoteFileProps } from './remote-file-form.ts';
+export { RemoteFile, RemoteFileProvider } from './remote-file.ts';
+export type { SshRunnerOptions } from './ssh-runner.ts';
+export { sshRunner } from './ssh-runner.ts';
+export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions, } from '../launchd/runner.ts';
+export { HostRunnerService, canActAsRoot, hostRunnerLayer } from '../launchd/runner.ts';
+export type { SystemdUnitAttributes, SystemdUnitProps, UnitSection } from './unit-form.ts';
+export { DEFAULT_UNIT_DIRECTORY, renderUnit } from './unit-form.ts';
+export { SystemdTimer, SystemdTimerProvider, SystemdUnit, SystemdUnitProvider } from './unit.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/linux/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/linux/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,UAAU,EACV,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}