@kitman-sh/loops 0.0.0-stage → 0.6.0

package/types/packages/core/src/package-declarations.d.ts

@@ -0,0 +1,427 @@
+import * as Schema from 'effect/Schema';
+import { KitKinds } from './kit';
+import type { JsonObject, JsonValue } from './runtime-type';
+import { type ScheduleRule, type ScheduleMisfirePolicy, type ScheduleOverlapPolicy } from './schedule';
+export declare const LoopCapabilities: readonly ['agent_work', 'ask', 'call', 'verify', 'change_request', 'write_back', 'post_comment', 'create_tasks', 'merge_change_request', 'publish_release'];
+declare const JsonObject: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+/** What the control plane reads from a Loop without running it. */
+export declare const LoopManifest: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly title: Schema.String;
+    readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly output: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+    readonly agents: Schema.$Record<Schema.String, Schema.String>;
+    readonly checkout: Schema.Literals<readonly ["none", "read", "write"]>;
+    readonly when: Schema.$Array<Schema.Struct<{
+        readonly event: Schema.String;
+        readonly filter: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.Null]>, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.Null]>>]>>>;
+        readonly input: Schema.$Record<Schema.String, Schema.String>;
+    }>>;
+    readonly offers: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly loop: Schema.String;
+    }>>;
+    readonly capabilities: Schema.$Array<Schema.Literals<readonly ["agent_work", "ask", "call", "verify", "change_request", "write_back", "post_comment", "create_tasks", "merge_change_request", "publish_release"]>>;
+    /** The names of the Secrets the Loop reads. */
+    readonly secrets: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export type LoopManifest = typeof LoopManifest.Type;
+/** An Agent as a Package declares it, with its instructions already read from the repository. */
+export declare const AgentDeclaration: Schema.Struct<{
+    readonly extends: Schema.optionalKey<Schema.String>;
+    readonly instructions: Schema.optionalKey<Schema.String>;
+    readonly harness: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+    readonly effort: Schema.optionalKey<Schema.Literals<readonly ["low", "medium", "high", "xhigh"]>>;
+    readonly kits: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly network: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+        readonly hosts: Schema.$Array<Schema.String>;
+    }>, Schema.Literal<"open">]>>;
+    readonly sandbox: Schema.optionalKey<Schema.Literal<"docker">>;
+}>;
+export type AgentDeclaration = typeof AgentDeclaration.Type;
+/** A recurring start of a Loop, as a Package declares it: by cron, or by a daily or weekly calendar rule. */
+export declare const ScheduleDeclaration: Schema.Union<readonly [Schema.Struct<{
+    readonly name: Schema.String;
+    readonly loop: Schema.String;
+    readonly project: Schema.optionalKey<Schema.String>;
+    readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly timezone: Schema.String;
+    readonly misfire: Schema.optionalKey<Schema.Literals<readonly ["skip", "fire_once", "catch_up"]>>;
+    readonly overlap: Schema.optionalKey<Schema.Literals<readonly ["allow", "skip", "coalesce"]>>;
+    /** Five fields, minute hour day-of-month month day-of-week, read in `timezone`. */
+    readonly cron: Schema.String;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly loop: Schema.String;
+    readonly project: Schema.optionalKey<Schema.String>;
+    readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly timezone: Schema.String;
+    readonly misfire: Schema.optionalKey<Schema.Literals<readonly ["skip", "fire_once", "catch_up"]>>;
+    readonly overlap: Schema.optionalKey<Schema.Literals<readonly ["allow", "skip", "coalesce"]>>;
+    readonly rule: Schema.declare<{
+        readonly frequency: "daily" | "weekly";
+        readonly hour: number;
+        readonly minute: number;
+        readonly second?: number;
+        readonly daysOfWeek?: readonly number[];
+    } | {
+        readonly cron: string;
+    }, unknown>;
+}>]>;
+export type ScheduleDeclaration = typeof ScheduleDeclaration.Type;
+/** A Kit the Package writes from its own files: context text, and each skill's files by path, `SKILL.md` among them. */
+export declare const AuthoredKitDeclaration: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.optionalKey<Schema.Literals<readonly ["technology", "brand", "domain", "process", "other"]>>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly context: Schema.String;
+    readonly skills: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
+}>;
+export type AuthoredKitDeclaration = typeof AuthoredKitDeclaration.Type;
+/** A Marketplace Kit the Workspace installs, by its source's slug or id. */
+export declare const KitInstallationDeclaration: Schema.Struct<{
+    readonly source: Schema.String;
+    readonly version: Schema.optionalKey<Schema.String>;
+}>;
+export type KitInstallationDeclaration = typeof KitInstallationDeclaration.Type;
+/** Where a Kit applies: as Workspace policy, and attached to Projects by slug. */
+export declare const KitAssignmentDeclaration: Schema.Struct<{
+    /** An authored Kit's key, or an installed Kit's source slug. */
+    readonly kit: Schema.String;
+    readonly workspace: Schema.optionalKey<Schema.Literals<readonly ["default", "mandatory"]>>;
+    readonly projects: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export type KitAssignmentDeclaration = typeof KitAssignmentDeclaration.Type;
+export declare const KitDeclaration: Schema.Union<readonly [Schema.Struct<{
+    readonly source: Schema.String;
+    readonly version: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    /** An authored Kit's key, or an installed Kit's source slug. */
+    readonly kit: Schema.String;
+    readonly workspace: Schema.optionalKey<Schema.Literals<readonly ["default", "mandatory"]>>;
+    readonly projects: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly kind: Schema.optionalKey<Schema.Literals<readonly ["technology", "brand", "domain", "process", "other"]>>;
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly context: Schema.String;
+    readonly skills: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
+}>]>;
+export type KitDeclaration = typeof KitDeclaration.Type;
+export declare const isKitInstallation: (declaration: KitDeclaration) => declaration is KitInstallationDeclaration;
+export declare const isKitAssignment: (declaration: KitDeclaration) => declaration is KitAssignmentDeclaration;
+export declare const isAuthoredKit: (declaration: KitDeclaration) => declaration is AuthoredKitDeclaration;
+/** Everything a Package declares, as its build encodes it and Kitman decodes it. */
+export declare const PackageDeclarations: Schema.Struct<{
+    readonly loops: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly output: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+        readonly agents: Schema.$Record<Schema.String, Schema.String>;
+        readonly checkout: Schema.Literals<readonly ["none", "read", "write"]>;
+        readonly when: Schema.$Array<Schema.Struct<{
+            readonly event: Schema.String;
+            readonly filter: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.Null]>, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.Null]>>]>>>;
+            readonly input: Schema.$Record<Schema.String, Schema.String>;
+        }>>;
+        readonly offers: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly title: Schema.String;
+            readonly loop: Schema.String;
+        }>>;
+        readonly capabilities: Schema.$Array<Schema.Literals<readonly ["agent_work", "ask", "call", "verify", "change_request", "write_back", "post_comment", "create_tasks", "merge_change_request", "publish_release"]>>;
+        /** The names of the Secrets the Loop reads. */
+        readonly secrets: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+    readonly agents: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly extends: Schema.optionalKey<Schema.String>;
+        readonly instructions: Schema.optionalKey<Schema.String>;
+        readonly harness: Schema.optionalKey<Schema.String>;
+        readonly model: Schema.optionalKey<Schema.String>;
+        readonly effort: Schema.optionalKey<Schema.Literals<readonly ["low", "medium", "high", "xhigh"]>>;
+        readonly kits: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly network: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly hosts: Schema.$Array<Schema.String>;
+        }>, Schema.Literal<"open">]>>;
+        readonly sandbox: Schema.optionalKey<Schema.Literal<"docker">>;
+    }>>;
+    readonly schedules: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+        readonly name: Schema.String;
+        readonly loop: Schema.String;
+        readonly project: Schema.optionalKey<Schema.String>;
+        readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly timezone: Schema.String;
+        readonly misfire: Schema.optionalKey<Schema.Literals<readonly ["skip", "fire_once", "catch_up"]>>;
+        readonly overlap: Schema.optionalKey<Schema.Literals<readonly ["allow", "skip", "coalesce"]>>;
+        /** Five fields, minute hour day-of-month month day-of-week, read in `timezone`. */
+        readonly cron: Schema.String;
+    }>, Schema.Struct<{
+        readonly name: Schema.String;
+        readonly loop: Schema.String;
+        readonly project: Schema.optionalKey<Schema.String>;
+        readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly timezone: Schema.String;
+        readonly misfire: Schema.optionalKey<Schema.Literals<readonly ["skip", "fire_once", "catch_up"]>>;
+        readonly overlap: Schema.optionalKey<Schema.Literals<readonly ["allow", "skip", "coalesce"]>>;
+        readonly rule: Schema.declare<{
+            readonly frequency: "daily" | "weekly";
+            readonly hour: number;
+            readonly minute: number;
+            readonly second?: number;
+            readonly daysOfWeek?: readonly number[];
+        } | {
+            readonly cron: string;
+        }, unknown>;
+    }>]>>>;
+    readonly kits: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+        readonly source: Schema.String;
+        readonly version: Schema.optionalKey<Schema.String>;
+    }>, Schema.Struct<{
+        /** An authored Kit's key, or an installed Kit's source slug. */
+        readonly kit: Schema.String;
+        readonly workspace: Schema.optionalKey<Schema.Literals<readonly ["default", "mandatory"]>>;
+        readonly projects: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>, Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.optionalKey<Schema.Literals<readonly ["technology", "brand", "domain", "process", "other"]>>;
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly context: Schema.String;
+        readonly skills: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.String>>>;
+    }>]>>>;
+}>;
+export type PackageDeclarations = typeof PackageDeclarations.Type;
+/** What a deploy does to one kind of record, by id. */
+export type PackageChanges = {
+    readonly created: readonly string[];
+    readonly changed: readonly string[];
+    readonly removed: readonly string[];
+};
+/** What a deploy does to records a Package owns, by key; `adopted` names the live record each key takes over. */
+export type PackageRecordChanges = PackageChanges & {
+    readonly adopted: readonly {
+        readonly key: string;
+        readonly id: string;
+    }[];
+};
+/** A Schedule as it is live, and as a Package last deployed it. */
+export type ScheduleRecord = {
+    readonly name?: string;
+    readonly loop: string;
+    readonly projectId: string;
+    readonly input: JsonValue;
+    readonly rule: ScheduleRule;
+    readonly timezone: string;
+    readonly misfire: ScheduleMisfirePolicy;
+    readonly overlap: ScheduleOverlapPolicy;
+    readonly status: 'published' | 'disabled' | 'archived';
+};
+/** One version of a live record: its value, and who made it when. */
+export type RecordChange<V> = {
+    readonly value: V;
+    /** Unknown for records that keep no author. */
+    readonly by?: {
+        readonly actorType: string;
+        readonly actorId: string;
+    };
+    readonly at: string;
+};
+/** An authored Kit as it is live, and as a Package last deployed it. */
+export type AuthoredKitRecord = {
+    readonly name: string;
+    readonly slug: string;
+    readonly kind: (typeof KitKinds)[number];
+    readonly description: string | null;
+    readonly context: string;
+    readonly skills: {
+        readonly [skill: string]: {
+            readonly [path: string]: string;
+        };
+    };
+};
+/** A Workspace's installation of a Kit source, pinned to a version or following the latest. */
+export type KitInstallationRecord = {
+    readonly source: string;
+    readonly version: string | null;
+};
+/** A Kit's Workspace policy mode and the Projects it is attached to. */
+export type KitAssignmentRecord = {
+    /** As declared: an authored Kit's key or an installed Kit's source slug. */
+    readonly kit: string;
+    readonly workspace: 'default' | 'mandatory' | null;
+    readonly projects: readonly string[];
+};
+/** A Kit source the Marketplace offers the Workspace, its versions newest first. */
+export type KitSourceOption = {
+    readonly id: string;
+    readonly slug: string;
+    /** Reviewed, approved, trusted and active, as installing requires. */
+    readonly installable: boolean;
+    readonly versions: readonly {
+        readonly id: string;
+        readonly version: string;
+        readonly installable: boolean;
+        /** The Kit that carries this version's content. */
+        readonly contentKitId?: string;
+    }[];
+};
+/** The live Kit records a deploy plan reads. */
+export type KitSnapshot = {
+    readonly authored: RecordSnapshot<AuthoredKitRecord>;
+    readonly installations: RecordSnapshot<KitInstallationRecord>;
+    /** Unowned entries are keyed by the id of the Kit they assign. */
+    readonly assignments: RecordSnapshot<KitAssignmentRecord>;
+    readonly sources: readonly KitSourceOption[];
+    /** The Workspace's live installations. */
+    readonly installed: readonly KitInstallationRecord[];
+    readonly policyEnabled: boolean;
+};
+export type RecordSnapshot<V> = {
+    readonly owned: readonly OwnedRecord<V>[];
+    readonly unowned: readonly {
+        readonly id: string;
+        readonly value: V;
+    }[];
+};
+/** A record a Package owns; `history` runs oldest first and ends with the live value. */
+export type OwnedRecord<V> = {
+    readonly key: string;
+    readonly id: string;
+    readonly deployed: V;
+    readonly history: readonly RecordChange<V>[];
+};
+export type PackageRecordKind = 'schedule' | 'kit' | 'kit_installation' | 'kit_assignment';
+export type RecordDrift = {
+    readonly kind: PackageRecordKind;
+    readonly key: string;
+    readonly field: string;
+    /** As the Package last deployed it. */
+    readonly declared: JsonValue;
+    readonly live: JsonValue;
+    readonly changedBy?: NonNullable<RecordChange<JsonObject>['by']>;
+    readonly changedAt?: string;
+};
+export type PackagePlanConflict = {
+    readonly kind: 'id_taken';
+    readonly resource: 'loop' | 'agent';
+    readonly id: string;
+    /** The other Package in the layer that declares it. */
+    readonly package: string;
+} | {
+    readonly kind: 'not_for_project';
+    readonly declaration: string;
+} | {
+    readonly kind: 'schedule_project';
+    readonly key: string;
+    /** `missing` in a Workspace Package, `not_allowed` in a Project Package, `unknown` for no such Project. */
+    readonly problem: 'missing' | 'not_allowed' | 'unknown';
+} | {
+    readonly kind: 'loop_unresolved';
+    readonly record: 'schedule';
+    readonly key: string;
+    readonly loop: string;
+} | {
+    readonly kind: 'kit_unresolved';
+    /** An Agent's id, or a Kit assignment's key. */
+    readonly record: 'agent' | 'kit_assignment';
+    readonly key: string;
+    readonly kit: string;
+} | {
+    readonly kind: 'kit_source';
+    readonly key: string;
+    readonly problem: 'unknown' | 'untrusted' | 'version_unknown';
+} | {
+    readonly kind: 'kit_policy_disabled';
+    readonly key: string;
+} | {
+    readonly kind: 'kit_project_unknown';
+    readonly key: string;
+    readonly project: string;
+};
+/** A Loop or Agent the deploy removes that a record outside the Package still names. */
+export type PackagePlanWarning = {
+    readonly kind: 'still_named';
+    readonly resource: 'loop' | 'agent';
+    readonly id: string;
+    readonly record: string;
+};
+/** A plan with conflicts cannot deploy. */
+export type PackagePlan = {
+    readonly loops: PackageChanges;
+    readonly agents: PackageChanges;
+    readonly schedules: PackageRecordChanges;
+    readonly kits: PackageRecordChanges;
+    readonly kitInstallations: PackageRecordChanges;
+    readonly kitAssignments: PackageRecordChanges;
+    readonly drift: readonly RecordDrift[];
+    readonly conflicts: readonly PackagePlanConflict[];
+    readonly warnings: readonly PackagePlanWarning[];
+};
+/** A Package's layer, and where it puts its Schedules. */
+export type PackagePlanScope = {
+    readonly layer: 'project';
+    readonly projectId: string;
+} | {
+    readonly layer: 'workspace';
+    /** The Workspace's Projects, by slug. */
+    readonly projects: ReadonlyMap<string, string>;
+};
+/** The Project a declared Schedule runs in, or why it has none. */
+export declare const scheduleProject: (declaration: ScheduleDeclaration, scope: PackagePlanScope) => {
+    readonly projectId: string;
+} | {
+    readonly problem: 'missing' | 'not_allowed' | 'unknown';
+};
+/** The live Schedule a declaration asks for. */
+export declare const scheduleRecord: (declaration: ScheduleDeclaration, projectId: string) => ScheduleRecord;
+/** The fields where a record's live value left what was deployed, each with the version that last changed it. */
+export declare const recordDrift: (kind: RecordDrift['kind'], owned: OwnedRecord<JsonObject>) => RecordDrift[];
+/** The live Kit an authored Kit declaration asks for; its key is its slug. */
+export declare const authoredKitRecord: (key: string, declaration: AuthoredKitDeclaration) => AuthoredKitRecord;
+/** The installation a declaration asks for, pinned to its version or the newest installable one. */
+export declare const kitInstallationRecord: (declaration: KitInstallationDeclaration, sources: readonly KitSourceOption[]) => KitInstallationRecord | {
+    readonly problem: 'unknown' | 'untrusted' | 'version_unknown';
+};
+/** The assignment a declaration asks for, with its Projects' ids, or the first Project slug that names none. */
+export declare const kitAssignmentRecord: (declaration: KitAssignmentDeclaration, projects: ReadonlyMap<string, string>) => KitAssignmentRecord | {
+    readonly unknownProject: string;
+};
+/**
+ * Compares a Package's current declarations with new ones. `others` are the other Packages in the same layer,
+ * `elsewhere` what the layers beneath it declare, and `otherDeclarations` the kinds the new version declares besides
+ * Loops, Agents and Schedules. `schedules` holds the Schedules the Package owns and, for adoption, those no Package owns;
+ * `outside` the records outside the Package that name a Loop or Agent.
+ */
+export declare const planPackageDeploy: (input: {
+    readonly scope: PackagePlanScope;
+    readonly current?: PackageDeclarations;
+    readonly next: PackageDeclarations;
+    readonly otherDeclarations?: readonly string[];
+    readonly others: readonly {
+        readonly name: string;
+        readonly loops: readonly string[];
+        readonly agents: readonly string[];
+    }[];
+    readonly elsewhere?: {
+        readonly loops: readonly string[];
+        readonly agents: readonly string[];
+    };
+    readonly schedules?: {
+        readonly owned: readonly OwnedRecord<ScheduleRecord>[];
+        readonly unowned: readonly {
+            readonly id: string;
+            readonly value: ScheduleRecord;
+        }[];
+    };
+    readonly outside?: readonly {
+        readonly record: string;
+        readonly loop?: string;
+        readonly agent?: string;
+    }[];
+    readonly kits?: KitSnapshot;
+}) => PackagePlan;
+export {};