@zq-silk/yui 0.0.0

package/dist/setup/setupCommand.js

@@ -0,0 +1,317 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { configuredAgentToDefinition, createConfiguredAgent } from "../agent/agent.js";
+import { runCompletionWizard } from "../completion/completionWizard.js";
+import { usageError } from "../errors/cliError.js";
+import { defaultTableWidth, renderTable } from "../output/table.js";
+import { createGlobalRole, createRoleAgentBinding } from "../role/role.js";
+import { SYSTEM_LEADER_ROLE, SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
+import { ensureYuiHome, FileTaskStore, resolveYuiHome } from "../storage/taskStore.js";
+import { ensureStorageSchema } from "../storage/storageSchema.js";
+const BUILTIN_AGENTS = Object.freeze([
+    Object.freeze({
+        id: "codex",
+        adapterId: "codex",
+        command: "codex",
+        description: "OpenAI Codex CLI"
+    }),
+    Object.freeze({
+        id: "claude",
+        adapterId: "claude",
+        command: "claude",
+        description: "Anthropic Claude Code"
+    })
+]);
+export async function runSetupCommand(args, env, executor, io = {}) {
+    const dependency = parseSetupOptions(args);
+    if (!shouldPrompt(io))
+        throw setupRequiresInteractiveError();
+    const readline = createInterface({
+        input: io.input,
+        output: io.output,
+        terminal: io.input.isTTY === true
+    });
+    try {
+        const question = createSetupQuestion(readline, io);
+        const home = resolveYuiHome(env);
+        ensureYuiHome(home);
+        ensureStorageSchema(home);
+        const store = new FileTaskStore(home);
+        const result = await configureYui(store, home, env, question, io);
+        const lines = [
+            "Yui home initialized.",
+            `Agents configured: ${result.agentIds.join(", ")}.`,
+            `Default Agent: ${result.defaultAgentId}.`,
+            `Operator Agent: ${result.operatorAgentId}.`,
+            `Operator workspace: ${result.workspace}.`
+        ];
+        if (dependency === undefined || dependency === "tmux") {
+            lines.push(...await setupTmux(env, executor, question));
+        }
+        const completion = await runCompletionWizard("install", store, env, cliIdentity(env), question, { width: tableWidth(io), defaultSelection: "skip" });
+        lines.push(completion.trimEnd());
+        lines.push("Yui setup complete.");
+        return `${lines.join("\n")}\n`;
+    }
+    finally {
+        readline.close();
+    }
+}
+export function validateSetupInvocation(args, io = {}) {
+    parseSetupOptions(args);
+    if (!shouldPrompt(io))
+        throw setupRequiresInteractiveError();
+}
+async function configureYui(store, home, env, question, io) {
+    const candidates = availableAgentChoices(store, env);
+    if (candidates.length === 0) {
+        throw usageError("No supported Agent CLI was found. Install Codex or Claude, then run setup again.");
+    }
+    io.output?.write(`${renderTable("Available Agents", [
+        { header: "#", minWidth: 1, maxWidth: 3 },
+        { header: "Agent", minWidth: 6, maxWidth: 16 },
+        { header: "Adapter", minWidth: 7, maxWidth: 10 },
+        { header: "Command", minWidth: 7, maxWidth: 24 },
+        { header: "Description", minWidth: 12, maxWidth: 42 }
+    ], candidates.map((candidate, index) => [
+        String(index + 1),
+        candidate.id,
+        candidate.adapterId,
+        candidate.command,
+        candidate.description
+    ]), tableWidth(io))}\n`);
+    const selected = parseAgentSetSelection(await question(`Choose Agents by number or name, comma-separated [all: ${candidates.map(({ id }) => id).join(", ")}]: `), candidates);
+    const now = new Date();
+    const persisted = selected.map((choice) => persistAgent(store, choice, now));
+    const configuredIds = new Set(persisted.map(({ id }) => id));
+    const config = store.getConfig();
+    const defaultFallback = configuredIds.has(config.defaultAgent ?? "")
+        ? config.defaultAgent
+        : persisted[0]?.id;
+    if (defaultFallback === undefined)
+        throw usageError("At least one Agent must be selected.");
+    const defaultAgentId = parseSingleAgentSelection(await question(`Choose default Agent [${defaultFallback}]: `), persisted, defaultFallback);
+    const currentOperatorAgent = store.getGlobalRole(SYSTEM_OPERATOR_ROLE)?.activeAgentId;
+    const operatorFallback = configuredIds.has(currentOperatorAgent ?? "")
+        ? currentOperatorAgent
+        : defaultAgentId;
+    const operatorAgentId = parseSingleAgentSelection(await question(`Choose Operator Agent [${operatorFallback}]: `), persisted, operatorFallback);
+    const suggestedWorkspace = config.defaultWorkspace?.trim() || join(home, "workspace");
+    const workspaceAnswer = (await question(`Operator workspace [${suggestedWorkspace}]: `)).trim();
+    const workspace = resolveWorkspace(workspaceAnswer || suggestedWorkspace);
+    const defaultAgent = persisted.find(({ id }) => id === defaultAgentId);
+    const operatorAgent = persisted.find(({ id }) => id === operatorAgentId);
+    if (defaultAgent === undefined || operatorAgent === undefined) {
+        throw usageError("Selected setup Agent is no longer available.");
+    }
+    assertSystemRoleCompatible(store, SYSTEM_OPERATOR_ROLE, operatorAgent, workspace);
+    assertSystemRoleCompatible(store, SYSTEM_LEADER_ROLE, defaultAgent, workspace);
+    mkdirSync(workspace, { recursive: true, mode: 0o700 });
+    store.saveConfig({
+        ...store.getConfig(),
+        defaultAgent: defaultAgentId,
+        defaultWorkspace: workspace
+    });
+    ensureSystemRole(store, SYSTEM_OPERATOR_ROLE, operatorAgent, workspace, now);
+    ensureSystemRole(store, SYSTEM_LEADER_ROLE, defaultAgent, workspace, now);
+    return {
+        agentIds: persisted.map(({ id }) => id),
+        defaultAgentId,
+        operatorAgentId,
+        workspace
+    };
+}
+function availableAgentChoices(store, env) {
+    const existing = new Map(store.listConfiguredAgents().map((agent) => [agent.id, agent]));
+    return BUILTIN_AGENTS.flatMap((builtin) => {
+        const configured = existing.get(builtin.id);
+        const command = configured?.command ?? builtin.command;
+        if (!commandOnPath(command, env))
+            return [];
+        return [{
+                ...builtin,
+                adapterId: configured?.adapterId ?? builtin.adapterId,
+                command
+            }];
+    });
+}
+function persistAgent(store, choice, now) {
+    const existing = store.getConfiguredAgent(choice.id);
+    if (existing !== null
+        && existing.adapterId === choice.adapterId
+        && existing.command === choice.command) {
+        return existing;
+    }
+    const agent = createConfiguredAgent(choice.id, choice.adapterId, choice.command, existing?.baseArgs ?? [], existing?.environment ?? [], now);
+    store.saveConfiguredAgent(agent);
+    return agent;
+}
+function ensureSystemRole(store, name, agent, workspace, now) {
+    const definition = configuredAgentToDefinition(agent);
+    const existing = store.getGlobalRole(name);
+    if (existing !== null)
+        return;
+    store.saveGlobalRole(createGlobalRole(name, [createRoleAgentBinding(definition)], definition.id, workspace, now));
+}
+function assertSystemRoleCompatible(store, name, agent, workspace) {
+    const existing = store.getGlobalRole(name);
+    if (existing === null)
+        return;
+    if (existing.activeAgentId === agent.id && existing.workspace === workspace)
+        return;
+    throw usageError(`Global Role ${name} is already configured with Agent ${existing.activeAgentId} `
+        + `and workspace ${existing.workspace}. Stop its Session and use role update before changing it.`);
+}
+function parseAgentSetSelection(answer, candidates) {
+    const value = answer.trim().toLowerCase();
+    if (value.length === 0 || value === "all")
+        return [...candidates];
+    const tokens = value.split(",").map((token) => token.trim()).filter(Boolean);
+    if (tokens.length === 0)
+        throw usageError("Select at least one Agent.");
+    const selected = [];
+    for (const token of tokens) {
+        const numeric = Number(token);
+        const choice = Number.isSafeInteger(numeric) && numeric >= 1 && numeric <= candidates.length
+            ? candidates[numeric - 1]
+            : candidates.find(({ id }) => id.toLowerCase() === token);
+        if (choice === undefined) {
+            throw usageError("Choose available Agents by number or name, separated by commas.");
+        }
+        if (!selected.some(({ id }) => id === choice.id))
+            selected.push(choice);
+    }
+    return selected;
+}
+function parseSingleAgentSelection(answer, agents, fallback) {
+    const value = answer.trim().toLowerCase();
+    if (value.length === 0)
+        return fallback;
+    const numeric = Number(value);
+    const selected = Number.isSafeInteger(numeric) && numeric >= 1 && numeric <= agents.length
+        ? agents[numeric - 1]
+        : agents.find(({ id }) => id.toLowerCase() === value);
+    if (selected === undefined) {
+        throw usageError("Choose one of the configured Agents by number or name.");
+    }
+    return selected.id;
+}
+function resolveWorkspace(value) {
+    if (!isAbsolute(value))
+        throw usageError("Operator workspace must be an absolute path.");
+    return resolve(value);
+}
+function commandOnPath(command, env) {
+    if (command.includes("/") || command.includes("\\"))
+        return existsSync(command);
+    const entries = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const extensions = process.platform === "win32"
+        ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+        : [""];
+    return entries.some((entry) => extensions.some((extension) => existsSync(join(entry, `${command}${extension}`))));
+}
+function createSetupQuestion(readline, io) {
+    if (io.input.isTTY === true)
+        return (prompt) => readline.question(prompt);
+    const lines = readline[Symbol.asyncIterator]();
+    return async (prompt) => {
+        io.output.write(prompt);
+        const line = await lines.next();
+        return line.done ? "" : line.value;
+    };
+}
+function shouldPrompt(io) {
+    return io.input !== undefined
+        && io.output !== undefined
+        && (io.forceInteractive === true || io.input.isTTY === true);
+}
+function setupRequiresInteractiveError() {
+    return usageError("Setup requires an interactive terminal.");
+}
+function tableWidth(io) {
+    return io.output?.columns === undefined
+        ? defaultTableWidth()
+        : Math.max(46, Math.min(io.output.columns, 140));
+}
+function cliIdentity(env) {
+    return env.YUI_CLI_NAME === "yui-dev" ? "yui-dev" : "yui";
+}
+function parseSetupOptions(args) {
+    if (args.length === 0)
+        return undefined;
+    if (args.length === 1 && args[0] === "tmux")
+        return "tmux";
+    throw usageError("Setup usage: yui setup [tmux]");
+}
+async function setupTmux(env, executor, question) {
+    const command = env.YUI_TMUX_BIN ?? "tmux";
+    if (hasExecutable(command, ["-V"], executor))
+        return ["Tmux already installed."];
+    const plan = detectTmuxInstallPlan(env, executor);
+    if (plan === null) {
+        return ["Tmux is not installed.", "Install tmux manually, then run yui doctor."];
+    }
+    const lines = [
+        "Tmux is not installed.",
+        `Install with ${plan.manager}:`,
+        ...plan.steps.map((step) => `  ${step.command} ${step.args.join(" ")}`)
+    ];
+    const answer = (await question("Install tmux now? [y/N]: ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+        return [...lines, "Skipped tmux installation.", "After installing tmux, run yui doctor."];
+    }
+    for (const step of plan.steps)
+        executor.run(step.command, [...step.args], { inheritStdio: true });
+    return hasExecutable(command, ["-V"], executor)
+        ? [...lines, "Tmux installed."]
+        : [...lines, `Tmux install command completed, but ${command} is still unavailable.`, plan.manualHint];
+}
+function detectTmuxInstallPlan(env, executor) {
+    if (process.platform === "darwin" && commandExists("brew", env, executor)) {
+        return {
+            manager: "Homebrew",
+            steps: [{ command: "brew", args: ["install", "tmux"] }],
+            manualHint: "brew install tmux"
+        };
+    }
+    if (process.platform !== "linux")
+        return null;
+    for (const candidate of [
+        { command: "apt-get", args: ["install", "-y", "tmux"], hint: "sudo apt-get install -y tmux" },
+        { command: "dnf", args: ["install", "-y", "tmux"], hint: "sudo dnf install -y tmux" },
+        { command: "pacman", args: ["-S", "--noconfirm", "tmux"], hint: "sudo pacman -S --noconfirm tmux" },
+        { command: "apk", args: ["add", "tmux"], hint: "sudo apk add tmux" }
+    ]) {
+        if (!commandExists(candidate.command, env, executor))
+            continue;
+        const step = withLinuxPrivilege(candidate.command, candidate.args, env, executor);
+        if (step !== null) {
+            return { manager: candidate.command, steps: [step], manualHint: candidate.hint };
+        }
+    }
+    return null;
+}
+function hasExecutable(command, args, executor) {
+    try {
+        executor.run(command, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function commandExists(command, env, executor) {
+    if (command.includes("/"))
+        return existsSync(command);
+    return (env.PATH ?? "").split(delimiter).filter(Boolean)
+        .some((entry) => existsSync(join(entry, command)))
+        || hasExecutable(command, ["--version"], executor);
+}
+function withLinuxPrivilege(command, args, env, executor) {
+    if (process.getuid?.() === 0)
+        return { command, args };
+    if (!commandExists("sudo", env, executor))
+        return null;
+    return { command: "sudo", args: [command, ...args] };
+}

package/dist/storage/durableFile.js

@@ -0,0 +1,38 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fsyncSync, mkdirSync, openSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * Replaces one authoritative file without ever exposing a partially-written
+ * JSON document. The temporary file lives beside the destination so rename is
+ * atomic on the supported local filesystems.
+ */
+export function writeTextFileAtomically(target, content) {
+    const directory = dirname(target);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.${basename(target)}.tmp-${process.pid}-${randomUUID()}`);
+    let descriptor = null;
+    try {
+        descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        writeFileSync(descriptor, content, "utf8");
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = null;
+        renameSync(temporary, target);
+        fsyncDirectory(directory);
+    }
+    catch (error) {
+        if (descriptor !== null)
+            closeSync(descriptor);
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+function fsyncDirectory(directory) {
+    const descriptor = openSync(directory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/storage/storageSchema.js

@@ -0,0 +1,259 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeTextFileAtomically } from "./durableFile.js";
+/** Version of the on-disk layout (`schema.json`, root `state.json`, and locks). */
+export const CURRENT_STORAGE_LAYOUT_VERSION = 5;
+/** Version of the authoritative aggregate stored in `state.json`. */
+export const CURRENT_AGGREGATE_SCHEMA_VERSION = 1;
+/** @deprecated Use CURRENT_STORAGE_LAYOUT_VERSION for new code. */
+export const CURRENT_STORAGE_SCHEMA_VERSION = CURRENT_STORAGE_LAYOUT_VERSION;
+export const STORAGE_SCHEMA_FILE = "schema.json";
+/**
+ * The dispatcher is intentionally present from the first v5 release. There
+ * are no v4-to-v5 migrations: v5 is a fresh authoritative storage contract.
+ */
+export const STORAGE_MIGRATIONS = Object.freeze([]);
+/** No historical aggregate is supported by this development release yet. */
+export const AGGREGATE_MIGRATIONS = Object.freeze([]);
+export class StorageSchemaError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "StorageSchemaError";
+        this.code = code;
+    }
+}
+export function inspectStorageSchema(rootDir) {
+    const manifestPath = join(rootDir, STORAGE_SCHEMA_FILE);
+    const raw = readOptionalText(manifestPath);
+    if (raw === null) {
+        return {
+            status: "uninitialized",
+            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            manifestPath
+        };
+    }
+    try {
+        const manifest = parseStorageManifest(raw);
+        if (manifest.storageVersion !== CURRENT_STORAGE_LAYOUT_VERSION) {
+            return {
+                status: "unsupported",
+                incompatibleComponent: "layout",
+                direction: manifest.storageVersion < CURRENT_STORAGE_LAYOUT_VERSION ? "older" : "newer",
+                currentVersion: manifest.storageVersion,
+                latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+                currentLayoutVersion: manifest.storageVersion,
+                latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+                currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+                latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+                manifestPath
+            };
+        }
+        if (manifest.aggregateSchemaVersion !== CURRENT_AGGREGATE_SCHEMA_VERSION) {
+            return {
+                status: "unsupported",
+                incompatibleComponent: "aggregate",
+                direction: manifest.aggregateSchemaVersion < CURRENT_AGGREGATE_SCHEMA_VERSION
+                    ? "older"
+                    : "newer",
+                currentVersion: manifest.aggregateSchemaVersion,
+                latestVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+                currentLayoutVersion: manifest.storageVersion,
+                latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+                currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+                latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+                manifestPath
+            };
+        }
+        return {
+            status: "current",
+            currentVersion: manifest.storageVersion,
+            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            currentLayoutVersion: manifest.storageVersion,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            currentAggregateSchemaVersion: manifest.aggregateSchemaVersion,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            activeGeneration: manifest.activeGeneration,
+            manifestPath
+        };
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            latestVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            latestLayoutVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+            latestAggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+            manifestPath,
+            detail: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export function ensureStorageSchema(rootDir, now = new Date()) {
+    const state = inspectStorageSchema(rootDir);
+    if (state.status === "uninitialized") {
+        writeStorageManifest(rootDir, now);
+        return;
+    }
+    requireInspectedSchema(state);
+}
+export function requireStorageSchema(rootDir) {
+    requireInspectedSchema(inspectStorageSchema(rootDir));
+}
+export function dispatchStorageMigrations(rootDir, fromVersion, targetVersion = CURRENT_STORAGE_LAYOUT_VERSION, migrations = STORAGE_MIGRATIONS) {
+    assertLayoutVersion(fromVersion, "Migration source");
+    assertLayoutVersion(targetVersion, "Migration target");
+    if (fromVersion > targetVersion) {
+        throw unsupportedVersion(fromVersion, targetVersion, "layout");
+    }
+    // Build and validate the complete plan before invoking any filesystem mutation.
+    const bySource = new Map();
+    for (const migration of migrations) {
+        assertLayoutVersion(migration.fromVersion, "Migration fromVersion");
+        assertLayoutVersion(migration.toVersion, "Migration toVersion");
+        if (migration.toVersion !== migration.fromVersion + 1) {
+            throw invalidMigration(`Migration ${migration.fromVersion}->${migration.toVersion} must advance exactly one layout version.`);
+        }
+        if (bySource.has(migration.fromVersion)) {
+            throw invalidMigration(`Duplicate migration from layout version ${migration.fromVersion}.`);
+        }
+        bySource.set(migration.fromVersion, migration);
+    }
+    const plan = [];
+    for (let current = fromVersion; current < targetVersion; current += 1) {
+        const migration = bySource.get(current);
+        if (migration === undefined || migration.toVersion !== current + 1) {
+            throw unsupportedVersion(current, targetVersion, "layout");
+        }
+        plan.push(migration);
+    }
+    for (const migration of plan)
+        migration.migrate(rootDir);
+}
+export function dispatchAggregateMigrations(state, fromVersion, targetVersion = CURRENT_AGGREGATE_SCHEMA_VERSION, migrations = AGGREGATE_MIGRATIONS) {
+    assertLayoutVersion(fromVersion, "Aggregate migration source");
+    assertLayoutVersion(targetVersion, "Aggregate migration target");
+    if (fromVersion > targetVersion) {
+        throw unsupportedVersion(fromVersion, targetVersion, "aggregate");
+    }
+    const bySource = new Map();
+    for (const migration of migrations) {
+        assertLayoutVersion(migration.fromVersion, "Aggregate migration fromVersion");
+        assertLayoutVersion(migration.toVersion, "Aggregate migration toVersion");
+        if (migration.toVersion !== migration.fromVersion + 1) {
+            throw invalidMigration(`Aggregate migration ${migration.fromVersion}->${migration.toVersion} must advance exactly one schema version.`);
+        }
+        if (bySource.has(migration.fromVersion)) {
+            throw invalidMigration(`Duplicate migration from aggregate schema version ${migration.fromVersion}.`);
+        }
+        bySource.set(migration.fromVersion, migration);
+    }
+    const plan = [];
+    for (let current = fromVersion; current < targetVersion; current += 1) {
+        const migration = bySource.get(current);
+        if (migration === undefined || migration.toVersion !== current + 1) {
+            throw unsupportedVersion(current, targetVersion, "aggregate");
+        }
+        plan.push(migration);
+    }
+    return plan.reduce((current, migration) => migration.migrate(current), state);
+}
+function writeStorageManifest(rootDir, now) {
+    const manifest = {
+        schemaVersion: 1,
+        storageVersion: CURRENT_STORAGE_LAYOUT_VERSION,
+        aggregateSchemaVersion: CURRENT_AGGREGATE_SCHEMA_VERSION,
+        activeGeneration: null,
+        updatedAt: now.toISOString()
+    };
+    writeTextFileAtomically(join(rootDir, STORAGE_SCHEMA_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function requireInspectedSchema(state) {
+    switch (state.status) {
+        case "current":
+            return;
+        case "uninitialized":
+            throw new StorageSchemaError("STORAGE_UNINITIALIZED", "Yui storage is not initialized. Run `yui setup`.");
+        case "invalid":
+            throw new StorageSchemaError("STORAGE_SCHEMA_INVALID", `Invalid storage schema manifest at ${state.manifestPath}: ${state.detail}`);
+        case "unsupported":
+            throw unsupportedVersion(state.currentVersion, state.latestVersion, state.incompatibleComponent);
+    }
+}
+function unsupportedVersion(current, required, component) {
+    const label = component === "layout" ? "Storage layout" : "Aggregate schema";
+    if (current < required) {
+        return new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", `${label} ${current} is older than required ${component} version ${required}; no migration is available in this Yui release.`);
+    }
+    return new StorageSchemaError("STORAGE_SCHEMA_UNSUPPORTED", `${label} ${current} is newer than supported ${component} version ${required}; use a newer Yui release.`);
+}
+function parseStorageManifest(raw) {
+    const value = parseJsonObject(raw, "Storage schema manifest");
+    assertKeys(value, ["schemaVersion", "storageVersion", "aggregateSchemaVersion", "updatedAt"], ["activeGeneration"], "Storage schema manifest");
+    if (value.schemaVersion !== 1)
+        throw new Error("schemaVersion must be 1");
+    if (!Number.isInteger(value.storageVersion) || value.storageVersion < 1) {
+        throw new Error("storageVersion must be a positive integer");
+    }
+    const aggregateSchemaVersion = value.aggregateSchemaVersion;
+    if (!Number.isInteger(aggregateSchemaVersion) || aggregateSchemaVersion < 1) {
+        throw new Error("aggregateSchemaVersion must be a positive integer");
+    }
+    const activeGeneration = value.activeGeneration ?? null;
+    if (activeGeneration !== null) {
+        throw new Error(`activeGeneration is not supported by storage layout ${String(value.storageVersion)}`);
+    }
+    if (typeof value.updatedAt !== "string" || !Number.isFinite(Date.parse(value.updatedAt))) {
+        throw new Error("updatedAt must be an ISO timestamp");
+    }
+    return {
+        schemaVersion: 1,
+        storageVersion: value.storageVersion,
+        aggregateSchemaVersion: aggregateSchemaVersion,
+        activeGeneration,
+        updatedAt: value.updatedAt
+    };
+}
+function parseJsonObject(raw, label) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON`, { cause: error });
+    }
+    if (!isRecord(value))
+        throw new Error(`${label} must be an object`);
+    return value;
+}
+function assertKeys(value, requiredKeys, optionalKeys, label) {
+    const expected = new Set([...requiredKeys, ...optionalKeys]);
+    const unknown = Object.keys(value).filter((key) => !expected.has(key));
+    const missing = requiredKeys.filter((key) => !Object.hasOwn(value, key));
+    if (unknown.length > 0)
+        throw new Error(`${label} has unknown field: ${unknown[0]}`);
+    if (missing.length > 0)
+        throw new Error(`${label} is missing field: ${missing[0]}`);
+}
+function assertLayoutVersion(version, label) {
+    if (!Number.isInteger(version) || version < 1) {
+        throw invalidMigration(`${label} must be a positive integer.`);
+    }
+}
+function invalidMigration(message) {
+    return new StorageSchemaError("STORAGE_MIGRATION_INVALID", message);
+}
+function readOptionalText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}