create-next-hydra 0.3.0 → 0.4.1

package/dist/workspace-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-state.d.ts","sourceRoot":"","sources":["../src/workspace-state.ts"],"names":[],"mappings":"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"}

package/dist/workspace-state.js

@@ -0,0 +1,571 @@
+import { isDeepStrictEqual } from "node:util";
+import { Context, Effect, FileSystem, Layer, Path, Ref, Schema } from "effect";
+import { WorkspaceBusy, WorkspaceRecoveryRequired, WorkspaceStateInvalid, } from "./errors.js";
+import { cacheDirectories, isEnvironmentFile } from "./file-policy.js";
+import { relativeFile } from "./files.js";
+import { validatePreservedFiles, workspaceSetting } from "./initialization.js";
+import { FileOrigin } from "./model.js";
+import { withWriteLock } from "./workspace-lock.js";
+const Fingerprint = Schema.Struct({ hash: Schema.String, mode: Schema.Int });
+export const sameFingerprint = (left, right) => left === null || right === null
+    ? left === right
+    : left.hash === right.hash && left.mode === right.mode;
+const Entry = Schema.Struct({
+    applied: Fingerprint,
+    desired: Fingerprint,
+    origin: FileOrigin,
+    target: Schema.String,
+});
+const Intent = Schema.Struct({
+    after: Schema.NullOr(Fingerprint),
+    before: Schema.NullOr(Fingerprint),
+    desired: Schema.NullOr(Fingerprint),
+    origin: Schema.NullOr(FileOrigin),
+    target: Schema.String,
+    temporary: Schema.NullOr(Schema.String),
+});
+const Installation = Schema.Struct({
+    inputs: Schema.String,
+    lockfile: Fingerprint,
+    modules: Fingerprint,
+    toolchain: Schema.String,
+    virtualLock: Fingerprint,
+});
+const Snapshot = Schema.Struct({
+    commit: Schema.String,
+    filesRevision: Schema.Int,
+    origins: Schema.Array(Schema.Struct({ origin: FileOrigin, target: Schema.String })),
+    revision: Schema.Int,
+});
+const Initialization = Schema.Struct({
+    status: Schema.Literals(["planned", "started", "completed"]),
+    target: Schema.String,
+});
+const PreservedFiles = Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([])));
+const Receipt = Schema.Struct({
+    directory: Schema.String,
+    entries: Schema.Array(Entry),
+    filesRevision: Schema.Int,
+    format: Schema.Literal("effect-workspace"),
+    installation: Schema.NullOr(Installation),
+    pending: Schema.NullOr(Schema.Union([
+        Schema.Struct({
+            files: Schema.Array(Intent),
+            initialization: Schema.Array(Initialization),
+            kind: Schema.Literal("files"),
+            preserved: PreservedFiles,
+        }),
+        Schema.Struct({
+            inputs: Schema.String,
+            kind: Schema.Literal("installation"),
+            stopped: Schema.Boolean,
+        }),
+    ])),
+    preserved: PreservedFiles,
+    revision: Schema.Int,
+    snapshot: Schema.NullOr(Snapshot),
+    sourceRoot: Schema.String,
+    version: Schema.Literal(1),
+});
+function validFingerprint(value) {
+    return (value === null ||
+        (/^[a-f0-9]{64}$/u.test(value.hash) &&
+            value.mode >= 0 &&
+            value.mode <= 0o777));
+}
+const validateOwnedTargets = (names, directory) => Effect.gen(function* () {
+    const invalid = () => new WorkspaceStateInvalid({ directory });
+    const targets = new Set(names);
+    if (targets.size !== names.length) {
+        return yield* invalid();
+    }
+    for (const name of names) {
+        const target = yield* relativeFile(name).pipe(Effect.mapError(invalid));
+        if (target !== name ||
+            target.startsWith(".workspace-composition") ||
+            workspaceSetting(target) ||
+            isEnvironmentFile(target) ||
+            target.split("/").some((part) => cacheDirectories.has(part))) {
+            return yield* invalid();
+        }
+        const parts = target.split("/");
+        for (let end = 1; end < parts.length; end += 1) {
+            const ancestor = parts.slice(0, end).join("/");
+            if (targets.has(ancestor) ||
+                workspaceSetting(ancestor) ||
+                isEnvironmentFile(ancestor)) {
+                return yield* invalid();
+            }
+        }
+    }
+});
+const validateFileIntent = (receipt) => Effect.gen(function* () {
+    if (receipt.pending?.kind !== "files") {
+        return;
+    }
+    const invalid = () => new WorkspaceStateInvalid({ directory: receipt.directory });
+    const { pending } = receipt;
+    const previous = new Map(receipt.entries
+        .filter((entry) => !pending.preserved.includes(entry.target))
+        .map((entry) => [entry.target, entry]));
+    const ownedTargets = receipt.pending.files.map((file) => file.target);
+    // Temporary siblings can look like runtime env files (for example
+    // .env.example.<uuid>.pending). Validate their exact derivation below;
+    // only final targets are subject to the owned-file classification.
+    yield* validateOwnedTargets([...ownedTargets, ...receipt.pending.preserved], receipt.directory);
+    yield* validatePreservedFiles(receipt.pending.preserved).pipe(Effect.mapError(invalid));
+    const allTargets = [
+        ...ownedTargets,
+        ...receipt.pending.files.flatMap((file) => file.temporary === null ? [] : [file.temporary]),
+        ...receipt.pending.initialization.map((file) => file.target),
+    ];
+    const targets = new Set(allTargets);
+    if (targets.size !== allTargets.length) {
+        return yield* invalid();
+    }
+    // Staging paths share the filesystem namespace, but are not application files.
+    // Their authority comes from the owned target and the operation ID below.
+    for (const target of allTargets) {
+        const parts = target.split("/");
+        for (let end = 1; end < parts.length; end += 1) {
+            if (targets.has(parts.slice(0, end).join("/"))) {
+                return yield* invalid();
+            }
+        }
+    }
+    for (const file of receipt.pending.initialization) {
+        const target = yield* relativeFile(file.target).pipe(Effect.mapError(invalid));
+        if (target !== file.target ||
+            (target !== ".gitignore" &&
+                !isEnvironmentFile(target) &&
+                !receipt.pending.preserved.includes(target)) ||
+            target.startsWith(".workspace-composition") ||
+            target.split("/").some((part) => cacheDirectories.has(part))) {
+            return yield* invalid();
+        }
+        const parts = target.split("/");
+        for (let end = 1; end < parts.length; end += 1) {
+            const ancestor = parts.slice(0, end).join("/");
+            if (targets.has(ancestor) ||
+                workspaceSetting(ancestor) ||
+                isEnvironmentFile(ancestor)) {
+                return yield* invalid();
+            }
+        }
+    }
+    for (const file of receipt.pending.files) {
+        const entry = previous.get(file.target);
+        if (![file.before, file.after, file.desired].every(validFingerprint) ||
+            (file.after === null) !== (file.desired === null) ||
+            (file.after === null) !== (file.origin === null) ||
+            (entry
+                ? !sameFingerprint(file.before, entry.applied) &&
+                    !sameFingerprint(file.before, file.after)
+                : file.before !== null &&
+                    !((receipt.preserved.includes(file.target) ||
+                        (file.target === "turbo.json" &&
+                            file.origin?.kind === "policy" &&
+                            file.origin.policy === "application-tasks" &&
+                            sameFingerprint(file.after, file.desired))) &&
+                        sameFingerprint(file.before, file.after)))) {
+            return yield* invalid();
+        }
+        const replaces = file.before !== null &&
+            file.after !== null &&
+            !sameFingerprint(file.before, file.after);
+        if (replaces !== (file.temporary !== null) ||
+            (file.temporary !== null &&
+                (!file.temporary.startsWith(`${file.target}.`) ||
+                    !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\.pending$/u.test(file.temporary.slice(file.target.length + 1))))) {
+            return yield* invalid();
+        }
+        previous.delete(file.target);
+    }
+    if (previous.size > 0) {
+        return yield* invalid();
+    }
+});
+const decodeReceipt = (identity, original, allowIncomplete = false) => Effect.gen(function* () {
+    if (original === null) {
+        return null;
+    }
+    const { directory, sourceRoot } = identity;
+    const invalid = () => new WorkspaceStateInvalid({ directory });
+    const decoded = yield* Schema.decodeEffect(Schema.fromJsonString(Receipt))(original, { onExcessProperty: "error" }).pipe(Effect.mapError(invalid));
+    if (decoded.directory !== directory ||
+        decoded.sourceRoot !== sourceRoot ||
+        decoded.revision < 1 ||
+        decoded.filesRevision < 0 ||
+        decoded.filesRevision > decoded.revision) {
+        return yield* invalid();
+    }
+    if (decoded.snapshot &&
+        (!/^[a-f0-9]{40}$/u.test(decoded.snapshot.commit) ||
+            decoded.snapshot.revision < 1 ||
+            decoded.snapshot.revision > decoded.revision ||
+            decoded.snapshot.filesRevision < 0 ||
+            decoded.snapshot.filesRevision > decoded.filesRevision)) {
+        return yield* invalid();
+    }
+    yield* validateOwnedTargets([...decoded.entries.map((entry) => entry.target), ...decoded.preserved], directory);
+    yield* validatePreservedFiles(decoded.preserved).pipe(Effect.mapError(invalid));
+    if (decoded.snapshot) {
+        yield* validateOwnedTargets(decoded.snapshot.origins.map((entry) => entry.target), directory);
+    }
+    for (const entry of decoded.entries) {
+        if (![entry.desired, entry.applied].every(validFingerprint)) {
+            return yield* invalid();
+        }
+    }
+    yield* validateFileIntent(decoded);
+    if (decoded.pending !== null && !allowIncomplete) {
+        return yield* new WorkspaceRecoveryRequired({ directory });
+    }
+    return decoded;
+});
+export class WorkspaceState extends Context.Service()("create-next-hydra/WorkspaceState") {
+    static layer = Layer.effect(WorkspaceState, Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const withRead = (identity, use, options) => Effect.gen(function* () {
+            const directory = path.resolve(identity.directory);
+            const sourceRoot = path.resolve(identity.sourceRoot);
+            const receiptPath = path.join(directory, ".workspace-composition.json");
+            const lock = path.join(directory, ".workspace-composition.lock");
+            const assertIdle = Effect.gen(function* () {
+                if (yield* fs.exists(lock)) {
+                    return yield* new WorkspaceBusy({ directory });
+                }
+            });
+            const read = Effect.gen(function* () {
+                return (yield* fs.exists(receiptPath))
+                    ? yield* fs.readFileString(receiptPath)
+                    : null;
+            });
+            yield* assertIdle;
+            const original = yield* read;
+            const decoded = yield* decodeReceipt({ directory, sourceRoot }, original, options?.allowIncomplete);
+            const result = yield* use({
+                directory,
+                entries: decoded?.entries ?? [],
+                filesRevision: decoded?.filesRevision ?? 0,
+                initialized: decoded !== null,
+                installation: decoded?.installation ?? null,
+                pending: decoded?.pending ?? null,
+                preserved: decoded?.preserved ?? [],
+                revision: decoded?.revision ?? 0,
+                snapshot: decoded?.snapshot ?? null,
+            });
+            yield* assertIdle;
+            if ((yield* read) !== original) {
+                return yield* new WorkspaceStateInvalid({ directory });
+            }
+            return result;
+        });
+        const withWrite = (identity, use, options) => {
+            const directory = path.resolve(identity.directory);
+            const sourceRoot = path.resolve(identity.sourceRoot);
+            const receiptPath = path.join(directory, ".workspace-composition.json");
+            const lock = path.join(directory, ".workspace-composition.lock");
+            const invalid = () => new WorkspaceStateInvalid({ directory });
+            return withWriteLock(directory, ({ writer, assertOwner, recoveryEvidence }) => Effect.gen(function* () {
+                const active = yield* Ref.make(true);
+                const original = (yield* fs.exists(receiptPath))
+                    ? yield* fs.readFileString(receiptPath)
+                    : null;
+                const decoded = yield* decodeReceipt({ directory, sourceRoot }, original, true);
+                const current = yield* Ref.make(decoded ?? {
+                    directory,
+                    entries: [],
+                    filesRevision: 0,
+                    format: "effect-workspace",
+                    installation: null,
+                    pending: null,
+                    preserved: [],
+                    revision: 0,
+                    snapshot: null,
+                    sourceRoot,
+                    version: 1,
+                });
+                const expected = yield* Ref.make(original);
+                const record = (next) => Effect.gen(function* () {
+                    yield* assertOwner;
+                    if (!(yield* Ref.get(active))) {
+                        return yield* invalid();
+                    }
+                    const observed = (yield* fs.exists(receiptPath))
+                        ? yield* fs.readFileString(receiptPath)
+                        : null;
+                    if (observed !== (yield* Ref.get(expected))) {
+                        return yield* invalid();
+                    }
+                    const text = yield* Schema.encodeEffect(Schema.fromJsonString(Receipt))(next).pipe(Effect.mapError(invalid));
+                    // The lock owns this temporary file. Failed publication leaves it
+                    // in place and prevents release, rather than discarding evidence.
+                    const temporary = path.join(lock, "receipt.json");
+                    yield* fs.writeFileString(temporary, text, {
+                        flag: "wx",
+                        mode: 0o600,
+                    });
+                    yield* fs.rename(temporary, receiptPath);
+                    yield* Ref.set(expected, text);
+                    yield* Ref.set(current, next);
+                }).pipe(Effect.uninterruptible);
+                const begin = (files, initialization, preserved = []) => Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.pending !== null) {
+                        return yield* new WorkspaceRecoveryRequired({
+                            directory,
+                        });
+                    }
+                    const next = {
+                        ...state,
+                        pending: {
+                            files,
+                            initialization: initialization.map((target) => ({
+                                status: "planned",
+                                target,
+                            })),
+                            kind: "files",
+                            preserved,
+                        },
+                        revision: state.revision + 1,
+                    };
+                    yield* validateFileIntent(next);
+                    yield* record(next);
+                });
+                const recordInitialization = (target, status) => Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    const expectedStatus = status === "started" ? "planned" : "started";
+                    if (state.pending?.kind !== "files" ||
+                        state.pending.initialization.find((file) => file.target === target)?.status !== expectedStatus) {
+                        return yield* invalid();
+                    }
+                    yield* record({
+                        ...state,
+                        pending: {
+                            ...state.pending,
+                            initialization: state.pending.initialization.map((file) => file.target === target ? { ...file, status } : file),
+                        },
+                        revision: state.revision + 1,
+                    });
+                });
+                const initialize = (target, write) => Effect.gen(function* () {
+                    yield* recordInitialization(target, "started");
+                    const result = yield* write;
+                    yield* recordInitialization(target, "completed");
+                    return result;
+                }).pipe(Effect.uninterruptible);
+                const complete = Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.pending?.kind !== "files" ||
+                        state.pending.initialization.some((file) => file.status !== "completed")) {
+                        return yield* invalid();
+                    }
+                    const entries = state.pending.files.flatMap((file) => file.after === null ||
+                        file.desired === null ||
+                        file.origin === null
+                        ? []
+                        : [
+                            {
+                                applied: file.after,
+                                desired: file.desired,
+                                origin: file.origin,
+                                target: file.target,
+                            },
+                        ]);
+                    const previous = new Map(state.entries.map((entry) => [entry.target, entry]));
+                    const changed = !isDeepStrictEqual(state.preserved, state.pending.preserved) ||
+                        entries.length !== previous.size ||
+                        entries.some((entry) => {
+                            const old = previous.get(entry.target);
+                            return (!old ||
+                                !sameFingerprint(entry.applied, old.applied) ||
+                                !sameFingerprint(entry.desired, old.desired) ||
+                                !isDeepStrictEqual(entry.origin, old.origin));
+                        });
+                    yield* record({
+                        ...state,
+                        entries,
+                        filesRevision: state.filesRevision + Number(changed),
+                        pending: null,
+                        preserved: state.pending.preserved,
+                        revision: state.revision + 1,
+                    });
+                });
+                const recoverFiles = (observed, expectedRevision) => Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.revision !== expectedRevision ||
+                        state.pending?.kind !== "files" ||
+                        observed.size !== state.pending.files.length) {
+                        return yield* invalid();
+                    }
+                    const { pending } = state;
+                    const previous = new Map(state.entries
+                        .filter((entry) => !pending.preserved.includes(entry.target))
+                        .map((entry) => [entry.target, entry]));
+                    const entries = [];
+                    for (const file of state.pending.files) {
+                        const currentFile = observed.get(file.target);
+                        if (currentFile === undefined) {
+                            return yield* invalid();
+                        }
+                        if (sameFingerprint(currentFile, file.after)) {
+                            if (file.after !== null &&
+                                file.desired !== null &&
+                                file.origin !== null) {
+                                entries.push({
+                                    applied: file.after,
+                                    desired: file.desired,
+                                    origin: file.origin,
+                                    target: file.target,
+                                });
+                            }
+                        }
+                        else if (sameFingerprint(currentFile, file.before)) {
+                            const entry = previous.get(file.target);
+                            if (!sameFingerprint(currentFile, entry?.applied ?? null)) {
+                                return yield* invalid();
+                            }
+                            if (entry) {
+                                entries.push(entry);
+                            }
+                        }
+                        else {
+                            return yield* new WorkspaceRecoveryRequired({
+                                directory,
+                            });
+                        }
+                        previous.delete(file.target);
+                    }
+                    if (previous.size > 0) {
+                        return yield* invalid();
+                    }
+                    yield* record({
+                        ...state,
+                        entries,
+                        filesRevision: state.filesRevision + 1,
+                        installation: null,
+                        pending: null,
+                        preserved: pending.preserved.filter((target) => !pending.initialization.some((file) => file.target === target &&
+                            file.status !== "completed")),
+                        revision: state.revision + 1,
+                    });
+                });
+                const beginInstall = (inputs) => Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.pending !== null) {
+                        return yield* invalid();
+                    }
+                    yield* record({
+                        ...state,
+                        pending: { inputs, kind: "installation", stopped: false },
+                        revision: state.revision + 1,
+                    });
+                    yield* Ref.set(writer, true);
+                }).pipe(Effect.uninterruptible);
+                const installStopped = Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.pending?.kind !== "installation") {
+                        return yield* invalid();
+                    }
+                    // Persist confirmed process completion before releasing the lease.
+                    // An in-memory flag cannot justify recovery in another invocation.
+                    yield* record({
+                        ...state,
+                        pending: { ...state.pending, stopped: true },
+                        revision: state.revision + 1,
+                    });
+                    yield* Ref.set(writer, false);
+                }).pipe(Effect.uninterruptible);
+                const recoverInstall = (expectedRevision) => Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.revision !== expectedRevision ||
+                        state.pending?.kind !== "installation" ||
+                        !state.pending.stopped ||
+                        (yield* Ref.get(writer))) {
+                        return yield* invalid();
+                    }
+                    yield* record({
+                        ...state,
+                        installation: null,
+                        pending: null,
+                        revision: state.revision + 1,
+                    });
+                });
+                const finishInstall = (installation, lockfile) => Effect.gen(function* () {
+                    const state = yield* Ref.get(current);
+                    if (state.pending?.kind !== "installation" ||
+                        !state.pending.stopped ||
+                        (yield* Ref.get(writer)) ||
+                        (installation &&
+                            installation.inputs !== state.pending.inputs)) {
+                        return yield* invalid();
+                    }
+                    const previousLock = state.entries.find((entry) => entry.target === "pnpm-lock.yaml");
+                    if (!previousLock) {
+                        return yield* invalid();
+                    }
+                    yield* record({
+                        ...state,
+                        entries: state.entries.map((entry) => entry.target === "pnpm-lock.yaml"
+                            ? { ...entry, applied: lockfile }
+                            : entry),
+                        filesRevision: state.filesRevision +
+                            Number(!sameFingerprint(previousLock.applied, lockfile)),
+                        installation,
+                        pending: null,
+                        revision: state.revision + 1,
+                    });
+                });
+                return yield* use({
+                    appliedEntries: Ref.get(current).pipe(Effect.map((state) => state.entries)),
+                    begin,
+                    beginInstall,
+                    complete,
+                    directory,
+                    finishInstall,
+                    initialize,
+                    installStopped,
+                    installation: Ref.get(current).pipe(Effect.map((state) => state.installation)),
+                    observation: Ref.get(current).pipe(Effect.map((state) => ({
+                        directory,
+                        entries: state.entries,
+                        filesRevision: state.filesRevision,
+                        initialized: state.revision > 0,
+                        installation: state.installation,
+                        pending: state.pending,
+                        preserved: state.preserved,
+                        revision: state.revision,
+                        snapshot: state.snapshot,
+                    }))),
+                    publishSnapshot: (commit, expectedRevision) => Effect.gen(function* () {
+                        const state = yield* Ref.get(current);
+                        if (state.pending !== null ||
+                            state.revision !== expectedRevision ||
+                            !/^[a-f0-9]{40}$/u.test(commit)) {
+                            return yield* invalid();
+                        }
+                        yield* record({
+                            ...state,
+                            revision: state.revision + 1,
+                            snapshot: {
+                                commit,
+                                filesRevision: state.filesRevision,
+                                origins: state.entries.map(({ target, origin }) => ({
+                                    origin,
+                                    target,
+                                })),
+                                revision: state.revision + 1,
+                            },
+                        });
+                    }),
+                    recoverFiles,
+                    recoverInstall,
+                    recoveryEvidence,
+                }).pipe(Effect.ensuring(Ref.set(active, false)));
+            }), options).pipe(Effect.provideService(FileSystem.FileSystem, fs), Effect.provideService(Path.Path, path));
+        };
+        return WorkspaceState.of({ withRead, withWrite });
+    }));
+}

