voratiq 0.1.0-beta.21 → 0.1.0-beta.23

package/dist/commands/auto/command.d.ts

@@ -69,6 +69,7 @@ export interface AutoVerifyStageResult {
     selectedSpecPath?: string;
     selection?: SelectionDecision;
     selectionWarnings?: readonly string[];
+    warningMessage?: string;
 }
 export interface AutoApplyStageInput {
     runId: string;

package/dist/commands/auto/command.js

@@ -101,12 +101,7 @@ export async function executeAutoCommand(options, dependencies) {
                     stderr: specVerifyResult.stderr,
                     exitCode: specVerifyResult.exitCode,
                 });
-                if (specVerifyResult.exitCode === 1) {
-                    specStatus = "failed";
-                    specDetail = "One or more spec verifiers failed.";
-                    hardFailure = true;
-                }
-                else if (typeof specVerifyResult.selectedSpecPath === "string" &&
+                if (typeof specVerifyResult.selectedSpecPath === "string" &&
                     specVerifyResult.selectedSpecPath.trim().length > 0) {
                     resolvedSpecPath = specVerifyResult.selectedSpecPath;
                     specPath = specVerifyResult.selectedSpecPath;
@@ -117,9 +112,8 @@ export async function executeAutoCommand(options, dependencies) {
                         "Spec verification returned a resolvable selection without a selected spec path.";
                     hardFailure = true;
                 }
-                else {
+                else if (specVerifyResult.selection) {
                     const specSelectionDisposition = classifyAutoVerificationSelection({
-                        targetKind: "spec",
                         selection: specVerifyResult.selection,
                     });
                     if (specSelectionDisposition.kind !== "action_required") {
@@ -128,6 +122,13 @@ export async function executeAutoCommand(options, dependencies) {
                     specDetail = specSelectionDisposition.detail;
                     markActionRequired(specSelectionDisposition.detail);
                 }
+                else if (specVerifyResult.exitCode === 1) {
+                    specStatus = "failed";
+                    specDetail =
+                        specVerifyResult.warningMessage?.trim() ||
+                            "Spec verification did not produce any successful verifier results.";
+                    hardFailure = true;
+                }
             }
             catch (error) {
                 specStatus = "failed";
@@ -215,11 +216,6 @@ export async function executeAutoCommand(options, dependencies) {
             });
             verifyStatus = "succeeded";
             verifySelection = verifyResult.selection;
-            if (verifyResult.exitCode === 1) {
-                verifyStatus = "failed";
-                verifyDetail = "One or more verifiers failed.";
-                hardFailure = true;
-            }
             recordEvent({
                 kind: "body",
                 body: verifyResult.body,
@@ -234,9 +230,14 @@ export async function executeAutoCommand(options, dependencies) {
                     separateWithDivider: bodyOutputEmitted,
                 });
             }
+            if (options.apply === true &&
+                (verifyResult.selectionWarnings?.length ?? 0) > 0) {
+                const warningDetail = "Verification reported warnings for the selected candidate; automatic apply halted. Review the verify output and apply manually if appropriate.";
+                verifyDetail = warningDetail;
+                markActionRequired(warningDetail);
+            }
             if (verifySelection?.state === "unresolved") {
                 const verifySelectionDisposition = classifyAutoVerificationSelection({
-                    targetKind: "run",
                     selection: verifySelection,
                 });
                 applyAutoVerificationSelectionDisposition({
@@ -247,6 +248,13 @@ export async function executeAutoCommand(options, dependencies) {
                     },
                 });
             }
+            else if (verifyResult.exitCode === 1) {
+                verifyStatus = "failed";
+                verifyDetail =
+                    verifyResult.warningMessage?.trim() ||
+                        "Verification did not produce any successful verifier results.";
+                hardFailure = true;
+            }
         }
         catch (error) {
             verifyStatus = "failed";
@@ -270,7 +278,6 @@ export async function executeAutoCommand(options, dependencies) {
                 });
             }
             classifyAutoVerificationSelection({
-                targetKind: "run",
                 selection: verifySelection,
             });
             if (verifySelection.state !== "resolvable") {

package/dist/commands/auto/errors.js

@@ -12,7 +12,7 @@ export class AutoPreflightError extends CliError {
             }
         });
         super("Preflight failed. Aborting auto.", detailLines, [
-            "Run `voratiq init` from the repository root, then retry.",
+            "Run `voratiq doctor --fix` to repair workspace setup.",
         ]);
         this.name = "AutoPreflightError";
     }

