@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/factory.ts

@@ -0,0 +1,481 @@
+// Factory-level wrapper composition: two seeds (perm/input), shared
+// Mode-generic wrappers, two composed bases (basePermission, baseInput). Each
+// wrapper owns one meta slot and refuses double-stacks via GateNoSlot.
+
+import type { z } from "zod";
+import type {
+  AddOptionalSlot,
+  AddRequiredSlot,
+  Builder,
+  FactoryFor,
+  GateNoSlot,
+  InputKind,
+  Mode,
+} from "./shared.ts";
+
+// Open template literal shape used as basePermission's KindUnion. The closed
+// `PermissionKind` (derived from schema/* in permissions.ts) can't be
+// referenced here without forming a type-level cycle: schema/host.ts →
+// host-registry.ts → factory.ts → ... → typeof schema/host.ts. Every prefix a
+// registry narrows to must appear here, or `make*(basePermission)` won't
+// typecheck for that prefix.
+type AnyPermissionKindShape =
+  | `host.${string}`
+  | `peers.${string}`
+  | `remote.${string}`
+  | `home.${string}`;
+
+// ----- Runtime helpers -----------------------------------------------------
+
+export function defineMethod<T extends object>(
+  target: T,
+  name: string,
+  fn: (this: T, ...args: never[]) => unknown,
+): void {
+  Object.defineProperty(target, name, {
+    value: fn,
+    enumerable: false,
+    writable: false,
+    configurable: true,
+  });
+}
+
+export function cloneAnd<T extends object>(source: T, patch: object): T {
+  const c = Object.create(
+    Object.getPrototypeOf(source),
+    Object.getOwnPropertyDescriptors(source),
+  ) as T;
+  Object.assign(c, patch);
+  return c;
+}
+
+// ----- Seeds ---------------------------------------------------------------
+
+const makePermRecord: Builder<{ readonly meta: object }, "perm", AnyPermissionKindShape> = (<
+  S extends z.ZodType,
+  K extends AnyPermissionKindShape,
+>(
+  kind: K,
+  schema: S,
+) => {
+  return (input?: z.input<S>) => ({
+    kind,
+    data: schema.parse(input),
+    meta: {} as object,
+  });
+}) as Builder<{ readonly meta: object }, "perm", AnyPermissionKindShape>;
+
+const makeInputRecord: Builder<{ readonly meta: object }, "input", InputKind> = <
+  S extends z.ZodType,
+  K extends InputKind,
+>(
+  kind: K,
+  schema: S,
+) => {
+  return () => ({
+    kind,
+    schema,
+    meta: {} as object,
+  });
+};
+
+// ----- Mode-agnostic wrappers ---------------------------------------------
+
+interface WithOptional {
+  // The intersection narrows the existing `meta.isOptional: boolean` slot
+  // to the literal `true`, which lets type-level walkers (`GrantsOf`,
+  // `ConfigOf`'s optional-key handling) tell `r.x()` apart from
+  // `r.x().optional()`.
+  optional(this: this): this & { readonly meta: { readonly isOptional: true } };
+}
+
+function makeOptional<BaseR extends { meta: object }, M extends Mode, KindUnion extends string>(
+  inner: Builder<BaseR, M, KindUnion>,
+  ..._gate: GateNoSlot<BaseR["meta"], "isOptional">
+): Builder<
+  BaseR & {
+    readonly meta: AddRequiredSlot<BaseR["meta"], "isOptional", boolean>;
+  } & WithOptional,
+  M,
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema) as (...args: unknown[]) => { meta: object };
+    return ((...args: unknown[]) => {
+      const innerRecord = factory(...args);
+      // Use cloneAnd (not spread) so non-enumerable chain methods carry over.
+      const seeded = cloneAnd(innerRecord, {
+        meta: { ...(innerRecord.meta as object), isOptional: false },
+      });
+      defineMethod(seeded, "optional", function (this: typeof seeded) {
+        return cloneAnd(this, { meta: { ...(this.meta as object), isOptional: true } });
+      });
+      return seeded;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & {
+        readonly meta: AddRequiredSlot<BaseR["meta"], "isOptional", boolean>;
+      } & WithOptional,
+      M
+    >;
+  }) as Builder<
+    BaseR & {
+      readonly meta: AddRequiredSlot<BaseR["meta"], "isOptional", boolean>;
+    } & WithOptional,
+    M,
+    KindUnion
+  >;
+}
+
+interface WithDescribe {
+  describe(this: this, text: string): this;
+}
+
+function makeDescribable<BaseR extends { meta: object }, M extends Mode, KindUnion extends string>(
+  inner: Builder<BaseR, M, KindUnion>,
+  ..._gate: GateNoSlot<BaseR["meta"], "description">
+): Builder<
+  BaseR & {
+    readonly meta: AddOptionalSlot<BaseR["meta"], "description", string>;
+  } & WithDescribe,
+  M,
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema) as (...args: unknown[]) => { meta: object };
+    return ((...args: unknown[]) => {
+      const record = factory(...args);
+      defineMethod(record, "describe", function (this: typeof record, text: string) {
+        return cloneAnd(this, { meta: { ...(this.meta as object), description: text } });
+      });
+      return record;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & {
+        readonly meta: AddOptionalSlot<BaseR["meta"], "description", string>;
+      } & WithDescribe,
+      M
+    >;
+  }) as Builder<
+    BaseR & {
+      readonly meta: AddOptionalSlot<BaseR["meta"], "description", string>;
+    } & WithDescribe,
+    M,
+    KindUnion
+  >;
+}
+
+// ----- Permission-only wrappers -------------------------------------------
+
+// `.reason()` widens meta.reason from optional to required, transitioning a
+// Draft permission to Complete (assignable to the configSchema slot).
+interface WithReason {
+  reason(this: this, text: string): this & { readonly meta: { readonly reason: string } };
+}
+
+// `.schema(z)` lands a live Zod schema as a non-enumerable `responseSchema`
+// property — JSON.stringify drops it; the sandbox reads it back inside QuickJS.
+// The method name (`schema`) and the property name (`responseSchema`) must
+// differ; one identifier for both breaks polymorphic-`this` chaining for
+// `.reason()` etc.
+interface WithSchema {
+  schema<S extends z.ZodType>(this: this, s: S): this & { readonly responseSchema: S };
+}
+
+function makeReasonable<BaseR extends { meta: object }, KindUnion extends string>(
+  inner: Builder<BaseR, "perm", KindUnion>,
+  ..._gate: GateNoSlot<BaseR["meta"], "reason">
+): Builder<
+  BaseR & {
+    readonly meta: AddOptionalSlot<BaseR["meta"], "reason", string>;
+  } & WithReason,
+  "perm",
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema);
+    return ((input?: z.input<S>) => {
+      const record = (factory as unknown as (input?: z.input<S>) => { meta: object })(input);
+      defineMethod(record, "reason", function (this: typeof record, text: string) {
+        return cloneAnd(this, { meta: { ...(this.meta as object), reason: text } });
+      });
+      return record;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & {
+        readonly meta: AddOptionalSlot<BaseR["meta"], "reason", string>;
+      } & WithReason,
+      "perm"
+    >;
+  }) as Builder<
+    BaseR & {
+      readonly meta: AddOptionalSlot<BaseR["meta"], "reason", string>;
+    } & WithReason,
+    "perm",
+    KindUnion
+  >;
+}
+
+// Opt-in mixin for factories that carry a live Zod object (today:
+// remote.fetchUrl).
+function makeSchemable<BaseR extends object, KindUnion extends string>(
+  inner: Builder<BaseR, "perm", KindUnion>,
+  ..._gate: GateNoSlot<BaseR, "responseSchema">
+): Builder<BaseR & WithSchema, "perm", KindUnion> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema);
+    return ((input?: z.input<S>) => {
+      const record = (factory as unknown as (input?: z.input<S>) => object)(input);
+      defineMethod(record, "schema", function (this: object, s: z.ZodType) {
+        const cloned = cloneAnd(this, {});
+        Object.defineProperty(cloned, "responseSchema", {
+          value: s,
+          enumerable: false,
+          writable: false,
+          configurable: true,
+        });
+        return cloned;
+      });
+      return record;
+    }) as unknown as FactoryFor<S, K, BaseR & WithSchema, "perm">;
+  }) as Builder<BaseR & WithSchema, "perm", KindUnion>;
+}
+
+// ----- Input-only wrappers ------------------------------------------------
+
+interface WithTitle {
+  title(this: this, text: string): this;
+}
+
+function makeTitleable<BaseR extends { meta: object }, KindUnion extends string>(
+  inner: Builder<BaseR, "input", KindUnion>,
+  ..._gate: GateNoSlot<BaseR["meta"], "title">
+): Builder<
+  BaseR & {
+    readonly meta: AddOptionalSlot<BaseR["meta"], "title", string>;
+  } & WithTitle,
+  "input",
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema);
+    return (() => {
+      const record = (factory as () => { meta: object })();
+      defineMethod(record, "title", function (this: typeof record, text: string) {
+        return cloneAnd(this, { meta: { ...(this.meta as object), title: text } });
+      });
+      return record;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & {
+        readonly meta: AddOptionalSlot<BaseR["meta"], "title", string>;
+      } & WithTitle,
+      "input"
+    >;
+  }) as Builder<
+    BaseR & {
+      readonly meta: AddOptionalSlot<BaseR["meta"], "title", string>;
+    } & WithTitle,
+    "input",
+    KindUnion
+  >;
+}
+
+// `.prefill` infers I from `this.schema` so the value is constrained to the
+// schema's I. Non-generic at the BaseR level so it sits cleanly alongside
+// other mixins.
+interface WithPrefill {
+  prefill<I>(
+    this: this & { readonly schema: z.ZodType<I> },
+    value: I,
+  ): this & { readonly meta: { readonly prefill: I } };
+}
+
+function makePrefillable<BaseR extends { meta: object }, KindUnion extends string>(
+  inner: Builder<BaseR, "input", KindUnion>,
+  ..._gate: GateNoSlot<BaseR["meta"], "prefill">
+): Builder<
+  BaseR & {
+    readonly meta: AddOptionalSlot<BaseR["meta"], "prefill", unknown>;
+  } & WithPrefill,
+  "input",
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema);
+    return (() => {
+      const record = (factory as () => { meta: object })();
+      defineMethod(record, "prefill", function (this: typeof record, value: unknown) {
+        return cloneAnd(this, { meta: { ...(this.meta as object), prefill: value } });
+      });
+      return record;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & {
+        readonly meta: AddOptionalSlot<BaseR["meta"], "prefill", unknown>;
+      } & WithPrefill,
+      "input"
+    >;
+  }) as Builder<
+    BaseR & {
+      readonly meta: AddOptionalSlot<BaseR["meta"], "prefill", unknown>;
+    } & WithPrefill,
+    "input",
+    KindUnion
+  >;
+}
+
+interface WithPlaceholder {
+  placeholder(this: this, text: string): this;
+}
+
+function makePlaceholdable<BaseR extends { meta: object }, KindUnion extends string>(
+  inner: Builder<BaseR, "input", KindUnion>,
+  ..._gate: GateNoSlot<BaseR["meta"], "placeholder">
+): Builder<
+  BaseR & {
+    readonly meta: AddOptionalSlot<BaseR["meta"], "placeholder", string>;
+  } & WithPlaceholder,
+  "input",
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema);
+    return (() => {
+      const record = (factory as () => { meta: object })();
+      defineMethod(record, "placeholder", function (this: typeof record, text: string) {
+        return cloneAnd(this, { meta: { ...(this.meta as object), placeholder: text } });
+      });
+      return record;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & {
+        readonly meta: AddOptionalSlot<BaseR["meta"], "placeholder", string>;
+      } & WithPlaceholder,
+      "input"
+    >;
+  }) as Builder<
+    BaseR & {
+      readonly meta: AddOptionalSlot<BaseR["meta"], "placeholder", string>;
+    } & WithPlaceholder,
+    "input",
+    KindUnion
+  >;
+}
+
+// ----- Number-input-only wrapper ------------------------------------------
+
+// The three numeric slots a number input can carry, stacked onto BaseR's meta.
+type WithNumericMeta<M> = AddOptionalSlot<
+  AddOptionalSlot<AddOptionalSlot<M, "int", boolean>, "min", number>,
+  "max",
+  number
+>;
+
+// `.int()` / `.min(n)` / `.max(n)` for `r.input.number()`. Each records the
+// bound in `meta` (so the schema walker surfaces it to the Home UI as an
+// `<input>` min/max/step without poking Zod internals) and tightens the
+// record's live Zod schema, so the constraint holds wherever it is parsed.
+// Composed onto `baseInput` for the number kind only, so `r.input.text().min()`
+// stays a type error.
+interface WithNumericConstraints {
+  int(this: this): this & { readonly meta: { readonly int: true } };
+  min(this: this, value: number): this & { readonly meta: { readonly min: number } };
+  max(this: this, value: number): this & { readonly meta: { readonly max: number } };
+}
+
+function makeNumericConstraints<BaseR extends { meta: object }, KindUnion extends string>(
+  inner: Builder<BaseR, "input", KindUnion>,
+): Builder<
+  BaseR & { readonly meta: WithNumericMeta<BaseR["meta"]> } & WithNumericConstraints,
+  "input",
+  KindUnion
+> {
+  return (<S extends z.ZodType, K extends KindUnion>(kind: K, schema: S) => {
+    const factory = inner<S, K>(kind, schema);
+    return (() => {
+      // numberInput is only ever composed onto z.number(), so the record's
+      // schema is a ZodNumber at runtime; route through unknown since the
+      // generic S doesn't structurally overlap ZodNumber.
+      const record = (factory as unknown as () => { meta: object; schema: z.ZodNumber })();
+      defineMethod(record, "int", function (this: typeof record) {
+        return cloneAnd(this, {
+          meta: { ...(this.meta as object), int: true },
+          schema: this.schema.int(),
+        });
+      });
+      defineMethod(record, "min", function (this: typeof record, value: number) {
+        return cloneAnd(this, {
+          meta: { ...(this.meta as object), min: value },
+          schema: this.schema.min(value),
+        });
+      });
+      defineMethod(record, "max", function (this: typeof record, value: number) {
+        return cloneAnd(this, {
+          meta: { ...(this.meta as object), max: value },
+          schema: this.schema.max(value),
+        });
+      });
+      return record;
+    }) as unknown as FactoryFor<
+      S,
+      K,
+      BaseR & { readonly meta: WithNumericMeta<BaseR["meta"]> } & WithNumericConstraints,
+      "input"
+    >;
+  }) as Builder<
+    BaseR & { readonly meta: WithNumericMeta<BaseR["meta"]> } & WithNumericConstraints,
+    "input",
+    KindUnion
+  >;
+}
+
+// ----- Composed bases ------------------------------------------------------
+
+export const basePermission = makeOptional(makeDescribable(makeReasonable(makePermRecord)));
+
+// Permission base with `.schema(z)` chained in. Use this for kinds that
+// carry a live Zod object on the record (today: remote.fetchUrl).
+// The chain method is mandatory at the type level — see CompleteOf.
+export const schemablePermission = makeSchemable(basePermission);
+
+export const baseInput = makeOptional(
+  makeDescribable(makeTitleable(makePrefillable(makePlaceholdable(makeInputRecord)))),
+);
+
+// `r.input.number()` adds the numeric-constraint chain on top of baseInput; the
+// other input kinds use baseInput directly, so `.int()/.min()/.max()` only
+// appear on number fields.
+export const numberInput = makeNumericConstraints(baseInput);
+
+// ----- Boundary contracts — derived from the compose chain -----------------
+
+// `R extends WithSchema` means the factory was composed via `makeSchemable`,
+// so a complete record must carry `responseSchema: ZodType` as a value. The
+// else branch ({ responseSchema?: never }) excludes records that carry the
+// property without going through the WithSchema chain.
+export type CompleteOf<B> =
+  B extends Builder<infer R, infer M, infer K>
+    ? M extends "perm"
+      ? (R extends WithReason ? R & { readonly meta: { readonly reason: string } } : R) &
+          (R extends WithSchema
+            ? { readonly responseSchema: z.ZodType<unknown> }
+            : { readonly responseSchema?: never }) & {
+            readonly kind: K;
+            readonly data: unknown;
+          }
+      : R & {
+          readonly kind: K;
+          readonly schema: z.ZodType<unknown>;
+        }
+    : never;
+
+export type CompletePermission = CompleteOf<typeof basePermission>;
+export type CompleteSchemablePermission = CompleteOf<typeof schemablePermission>;
+export type CompleteInput = CompleteOf<typeof baseInput>;

