@hunsu/core 0.1.0

package/dist/board.js

@@ -0,0 +1,223 @@
+import { err, ok } from "@hunsu/protocol";
+import { getTrailer, parseTrailers } from "./trailer.js";
+import { InvalidTrailerError } from "./errors.js";
+import { makeCommitSha, makeGitGoal, makeGitHunsuId, makeGitMoveId, makeGitMoveNumber, makeGitPriority, makeGitRunId, makeGitTrailerActor, makeGitTrailerRole } from "./primitives.js";
+const HUNSU_EVENT_TYPES = ["move", "hunsu"];
+const MOVE_EVENT_STATUSES = ["complete", "failed", "blocked"];
+export function commitToBoardEvent(commit) {
+    const trailers = parseCommitTrailers(commit);
+    if (!trailers.ok)
+        return trailers;
+    const eventType = tryParseHunsuEventType(getTrailer(trailers.value, "Hunsu-Event"), commit.sha);
+    if (!eventType.ok)
+        return eventType;
+    if (eventType.value === "move") {
+        const runId = parseRequiredTrailer(trailers.value, "Hunsu-Run", commit.sha, makeGitRunId);
+        if (!runId.ok)
+            return runId;
+        const moveNumber = parseRequiredTrailer(trailers.value, "Hunsu-Move", commit.sha, makeGitMoveNumber, "invalid_move_number");
+        if (!moveNumber.ok)
+            return moveNumber;
+        const moveId = parseRequiredTrailer(trailers.value, "Hunsu-Move", commit.sha, makeGitMoveId, "invalid_move_number");
+        if (!moveId.ok)
+            return moveId;
+        const role = parseRequiredTrailer(trailers.value, "Hunsu-Role", commit.sha, makeGitTrailerRole);
+        if (!role.ok)
+            return role;
+        const actor = parseRequiredTrailer(trailers.value, "Hunsu-Actor", commit.sha, makeGitTrailerActor);
+        if (!actor.ok)
+            return actor;
+        const statusValue = requireTrailerResult(trailers.value, "Hunsu-Status", commit.sha);
+        if (!statusValue.ok)
+            return statusValue;
+        const status = makeMoveEventStatus(statusValue.value, commit.sha);
+        if (!status.ok)
+            return status;
+        const goal = parseRequiredTrailer(trailers.value, "Hunsu-Goal", commit.sha, makeGitGoal);
+        if (!goal.ok)
+            return goal;
+        return ok({
+            type: "move",
+            commit,
+            runId: runId.value,
+            moveNumber: moveNumber.value,
+            moveId: moveId.value,
+            goal: goal.value,
+            role: role.value,
+            actor: actor.value,
+            status: status.value,
+            trailers: trailers.value
+        });
+    }
+    if (eventType.value === "hunsu") {
+        const hunsuId = parseRequiredTrailer(trailers.value, "Hunsu-ID", commit.sha, makeGitHunsuId);
+        if (!hunsuId.ok)
+            return hunsuId;
+        const target = parseRequiredTrailer(trailers.value, "Hunsu-Target", commit.sha, makeCommitSha);
+        if (!target.ok)
+            return target;
+        const sourceRun = parseRequiredTrailer(trailers.value, "Hunsu-Source-Run", commit.sha, makeGitRunId);
+        if (!sourceRun.ok)
+            return sourceRun;
+        const newRun = parseRequiredTrailer(trailers.value, "Hunsu-New-Run", commit.sha, makeGitRunId);
+        if (!newRun.ok)
+            return newRun;
+        const role = parseRequiredTrailer(trailers.value, "Hunsu-Role", commit.sha, makeGitTrailerRole);
+        if (!role.ok)
+            return role;
+        const actor = parseRequiredTrailer(trailers.value, "Hunsu-Actor", commit.sha, makeGitTrailerActor);
+        if (!actor.ok)
+            return actor;
+        const priority = parseOptionalTrailer(trailers.value, "Hunsu-Priority", commit.sha, makeGitPriority);
+        if (!priority.ok)
+            return priority;
+        return ok({
+            type: "hunsu",
+            commit,
+            hunsuId: hunsuId.value,
+            target: target.value,
+            sourceRun: sourceRun.value,
+            newRun: newRun.value,
+            role: role.value,
+            actor: actor.value,
+            priority: priority.value,
+            trailers: trailers.value
+        });
+    }
+    return ok(null);
+}
+export function createBoardFromCommits(commits) {
+    const events = commits
+        .map(commitToBoardEvent)
+        .map(unwrapTrailerParseResult)
+        .filter((event) => event !== null)
+        .sort(compareEvents);
+    const runsById = new Map();
+    const moves = [];
+    const hunsus = [];
+    const positions = new Map();
+    for (const event of events) {
+        if (event.type === "move") {
+            moves.push(event);
+            const run = getOrCreateRun(runsById, event.runId);
+            run.moves.push(event);
+            run.events.push(event);
+            positions.set(event.commit.sha, event);
+            positions.set(event.commit.shortSha, event);
+            positions.set(event.moveId, event);
+            positions.set(`${event.runId}:${event.moveId}`, event);
+        }
+        else {
+            hunsus.push(event);
+            const sourceRun = getOrCreateRun(runsById, event.sourceRun);
+            sourceRun.hunsus.push(event);
+            sourceRun.events.push(event);
+            const newRun = getOrCreateRun(runsById, event.newRun);
+            newRun.hunsus.push(event);
+            newRun.events.push(event);
+        }
+    }
+    for (const run of runsById.values()) {
+        run.moves.sort(compareEvents);
+        run.hunsus.sort(compareEvents);
+        run.events.sort(compareEvents);
+    }
+    return {
+        runs: [...runsById.values()].sort((left, right) => left.runId.localeCompare(right.runId)),
+        moves,
+        hunsus,
+        positions
+    };
+}
+function getOrCreateRun(runsById, runId) {
+    const existing = runsById.get(runId);
+    if (existing) {
+        return existing;
+    }
+    const run = { runId, moves: [], hunsus: [], events: [] };
+    runsById.set(runId, run);
+    return run;
+}
+function compareEvents(left, right) {
+    const leftTime = Date.parse(left.commit.authoredAt);
+    const rightTime = Date.parse(right.commit.authoredAt);
+    if (Number.isFinite(leftTime) && Number.isFinite(rightTime) && leftTime !== rightTime) {
+        return leftTime - rightTime;
+    }
+    if (left.type === "move" && right.type === "move") {
+        const moveOrder = compareMoveNumbers(left.moveNumber, right.moveNumber);
+        if (moveOrder !== 0) {
+            return moveOrder;
+        }
+    }
+    return left.commit.sha.localeCompare(right.commit.sha);
+}
+function compareMoveNumbers(left, right) {
+    const leftNumber = Number(left);
+    const rightNumber = Number(right);
+    if (Number.isFinite(leftNumber) && Number.isFinite(rightNumber) && leftNumber !== rightNumber) {
+        return leftNumber - rightNumber;
+    }
+    return left.localeCompare(right);
+}
+export function parseHunsuEventType(value, commitSha) {
+    return unwrapTrailerParseResult(tryParseHunsuEventType(value, commitSha));
+}
+export function parseMoveEventStatus(value, commitSha) {
+    return unwrapTrailerParseResult(makeMoveEventStatus(value, commitSha));
+}
+function parseCommitTrailers(commit) {
+    try {
+        return ok(parseTrailers(commit.body));
+    }
+    catch (error) {
+        return trailerParseError("invalid_trailer_block", commit.sha, undefined, undefined, error instanceof Error ? error.message : String(error));
+    }
+}
+function tryParseHunsuEventType(value, commitSha) {
+    if (value === undefined) {
+        return ok(undefined);
+    }
+    if (HUNSU_EVENT_TYPES.includes(value)) {
+        return ok(value);
+    }
+    return trailerParseError("invalid_hunsu_event_type", commitSha, "Hunsu-Event", value, `Commit ${commitSha} has unsupported Hunsu-Event ${value}`);
+}
+function makeMoveEventStatus(value, commitSha) {
+    if (typeof value === "string" && MOVE_EVENT_STATUSES.includes(value)) {
+        return ok(value);
+    }
+    return trailerParseError("invalid_move_status", commitSha, "Hunsu-Status", String(value), `Commit ${commitSha} has unsupported Hunsu-Status ${String(value)}`);
+}
+function requireTrailerResult(trailers, key, commitSha) {
+    const value = getTrailer(trailers, key);
+    return value ? ok(value) : trailerParseError("missing_trailer", commitSha, key, undefined, `Commit ${commitSha} is missing required trailer ${key}`);
+}
+function parseRequiredTrailer(trailers, key, commitSha, parser, code = "invalid_trailer_value") {
+    const value = requireTrailerResult(trailers, key, commitSha);
+    if (!value.ok)
+        return value;
+    const parsed = parser(value.value, key);
+    return parsed.ok
+        ? ok(parsed.value)
+        : trailerParseError(code, commitSha, key, value.value, `Commit ${commitSha} has invalid ${key}: ${parsed.error.message}`);
+}
+function parseOptionalTrailer(trailers, key, commitSha, parser, code = "invalid_trailer_value") {
+    const value = getTrailer(trailers, key);
+    if (value === undefined) {
+        return ok(undefined);
+    }
+    const parsed = parser(value, key);
+    return parsed.ok
+        ? ok(parsed.value)
+        : trailerParseError(code, commitSha, key, value, `Commit ${commitSha} has invalid ${key}: ${parsed.error.message}`);
+}
+function trailerParseError(code, commitSha, trailer, value, message) {
+    return err({ type: "TrailerParseError", code, commitSha, trailer, value, message });
+}
+function unwrapTrailerParseResult(result) {
+    if (result.ok) {
+        return result.value;
+    }
+    throw new InvalidTrailerError(result.error.message);
+}

