@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/seed.d.ts

@@ -0,0 +1,16 @@
+import { type HolderId, type StackId } from './contract.js';
+import { type StateNamespace } from './state.js';
+/** The instant of the last successful seed, null when none is recorded, undefined when the record is unreadable. */
+export declare function readSeededAt(namespace: StateNamespace, stackId: StackId): Promise<string | null | undefined>;
+export declare function recordSeeded(input: Readonly<{
+    namespace: StateNamespace;
+    stackId: StackId;
+    holderId: HolderId;
+    seededAt: string;
+}>): Promise<boolean>;
+/**
+ * Docker records a volume's creation in whole seconds, so a volume created in the second the seed
+ * was recorded is read as the one the seed filled: a start creates the volume and seeds it moments
+ * later, and reading it as newer would seed again on every later `up`.
+ */
+export declare function seedDue(seededAt: string | null, volumesCreatedAt: readonly number[]): boolean;

package/dist/environment/seed.js

@@ -0,0 +1,43 @@
+// Owns when `environment.seed` is due and the record of its last success. A seed fills the stack's
+// resettable volumes, so it is due on the first start and again whenever one of those volumes was
+// created after the last successful seed: after `reset`, a `docker volume rm`, or a start that
+// failed before the seed ran. The record is the stack's data-outcome state; the volume creation
+// times come from Docker, which the lifecycle composition reads and hands in.
+import { isCanonicalTimestamp } from './contract.js';
+import { readState, transactState } from './state.js';
+/** The instant of the last successful seed, null when none is recorded, undefined when the record is unreadable. */
+export async function readSeededAt(namespace, stackId) {
+    const record = await readState(namespace.paths.dataOutcome(stackId));
+    if (record.kind === 'missing')
+        return null;
+    if (record.kind !== 'complete' || record.value.kind !== 'data-outcome' || record.value.subjectId !== stackId)
+        return undefined;
+    const value = record.value.value;
+    const seededAt = value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).join(',') === 'seededAt' ? value.seededAt : undefined;
+    return typeof seededAt === 'string' && isCanonicalTimestamp(seededAt) ? seededAt : undefined;
+}
+export async function recordSeeded(input) {
+    const address = input.namespace.paths.dataOutcome(input.stackId);
+    const result = await transactState(input.namespace, address, { ownerId: input.holderId }, (current) => ({
+        format: 'cockpit-state/v1',
+        kind: 'data-outcome',
+        cockpitId: address.cockpitId,
+        subjectId: input.stackId,
+        revision: (current?.revision ?? -1) + 1,
+        updatedAt: input.seededAt,
+        value: { seededAt: input.seededAt },
+    }));
+    return result.kind === 'complete';
+}
+/**
+ * Docker records a volume's creation in whole seconds, so a volume created in the second the seed
+ * was recorded is read as the one the seed filled: a start creates the volume and seeds it moments
+ * later, and reading it as newer would seed again on every later `up`.
+ */
+export function seedDue(seededAt, volumesCreatedAt) {
+    if (seededAt === null)
+        return true;
+    const seededSecond = Math.floor(Date.parse(seededAt) / 1000);
+    return volumesCreatedAt.some((instant) => Math.floor(instant / 1000) > seededSecond);
+}

package/dist/environment/selftest-application.d.ts

