@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/engine/runtime-proposal-helpers.js

@@ -0,0 +1,251 @@
+/**
+ * Pure helpers used by the runtime's action-proposal and method-authoring
+ * paths. None of these depend on runtime state — they shape strings, parse
+ * proposal values, and build CLI previews. Keeping them out of runtime.ts
+ * lets the coordinator stay small and means future tests can reach these
+ * helpers without booting a runtime.
+ */
+import { existsSync } from "node:fs";
+import { AGENTS, } from "./agents/lib/constants.js";
+import { detectAgents, supportsAutomatedRuns, } from "./agents/lib/detection.js";
+import { loadUserConfig, } from "./agents/lib/user-config.js";
+import { asPreparationDataDir, preparationPortableContextPath, } from "../contracts/lib/preparation-paths.js";
+import { DEFAULT_METHOD_ID, methodIdForSourcePreparationConfig, } from "../project/source-config.js";
+import { createCompiledTestTarget, } from "./verify/test-targets.js";
+import { methodAuthoringTaskPrompt, MethodAuthoringActionValuesSchema, } from "./action-values.js";
+import { ActionProposalPlanActionTypeSchema, } from "./lib/schema.js";
+export const ACTION_PLANNER_CLARIFICATION_MESSAGE = "I can help with this Interf Workspace. Ask a question about Interf, or ask me to create a Preparation, prepare, check readiness, improve, or draft a Method and I will prepare an approval proposal.";
+export function createActionProposalId() {
+    return `action_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export function sanitizeActionProposalPlan(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const plan = { ...value };
+    for (const key of ["preparation", "method", "title", "summary", "assistant_message", "command_preview"]) {
+        const current = plan[key];
+        if (current === null || current === undefined) {
+            delete plan[key];
+            continue;
+        }
+        if (typeof current === "string" && current.trim().length === 0) {
+            delete plan[key];
+        }
+    }
+    return plan;
+}
+export function configuredAgentName() {
+    const config = loadUserConfig();
+    if (!config)
+        return null;
+    const configured = AGENTS.find((agent) => agent.command === config.agentCommand) ??
+        AGENTS.find((agent) => agent.name === config.agent) ??
+        AGENTS.find((agent) => agent.displayName === config.agent);
+    return configured?.name ?? null;
+}
+export function detectedExecutorOptions(currentAgentName) {
+    return detectAgents()
+        .filter(supportsAutomatedRuns)
+        .map((agent) => ({
+        name: agent.name,
+        display_name: agent.displayName,
+        command: agent.command,
+        current: agent.name === currentAgentName,
+    }));
+}
+export function slugFromText(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 42)
+        .replace(/-+$/g, "");
+    return slug || "custom";
+}
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function stringValue(values, key) {
+    const value = values?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+export function actionTypeFromValues(values) {
+    const explicit = stringValue(values, "action_type") ?? stringValue(values, "service_action");
+    if (explicit) {
+        const parsed = ActionProposalPlanActionTypeSchema.safeParse(explicit);
+        if (parsed.success && parsed.data !== "clarification")
+            return parsed.data;
+    }
+    const action = stringValue(values, "action");
+    if (action === "compile" || action === "compile-run" || action === "run-preparation")
+        return "compile";
+    if (action === "test" || action === "check-readiness")
+        return "test";
+    if (action === "draft-readiness-checks" || action === "readiness-check-draft")
+        return "readiness-check-draft";
+    if (action === "create-method" || action === "method-authoring")
+        return "method-authoring";
+    if (action === "method-duplicate" || action === "method-remove" || action === "method-change")
+        return "method-change";
+    if (action === "preparation-remove" || action === "preparation-change")
+        return "preparation-change";
+    if (action === "improve-preparation" || action === "method-improvement")
+        return "method-improvement";
+    return null;
+}
+export function directServiceEndpointForAction(actionType) {
+    if (actionType === "preparation-setup")
+        return "/v1/preparation-setups";
+    if (actionType === "method-change")
+        return "/v1/method-changes";
+    if (actionType === "preparation-change")
+        return "/v1/preparation-changes";
+    return null;
+}
+export function numberValue(values, key) {
+    const value = values?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function testModeFromValues(values) {
+    const value = stringValue(values, "mode") ?? stringValue(values, "target");
+    if (value === "portable-context")
+        return "compiled";
+    return value === "source-files" || value === "compiled" || value === "both" ? value : null;
+}
+export function testModeValue(values, defaultMode = "both") {
+    return testModeFromValues(values) ?? defaultMode;
+}
+export function testModeCliTarget(mode) {
+    if (mode === "source-files")
+        return "source-files";
+    if (mode === "compiled")
+        return "portable-context";
+    return "both";
+}
+export function methodIdForProposal(message, values) {
+    const explicit = stringValue(values, "method_id") ??
+        stringValue(values, "method");
+    const fromMessage = message.match(/\b(?:create|reate|eate|draft|author|build|make)\s+(?:a\s+new\s+)?(?:interf\s+)?method\s+([a-z0-9][a-z0-9-]{0,79})\b/i)?.[1];
+    return explicit ?? fromMessage ?? `custom-${slugFromText(message)}`;
+}
+export function actionValueMethodTaskPrompt(values) {
+    const parsed = MethodAuthoringActionValuesSchema.safeParse(values);
+    return parsed.success ? methodAuthoringTaskPrompt(parsed.data) : null;
+}
+const METHOD_AUTHORING_INTERNAL_INSTRUCTION = /Use the attached values as the Method authoring request before proposing the action\.?/gi;
+const METHOD_AUTHORING_LABELS = [
+    "Agent work",
+    "Portable-context output",
+    "Readiness checks",
+    "CLI preview",
+];
+export function normalizeMethodAuthoringText(value) {
+    return value
+        .replace(/[│]+/g, " ")
+        .replace(METHOD_AUTHORING_INTERNAL_INSTRUCTION, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function extractMethodAuthoringSection(value, label) {
+    const otherLabels = METHOD_AUTHORING_LABELS
+        .filter((candidate) => candidate !== label)
+        .map(escapeRegExp)
+        .join("|");
+    const match = value.match(new RegExp(`${escapeRegExp(label)}\\s*:\\s*([\\s\\S]*?)(?=\\s*(?:${otherLabels})\\s*:|$)`, "i"));
+    return match?.[1] ? normalizeMethodAuthoringText(match[1]) : null;
+}
+export function stripMethodCommandPrefix(value, methodId) {
+    const specific = new RegExp(`^(?:create|reate|eate|draft|author|build|make)\\s+(?:a\\s+new\\s+)?(?:interf\\s+)?method\\s+${escapeRegExp(methodId)}\\.?\\s*`, "i");
+    const generic = /^(?:create|reate|eate|draft|author|build|make)\s+(?:a\s+new\s+)?(?:interf\s+)?method\b[^.]{0,180}\.\s*/i;
+    const stripped = normalizeMethodAuthoringText(value)
+        .replace(specific, "")
+        .replace(generic, "")
+        .trim();
+    return stripped || normalizeMethodAuthoringText(value);
+}
+export function methodAuthoringPromptFallback(message, methodId) {
+    const cleaned = message
+        .replace(/[│]+/g, " ")
+        .replace(METHOD_AUTHORING_INTERNAL_INSTRUCTION, " ")
+        .trim();
+    const agentWork = extractMethodAuthoringSection(cleaned, "Agent work");
+    const portableOutput = extractMethodAuthoringSection(cleaned, "Portable-context output");
+    const readinessNotes = extractMethodAuthoringSection(cleaned, "Readiness checks");
+    const lines = [
+        agentWork ? `Agent work: ${stripMethodCommandPrefix(agentWork, methodId)}` : null,
+        portableOutput ? `Portable-context output: ${portableOutput}` : null,
+        readinessNotes ? `Readiness checks: ${readinessNotes}` : null,
+    ].filter((line) => Boolean(line));
+    if (lines.length > 0)
+        return lines.join("\n");
+    return stripMethodCommandPrefix(cleaned, methodId);
+}
+export function methodAuthoringHintFromPrompt(prompt) {
+    const plain = normalizeMethodAuthoringText(prompt.replace(/\b(?:Agent work|Portable-context output|Readiness checks)\s*:/gi, " "));
+    if (plain.length <= 180)
+        return plain || "Custom Method";
+    const clipped = plain.slice(0, 177).replace(/\s+\S*$/, "").trim();
+    return `${clipped || plain.slice(0, 177)}...`;
+}
+export function methodLabelFromId(methodId) {
+    return methodId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+        .join(" ") || methodId;
+}
+export function detachMethodFromPreparation(preparation, methodId) {
+    if (methodIdForSourcePreparationConfig(preparation) !== methodId)
+        return preparation;
+    const { method: _removedMethod, ...detachedPreparation } = preparation;
+    return detachedPreparation;
+}
+export function requireSelectedMethod(preparation) {
+    const methodId = methodIdForSourcePreparationConfig(preparation);
+    if (methodId)
+        return methodId;
+    throw new Error(`Select a Method for Preparation "${preparation.name}" before preparing it.`);
+}
+export function actionCommandPreview(actionType, preparationName, methodId, values) {
+    if (actionType === "compile") {
+        const methodSuffix = methodId ? ` # Method: ${methodId}` : "";
+        return preparationName
+            ? `interf compile --preparation ${preparationName}${methodSuffix}`
+            : `interf compile${methodSuffix}`;
+    }
+    if (actionType === "test") {
+        const mode = testModeCliTarget(testModeValue(values));
+        return preparationName
+            ? `interf test --preparation ${preparationName} --target ${mode}`
+            : `interf test --target ${mode}`;
+    }
+    if (actionType === "readiness-check-draft") {
+        return "interf # choose Auto-create readiness checks";
+    }
+    if (actionType === "method-authoring" || actionType === "method-improvement") {
+        return "interf create method";
+    }
+    return "Try: create a Preparation, prepare, check readiness, draft readiness checks, or draft a Method.";
+}
+export function hasCompiledTestTarget(sourcePath, preparationConfig) {
+    const compiledPath = preparationPortableContextPath(asPreparationDataDir(sourcePath), preparationConfig.name);
+    if (!existsSync(compiledPath))
+        return false;
+    return createCompiledTestTarget(compiledPath, preparationConfig.name, methodIdForSourcePreparationConfig(preparationConfig) ?? DEFAULT_METHOD_ID).eligible;
+}
+export function actionAssistantMessage(actionType, preparationName, commandPreview) {
+    const preparationSuffix = preparationName ? ` for Preparation "${preparationName}"` : "";
+    if (actionType === "compile") {
+        return `Interf prepared a compile-run proposal${preparationSuffix}. Approve to submit it through the local Interf service and watch the run in Interf. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "test") {
+        return `Interf prepared a readiness-check proposal${preparationSuffix}. Approve to run the requested target against saved readiness checks. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "readiness-check-draft") {
+        return `Interf prepared a proposal to draft readiness checks${preparationSuffix}. Approve to ask the configured local executor to draft saved checks as a visible run. CLI equivalent: ${commandPreview}`;
+    }
+    if (actionType === "method-authoring" || actionType === "method-improvement") {
+        return `Interf prepared a Method draft proposal${preparationSuffix}. Approve to draft a reusable local Method as a visible run. CLI equivalent: ${commandPreview}`;
+    }
+    return "I could not map that to a safe Interf action. Ask for one action in plain English, such as create a Preparation, prepare the data, check readiness, draft readiness checks, or draft a Method.";
+}