package/dist/domain-store.d.ts

@@ -0,0 +1,268 @@
+import { type Result } from "@hunsu/protocol";
+import type { AgentConversationRef, ArtifactActionDefinition, BoardProjection, Command, Destination, DomainEvent, ExecutorEntity, ExecutorId, GuardrailConfig, HubPackageLock, HunsuOrigin, MoveId, NodeId, ExecutionPlan, PathId, MemberPath, PositiveInteger, ResourceEntity, WorktreeRef } from "@hunsu/protocol";
+import type { CommitSha, RuntimeChecksum } from "./primitives.ts";
+export declare const HUNSU_COMPLETED_DESTINATIONS_PATH = ".hunsu/completed-destinations.hunsu";
+export declare const HUNSU_DESTINATIONS_PATH = ".hunsu/destinations.hunsu";
+export declare const HUNSU_HARNESS_PATH = ".hunsu/harness.hunsu";
+export declare const HUNSU_EXECUTORS_PATH = ".hunsu/executors.hunsu";
+export declare const HUNSU_RESOURCES_PATH = ".hunsu/resources.hunsu";
+export declare const HUNSU_ARTIFACT_ACTIONS_PATH = ".hunsu/artifact-actions.hunsu";
+export declare const HUNSU_CURRENT_EXECUTION_PATH = ".hunsu/current-execution.hunsu";
+export declare const HUNSU_PREVIOUS_EXECUTION_PATH = ".hunsu/previous-execution.hunsu";
+export declare const HUNSU_HUNSU_DRAFT_PATH = ".hunsu/hunsu-draft.hunsu";
+export declare const HUNSU_RUNTIME_PATHS: readonly [".hunsu/completed-destinations.hunsu", ".hunsu/destinations.hunsu", ".hunsu/harness.hunsu", ".hunsu/executors.hunsu", ".hunsu/resources.hunsu", ".hunsu/artifact-actions.hunsu"];
+export declare const HUNSU_LEGACY_STATE_PATH = ".hunsu/state.hunsu";
+export declare const HUNSU_RUNTIME_ENCODING = "gzip+base64url";
+export declare const HUNSU_DRAFT_RUNTIME_FILE_NAMES: readonly ["destinations.json", "harness.json", "executors.json", "resources.json", "artifact-actions.json"];
+export declare const HUNSU_SELF_COMMIT_REF: MoveCommitRef;
+export declare const HUNSU_SELF_COMMIT_SENTINEL = "__HUNSU_SELF_COMMIT__";
+export type DomainStore = {
+    root: string;
+    eventRefs: DomainEventRef[];
+    events: DomainEvent[];
+    board: BoardProjection;
+    runtimePaths: typeof HUNSU_RUNTIME_PATHS;
+    runtime: HunsuRuntimeState;
+    source: "worktree-runtime" | "reachable-runtime" | "legacy-state" | "legacy-refs" | "empty";
+    checksum: RuntimeChecksum;
+    commit?: CommitSha;
+};
+export type DomainEventRef = {
+    ref: string;
+    object: string;
+    objectType: string;
+    ordinal: number;
+};
+export type DomainStoreError = {
+    type: "DomainStoreError";
+    message: string;
+};
+export type CompletedDestinationEntry = {
+    destinationId: string;
+    title: string;
+    completedAt?: string;
+    resultCommit: CommitSha | typeof HUNSU_SELF_COMMIT_SENTINEL | MoveCommitRef;
+    moveId: MoveId;
+    harnessId?: string;
+    digest: {
+        summary: string;
+        evidence: string[];
+        changedPaths?: string[];
+        checks?: Array<{
+            command: string;
+            status: "passed" | "failed";
+            summary?: string;
+        }>;
+        risks?: string[];
+        transcriptDigest?: string;
+    };
+};
+export type HunsuCompletedDestinationsFile = {
+    schema: "hunsu.completed-destinations.v1";
+    order: "oldest-first-tail-append";
+    entries: CompletedDestinationEntry[];
+};
+export type HunsuPendingDestinationsFile = {
+    schema: "hunsu.destinations.v1";
+    order: "queue-head-is-current";
+    destinations: Destination[];
+    compatibility: {
+        events: DomainEvent[];
+        updatedAt?: string;
+    };
+};
+export type HunsuHarnessFile = {
+    schema: "hunsu.harness.v1";
+    origins?: HunsuOrigin[];
+    harness: {
+        name: string;
+        rootTeamId: ExecutorId;
+        guardrails?: GuardrailConfig[];
+        lock?: HubPackageLock;
+    };
+};
+export type HunsuExecutorsFile = {
+    schema: "hunsu.executors.v1";
+    executors: ExecutorEntity[];
+};
+export type HunsuResourcesFile = {
+    schema: "hunsu.resources.v1";
+    resources: ResourceEntity[];
+    bindings: Array<{
+        destinationId: string;
+        executorPackageBindings?: BoardProjection["nodes"][number]["executorPackageBindings"];
+        resourcePackageBindings?: BoardProjection["nodes"][number]["resourcePackageBindings"];
+    }>;
+};
+export type HunsuArtifactActionsFile = {
+    schema: "hunsu.artifact-actions.v1";
+    order: "display-order";
+    actions: ArtifactActionDefinition[];
+};
+export type HunsuRuntimeEventLog = {
+    events: DomainEvent[];
+    updatedAt?: string;
+};
+export type HunsuCurrentExecutionFile = {
+    schema: "hunsu.current-execution.v1";
+    execution: ExecutionPlan;
+    updatedAt?: string;
+};
+export type MoveCommitRef = {
+    type: "self";
+} | {
+    type: "external";
+    commit: CommitSha;
+};
+export type RouteNodeLifecycle = "Waiting" | "Executing" | "Completed" | "Failed";
+export type PreviousExecutionAgentSessionRef = {
+    sessionId: string;
+    ownerKind: "TeamPlan" | "ExecutionPlan" | "MoveFinalizer";
+    providerThreadId?: string;
+    providerTurnId?: string;
+    state: "waiting" | "starting" | "executing" | "interactWait" | "completed" | "failed";
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+};
+export type PlanNodeExecutionRecord = {
+    nodeType: "PlanNode";
+    lifecycle: Extract<RouteNodeLifecycle, "Completed" | "Failed">;
+    session?: PreviousExecutionAgentSessionRef;
+    completedAt?: string;
+    error?: string;
+};
+export type PathNodeExecutionRecord = {
+    nodeType: "PathNode";
+    pathId: PathId;
+    executorId: string;
+    goal: string;
+    requires: MemberPath["requires"];
+    lifecycle: RouteNodeLifecycle;
+    session?: PreviousExecutionAgentSessionRef;
+    commit?: CommitSha;
+    parentCommit?: CommitSha;
+    treeChanged?: boolean;
+    startedAt?: string;
+    completedAt?: string;
+    error?: string;
+};
+export type RouteNodeExecutionRecord = PlanNodeExecutionRecord | PathNodeExecutionRecord;
+export type HunsuPreviousExecutionFile = {
+    schema: "hunsu.previous-execution.v1";
+    sourceMoveCommit: CommitSha;
+    targetMoveId: MoveId;
+    executeId: string;
+    runId: string;
+    lineId: string;
+    sourceNodeId?: NodeId;
+    sourceMoveId?: MoveId;
+    targetMoveOrdinal?: PositiveInteger;
+    selectedDestinationIds: string[];
+    worktree?: WorktreeRef;
+    conversationRef?: AgentConversationRef;
+    plan: PlanNodeExecutionRecord;
+    paths: PathNodeExecutionRecord[];
+    pathCommits: Record<string, CommitSha>;
+    terminalPathId?: PathId;
+    terminalPathCommit?: CommitSha;
+    finalizerSession?: PreviousExecutionAgentSessionRef;
+    moveFinalizerCommit?: MoveCommitRef;
+    moveFinalizerMessage?: string;
+    startedAt?: string;
+    completedAt?: string;
+};
+export type PreviousExecutionState = {
+    type: "none";
+} | {
+    type: "present";
+    value: HunsuPreviousExecutionFile;
+};
+export type CurrentExecutionState = {
+    type: "none";
+} | {
+    type: "present";
+    value: HunsuCurrentExecutionFile;
+};
+export type HunsuRuntimeState = {
+    completed: HunsuCompletedDestinationsFile;
+    destinations: HunsuPendingDestinationsFile;
+    harness: HunsuHarnessFile;
+    executors: HunsuExecutorsFile;
+    resources: HunsuResourcesFile;
+    artifactActions: HunsuArtifactActionsFile;
+    currentExecution: CurrentExecutionState;
+    previousExecution: PreviousExecutionState;
+    eventLog: HunsuRuntimeEventLog;
+};
+export type HunsuDraftRuntimeFileName = (typeof HUNSU_DRAFT_RUNTIME_FILE_NAMES)[number];
+export type HunsuDraftRuntimeBundle = Pick<HunsuRuntimeState, "destinations" | "harness" | "executors" | "resources" | "artifactActions">;
+export type HunsuDraftRuntimeValidation = {
+    previous: HunsuDraftRuntimeBundle;
+    request: HunsuDraftRuntimeBundle;
+    requestRuntime: HunsuRuntimeState;
+};
+export type EncodedHunsuRuntimeFile = {
+    text: string;
+    checksum: RuntimeChecksum;
+};
+export declare function loadDomainStore(cwd?: string): DomainStore;
+export declare function initializeDomainStore(cwd?: string, options?: {
+    commitMessage?: string;
+}): DomainStore;
+export declare function dryRunCommand(command: Command, cwd?: string): {
+    store: DomainStore;
+    acceptedEvents: DomainEvent[];
+    board: BoardProjection;
+};
+export declare function dryRunCommands(commands: Command[], cwd?: string): {
+    store: DomainStore;
+    acceptedEvents: DomainEvent[];
+    board: BoardProjection;
+};
+export declare function writeCommand(command: Command, options?: {
+    cwd?: string;
+    commitMessage?: string;
+    previousExecution?: PreviousExecutionState;
+    selfCommitMoveIds?: string[];
+}): {
+    acceptedEvents: DomainEvent[];
+    board: BoardProjection;
+};
+export declare function writeCommands(commands: Command[], options?: {
+    cwd?: string;
+    commitMessage?: string;
+    previousExecution?: PreviousExecutionState;
+    selfCommitMoveIds?: string[];
+}): {
+    acceptedEvents: DomainEvent[];
+    board: BoardProjection;
+};
+export declare function encodeHunsuRuntimeFile(value: unknown): EncodedHunsuRuntimeFile;
+export declare function decodeHunsuRuntimeFileText<T = unknown>(text: string, source: string): Result<T, DomainStoreError>;
+export declare function decodeRuntimeBundleToDraftFiles(runtime: HunsuRuntimeState): Record<HunsuDraftRuntimeFileName, unknown>;
+export declare function hunsuDraftRuntimeBundleFromRuntime(runtime: HunsuRuntimeState): HunsuDraftRuntimeBundle;
+export declare function readDraftRuntimeBundle(cwd: string, dir: string): Result<HunsuDraftRuntimeBundle, DomainStoreError>;
+export declare function validateDraftRuntimeBundle(previous: HunsuDraftRuntimeBundle, request: HunsuDraftRuntimeBundle, sourceRuntime: HunsuRuntimeState): Result<HunsuDraftRuntimeValidation, DomainStoreError>;
+export declare function encodeDraftRuntimeBundleToHunsuFiles(request: HunsuDraftRuntimeBundle): Record<typeof HUNSU_DESTINATIONS_PATH | typeof HUNSU_HARNESS_PATH | typeof HUNSU_EXECUTORS_PATH | typeof HUNSU_RESOURCES_PATH | typeof HUNSU_ARTIFACT_ACTIONS_PATH, EncodedHunsuRuntimeFile>;
+export declare function readHunsuRuntimeStateFromWorktree(cwd?: string): {
+    runtime: HunsuRuntimeState;
+    checksum: RuntimeChecksum;
+} | undefined;
+export declare function readHunsuRuntimeStateAtRef(cwd?: string, ref?: string): {
+    runtime: HunsuRuntimeState;
+    checksum: RuntimeChecksum;
+} | undefined;
+export declare function readReachableHunsuRuntimeStates(cwd?: string): Array<{
+    commit: CommitSha;
+    runtime: HunsuRuntimeState;
+    checksum: RuntimeChecksum;
+}>;
+export declare function readPreviousExecutionChain(cwd?: string, ref?: string): Array<{
+    commit: CommitSha;
+    execution: HunsuPreviousExecutionFile;
+}>;
+export declare function hasHunsuRuntimeState(cwd?: string): boolean;
+export declare function readDomainEventRefs(cwd?: string): DomainEventRef[];
+export declare function readDomainEventObject(cwd: string, ref: Pick<DomainEventRef, "object" | "ref">): Result<DomainEvent, DomainStoreError>;
+export declare function decodeDomainEventText(text: string, ref: string): Result<DomainEvent, DomainStoreError>;