@forgezero/agent 0.1.53 → 0.1.56

package/dist/deploy-providers.d.ts

@@ -0,0 +1,85 @@
+import { type Condition, type RequirementDefinition } from './deploy';
+export interface BunProviderConfig {
+    installScope: 'host';
+}
+export interface DockerProviderConfig {
+    installScope: 'host';
+    storageDriver: 'overlay2';
+    dataRoot: string;
+    liveRestore: boolean;
+    logDriver: 'journald' | 'local';
+    defaultNetwork: 'bridge';
+    rootless: boolean;
+}
+export interface NginxProviderConfig {
+    installScope: 'host';
+    websocket: boolean;
+    maximumBodyMiB: number;
+    workerProcesses: 'auto' | number;
+    workerConnections: number;
+}
+export interface ArangoDbProviderConfig {
+    installScope: 'host';
+    runtime: 'native';
+    dataPath: string;
+    bind: 'private';
+}
+export interface CloudflaredProviderConfig {
+    installScope: 'host';
+    mode: 'tunnel';
+}
+export interface WarpProviderConfig {
+    installScope: 'host';
+    mode: 'device' | 'mesh';
+}
+export interface UfwProviderConfig {
+    installScope: 'host';
+    defaultIncoming: 'deny';
+    defaultOutgoing: 'allow';
+}
+export interface OpenSshProviderConfig {
+    installScope: 'host';
+    mode: 'client';
+}
+export interface SystemdProviderConfig {
+    installScope: 'host';
+    credentials: 'encrypted';
+    serviceSandbox: 'strict';
+}
+type RequirementOptions<T> = {
+    version: string;
+    config?: Partial<T>;
+    when?: Condition;
+};
+export declare const providers: {
+    readonly bun: {
+        readonly require: (options?: RequirementOptions<BunProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly docker: {
+        readonly require: (options?: RequirementOptions<DockerProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly nginx: {
+        readonly require: (options?: RequirementOptions<NginxProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly arangodb: {
+        readonly require: (options?: RequirementOptions<ArangoDbProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly cloudflared: {
+        readonly require: (options?: RequirementOptions<CloudflaredProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly warp: {
+        readonly require: (options?: RequirementOptions<WarpProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly ufw: {
+        readonly require: (options?: RequirementOptions<UfwProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly openssh: {
+        readonly require: (options?: RequirementOptions<OpenSshProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+    readonly systemd: {
+        readonly require: (options?: RequirementOptions<SystemdProviderConfig>) => RequirementDefinition<import("./deploy").JsonObject>;
+    };
+};
+/** Runtime validation for package-owned provider contracts; TypeScript is not a trust boundary. */
+export declare function validateBuiltInProvider(requirement: RequirementDefinition, where: string): void;
+export {};

package/dist/deploy.d.ts

@@ -0,0 +1,439 @@
+/**
+ * TypeScript authoring surface for ForgeZero deployment plans.
+ *
+ * This module only constructs inert data. The production Agent never imports a
+ * repository's TypeScript definition; `fz deploy compile` turns it into the
+ * canonical JSON plan consumed by the Agent.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type InputDefinition = {
+    type: 'string';
+    required?: boolean;
+    default?: string;
+    minimumLength?: number;
+    maximumLength?: number;
+    pattern?: string;
+} | {
+    type: 'integer';
+    required?: boolean;
+    default?: number;
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: 'number';
+    required?: boolean;
+    default?: number;
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: 'boolean';
+    required?: boolean;
+    default?: boolean;
+} | {
+    type: 'enum';
+    values: readonly string[];
+    required?: boolean;
+    default?: string;
+} | {
+    type: 'hostname';
+    required?: boolean;
+    default?: string;
+};
+export interface ValueReference {
+    readonly $ref: `inputs.${string}` | `steps.${string}.status` | `steps.${string}.outputs.${string}` | `components.${string}.${string}` | `targets.${string}.${string}` | `deployment.${string}`;
+}
+export type ResolvableJsonValue = JsonPrimitive | ValueReference | readonly ResolvableJsonValue[] | {
+    [key: string]: ResolvableJsonValue;
+};
+export type ResolvableJsonObject = {
+    [key: string]: ResolvableJsonValue;
+};
+export type ConditionOperand = JsonPrimitive | ValueReference;
+export type Condition = {
+    all: readonly Condition[];
+} | {
+    any: readonly Condition[];
+} | {
+    not: Condition;
+} | {
+    equals: readonly [ConditionOperand, ConditionOperand];
+} | {
+    notEquals: readonly [ConditionOperand, ConditionOperand];
+} | {
+    greaterThan: readonly [ConditionOperand, ConditionOperand];
+} | {
+    greaterThanOrEqual: readonly [ConditionOperand, ConditionOperand];
+} | {
+    lessThan: readonly [ConditionOperand, ConditionOperand];
+} | {
+    lessThanOrEqual: readonly [ConditionOperand, ConditionOperand];
+} | {
+    contains: readonly [ConditionOperand, ConditionOperand];
+} | {
+    startsWith: readonly [ConditionOperand, ConditionOperand];
+} | {
+    exists: ValueReference;
+} | {
+    succeeded: string;
+} | {
+    failed: string;
+} | {
+    changed: string;
+};
+export interface CredentialDefinition {
+    schema: string;
+    source: {
+        kind: 'vault' | 'systemd';
+        name: string;
+        fallback?: 'systemd';
+    };
+}
+export interface TargetDefinition {
+    kind: 'compute';
+    selector: {
+        profiles: readonly string[];
+        confidentialCompute?: 'required' | 'preferred' | 'disabled';
+        labels?: Readonly<Record<string, string>>;
+    };
+    cardinality: {
+        minimum: number;
+        desired: number | ValueReference;
+        maximum: number;
+    };
+    placement?: {
+        spreadBy?: readonly ('metal' | 'region' | 'zone')[];
+        antiAffinity?: readonly string[];
+    };
+}
+export interface RequirementDefinition<TConfig extends JsonObject = JsonObject> {
+    capability: string;
+    provider: string;
+    contract: number;
+    version: string;
+    config: TConfig;
+    when?: Condition;
+}
+export interface ResourceDefinition {
+    cpu?: {
+        limit: number;
+        weight?: number;
+        pinning?: 'automatic' | 'dedicated';
+    };
+    memory?: {
+        limitMiB: number;
+        reservationMiB?: number;
+        swap?: 'disabled' | 'bounded';
+    };
+    pids?: {
+        limit: number;
+    };
+    io?: {
+        weight?: number;
+        readBps?: number;
+        writeBps?: number;
+        readIops?: number;
+        writeIops?: number;
+    };
+}
+export interface HealthDefinition {
+    protocol: 'http';
+    method: 'GET' | 'HEAD';
+    path: string;
+    expectedStatus: readonly number[];
+    timeoutMs: number;
+    intervalMs?: number;
+    attempts?: number;
+}
+export type StorageMount = {
+    class: 'ephemeral';
+    path: string;
+    type: 'tmpfs';
+    sizeMiB: number;
+} | {
+    class: 'persistent';
+    name: string;
+    path: string;
+    minimumFreePercent?: number;
+} | {
+    class: 'database';
+    name: string;
+    path: string;
+    minimumFreePercent: number;
+    minimumIops?: number;
+    latencyTargetMs?: number;
+};
+export interface NetworkDefinition {
+    ingress?: {
+        exposure: 'loopback' | 'private' | 'public';
+        stablePort?: number;
+    };
+    private?: {
+        mode: 'private-lan' | 'cloudflare-warp' | 'auto';
+        preferences?: readonly ('private-lan' | 'cloudflare-warp')[];
+    };
+    public?: {
+        mode: 'disabled' | 'cloudflare-tunnel';
+        optional?: boolean;
+    };
+    container?: {
+        mode: 'bridge' | 'host';
+        network?: string;
+    };
+}
+export type ApplicationRuntime = {
+    kind: 'native';
+    provider: string;
+    requirement: string;
+    argv: readonly string[];
+} | {
+    kind: 'container';
+    provider: string;
+    requirement: string;
+    image: {
+        source: {
+            kind: 'build';
+            context: string;
+            dockerfile: string;
+        } | {
+            kind: 'registry';
+            reference: string;
+        };
+    };
+    entrypoint?: readonly string[];
+    security: {
+        privileged: false;
+        noNewPrivileges: true;
+        root: 'read-only' | 'writable';
+        dropCapabilities: readonly string[];
+    };
+};
+export interface ApplicationComponent {
+    kind: 'application';
+    target: string;
+    runtime: ApplicationRuntime;
+    service: {
+        protocol: 'http';
+        port: number;
+        health: HealthDefinition;
+        websocket?: boolean;
+        maximumConnections?: number;
+    };
+    resources: ResourceDefinition;
+    storage?: readonly StorageMount[];
+    network?: NetworkDefinition;
+    rollout: {
+        strategy: 'direct' | 'blue-green' | 'rolling' | 'canary';
+        proxy?: string;
+        drainMs?: number;
+        automaticRollback?: boolean;
+    };
+}
+export interface DatabaseComponent {
+    kind: 'database';
+    target: string;
+    runtime: {
+        provider: string;
+        requirement: string;
+        mode: 'native';
+    };
+    topology: {
+        mode: 'standalone';
+    } | {
+        mode: 'cluster';
+        bootstrapMembers: number;
+        replicationFactor: number;
+        writeConcern: number;
+        additionalJoiners: 'allowed' | 'disabled';
+    };
+    resources?: ResourceDefinition;
+    storage: StorageMount & {
+        class: 'database';
+    };
+    network: NetworkDefinition;
+}
+export type ComponentDefinition = ApplicationComponent | DatabaseComponent;
+export type StepScope = {
+    kind: 'release-executor';
+} | {
+    kind: 'elected-one';
+    group: string;
+} | {
+    kind: 'each-target';
+    target: string;
+} | {
+    kind: 'target-batches';
+    target: string;
+    size: number;
+};
+export interface RetryDefinition {
+    attempts: number;
+    backoff: {
+        kind: 'fixed' | 'linear' | 'exponential';
+        initialMs: number;
+        maximumMs: number;
+    };
+    retryOn?: readonly ('network' | 'timeout' | 'provider-unavailable' | 'rate-limited' | 'conflict')[];
+}
+export interface WorkflowStepDefinition<TWith extends ResolvableJsonObject = ResolvableJsonObject> {
+    uses: `${string}@${number}`;
+    with: TWith;
+    if?: Condition;
+    scope: StepScope;
+    timeoutMs?: number;
+    retry?: RetryDefinition;
+    failure?: {
+        policy: 'continue' | 'stop' | 'rollback-stage' | 'rollback-deployment' | 'compensate' | 'manual-intervention';
+    };
+    compensate?: {
+        uses: `${string}@${number}`;
+        with: ResolvableJsonObject;
+    };
+}
+export interface StageDefinition {
+    dependsOn?: readonly string[];
+    if?: Condition;
+    strategy: {
+        mode: 'sequential' | 'parallel' | 'rolling' | 'blue-green' | 'canary';
+        maximumConcurrency?: number;
+        batchSize?: number;
+        minimumHealthy?: number;
+        increments?: readonly number[];
+        observationMs?: number;
+    };
+    steps: Readonly<Record<string, WorkflowStepDefinition>>;
+}
+export interface WorkflowDefinition {
+    concurrency?: {
+        group: string;
+        limit: number;
+    };
+    stages: Readonly<Record<string, StageDefinition>>;
+}
+export interface DeploymentSource {
+    apiVersion: 'deploy.forgezero.net/v1';
+    kind: 'Deployment';
+    metadata: {
+        name: string;
+        description?: string;
+    };
+    spec: {
+        security?: {
+            attestation?: 'required' | 'preferred' | 'disabled';
+        };
+        inputs?: Readonly<Record<string, InputDefinition>>;
+        credentials?: Readonly<Record<string, CredentialDefinition>>;
+        targets: Readonly<Record<string, TargetDefinition>>;
+        requirements?: Readonly<Record<string, RequirementDefinition>>;
+        components: Readonly<Record<string, ComponentDefinition>>;
+        workflows: Readonly<Record<string, WorkflowDefinition>>;
+    };
+}
+export declare const input: {
+    string: (value?: Omit<Extract<InputDefinition, {
+        type: "string";
+    }>, "type">) => {
+        readonly required?: boolean;
+        readonly default?: string;
+        readonly minimumLength?: number;
+        readonly maximumLength?: number;
+        readonly pattern?: string;
+        readonly type: "string";
+    };
+    integer: (value?: Omit<Extract<InputDefinition, {
+        type: "integer";
+    }>, "type">) => {
+        readonly required?: boolean;
+        readonly default?: number;
+        readonly minimum?: number;
+        readonly maximum?: number;
+        readonly type: "integer";
+    };
+    number: (value?: Omit<Extract<InputDefinition, {
+        type: "number";
+    }>, "type">) => {
+        readonly required?: boolean;
+        readonly default?: number;
+        readonly minimum?: number;
+        readonly maximum?: number;
+        readonly type: "number";
+    };
+    boolean: (value?: Omit<Extract<InputDefinition, {
+        type: "boolean";
+    }>, "type">) => {
+        readonly required?: boolean;
+        readonly default?: boolean;
+        readonly type: "boolean";
+    };
+    enum: <const T extends readonly string[]>(value: {
+        values: T;
+        required?: boolean;
+        default?: T[number];
+    }) => {
+        readonly values: T;
+        readonly required?: boolean;
+        readonly default?: T[number];
+        readonly type: "enum";
+    };
+    hostname: (value?: Omit<Extract<InputDefinition, {
+        type: "hostname";
+    }>, "type">) => {
+        readonly required?: boolean;
+        readonly default?: string;
+        readonly type: "hostname";
+    };
+    ref: <T extends string>(name: T) => ValueReference;
+};
+export declare const ref: {
+    stepStatus: (step: string) => ValueReference;
+    stepOutput: (step: string, output: string) => ValueReference;
+    component: (component: string, property: string) => ValueReference;
+    target: (target: string, property: string) => ValueReference;
+    deployment: (property: string) => ValueReference;
+};
+export declare const conditions: {
+    all: (...values: Condition[]) => Condition;
+    any: (...values: Condition[]) => Condition;
+    not: (value: Condition) => Condition;
+    equals: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    notEquals: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    greaterThan: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    greaterThanOrEqual: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    lessThan: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    lessThanOrEqual: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    contains: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    startsWith: (left: ConditionOperand, right: ConditionOperand) => Condition;
+    exists: (value: ValueReference) => Condition;
+    succeeded: (step: string) => Condition;
+    failed: (step: string) => Condition;
+    changed: (step: string) => Condition;
+};
+export declare const credential: {
+    vault: (value: {
+        schema: string;
+        name: string;
+        fallback?: "systemd";
+    }) => CredentialDefinition;
+    systemd: (value: {
+        schema: string;
+        name: string;
+    }) => CredentialDefinition;
+};
+export declare const target: {
+    compute: (value: Omit<TargetDefinition, "kind">) => TargetDefinition;
+};
+export declare function requirement<TConfig extends JsonObject>(value: RequirementDefinition<TConfig>): RequirementDefinition<TConfig>;
+export declare function application(value: Omit<ApplicationComponent, 'kind'>): ApplicationComponent;
+export declare function database(value: Omit<DatabaseComponent, 'kind'>): DatabaseComponent;
+export declare function step<TWith extends ResolvableJsonObject>(value: WorkflowStepDefinition<TWith>): WorkflowStepDefinition<TWith>;
+export declare function stage(value: StageDefinition): StageDefinition;
+export declare function workflow(value: WorkflowDefinition): WorkflowDefinition;
+export declare function defineDeployment<const T extends DeploymentSource>(definition: T): T;
+export { actions } from './deploy-actions';
+export { providers } from './deploy-providers';
+export type { ArangoDbProviderConfig, BunProviderConfig, CloudflaredProviderConfig, DockerProviderConfig, NginxProviderConfig, OpenSshProviderConfig, SystemdProviderConfig, UfwProviderConfig, WarpProviderConfig } from './deploy-providers';

package/dist/deploy.js

@@ -0,0 +1,169 @@
+// src/deploy-actions.ts
+function action(uses, withValue, options) {
+  return step({ uses, with: withValue, scope: options.scope, ...options.if ? { if: options.if } : {}, ...options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}, ...options.retry ? { retry: options.retry } : {}, ...options.failure ? { failure: options.failure } : {}, ...options.compensate ? { compensate: options.compensate } : {} });
+}
+var actions = {
+  software: {
+    ensure: (withValue, options) => action("forgezero.software/ensure@1", withValue, options)
+  },
+  exec: {
+    argv: (withValue, options) => action("forgezero.exec/argv@1", withValue, options)
+  },
+  container: {
+    build: (withValue, options) => action("forgezero.oci/build@1", withValue, options),
+    pull: (withValue, options) => action("forgezero.oci/pull@1", withValue, options)
+  },
+  service: {
+    deploy: (withValue, options) => action("forgezero.service/deploy@1", withValue, options),
+    health: (withValue, options) => action("forgezero.health/http@1", withValue, options),
+    promote: (withValue, options) => action("forgezero.service/promote@1", withValue, options)
+  },
+  storage: {
+    verify: (withValue, options) => action("forgezero.storage/verify@1", withValue, options)
+  },
+  extension: (uses, withValue, options) => action(uses, withValue, options)
+};
+// src/deploy-providers.ts
+function define(capability, provider, options, defaults) {
+  return requirement({
+    capability,
+    provider,
+    contract: 1,
+    version: options.version,
+    config: { ...defaults, ...options.config ?? {} },
+    ...options.when ? { when: options.when } : {}
+  });
+}
+var providers = {
+  bun: {
+    require: (options = { version: "1.3.14" }) => define("runtime.javascript", "forgezero.bun", options, { installScope: "host" })
+  },
+  docker: {
+    require: (options = { version: "ubuntu-26.04" }) => define("runtime.container", "forgezero.docker", options, {
+      installScope: "host",
+      storageDriver: "overlay2",
+      dataRoot: "/var/lib/docker",
+      liveRestore: true,
+      logDriver: "local",
+      defaultNetwork: "bridge",
+      rootless: false
+    })
+  },
+  nginx: {
+    require: (options = { version: "ubuntu-26.04" }) => define("proxy.http", "forgezero.nginx", options, {
+      installScope: "host",
+      websocket: true,
+      maximumBodyMiB: 16,
+      workerProcesses: "auto",
+      workerConnections: 4096
+    })
+  },
+  arangodb: {
+    require: (options = { version: "3.11.14" }) => define("database.arangodb", "forgezero.arangodb", options, {
+      installScope: "host",
+      runtime: "native",
+      dataPath: "/var/lib/arangodb3",
+      bind: "private"
+    })
+  },
+  cloudflared: {
+    require: (options = { version: "2026.7.3" }) => define("network.public-tunnel", "forgezero.cloudflared", options, { installScope: "host", mode: "tunnel" })
+  },
+  warp: {
+    require: (options = { version: "2026.6.822.0-min" }) => define("network.private", "forgezero.warp", options, { installScope: "host", mode: "device" })
+  },
+  ufw: {
+    require: (options = { version: "ubuntu-26.04" }) => define("security.firewall", "forgezero.ufw", options, { installScope: "host", defaultIncoming: "deny", defaultOutgoing: "allow" })
+  },
+  openssh: {
+    require: (options = { version: "ubuntu-26.04" }) => define("transport.ssh", "forgezero.openssh", options, { installScope: "host", mode: "client" })
+  },
+  systemd: {
+    require: (options = { version: "ubuntu-26.04" }) => define("service.manager", "forgezero.systemd", options, { installScope: "host", credentials: "encrypted", serviceSandbox: "strict" })
+  }
+};
+
+// src/deploy.ts
+var input = {
+  string: (value = {}) => ({ type: "string", ...value }),
+  integer: (value = {}) => ({ type: "integer", ...value }),
+  number: (value = {}) => ({ type: "number", ...value }),
+  boolean: (value = {}) => ({ type: "boolean", ...value }),
+  enum: (value) => ({ type: "enum", ...value }),
+  hostname: (value = {}) => ({ type: "hostname", ...value }),
+  ref: (name) => ({ $ref: `inputs.${name}` })
+};
+var ref = {
+  stepStatus: (step2) => ({ $ref: `steps.${step2}.status` }),
+  stepOutput: (step2, output) => ({ $ref: `steps.${step2}.outputs.${output}` }),
+  component: (component, property) => ({ $ref: `components.${component}.${property}` }),
+  target: (target, property) => ({ $ref: `targets.${target}.${property}` }),
+  deployment: (property) => ({ $ref: `deployment.${property}` })
+};
+var conditions = {
+  all: (...values) => ({ all: values }),
+  any: (...values) => ({ any: values }),
+  not: (value) => ({ not: value }),
+  equals: (left, right) => ({ equals: [left, right] }),
+  notEquals: (left, right) => ({ notEquals: [left, right] }),
+  greaterThan: (left, right) => ({ greaterThan: [left, right] }),
+  greaterThanOrEqual: (left, right) => ({ greaterThanOrEqual: [left, right] }),
+  lessThan: (left, right) => ({ lessThan: [left, right] }),
+  lessThanOrEqual: (left, right) => ({ lessThanOrEqual: [left, right] }),
+  contains: (left, right) => ({ contains: [left, right] }),
+  startsWith: (left, right) => ({ startsWith: [left, right] }),
+  exists: (value) => ({ exists: value }),
+  succeeded: (step2) => ({ succeeded: step2 }),
+  failed: (step2) => ({ failed: step2 }),
+  changed: (step2) => ({ changed: step2 })
+};
+var credential = {
+  vault: (value) => ({
+    schema: value.schema,
+    source: { kind: "vault", name: value.name, ...value.fallback ? { fallback: value.fallback } : {} }
+  }),
+  systemd: (value) => ({
+    schema: value.schema,
+    source: { kind: "systemd", name: value.name }
+  })
+};
+var target = {
+  compute: (value) => ({ kind: "compute", ...value })
+};
+function requirement(value) {
+  return value;
+}
+function application(value) {
+  return { kind: "application", ...value };
+}
+function database(value) {
+  return { kind: "database", ...value };
+}
+function step(value) {
+  return value;
+}
+function stage(value) {
+  return value;
+}
+function workflow(value) {
+  return value;
+}
+function defineDeployment(definition) {
+  return definition;
+}
+export {
+  workflow,
+  target,
+  step,
+  stage,
+  requirement,
+  ref,
+  providers,
+  input,
+  defineDeployment,
+  database,
+  credential,
+  conditions,
+  application,
+  actions
+};