package/dist/packages/engine/runtime-resource-builders.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure shaping helpers used by the runtime to assemble resource payloads
+ * (preparations, methods, proofs, log paths, readiness summaries) from
+ * raw state/run records. No I/O, no `this` — every input is passed in.
+ *
+ * Splitting these out keeps the runtime coordinator focused on
+ * orchestration rather than payload formatting.
+ */
+import { type ArtifactRef, type ProofRecord } from "./execution/lib/schema.js";
+import { type CompiledState } from "./compile/state.js";
+import { type RuntimeRun } from "./compile/lib/schema.js";
+import { type ReadinessState, type ReadinessTargetResult } from "../contracts/lib/schema.js";
+import { type TestRunTargetSummary } from "./verify/lib/schema.js";
+import { type SourcePreparationConfig } from "../project/lib/schema.js";
+import { type MethodResource, type PreparationResource } from "./lib/schema.js";
+export declare function createRunId(prefix: "compile" | "verify" | "job"): string;
+export declare function stageArtifactRefs(stageId: string, artifacts: string[] | undefined): ArtifactRef[];
+export declare function proofForStage(options: {
+    runId: string;
+    stageId: string;
+    summary?: string | null;
+    stageState: NonNullable<CompiledState["stages"]>[string];
+    artifacts: ArtifactRef[];
+}): ProofRecord;
+export declare function logsForStageRun(stageState: NonNullable<CompiledState["stages"]>[string] | undefined): {
+    prompt_path: string;
+    event_stream_path: string;
+    status_path: string;
+    contract_path: string;
+} | undefined;
+export declare function logsForRuntimeRun(run: RuntimeRun | undefined): {
+    contract_path: string;
+    status_path?: string | undefined;
+    event_stream_path?: string | undefined;
+    prompt_path?: string | undefined;
+} | undefined;
+export declare function passRate(passed: number, total: number): number | null;
+export declare function readinessTargetResult(summary: TestRunTargetSummary | null | undefined, currentFingerprint: string | null, readinessRunFingerprint: string | null | undefined): ReadinessTargetResult | null;
+export declare function readinessSummaryForStatus(status: ReadinessState["status"]): string;
+export declare function readinessStateToPreparationReadiness(readiness: ReadinessState): ReadinessState;
+export declare function buildPreparationResource(rootPath: string, preparation: SourcePreparationConfig, readiness: ReadinessState, latestCompileRunId: string | null, latestTestRunId: string | null): PreparationResource;
+export declare function buildMethodResource(resource: {
+    id: string;
+    path: string;
+    label?: string;
+    hint?: string;
+    source_kind: "builtin" | "local";
+    built_in: boolean;
+    active_for_preparations: string[];
+    output_paths: string[];
+    stages: MethodResource["stages"];
+}): MethodResource;

