@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/generated-application/sync.d.ts

@@ -0,0 +1,6 @@
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentCommandOutcome, type GeneratedEnvironmentRepairAuthority, type GeneratedEnvironmentSyncInput } from './shared.js';
+export declare function syncGeneratedEnvironment(input: GeneratedEnvironmentSyncInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCommandOutcome>;
+export declare function syncTeamGeneratedEnvironment(input: GeneratedEnvironmentSyncInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCommandOutcome>;
+export declare function applyGeneratedEnvironmentRepair(authority: GeneratedEnvironmentRepairAuthority, options?: Readonly<{
+    dryRun?: boolean;
+}>): Promise<GeneratedEnvironmentCommandOutcome>;

package/dist/environment/generated-application/sync.js

@@ -0,0 +1,124 @@
+import { prepareTeamMetadata, applyTeamMetadata } from '../../team-metadata.js';
+import { basename } from 'node:path';
+import { GUARD_LOCAL_PATHS, writeCockpitLocalFiles, writeGuardLocalIdentity } from '../../guards/local-identity.js';
+import { portablePublicationPaths, authorizePublicationPlan, runPublicationPlan } from '../../generated-environment/transaction.js';
+import { refusalOutcome as refuse } from '../../refusal.js';
+import { readBoundedInput } from '../../config/load.js';
+import { complete, mergedAdapters, overrideChangedRefusal, ownRecord, sha256, } from './shared.js';
+import { syncCommandInput } from './prepare.js';
+import { inputSourcesCurrent, ownedInputOverlap, preparePublication } from './publication.js';
+import { checkCanonicalGeneratedEnvironment, issueRepairAuthority, issuedRepairs } from './check.js';
+import { openCodeGrantFile } from './surface-outputs.js';
+import { readSiblingCheckouts } from '../sibling-checkouts.js';
+import { openCodeGrantDirectory, openCodePatternUnsafe } from '../served-checkout-grants.js';
+async function prepareGeneratedEnvironmentSync(input, adapterOverrides, metadataChanges = []) {
+    const request = syncCommandInput(input);
+    if (!request)
+        return refuse('GENERATED_INPUT_INVALID', 'generated environment command input is invalid', 'generated-environment');
+    const adapters = mergedAdapters(adapterOverrides);
+    const publication = await preparePublication(request, adapters);
+    if ('status' in publication)
+        return publication;
+    if ('refusal' in publication)
+        return publication.refusal;
+    if (metadataChanges.length > 0) {
+        const generatedPaths = [...new Set([
+                ...publication.prepared.owned.map(row => row.path),
+                ...publication.prepared.surfaces.map(row => row.path),
+                ...(publication.ownership.kind === 'complete' ? publication.ownership.manifest.entries.map(row => row.path) : []),
+            ])];
+        const destination = metadataChanges.find(change => generatedPaths.some(path => path === change.path || path.startsWith(`${change.path}/`))
+            || !portablePublicationPaths([...generatedPaths, change.path]));
+        if (destination)
+            return refuse('TEAM_METADATA_UNAVAILABLE', 'a pending team metadata write overlaps a generated destination; move the generated output to a separate path, then run npx --no cockpit sync --config <your cockpit.toml> again', destination.path);
+        const overlap = await ownedInputOverlap(publication.prepared, metadataChanges);
+        if (overlap.kind === 'invalid' || overlap.path)
+            return refuse('TEAM_METADATA_UNAVAILABLE', 'pending team metadata writes overlap an authenticated input or its identity could not be checked; move the input to a separate file, update its declaration, then run npx --no cockpit sync --config <your cockpit.toml> again', overlap.kind === 'complete' ? overlap.path : 'team-metadata');
+    }
+    const authority = issueRepairAuthority({ prepared: publication.prepared, plan: publication.plan, adapters });
+    return { kind: 'complete', authority, dryRun: request.dryRun === true };
+}
+export async function syncGeneratedEnvironment(input, adapterOverrides = {}) {
+    const prepared = await prepareGeneratedEnvironmentSync(input, adapterOverrides);
+    return prepared.kind === 'refusal' ? prepared : applyGeneratedEnvironmentRepair(prepared.authority, { dryRun: prepared.dryRun });
+}
+export async function syncTeamGeneratedEnvironment(input, adapterOverrides = {}) {
+    const request = syncCommandInput(input);
+    if (!request)
+        return refuse('GENERATED_INPUT_INVALID', 'generated environment command input is invalid', 'generated-environment');
+    const metadata = await prepareTeamMetadata(request.configPath);
+    if (metadata.kind === 'refusal')
+        return refuse(metadata.code, metadata.message, metadata.target, metadata.fix);
+    const prepared = await prepareGeneratedEnvironmentSync(request, adapterOverrides, metadata.authority.changes);
+    if (prepared.kind === 'refusal')
+        return prepared;
+    if (!prepared.dryRun) {
+        const record = issuedRepairs.get(prepared.authority);
+        const approved = await authorizePublicationPlan(record.plan, record.adapters);
+        if (approved !== true)
+            return approved;
+        const applied = await applyTeamMetadata(metadata.authority);
+        if (applied.kind === 'refusal')
+            return refuse(applied.code, applied.message, applied.target);
+    }
+    const outcome = await applyGeneratedEnvironmentRepair(prepared.authority, { dryRun: prepared.dryRun });
+    return outcome.kind === 'refusal' ? outcome : { ...outcome,
+        result: { ...outcome.result, changes: [...metadata.authority.changes, ...outcome.result.changes] } };
+}
+export async function applyGeneratedEnvironmentRepair(authority, options = {}) {
+    const settings = ownRecord(options);
+    if (!settings || Object.keys(settings).some(key => key !== 'dryRun')
+        || settings.dryRun !== undefined && typeof settings.dryRun !== 'boolean')
+        return refuse('GENERATED_INPUT_INVALID', 'repair publication options are invalid', 'generated-environment');
+    const record = issuedRepairs.get(authority);
+    if (!record)
+        return refuse('GENERATED_PUBLICATION_FAILED', 'repair authority is unknown or already consumed', 'generated-environment');
+    issuedRepairs.delete(authority);
+    const { prepared, adapters } = record;
+    const changedOriginal = prepared.changedOverrideOriginals[0];
+    if (changedOriginal && settings.dryRun !== true)
+        return overrideChangedRefusal(changedOriginal);
+    const outcome = await runPublicationPlan(record.plan, {
+        ...adapters,
+        dryRun: settings.dryRun === true,
+        revalidate: async (deadline, stage) => {
+            const source = await adapters.observeSource(prepared.configPath);
+            if (source.state !== 'available' || source.sha256 !== prepared.sourceSha256)
+                return refuse('GENERATED_SOURCE_CHANGED', 'the configuration changed before generated files could be published', 'generated-environment');
+            if (stage === 'after-publish') {
+                const checked = await checkCanonicalGeneratedEnvironment({ configPath: prepared.configPath }, prepared, adapters);
+                return checked.kind === 'complete' ? true : checked;
+            }
+            if (!await inputSourcesCurrent(prepared, adapters, deadline))
+                return refuse('GENERATED_SOURCE_CHANGED', 'a generated input changed before publication', stage === 'before-stage' ? prepared.configSource.path : 'generated-environment');
+            return true;
+        },
+    });
+    if (outcome.kind === 'refusal')
+        return outcome;
+    if (prepared.guardHandler && settings.dryRun !== true) {
+        // The guard compares a later edit with exactly the text this identity names, so it is read
+        // again and must still be that text.
+        const configRead = await readBoundedInput(prepared.configPath);
+        if (configRead.kind !== 'complete' || sha256(configRead.bytes) !== prepared.guardHandler.configSha256)
+            return refuse('GENERATED_SOURCE_CHANGED', 'the configuration changed after generated files were published, so the guard identity was not recorded; the guard refuses every agent tool call until it is', prepared.configSource.path, 'run `npx --no cockpit sync --config <your cockpit.toml>` again');
+        const local = await writeGuardLocalIdentity(prepared.root, prepared.guardHandler, configRead.bytes.toString('utf8'));
+        if (local.kind === 'refusal')
+            return refuse('GENERATED_PUBLICATION_FAILED', `the committed guard files were published, but ${local.message}; the guard refuses every agent tool call until it exists`, GUARD_LOCAL_PATHS.identity, 'fix the path, then run `npx --no cockpit sync --config <your cockpit.toml>` again in a terminal');
+    }
+    if (prepared.openCodeGrantRoots.length > 0 && settings.dryRun !== true) {
+        // A checkout `use` serves from outside the declared one is what OpenCode is granted, as `use` wrote it.
+        const recorded = await readSiblingCheckouts(prepared.root);
+        if (recorded.kind !== 'complete')
+            return refuse(recorded.diagnostic.code, `the committed OpenCode settings were published, but its grants were not written: ${recorded.diagnostic.message}`, recorded.diagnostic.target, recorded.diagnostic.fix);
+        const grants = prepared.openCodeGrantRoots.map(row => ({ name: basename(openCodeGrantFile(row.slug)),
+            bytes: openCodeGrantDirectory(row.root, Object.hasOwn(recorded.checkouts, row.slug) ? recorded.checkouts[row.slug] : undefined) }));
+        const unsafe = grants.map(row => openCodePatternUnsafe(row.bytes)).find(reason => reason !== undefined);
+        if (unsafe)
+            return refuse('GENERATED_PUBLICATION_FAILED', `the committed OpenCode settings were published, but its grants were not written: ${unsafe}`, GUARD_LOCAL_PATHS.directory, 'serve the sibling from a checkout at a plain path with `npx --no cockpit use`, then run sync again');
+        const local = await writeCockpitLocalFiles(prepared.root, grants);
+        if (local.kind === 'refusal')
+            return refuse('GENERATED_PUBLICATION_FAILED', `the committed OpenCode settings were published, but ${local.message}; OpenCode refuses to start until it exists`, GUARD_LOCAL_PATHS.directory, 'fix the path, then run `npx --no cockpit sync --config <your cockpit.toml>` again in a terminal');
+    }
+    return complete('sync', prepared, settings.dryRun === true, outcome.changes, settings.dryRun ? outcome.staleRemoval : undefined);
+}

package/dist/environment/git-observation.d.ts

@@ -0,0 +1,202 @@
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { ENVIRONMENT_CODES, type CheckoutId, type EnvironmentDiagnostic, type EnvironmentObservation, type ExecutionStep, type StackId } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+import { type RuntimeTopologyEvidence } from './runtime.js';
+import { type SetupCheckoutProjection } from './setup-observation.js';
+export declare const observationDeclarations: readonly [{
+    readonly id: 'git-working-tree';
+    readonly owner: "git-observation";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "GIT_STATE_UNHEALTHY";
+    readonly isIssued: typeof isGitObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}, {
+    readonly id: 'git-adjacency';
+    readonly owner: "git-observation";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "CHECKOUT_ADJACENCY_UNHEALTHY";
+    readonly isIssued: typeof isGitObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}, {
+    readonly id: 'running-checkout';
+    readonly owner: "git-observation";
+    readonly postures: readonly ["running-stack"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'not-applicable';
+        readonly reason: 'no running checkout exists before the first seed';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "RUNNING_CHECKOUT_MISMATCH";
+    readonly isIssued: typeof isGitObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+declare function isGitObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+interface GitObservationEvidence {
+    readonly revision: string | null;
+    readonly branch: string;
+    readonly upstream: string | null;
+    readonly ahead: number;
+    readonly behind: number;
+    readonly trackedDirtyCount: number;
+    readonly untrackedCount: number;
+    readonly workingTree: 'clean' | 'dirty' | 'untracked' | 'dirty-and-untracked';
+    readonly adjacency: 'aligned' | 'ahead' | 'behind' | 'diverged' | 'untracked-upstream' | 'upstream-gone';
+}
+type GitObservationResult = {
+    readonly kind: 'complete';
+    readonly evidence: GitObservationEvidence;
+    readonly observations: readonly EnvironmentObservation[];
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export declare function createGitObservationStep(input: {
+    readonly executable: ResolvedExecutable;
+    readonly checkoutRoot: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly stackId: StackId;
+    readonly source: string;
+    readonly checkoutId: CheckoutId;
+}): ExecutionStep | undefined;
+export type GitBranchStatus = Readonly<{
+    kind: 'complete';
+    /** An object name, or `(initial)` while HEAD is unborn. */
+    revision: string;
+    /** The branch name, or `(detached)` on a detached HEAD. */
+    branch: string;
+    upstream: string | null;
+    ahead: number;
+    behind: number;
+    /** False when Git names an upstream it cannot count against, because the upstream ref is gone. */
+    adjacencyReported: boolean;
+    trackedDirtyCount: number;
+    untrackedCount: number;
+}>;
+/** `git status --porcelain=v2 --branch` output as numbers and names, or why it cannot be read as such. */
+export declare function parseGitBranchStatus(source: string): GitBranchStatus | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>;
+export declare function decodeGitObservation(bytes: Buffer, context: {
+    readonly stackId: StackId;
+    readonly observedAt: string;
+    readonly source: string;
+    readonly checkoutRoot: string;
+}): GitObservationResult;
+export declare function observeGit(step: ExecutionStep, outcome: ExecuteProbeOutcome, context: {
+    readonly stackId: StackId;
+    readonly checkoutId: CheckoutId;
+    readonly source: string;
+}): GitObservationResult;
+type AcquirePosture = 'auto' | 'manual' | 'none';
+type ComparisonRemoteCode = typeof ENVIRONMENT_CODES.GIT_COMPARISON_REMOTE_MISMATCH;
+export type ComparisonRemoteResult = Readonly<{
+    kind: 'complete';
+    code: ComparisonRemoteCode;
+    state: 'match';
+    remoteName: string;
+}> | Readonly<{
+    kind: 'complete';
+    code: ComparisonRemoteCode;
+    state: 'mismatch';
+    remoteName: string;
+    reason: string;
+}> | Readonly<{
+    kind: 'not-applicable';
+    code: ComparisonRemoteCode;
+    reason: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    code: ComparisonRemoteCode;
+    reason: string;
+    remoteName?: string;
+}>;
+type ComparisonRemoteRefStage = Readonly<{
+    kind: 'probe';
+    step: ExecutionStep;
+}> | Extract<ComparisonRemoteResult, {
+    kind: 'not-applicable' | 'unavailable';
+}>;
+type ComparisonRemoteUrlStage = Readonly<{
+    kind: 'probe';
+    step: ExecutionStep;
+    remoteName: string;
+}> | Extract<ComparisonRemoteResult, {
+    kind: 'unavailable';
+}>;
+type ComparisonRemoteRevalidationStage = Readonly<{
+    kind: 'probe';
+    step: ExecutionStep;
+    remoteName: string;
+}> | Extract<ComparisonRemoteResult, {
+    kind: 'unavailable';
+}>;
+export declare function createComparisonRemoteRefStep(input: {
+    readonly executable: ResolvedExecutable;
+    readonly checkoutRoot: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly stackId: StackId;
+    readonly checkoutId: CheckoutId;
+    readonly source: string;
+    readonly sibling: string;
+    readonly acquire: AcquirePosture;
+    readonly declaredRemote?: string;
+    readonly git?: GitObservationResult;
+}): ComparisonRemoteRefStage;
+export declare function observeComparisonRemoteRef(stage: ComparisonRemoteRefStage, outcome: ExecuteProbeOutcome): ComparisonRemoteUrlStage;
+export declare function observeComparisonRemoteUrl(stage: ComparisonRemoteUrlStage, outcome: ExecuteProbeOutcome): ComparisonRemoteRevalidationStage;
+export declare function observeComparisonRemoteRevalidation(stage: ComparisonRemoteRevalidationStage, outcome: ExecuteProbeOutcome): ComparisonRemoteResult;
+type RunningCheckoutObservationResult = {
+    readonly kind: 'complete';
+    readonly observation: EnvironmentObservation;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export declare function observeRunningCheckout(topology: RuntimeTopologyEvidence, checkoutProjection: SetupCheckoutProjection, runtimeSha256: string, observedAt: string): RunningCheckoutObservationResult;
+/**
+ * Why a Git step that exited non-zero failed: the directory is in no repository, or Git refused to
+ * read the repository. A refusal names the cause and its remedy; ownership is a trust decision about
+ * another user's files, so its remedy goes through a person.
+ */
+export declare function gitRepositoryRefusal(stderr: Buffer): Readonly<{
+    kind: 'not-a-repository';
+}> | Readonly<{
+    kind: 'refused';
+    reason: string;
+    fix: string;
+}>;
+/**
+ * Secret-shaped files a repository commits. The guard keeps agents from reading them, which
+ * protects the session but not the history: every clone already holds the values, and nothing
+ * told the person so. Reports paths only.
+ */
+export declare function inspectTrackedSecretFiles(input: {
+    readonly executable: ResolvedExecutable;
+    readonly repositories: readonly Readonly<{
+        slug: string;
+        root: string;
+    }>[];
+    readonly timeoutMs: number;
+}, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<readonly EnvironmentDiagnostic[]>;
+export {};