package/src/garage.ts

@@ -0,0 +1,56 @@
+import type { Ref } from "./ref.ts";
+import { interpolate as i } from "./ref.ts";
+import { Service } from "./service.ts";
+
+interface GarageOptions {
+  version?: string;
+}
+
+export class Garage extends Service {
+  readonly image: string;
+  readonly port = 3900;
+  readonly adminPort = 3903;
+  readonly bucket = "data";
+
+  constructor(options?: GarageOptions) {
+    super();
+    this.image = `dxflrs/garage:${options?.version ?? "v1"}`;
+  }
+
+  get accessKey(): Ref<string> {
+    return this.derived("access-key");
+  }
+
+  get secretKey(): Ref<string> {
+    return this.derived("secret-key");
+  }
+
+  get url(): Ref<string> {
+    return i`http://${this.host}:${this.port}`;
+  }
+
+  get adminUrl(): Ref<string> {
+    return i`http://${this.host}:${this.adminPort}`;
+  }
+
+  getServiceDefinition() {
+    return {
+      image: this.image,
+      volumes: [
+        {
+          hostPath: i`./data/${this.host}`,
+          containerPath: "/var/lib/garage/data",
+          backup: { kind: "file-copy" as const },
+        },
+      ],
+      env: {
+        GARAGE_ACCESS_KEY: this.accessKey,
+        GARAGE_SECRET_KEY: this.secretKey,
+        GARAGE_DEFAULT_BUCKET: this.bucket,
+      },
+      healthcheck: {
+        test: ["CMD", "/garage", "status"],
+      },
+    };
+  }
+}

package/src/generator/hash.ts

@@ -0,0 +1,6 @@
+export async function sha256Hex(input: string): Promise<string> {
+  const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}