package/dist/packages/engine/runtime-resource-builders.js

@@ -0,0 +1,149 @@
+import { ReadinessStateSchema, } from "../contracts/lib/schema.js";
+import { methodIdForSourcePreparationConfig, resolveSourcePreparationPath, } from "../project/source-config.js";
+import { MethodResourceSchema, PreparationResourceSchema, } from "./lib/schema.js";
+export function createRunId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export function stageArtifactRefs(stageId, artifacts) {
+    return (artifacts ?? []).map((path) => ({
+        path,
+        role: "output",
+        stage_id: stageId,
+        label: path,
+    }));
+}
+export function proofForStage(options) {
+    return {
+        id: `${options.runId}-${options.stageId}-proof`,
+        run_id: options.runId,
+        stage_id: options.stageId,
+        generated_at: options.stageState.finished_at ?? new Date().toISOString(),
+        summary: options.summary ?? `${options.stageId} produced stage evidence.`,
+        files_processed: options.stageState.counts?.source_total,
+        artifacts: options.artifacts,
+        checks: [
+            {
+                id: `${options.stageId}-status`,
+                label: "stage completed",
+                ok: options.stageState.status === "succeeded",
+                ...(options.stageState.status === "succeeded"
+                    ? {}
+                    : { detail: options.stageState.summary ?? "Stage did not complete successfully." }),
+            },
+            {
+                id: `${options.stageId}-artifacts`,
+                label: "artifacts recorded",
+                ok: options.artifacts.length > 0,
+                ...(options.artifacts.length > 0
+                    ? {}
+                    : { detail: "No stage artifacts were recorded." }),
+            },
+        ],
+    };
+}
+export function logsForStageRun(stageState) {
+    const runId = stageState?.run_id;
+    if (!runId)
+        return undefined;
+    return {
+        prompt_path: `.interf/runtime/logs/${runId}.prompt.txt`,
+        event_stream_path: `.interf/runtime/logs/${runId}.events.ndjson`,
+        status_path: `.interf/runtime/logs/${runId}.status.log`,
+        contract_path: `.interf/runtime/logs/${runId}.stage-contract.json`,
+    };
+}
+export function logsForRuntimeRun(run) {
+    if (!run)
+        return undefined;
+    return {
+        ...(run.logs?.prompt_path ? { prompt_path: run.logs.prompt_path } : {}),
+        ...(run.logs?.event_stream_path ? { event_stream_path: run.logs.event_stream_path } : {}),
+        ...(run.logs?.status_path ? { status_path: run.logs.status_path } : {}),
+        contract_path: run.contract_path,
+    };
+}
+export function passRate(passed, total) {
+    if (total <= 0)
+        return null;
+    return Math.round((passed / total) * 100);
+}
+export function readinessTargetResult(summary, currentFingerprint, readinessRunFingerprint) {
+    if (!summary)
+        return null;
+    const resultFingerprint = readinessRunFingerprint ?? null;
+    return {
+        passed: summary.passed_cases,
+        total: summary.total_cases,
+        pass_rate: passRate(summary.passed_cases, summary.total_cases),
+        checks_fingerprint: resultFingerprint,
+        stale: Boolean(currentFingerprint && resultFingerprint && currentFingerprint !== resultFingerprint),
+        run_id: null,
+        run_path: summary.run_path,
+    };
+}
+export function readinessSummaryForStatus(status) {
+    if (status === "ready")
+        return "Ready for agent work.";
+    if (status === "not-ready")
+        return "Readiness checks did not pass.";
+    if (status === "stale")
+        return "Readiness checks are stale for the current saved checks.";
+    if (status === "checking")
+        return "Readiness checks are running.";
+    if (status === "building")
+        return "Portable context is building.";
+    if (status === "built")
+        return "Portable context is built; readiness has not been proven yet.";
+    if (status === "not-built")
+        return "Portable context has not been built yet.";
+    if (status === "not-configured")
+        return "No readiness checks are configured.";
+    return "Latest preparation failed.";
+}
+export function readinessStateToPreparationReadiness(readiness) {
+    return ReadinessStateSchema.parse({
+        ...readiness,
+        checks: readiness.checks.map((check) => ({ ...check })),
+    });
+}
+export function buildPreparationResource(rootPath, preparation, readiness, latestCompileRunId, latestTestRunId) {
+    const methodId = methodIdForSourcePreparationConfig(preparation);
+    return PreparationResourceSchema.parse({
+        id: preparation.name,
+        name: preparation.name,
+        preparation,
+        source_path: resolveSourcePreparationPath(rootPath, preparation),
+        method_id: methodId,
+        checks: preparation.checks,
+        portable_context: {
+            preparation: preparation.name,
+            path: readiness.portable_context_path,
+            exists: readiness.portable_context_path !== null,
+            method_id: methodId,
+            latest_compile_run_id: latestCompileRunId,
+            latest_test_run_id: latestTestRunId,
+        },
+        portable_context_path: readiness.portable_context_path,
+        readiness: readinessStateToPreparationReadiness(readiness),
+        runs: {
+            latest_compile_run_id: latestCompileRunId,
+            latest_test_run_id: latestTestRunId,
+        },
+        latest_compile_run_id: latestCompileRunId,
+        latest_test_run_id: latestTestRunId,
+    });
+}
+export function buildMethodResource(resource) {
+    return MethodResourceSchema.parse({
+        id: resource.id,
+        method_id: resource.id,
+        path: resource.path,
+        ...(resource.label ? { label: resource.label } : {}),
+        ...(resource.hint ? { hint: resource.hint } : {}),
+        source_kind: resource.source_kind,
+        built_in: resource.built_in,
+        active_for_preparations: resource.active_for_preparations,
+        output_paths: resource.output_paths,
+        stages: resource.stages,
+    });
+}