package/dist/workspaces.d.ts

@@ -0,0 +1,73 @@
+import { Context, Effect, FileSystem, Layer, Path, Stream } from "effect";
+import type { PlatformError } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import type { ExistingWorkspace } from "./addition.ts";
+import type { ApplicationGitFailed } from "./application-git.ts";
+import { Composition } from "./composition.ts";
+import type { PreparationError as CompositionError } from "./composition.ts";
+import { DestinationNotEmpty, InvalidComposition, MaterializationFailed, SourceChanged, WorkspaceUninitialized } from "./errors.ts";
+import type { EnvironmentInitializationFailed } from "./errors.ts";
+import type { ExplanationReport, CheckReport, DiffReport, MaterializationReport, SelectionRequest } from "./model.ts";
+import { Shadcn } from "./shadcn.ts";
+import { SourceChanges, SourceWatchFailure } from "./source-changes.ts";
+import { SourceInventory } from "./source-inventory.ts";
+import { WorkspaceDependencies } from "./workspace-dependencies.ts";
+import type { DependencyOptions, DependencyError } from "./workspace-dependencies.ts";
+import { WorkspaceFiles } from "./workspace-files.ts";
+import type { WorkspaceFileError } from "./workspace-files.ts";
+import { WorkspaceSnapshots } from "./workspace-snapshots.ts";
+import type { SnapshotError } from "./workspace-snapshots.ts";
+import { WorkspaceSources } from "./workspace-sources.ts";
+import type { SourceRequest, SourceError } from "./workspace-sources.ts";
+import { WorkspaceState } from "./workspace-state.ts";
+import type { WorkspaceStateError } from "./workspace-state.ts";
+type PreparationError = CompositionError | SourceError;
+export interface FreshRequest {
+    readonly source: SourceRequest;
+    readonly destination: string;
+    readonly selection: SelectionRequest;
+    readonly name: string;
+}
+export interface NamedWorkspaceRef {
+    readonly sourceRoot: string;
+    readonly name: string;
+}
+export interface SyncOptions extends DependencyOptions {
+    readonly environment?: "preserve" | "copy-missing-local";
+}
+export interface NamedSyncOptions extends SyncOptions {
+    readonly breakLock?: string;
+}
+export interface FreshOptions extends SyncOptions {
+    readonly git?: "skip" | "initialize" | "commit";
+}
+export interface FreshWorkspace {
+    readonly materialize: (options: FreshOptions) => Effect.Effect<MaterializationReport, PreparationError | ApplicationGitFailed | DestinationNotEmpty | EnvironmentInitializationFailed | MaterializationFailed | PlatformError.PlatformError | DependencyError>;
+}
+export interface NamedWorkspace {
+    readonly watch: (options: SyncOptions) => Stream.Stream<WatchEvent, Effect.Error<ReturnType<NamedWorkspace["sync"]>> | SourceWatchFailure>;
+    readonly diff: Effect.Effect<DiffReport, WorkspaceFileError | WorkspaceStateError | SnapshotError | DestinationNotEmpty | SourceChanged | WorkspaceUninitialized>;
+    readonly check: Effect.Effect<CheckReport, PreparationError | WorkspaceFileError | WorkspaceStateError | DestinationNotEmpty>;
+    readonly explain: (target?: string) => Effect.Effect<ExplanationReport, PreparationError>;
+    readonly sync: (options: NamedSyncOptions) => Effect.Effect<MaterializationReport, Effect.Error<ReturnType<FreshWorkspace["materialize"]>> | WorkspaceFileError | WorkspaceStateError | SnapshotError>;
+}
+export type WatchEvent = {
+    readonly _tag: "Synchronized";
+    readonly result: MaterializationReport;
+} | {
+    readonly _tag: "RefreshFailed";
+    readonly error: Effect.Error<ReturnType<NamedWorkspace["sync"]>>;
+};
+declare const Workspaces_base: Context.ServiceClass<Workspaces, "create-next-hydra/Workspaces", {
+    readonly existing: (request: {
+        readonly root: string;
+    }) => Effect.Effect<ExistingWorkspace>;
+    readonly discover: (sourceRoot: string) => Effect.Effect<readonly NamedWorkspaceRef[], PlatformError.PlatformError | InvalidComposition>;
+    readonly fresh: (request: FreshRequest) => Effect.Effect<FreshWorkspace>;
+    readonly named: (request: NamedWorkspaceRef) => Effect.Effect<NamedWorkspace, InvalidComposition>;
+}>;
+export declare class Workspaces extends Workspaces_base {
+    static readonly layer: Layer.Layer<Workspaces, never, FileSystem.FileSystem | Path.Path | Shadcn | ChildProcessSpawner.ChildProcessSpawner | WorkspaceState | WorkspaceDependencies | SourceInventory | WorkspaceSources | Composition | SourceChanges | WorkspaceSnapshots | WorkspaceFiles>;
+}
+export {};
+//# sourceMappingURL=workspaces.d.ts.map

package/dist/workspaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../src/workspaces.ts"],"names":[],"mappings":"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"}