@@ -0,0 +1,86 @@
+import { validateSelftestEvidenceBundle, type SelftestEvidenceBundle } from '../../libexec/validate-harness-evidence.mjs';
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import type { Diagnostic } from '../diagnostics.js';
+import { type GeneratedApplicationProjection } from './generated-application/shared.js';
+import { type ExecutionStep } from './contract.js';
+import { type SelftestProbeSpecification } from '../surfaces/selftest.js';
+export interface ConfiguredSurfaceSelftestCommandInput {
+    readonly configPath: string;
+    readonly probeSpecificationsPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface SurfaceSelftestDraftInput {
+    readonly configPath: string;
+    readonly writeProbeSpecificationsPath: string;
+    /** An earlier probe-specification file whose filled rows for unchanged cells carry into the new one. */
+    readonly previousProbeSpecificationsPath?: string;
+}
+export interface SurfaceSelftestCommandInput {
+    readonly application: GeneratedApplicationProjection;
+    readonly root: string;
+    readonly specifications: readonly SelftestProbeSpecification[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface SurfaceSelftestExecutableCandidate {
+    readonly harness: 'Claude Code' | 'Codex' | 'OpenCode';
+    readonly canonicalPath: string;
+    readonly sha256: string;
+}
+export interface SurfaceSelftestProbeSpecificationsCandidate {
+    readonly canonicalPath: string;
+    readonly sha256: string;
+    readonly sourceSha256: string;
+    readonly generatedManifestSha256: string;
+    readonly commandVectors: readonly Readonly<{
+        harness: string;
+        capability: string;
+        skill: string | null;
+        invocation: readonly [string, ...string[]];
+        versionCommand: readonly [string, ...string[]];
+        helpCommand: readonly [string, ...string[]];
+    }>[];
+}
+export interface SurfaceSelftestCommandAdapters {
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+    readonly requestExecutableApproval?: (candidate: SurfaceSelftestExecutableCandidate) => Promise<string | undefined>;
+    readonly requestProbeSpecificationsApproval?: (candidate: SurfaceSelftestProbeSpecificationsCandidate) => Promise<string | undefined>;
+    readonly testOnlyExecutableIdentities?: Partial<Record<'Claude Code' | 'Codex' | 'OpenCode', readonly string[]>>;
+}
+export type SurfaceSelftestCommandOutcome = Readonly<{
+    kind: 'complete';
+    status: 0;
+    bundle: SelftestEvidenceBundle;
+    evidence: ReturnType<typeof validateSelftestEvidenceBundle>;
+}> | Readonly<{
+    kind: 'refusal';
+    status: 2;
+    code: 'SELFTEST_SOURCE_INVALID' | 'SELFTEST_EXECUTION_INVALID';
+    reason: string;
+    fix?: string;
+}>;
+export declare function runSurfaceSelftestApplication(input: SurfaceSelftestCommandInput, adapters?: SurfaceSelftestCommandAdapters): Promise<SurfaceSelftestCommandOutcome>;
+export declare function runConfiguredSurfaceSelftestApplication(input: ConfiguredSurfaceSelftestCommandInput, adapters?: SurfaceSelftestCommandAdapters): Promise<SurfaceSelftestCommandOutcome>;
+export interface SurfaceSelftestHandlerInput extends ConfiguredSurfaceSelftestCommandInput {
+    readonly requestExecutableApproval?: SurfaceSelftestCommandAdapters['requestExecutableApproval'];
+    readonly requestProbeSpecificationsApproval?: SurfaceSelftestCommandAdapters['requestProbeSpecificationsApproval'];
+}
+export interface SurfaceSelftestDispatchOutcome {
+    readonly artifact?: string | null;
+    readonly destination?: string | null;
+    readonly status: number;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly result: unknown;
+}
+export interface SelftestOperatorIo {
+    readonly stderr: Pick<NodeJS.WriteStream, 'write'>;
+    readonly stdin?: NodeJS.ReadStream;
+    readonly confirmSelftestExecutable?: SurfaceSelftestCommandAdapters['requestExecutableApproval'];
+    readonly confirmSelftestProbeSpecifications?: SurfaceSelftestCommandAdapters['requestProbeSpecificationsApproval'];
+}
+export interface SelftestOperatorOptions {
+    readonly interactive: boolean;
+    readonly json: boolean;
+    readonly ci: string | undefined;
+}
+export declare function runConfiguredSurfaceSelftestOutcome(input: SurfaceSelftestHandlerInput | SurfaceSelftestDraftInput): Promise<SurfaceSelftestDispatchOutcome>;
+export declare function runSelftestOperatorCommand(input: SurfaceSelftestHandlerInput, options: SelftestOperatorOptions, io: SelftestOperatorIo, handler: (input: SurfaceSelftestHandlerInput) => Promise<SurfaceSelftestDispatchOutcome>): Promise<SurfaceSelftestDispatchOutcome>;