package/dist/commands/auto/validation.js

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import { HintedError } from "../../utils/errors.js";
 import { isDirectory, isFile } from "../../utils/fs.js";
-import { formatWorkspacePath, resolveWorkspacePath, VORATIQ_VERIFICATION_TEMPLATES_DIR, } from "../../workspace/structure.js";
+import { VORATIQ_VERIFICATION_TEMPLATES_DIR } from "../../workspace/constants.js";
+import { formatWorkspacePath } from "../../workspace/path-formatters.js";
+import { resolveWorkspacePath } from "../../workspace/path-resolvers.js";
 import { AutoPreflightError } from "./errors.js";
 export async function validateAutoVerificationConfig(options) {
     const requiredSelectors = resolveRequiredAutoSelectors(options.command);

package/dist/commands/doctor/agents.d.ts

@@ -0,0 +1,5 @@
+import { type AgentPreset } from "../../workspace/templates.js";
+import type { AgentInitSummary, DoctorBootstrapConfigureOptions } from "./fix-types.js";
+export declare const AGENTS_CONFIG_DISPLAY_PATH: string;
+export declare function bootstrapDoctorAgents(root: string, preset: AgentPreset, options: DoctorBootstrapConfigureOptions): Promise<AgentInitSummary>;
+export declare function reconcileManagedDoctorAgents(root: string): Promise<AgentInitSummary>;

package/dist/commands/{init → doctor}/agents.js

@@ -1,21 +1,37 @@
 import { getAgentDefaultId, getSupportedAgentDefaults, } from "../../configs/agents/defaults.js";
 import { readAgentsConfig } from "../../configs/agents/loader.js";
 import { detectBinary } from "../../utils/binaries.js";
-import { isDefaultYamlTemplate, loadYamlConfig, persistYamlConfig, } from "../../utils/yaml.js";
-import { formatWorkspacePath, resolveWorkspacePath, VORATIQ_AGENTS_FILE, } from "../../workspace/structure.js";
+import { isDefaultYamlTemplate, loadYamlConfig, writeConfigIfChanged, } from "../../utils/yaml.js";
+import { VORATIQ_AGENTS_FILE } from "../../workspace/constants.js";
+import { isManagedAgentsFingerprintMatch, readManagedState, } from "../../workspace/managed-state.js";
+import { formatWorkspacePath } from "../../workspace/path-formatters.js";
+import { resolveWorkspacePath } from "../../workspace/path-resolvers.js";
 import { buildDefaultAgentsTemplate, serializeAgentsConfigEntries, } from "../../workspace/templates.js";
 export const AGENTS_CONFIG_DISPLAY_PATH = formatWorkspacePath(VORATIQ_AGENTS_FILE);
-export async function configureAgents(root, preset, options) {
+export async function bootstrapDoctorAgents(root, preset, options) {
     void preset;
     void options;
-    const filePath = resolveWorkspacePath(root, VORATIQ_AGENTS_FILE);
     const defaultTemplate = buildDefaultAgentsTemplate();
+    return configureAgentsWithMode(root, defaultTemplate, "bootstrap");
+}
+export async function reconcileManagedDoctorAgents(root) {
+    const defaultTemplate = buildDefaultAgentsTemplate();
+    return configureAgentsWithMode(root, defaultTemplate, "reconcile");
+}
+async function configureAgentsWithMode(root, defaultTemplate, mode) {
+    const filePath = resolveWorkspacePath(root, VORATIQ_AGENTS_FILE);
     const loadResult = await loadYamlConfig(filePath, readAgentsConfig);
     const defaultStatus = isDefaultYamlTemplate(loadResult.snapshot, defaultTemplate);
     const configCreated = !loadResult.snapshot.exists;
-    const lifecycle = scanWorkspaceForAgentDefaults(loadResult.config, defaultStatus, getSupportedAgentDefaults());
+    const managedState = mode === "reconcile" ? await readManagedState(root) : undefined;
+    const managed = mode === "reconcile"
+        ? !loadResult.snapshot.exists ||
+            isManagedAgentsFingerprintMatch(managedState?.configs.agents, loadResult.snapshot.content) ||
+            defaultStatus
+        : defaultStatus;
+    const lifecycle = scanWorkspaceForAgentDefaults(loadResult.config, mode, getSupportedAgentDefaults());
     const detectedProviders = collectDetectedProviders(lifecycle.templates);
-    if (!defaultStatus && loadResult.snapshot.exists) {
+    if (!managed && loadResult.snapshot.exists) {
         return buildAgentSummary({
             entries: loadResult.config.agents,
             zeroDetections: detectedProviders.length === 0,
@@ -23,16 +39,14 @@ export async function configureAgents(root, preset, options) {
             providerEnablementPrompted: false,
             configCreated,
             configUpdated: false,
+            managed: false,
         });
     }
     const snapshotResult = finalizeAgentConfigSnapshot(lifecycle);
-    const updated = await persistYamlConfig({
-        filePath,
-        serialized: snapshotResult.serialized,
-        original: loadResult.snapshot,
-        defaultTemplate,
-        isDefaultTemplate: defaultStatus,
-    });
+    const previousNormalized = loadResult.snapshot.exists
+        ? loadResult.snapshot.normalized
+        : "__missing__";
+    const updated = await writeConfigIfChanged(filePath, snapshotResult.serialized, previousNormalized);
     return buildAgentSummary({
         entries: snapshotResult.entries,
         zeroDetections: lifecycle.zeroDetections,
@@ -40,9 +54,10 @@ export async function configureAgents(root, preset, options) {
         providerEnablementPrompted: false,
         configCreated,
         configUpdated: updated,
+        managed: true,
     });
 }
-function scanWorkspaceForAgentDefaults(config, isDefaultTemplate, templates) {
+function scanWorkspaceForAgentDefaults(config, mode, templates) {
     const templatesById = new Map();
     for (const entry of config.agents) {
         templatesById.set(entry.id, entry);
@@ -56,9 +71,7 @@ function scanWorkspaceForAgentDefaults(config, isDefaultTemplate, templates) {
     }));
     for (const { template, templateId } of templateEntries) {
         templateIds.add(templateId);
-        const existing = isDefaultTemplate
-            ? undefined
-            : templatesById.get(templateId);
+        const existing = templatesById.get(templateId);
         let detectedBinary = detectedBinaryByProvider.get(template.provider);
         if (!detectedBinaryByProvider.has(template.provider)) {
             detectedBinary = detectBinary(template.provider);
@@ -66,8 +79,14 @@ function scanWorkspaceForAgentDefaults(config, isDefaultTemplate, templates) {
         }
         const baseEntry = existing ?? buildEntryFromTemplate(template, templateId);
         const entry = cloneAgentEntry(baseEntry);
-        entry.binary = detectedBinary ?? "";
-        entry.enabled = entry.enabled !== false;
+        if (hasBinary(detectedBinary)) {
+            entry.binary = detectedBinary ?? "";
+            entry.enabled = true;
+        }
+        else if (!existing || mode === "bootstrap") {
+            entry.binary = "";
+            entry.enabled = false;
+        }
         templateStates.push({
             templateId,
             template,
@@ -142,7 +161,7 @@ function finalizeAgentConfigSnapshot(state) {
     return { entries, serialized };
 }
 function buildAgentSummary(options) {
-    const { entries, zeroDetections, detectedProviders, providerEnablementPrompted, configCreated, configUpdated, } = options;
+    const { entries, zeroDetections, detectedProviders, providerEnablementPrompted, configCreated, configUpdated, managed, } = options;
     const enabledAgents = entries
         .filter((entry) => entry.enabled !== false)
         .map((entry) => entry.id);
@@ -155,6 +174,7 @@ function buildAgentSummary(options) {
         providerEnablementPrompted,
         configCreated,
         configUpdated,
+        managed,
     };
 }
 function hasBinary(binary) {

package/dist/commands/doctor/command.d.ts

@@ -0,0 +1,22 @@
+import { executeDoctorBootstrap } from "./fix.js";
+import type { DoctorReconcileResult } from "./fix-types.js";
+export interface DoctorDiagnosisResult {
+    readonly healthy: boolean;
+    readonly issueLines: readonly string[];
+}
+export type DoctorFixMode = "bootstrap-workspace" | "repair-and-reconcile";
+export interface DoctorFixResult {
+    readonly mode: DoctorFixMode;
+    readonly reconcileResult?: DoctorReconcileResult;
+}
+export interface ExecuteDoctorDiagnosisInput {
+    readonly root: string;
+}
+export interface ExecuteDoctorFixInput {
+    readonly root: string;
+    readonly mode?: DoctorFixMode;
+    readonly bootstrapOptions?: Pick<Parameters<typeof executeDoctorBootstrap>[0], "preset" | "interactive" | "assumeYes" | "confirm" | "prompt">;
+}
+export declare function executeDoctorDiagnosis(input: ExecuteDoctorDiagnosisInput): Promise<DoctorDiagnosisResult>;
+export declare function resolveDoctorFixMode(root: string): Promise<DoctorFixMode>;
+export declare function executeDoctorFix(input: ExecuteDoctorFixInput): Promise<DoctorFixResult>;

package/dist/commands/doctor/command.js

@@ -0,0 +1,100 @@
+import { formatPreflightIssueLines } from "../../competition/shared/preflight.js";
+import { EnvironmentConfigParseError, MissingEnvironmentConfigError, } from "../../configs/environment/errors.js";
+import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
+import { prepareConfiguredOperatorReadiness } from "../../preflight/operator.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { pathExists } from "../../utils/fs.js";
+import { WorkspaceError, WorkspaceMissingEntryError, } from "../../workspace/errors.js";
+import { formatWorkspacePath } from "../../workspace/path-formatters.js";
+import { resolveWorkspacePath } from "../../workspace/path-resolvers.js";
+import { repairWorkspaceStructure, validateWorkspace, } from "../../workspace/setup.js";
+import { executeDoctorBootstrap } from "./fix.js";
+import { executeDoctorReconcile } from "./reconcile.js";
+const DOCTOR_PREFLIGHT_UNLABELED_AGENT_IDS = ["settings"];
+export async function executeDoctorDiagnosis(input) {
+    const { root } = input;
+    const issueLines = [];
+    const workspacePresent = await pathExists(resolveWorkspacePath(root));
+    if (!workspacePresent) {
+        const missingWorkspaceIssue = new WorkspaceMissingEntryError(`${formatWorkspacePath()}/`);
+        issueLines.push(`- ${missingWorkspaceIssue.headline}`);
+        return {
+            healthy: false,
+            issueLines,
+        };
+    }
+    try {
+        await validateWorkspace(root);
+    }
+    catch (error) {
+        issueLines.push(...formatDoctorIssueLines(error));
+        return {
+            healthy: false,
+            issueLines,
+        };
+    }
+    try {
+        const diagnostics = await prepareConfiguredOperatorReadiness({ root });
+        if (diagnostics.noAgentsEnabled) {
+            issueLines.push("- No agents are enabled in `agents.yaml`.");
+        }
+        issueLines.push(...formatPreflightIssueLines(diagnostics.issues, {
+            unlabeledAgentIds: DOCTOR_PREFLIGHT_UNLABELED_AGENT_IDS,
+        }));
+    }
+    catch (error) {
+        issueLines.push(...formatDoctorIssueLines(error));
+    }
+    try {
+        loadEnvironmentConfig({ root });
+    }
+    catch (error) {
+        if (error instanceof MissingEnvironmentConfigError) {
+            issueLines.push(`- ${error.headline}`);
+        }
+        else if (error instanceof EnvironmentConfigParseError) {
+            issueLines.push(`- ${error.headline}`);
+        }
+        else {
+            issueLines.push(`- ${toErrorMessage(error)}`);
+        }
+    }
+    return {
+        healthy: issueLines.length === 0,
+        issueLines,
+    };
+}
+export async function resolveDoctorFixMode(root) {
+    const workspacePresent = await pathExists(resolveWorkspacePath(root));
+    return workspacePresent ? "repair-and-reconcile" : "bootstrap-workspace";
+}
+export async function executeDoctorFix(input) {
+    const mode = input.mode ?? (await resolveDoctorFixMode(input.root));
+    if (mode === "bootstrap-workspace") {
+        const bootstrapOptions = input.bootstrapOptions;
+        await executeDoctorBootstrap({
+            root: input.root,
+            preset: bootstrapOptions?.preset ?? "pro",
+            interactive: bootstrapOptions?.interactive ?? false,
+            assumeYes: bootstrapOptions?.assumeYes,
+            confirm: bootstrapOptions?.confirm,
+            prompt: bootstrapOptions?.prompt,
+        });
+        return { mode };
+    }
+    await repairWorkspaceStructure(input.root);
+    const reconcileResult = await executeDoctorReconcile({ root: input.root });
+    return {
+        mode,
+        reconcileResult,
+    };
+}
+function formatDoctorIssueLines(error) {
+    if (error instanceof WorkspaceError) {
+        return [`- ${error.headline}`];
+    }
+    if (error instanceof Error && error.message.length > 0) {
+        return [`- ${error.message}`];
+    }
+    return [`- ${toErrorMessage(error)}`];
+}

package/dist/commands/doctor/environment.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorBootstrapConfigureOptions, EnvironmentInitSummary } from "./fix-types.js";
+export declare function reconcileDoctorEnvironment(root: string, options: DoctorBootstrapConfigureOptions): Promise<EnvironmentInitSummary>;

package/dist/commands/{init → doctor}/environment.js

@@ -1,15 +1,18 @@
 import { detectEnvironmentConfig } from "../../configs/environment/detect.js";
+import { EnvironmentConfigParseError } from "../../configs/environment/errors.js";
 import { readEnvironmentConfig, serializeEnvironmentConfig, } from "../../configs/environment/loader.js";
 import { getNodeDependencyRoots, getPythonEnvironmentPath, isNodeEnvironmentDisabled, isPythonEnvironmentDisabled, } from "../../configs/environment/types.js";
-import { loadYamlConfig, persistYamlConfig } from "../../utils/yaml.js";
-import { formatWorkspacePath, resolveWorkspacePath, VORATIQ_ENVIRONMENT_FILE, } from "../../workspace/structure.js";
+import { persistYamlConfig, readConfigSnapshot } from "../../utils/yaml.js";
+import { VORATIQ_ENVIRONMENT_FILE } from "../../workspace/constants.js";
+import { formatWorkspacePath } from "../../workspace/path-formatters.js";
+import { resolveWorkspacePath } from "../../workspace/path-resolvers.js";
 import { buildDefaultEnvironmentTemplate } from "../../workspace/templates.js";
 const ENVIRONMENT_CONFIG_DISPLAY_PATH = formatWorkspacePath(VORATIQ_ENVIRONMENT_FILE);
-export async function configureEnvironment(root, options) {
+export async function reconcileDoctorEnvironment(root, options) {
     const filePath = resolveWorkspacePath(root, VORATIQ_ENVIRONMENT_FILE);
     const defaultTemplate = buildDefaultEnvironmentTemplate();
-    const loadResult = await loadYamlConfig(filePath, readEnvironmentConfig);
-    const existingConfig = loadResult.config;
+    const originalSnapshot = await readConfigSnapshot(filePath);
+    const existingConfig = resolveExistingConfig(originalSnapshot);
     const detection = await detectEnvironmentConfig({
         root,
         interactive: options.interactive,
@@ -20,17 +23,48 @@ export async function configureEnvironment(root, options) {
     const configUpdated = await persistYamlConfig({
         filePath,
         serialized: finalSerialized,
-        original: loadResult.snapshot,
+        original: shouldRewriteFromScratch(originalSnapshot)
+            ? { content: "", normalized: "", exists: false }
+            : originalSnapshot,
         defaultTemplate,
     });
     return {
         configPath: ENVIRONMENT_CONFIG_DISPLAY_PATH,
         detectedEntries: describeEnvironmentEntries(mergedConfig),
-        configCreated: !loadResult.snapshot.exists,
+        configCreated: !originalSnapshot.exists,
         configUpdated,
         config: mergedConfig,
     };
 }
+function resolveExistingConfig(snapshot) {
+    if (!snapshot.exists) {
+        return {};
+    }
+    try {
+        return readEnvironmentConfig(snapshot.content);
+    }
+    catch (error) {
+        if (error instanceof EnvironmentConfigParseError) {
+            return {};
+        }
+        throw error;
+    }
+}
+function shouldRewriteFromScratch(snapshot) {
+    if (!snapshot.exists) {
+        return false;
+    }
+    try {
+        readEnvironmentConfig(snapshot.content);
+        return false;
+    }
+    catch (error) {
+        if (error instanceof EnvironmentConfigParseError) {
+            return true;
+        }
+        throw error;
+    }
+}
 function mergeEnvironmentConfig(existing, detected) {
     const merged = { ...existing };
     if (!isNodeEnvironmentDisabled(merged)) {

package/dist/commands/{init/types.d.ts → doctor/fix-types.d.ts}

@@ -2,17 +2,18 @@ import type { EnvironmentConfig } from "../../configs/environment/types.js";
 import type { ConfirmationOptions, PromptOptions } from "../../render/interactions/confirmation.js";
 import type { AgentPreset } from "../../workspace/templates.js";
 import type { CreateWorkspaceResult } from "../../workspace/types.js";
-export interface InitCommandInput {
+export interface DoctorBootstrapInput {
     root: string;
     preset: AgentPreset;
     presetProvided?: boolean;
     onPresetResolved?: (preset: AgentPreset) => void;
     assumeYes?: boolean;
     interactive: boolean;
-    confirm?: InitConfirmationHandler;
-    prompt?: InitPromptHandler;
+    confirm?: DoctorConfirmationHandler;
+    prompt?: DoctorPromptHandler;
 }
-export interface InitCommandResult {
+export interface DoctorBootstrapResult {
+    mode: "bootstrap" | "repair";
     preset: AgentPreset;
     workspaceResult: CreateWorkspaceResult;
     agentSummary: AgentInitSummary;
@@ -29,6 +30,7 @@ export interface AgentInitSummary {
     providerEnablementPrompted: boolean;
     configCreated: boolean;
     configUpdated: boolean;
+    managed: boolean;
 }
 export interface DetectedProviderSummary {
     provider: string;
@@ -48,12 +50,31 @@ export interface SandboxInitSummary {
 export interface OrchestrationInitSummary {
     configPath: string;
     configCreated: boolean;
+    configUpdated?: boolean;
 }
-export type InitConfirmationHandler = (options: ConfirmationOptions) => Promise<boolean>;
-export type InitPromptHandler = (options: PromptOptions) => Promise<string>;
-export interface InitConfigureOptions {
+export type DoctorConfirmationHandler = (options: ConfirmationOptions) => Promise<boolean>;
+export type DoctorPromptHandler = (options: PromptOptions) => Promise<string>;
+export interface DoctorBootstrapConfigureOptions {
     interactive: boolean;
     assumeYes?: boolean;
-    confirm?: InitConfirmationHandler;
-    prompt?: InitPromptHandler;
+    confirm?: DoctorConfirmationHandler;
+    prompt?: DoctorPromptHandler;
+}
+export interface DoctorReconcileInput {
+    root: string;
+}
+export interface DoctorReconcileOrchestrationSummary {
+    configPath: string;
+    configCreated: boolean;
+    configUpdated: boolean;
+    skippedCustomized: boolean;
+    managed: boolean;
+    preset: AgentPreset;
+}
+export interface DoctorReconcileResult {
+    workspaceBootstrapped: boolean;
+    workspaceResult?: CreateWorkspaceResult;
+    agentSummary: AgentInitSummary;
+    environmentSummary: EnvironmentInitSummary;
+    orchestrationSummary: DoctorReconcileOrchestrationSummary;
 }

package/dist/commands/doctor/fix.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorBootstrapInput, DoctorBootstrapResult } from "./fix-types.js";
+export declare function executeDoctorBootstrap(input: DoctorBootstrapInput): Promise<DoctorBootstrapResult>;