@interf/compiler 0.7.3 → 0.9.3

package/dist/cli/commands/create-method-wizard.js

@@ -0,0 +1,465 @@
+import chalk from "chalk";
+import * as p from "@clack/prompts";
+import { resolve } from "node:path";
+import { listCompiledMethodChoices, getCompiledMethod, } from "../../packages/method-package/method-definitions.js";
+import { createLocalMethodPackageFromTemplate } from "../../packages/method-package/interf-method-package.js";
+import { rmSync } from "node:fs";
+import { isMethodId, loadMethodDefinitionFromDir, seedLocalDefaultMethod, } from "../../packages/method-package/local-methods.js";
+import { resolveOrConfigureLocalExecutor } from "./executor-flow.js";
+import { runMethodAuthoringDraft } from "../../packages/method-authoring/method-authoring.js";
+import { listSourcePreparationConfigs, loadSourceFolderConfig, resolveSourcePreparationPath, } from "../../packages/project-model/source-config.js";
+import { slugify } from "../../packages/shared/naming.js";
+import { submitMethodAuthoringRunToLocalService } from "../../packages/local-service/index.js";
+import { DEFAULT_SOURCE_FOLDER_PATH_PLACEHOLDER, listSourceFolderChoices, normalizeSourceFolderPathForConfig, } from "./source-config-wizard.js";
+export const clackMethodPrompts = {
+    intro: p.intro,
+    select: (options) => p.select(options),
+    text: (options) => p.text(options),
+    isCancel: p.isCancel,
+    log: {
+        info: p.log.info,
+        error: p.log.error,
+    },
+};
+function normalizeMethodCreationMode(mode) {
+    if (mode === "draft")
+        return "draft-from-scratch";
+    if (mode === "manual")
+        return "fork-existing";
+    return mode;
+}
+function findMatchingPreparationConfig(sourcePath, sourceFolderPath) {
+    const config = loadSourceFolderConfig(sourcePath);
+    for (const preparation of listSourcePreparationConfigs(config)) {
+        if (resolveSourcePreparationPath(sourcePath, preparation) === sourceFolderPath) {
+            return preparation;
+        }
+    }
+    return null;
+}
+function describeSavedPreparation(preparation) {
+    return preparation.about
+        ? `${preparation.path} · ${preparation.about}`
+        : `${preparation.path} · ${preparation.checks.length} readiness check${preparation.checks.length === 1 ? "" : "s"}`;
+}
+async function promptMethodSourceFolder(sourcePath, prompts) {
+    const savedPreparations = listSourcePreparationConfigs(loadSourceFolderConfig(sourcePath));
+    const folderChoices = listSourceFolderChoices(sourcePath);
+    if (folderChoices.length > 0) {
+        const selected = await prompts.select({
+            message: "Which Source Folder should shape this Method?",
+            options: [
+                ...savedPreparations.map((preparation) => ({
+                    value: preparation.name,
+                    label: preparation.name,
+                    hint: describeSavedPreparation(preparation),
+                })),
+                ...folderChoices,
+                {
+                    value: "__manual__",
+                    label: "Enter a different path",
+                    hint: "Use a relative path if the Source Folder is not listed here",
+                },
+            ],
+        });
+        if (prompts.isCancel(selected))
+            return selected;
+        if (selected !== "__manual__") {
+            const savedPreparation = savedPreparations.find((preparation) => preparation.name === selected);
+            if (savedPreparation) {
+                return resolveSourcePreparationPath(sourcePath, savedPreparation);
+            }
+            return resolve(sourcePath, normalizeSourceFolderPathForConfig(sourcePath, String(selected)));
+        }
+    }
+    const sourceFolderPrompt = await prompts.text({
+        message: "Which Source Folder should shape this Method?",
+        placeholder: DEFAULT_SOURCE_FOLDER_PATH_PLACEHOLDER,
+        initialValue: folderChoices.length === 1 ? folderChoices[0]?.value : undefined,
+        validate: (value) => {
+            const trimmed = value.trim();
+            if (trimmed.length === 0)
+                return "Source Folder is required";
+            try {
+                normalizeSourceFolderPathForConfig(sourcePath, trimmed);
+                return undefined;
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : String(error);
+            }
+        },
+    });
+    if (prompts.isCancel(sourceFolderPrompt))
+        return sourceFolderPrompt;
+    return resolve(sourcePath, normalizeSourceFolderPathForConfig(sourcePath, String(sourceFolderPrompt)));
+}
+export function formatMethodLabel(method) {
+    return {
+        value: method.id,
+        label: method.scope === "local" ? `${method.label} (Local)` : method.label,
+        hint: method.hint,
+    };
+}
+export function buildCompiledMethodOptions(sourcePath) {
+    return listCompiledMethodChoices(sourcePath).map(formatMethodLabel);
+}
+function methodUseLabel(method) {
+    if (method.value === "interf-default") {
+        return "built-in Method";
+    }
+    return method.label.replace(/ \(Local\)$/, "");
+}
+function methodForkLabel(method) {
+    return `Fork ${methodUseLabel(method)}`;
+}
+export async function chooseCompiledMethod(sourcePath, options = {}) {
+    const currentMethodId = options.currentMethodId;
+    const methodOptions = buildCompiledMethodOptions(sourcePath);
+    const orderedOptions = methodOptions
+        .map((option) => option.value === currentMethodId
+        ? {
+            ...option,
+            label: `${option.label} (Current)`,
+            hint: option.hint,
+        }
+        : option)
+        .sort((left, right) => {
+        if (left.value === currentMethodId)
+            return -1;
+        if (right.value === currentMethodId)
+            return 1;
+        return 0;
+    });
+    if (orderedOptions.length === 1) {
+        return orderedOptions[0]?.value ?? "interf-default";
+    }
+    return p.select({
+        message: options.message ?? "Preparation Method?",
+        options: orderedOptions,
+    });
+}
+export async function chooseOrCreateCompiledMethodForPreparation(sourcePath, preparationConfig, options = {}, prompts = clackMethodPrompts) {
+    const currentMethodId = options.currentMethodId ?? preparationConfig.method ?? "interf-default";
+    const methodOptions = buildCompiledMethodOptions(sourcePath);
+    const currentMethod = methodOptions.find((method) => method.value === currentMethodId) ??
+        methodOptions.find((method) => method.value === "interf-default") ??
+        methodOptions[0];
+    const selected = await prompts.select({
+        message: "Which Method should Interf use for this Preparation?",
+        options: [
+            {
+                value: "__draft_from_scratch__",
+                label: "Draft a new Method from scratch (Recommended)",
+                hint: "Start from a neutral scaffold; an agent designs stages, outputs, and proof for this Preparation",
+            },
+            ...(currentMethod
+                ? [{
+                        value: "__current__",
+                        label: `Use ${methodUseLabel(currentMethod)}`,
+                        hint: currentMethod.value === "interf-default"
+                            ? "Use the built-in Method without drafting a custom package"
+                            : currentMethod.hint,
+                    }]
+                : []),
+            ...(currentMethod
+                ? [{
+                        value: "__fork_existing__",
+                        label: methodForkLabel(currentMethod),
+                        hint: "Copy its existing stage topology, then write the per-stage guidance yourself",
+                    }]
+                : []),
+            ...methodOptions
+                .filter((method) => method.value !== currentMethod?.value)
+                .map((method) => ({
+                ...method,
+                label: `Use ${methodUseLabel(method)}`,
+            })),
+        ],
+    });
+    if (prompts.isCancel(selected))
+        return selected;
+    if (selected === "__current__") {
+        if (currentMethod?.value === "interf-default") {
+            seedLocalDefaultMethod({ sourcePath });
+        }
+        return currentMethod?.value ?? currentMethodId;
+    }
+    if (selected === "__draft_from_scratch__" || selected === "__fork_existing__") {
+        if (selected === "__fork_existing__" && currentMethod?.value === "interf-default") {
+            seedLocalDefaultMethod({ sourcePath });
+        }
+        const methodId = await createMethodWizard({
+            intro: false,
+            sourcePath,
+            baseMethodId: selected === "__fork_existing__"
+                ? currentMethod?.value ?? currentMethodId
+                : undefined,
+            creationMode: selected === "__draft_from_scratch__" ? "draft-from-scratch" : "fork-existing",
+            executionProfile: options.executionProfile,
+            resolveExecutor: options.resolveExecutor,
+            runDraft: options.runDraft,
+            preparationContext: {
+                config: preparationConfig,
+                sourceFolderPath: resolveSourcePreparationPath(sourcePath, preparationConfig),
+            },
+        }, prompts);
+        return methodId;
+    }
+    return String(selected);
+}
+export async function createMethodWizard(options = {}, prompts = clackMethodPrompts) {
+    if (options.intro !== false) {
+        prompts.intro(chalk.bold("Create a Method"));
+    }
+    const sourcePath = options.sourcePath ?? process.cwd();
+    return createCompiledMethodWizard(sourcePath, prompts, {
+        executionProfile: options.executionProfile,
+        baseMethodId: options.baseMethodId,
+        creationMode: options.creationMode,
+        preparationContext: options.preparationContext,
+        resolveExecutor: options.resolveExecutor,
+        runDraft: options.runDraft,
+    });
+}
+export async function createCompiledMethodWizard(sourcePath, prompts = clackMethodPrompts, options = {}) {
+    const creationMode = options.creationMode ?? await prompts.select({
+        message: "How do you want to create it?",
+        options: [
+            {
+                value: "draft-from-scratch",
+                label: "Draft a new Method from scratch (Recommended)",
+                hint: "Start from a neutral scaffold and let a local agent design a reusable Method for this kind of agent work",
+            },
+            {
+                value: "fork-existing",
+                label: "Fork an existing Method and edit stage guidance",
+                hint: "Copy an existing topology; choose this when the stages are right but their emphasis should change",
+            },
+        ],
+    });
+    if (prompts.isCancel(creationMode))
+        return creationMode;
+    const creationModeValue = normalizeMethodCreationMode(creationMode);
+    const baseMethod = creationModeValue === "fork-existing"
+        ? options.baseMethodId ?? await prompts.select({
+            message: "Which existing Method should Interf fork?",
+            options: listCompiledMethodChoices(sourcePath).map(formatMethodLabel),
+        })
+        : null;
+    if (prompts.isCancel(baseMethod))
+        return baseMethod;
+    const baseMethodId = typeof baseMethod === "string" ? baseMethod : null;
+    const resolvedBaseMethod = baseMethodId
+        ? getCompiledMethod(baseMethodId, { sourcePath })
+        : null;
+    const rawName = await prompts.text({
+        message: "New Method name?",
+        placeholder: "customer-research",
+        validate: (value) => {
+            if (value.trim().length === 0)
+                return "Name is required";
+            const methodId = slugify(value);
+            if (!isMethodId(methodId))
+                return "Use letters, numbers, and dashes only";
+            if (listCompiledMethodChoices(sourcePath).some((method) => method.id === methodId)) {
+                return "That Method name already exists";
+            }
+            return undefined;
+        },
+    });
+    if (prompts.isCancel(rawName))
+        return rawName;
+    const methodId = slugify(rawName);
+    const label = rawName.trim();
+    const hint = await prompts.text({
+        message: "One-line Method description?",
+        placeholder: "Bias toward evidence-backed summaries and strong retrieval structure",
+        validate: (value) => (value.trim().length === 0 ? "Description is required" : undefined),
+    });
+    if (prompts.isCancel(hint))
+        return hint;
+    if (creationModeValue === "draft-from-scratch") {
+        let sourceFolderPath = options.preparationContext?.sourceFolderPath ?? null;
+        let matchedPreparation = options.preparationContext?.config ?? null;
+        if (!sourceFolderPath) {
+            const savedPreparations = listSourcePreparationConfigs(loadSourceFolderConfig(sourcePath));
+            if (savedPreparations.length > 0) {
+                const preparationChoice = await prompts.select({
+                    message: "Which saved Preparation should shape this Method?",
+                    options: [
+                        ...savedPreparations.map((preparation) => ({
+                            value: preparation.name,
+                            label: preparation.name,
+                            hint: describeSavedPreparation(preparation),
+                        })),
+                        {
+                            value: "__manual__",
+                            label: "Enter folder path manually",
+                            hint: "Use a folder that is not saved as a Preparation yet",
+                        },
+                    ],
+                });
+                if (prompts.isCancel(preparationChoice))
+                    return preparationChoice;
+                if (preparationChoice !== "__manual__") {
+                    matchedPreparation = savedPreparations.find((preparation) => preparation.name === preparationChoice) ?? null;
+                    sourceFolderPath = matchedPreparation
+                        ? resolveSourcePreparationPath(sourcePath, matchedPreparation)
+                        : null;
+                }
+            }
+        }
+        if (!sourceFolderPath) {
+            const sourceFolderPrompt = await promptMethodSourceFolder(sourcePath, prompts);
+            if (prompts.isCancel(sourceFolderPrompt))
+                return sourceFolderPrompt;
+            if (!sourceFolderPrompt)
+                return null;
+            sourceFolderPath = String(sourceFolderPrompt);
+            matchedPreparation = matchedPreparation ?? findMatchingPreparationConfig(sourcePath, sourceFolderPath);
+        }
+        const taskPrompt = await prompts.text({
+            message: "What should this Method prepare for agents, and what evidence should show the data is ready?",
+            placeholder: "Data: research interviews. Output: per-file summaries, themes, entities, claims, and source links. Evidence: every file processed, evidence linked to sources, required outputs created.",
+            validate: (value) => (value.trim().length === 0 ? "A description is required" : undefined),
+        });
+        if (prompts.isCancel(taskPrompt))
+            return taskPrompt;
+        if (matchedPreparation) {
+            prompts.log.info(`Shaping this Method from Preparation "${matchedPreparation.name}".`);
+        }
+        if (matchedPreparation?.checks.length) {
+            prompts.log.info(`Using ${matchedPreparation.checks.length} saved readiness check${matchedPreparation.checks.length === 1 ? "" : "s"} from Preparation "${matchedPreparation.name}" as authoring context.`);
+        }
+        prompts.log.info("Preparing a Method-authoring shell from the Source Folder, then drafting the package.");
+        let lastServiceStatus = "";
+        const serviceRun = await submitMethodAuthoringRunToLocalService({
+            projectPath: sourcePath,
+            request: {
+                preparation: matchedPreparation?.name ?? null,
+                source_folder_path: sourceFolderPath,
+                method_id: methodId,
+                label,
+                hint: hint.trim(),
+                task_prompt: taskPrompt.trim(),
+                checks: matchedPreparation?.checks ?? [],
+            },
+            onSubmitted: (submission) => {
+                prompts.log.info(`Visible in Interf: ${submission.serviceUrl}/`);
+            },
+            onUpdate: (job) => {
+                const activeStep = job.steps.find((step) => step.status === "running")
+                    ?? [...job.steps].reverse().find((step) => step.status === "succeeded" || step.status === "failed")
+                    ?? null;
+                const statusKey = `${job.status}:${activeStep?.id ?? ""}:${activeStep?.status ?? ""}`;
+                if (statusKey === lastServiceStatus)
+                    return;
+                lastServiceStatus = statusKey;
+                prompts.log.info(activeStep
+                    ? `${activeStep.label}: ${activeStep.status}`
+                    : `Method draft run: ${job.status}`);
+            },
+        });
+        const result = serviceRun
+            ? serviceRun.result
+                ? {
+                    status: serviceRun.result.status,
+                    changed: serviceRun.result.changed,
+                    summary: serviceRun.result.summary,
+                    validation: serviceRun.result.validation ?? null,
+                    methodPath: serviceRun.result.method_path,
+                    shellPath: serviceRun.result.shell_path,
+                }
+                : {
+                    status: "executor-failed",
+                    changed: false,
+                    summary: serviceRun.error ?? "Method authoring failed in the local Interf service.",
+                    validation: null,
+                    methodPath: resolve(sourcePath, "interf", "methods", methodId),
+                    shellPath: resolve(sourcePath, "interf", "methods", methodId),
+                }
+            : await (async () => {
+                const resolveExecutor = options.resolveExecutor ?? resolveOrConfigureLocalExecutor;
+                const runDraft = options.runDraft ?? runMethodAuthoringDraft;
+                const { executor, error } = await resolveExecutor({
+                    executionProfile: options.executionProfile,
+                    purpose: "method",
+                });
+                if (!executor && !error) {
+                    return null;
+                }
+                if (!executor) {
+                    process.exitCode = 1;
+                    (prompts.log.error ?? prompts.log.info)(error ?? "No coding agent detected.");
+                    return null;
+                }
+                return runDraft({
+                    sourcePath,
+                    sourceFolderPath,
+                    methodId,
+                    label,
+                    hint: hint.trim(),
+                    taskPrompt: taskPrompt.trim(),
+                    checks: matchedPreparation?.checks ?? [],
+                    executor,
+                    onStatus: (line) => prompts.log.info(line),
+                });
+            })();
+        if (!result)
+            return null;
+        if (result.status === "updated") {
+            const draft = loadMethodDefinitionFromDir(result.methodPath);
+            const stageList = draft?.stages?.map((stage) => stage.id).join(" -> ") ?? "-";
+            prompts.log.info(`Draft ready at ${result.methodPath}`);
+            prompts.log.info(`  Name: ${draft?.label ?? label}`);
+            prompts.log.info(`  Description: ${draft?.hint ?? hint.trim()}`);
+            if (draft?.purpose)
+                prompts.log.info(`  Purpose: ${draft.purpose}`);
+            prompts.log.info(`  Stages: ${stageList}`);
+            const confirmChoice = await prompts.select({
+                message: "Save this Method?",
+                options: [
+                    { value: "save", label: "Save", hint: "Keep the draft as your new Method package" },
+                    { value: "cancel", label: "Discard", hint: "Remove the draft folder and exit without saving" },
+                ],
+            });
+            if (prompts.isCancel(confirmChoice) || confirmChoice === "cancel") {
+                rmSync(result.methodPath, { recursive: true, force: true });
+                prompts.log.info(`Discarded draft at ${result.methodPath}`);
+                return null;
+            }
+            prompts.log.info(`Saved local Method: ${result.methodPath}`);
+            return methodId;
+        }
+        process.exitCode = 1;
+        (prompts.log.error ?? prompts.log.info)(result.status === "no-change"
+            ? `${result.summary} Draft mode only succeeds when it produces an agent-work-specific package change.`
+            : result.summary);
+        prompts.log.info(`Method shell kept at: ${result.shellPath}`);
+        return null;
+    }
+    const stagePolicyNotes = {};
+    if (!baseMethodId || !resolvedBaseMethod) {
+        throw new Error("Fork-existing Method creation needs a base Method.");
+    }
+    for (const stage of resolvedBaseMethod.stages) {
+        const stagePrompt = await prompts.text({
+            message: `What should ${stage.id} (${stage.label}) emphasize?`,
+            placeholder: stage.description,
+            validate: (value) => (value.trim().length === 0 ? `${stage.label} guidance is required` : undefined),
+        });
+        if (prompts.isCancel(stagePrompt))
+            return stagePrompt;
+        stagePolicyNotes[stage.id] = [String(stagePrompt).trim()];
+    }
+    const methodPath = createLocalMethodPackageFromTemplate({
+        sourcePath,
+        baseMethodId,
+        methodId,
+        label,
+        hint: hint.trim(),
+        stagePolicyNotes,
+    });
+    prompts.log.info(`Saved local Method: ${methodPath}`);
+    return methodId;
+}

package/dist/cli/commands/create.d.ts

@@ -1,8 +1,8 @@
 import type { CommandModule } from "yargs";
-import type { WorkflowExecutionProfile } from "../../packages/agents/lib/executors.js";
+import type { MethodExecutionProfile } from "../../packages/agents/lib/executors.js";
 export declare const createCommand: CommandModule;
 export declare function createCompiledWizard(options?: {
     intro?: boolean;
-    executionProfile?: WorkflowExecutionProfile;
+    executionProfile?: MethodExecutionProfile;
 }): Promise<void>;
-export { type WorkflowWizardPrompts, formatWorkflowLabel, createWorkflowWizard, createCompiledWorkflowWizard, } from "./create-workflow-wizard.js";
+export { type MethodWizardPrompts, formatMethodLabel, createMethodWizard, createCompiledMethodWizard, } from "./create-method-wizard.js";