@interf/compiler 0.7.3 → 0.9.3

package/dist/cli/commands/compile.js

@@ -1,23 +1,29 @@
 import chalk from "chalk";
 import * as p from "@clack/prompts";
 import { detectInterf, readInterfConfig, resolveSourceControlPath, } from "../../packages/project-model/interf.js";
-import { loadCompiledDatasetConfig, sourceDatasetConfigFromInterfConfig, resolveDatasetCompileMaxAttempts, resolveDatasetCompileMaxLoops, } from "../../packages/project-model/source-config.js";
+import { loadCompiledPreparationConfig, sourcePreparationConfigFromInterfConfig, resolvePreparationCompileMaxAttempts, resolvePreparationCompileMaxLoops, } from "../../packages/project-model/source-config.js";
 import { addExecutionProfileOptions, executionProfileFromArgv, } from "../../packages/agents/lib/execution-profile.js";
 import { chooseCompiledConfigToBuild, ensureCompiledFromConfig, } from "./compiled-flow.js";
-import { resolveConfiguredDatasetSelection } from "./dataset-selection.js";
+import { resolveConfiguredPreparationSelection } from "./preparation-selection.js";
 import { promptCompileLoopSelection, } from "./source-config-wizard.js";
 import { resolveOrConfigureLocalExecutor } from "./executor-flow.js";
 import { runConfiguredCompiledCompile } from "./compile-controller.js";
+import { submitCompileRunToLocalService, waitForLocalCompileRun, } from "../../packages/local-service/index.js";
+import { resolveCommandControlPath } from "./control-path.js";
+import { resolveMethodId } from "../../packages/methods/method-resolution.js";
 export { runConfiguredCompiledCompile } from "./compile-controller.js";
 export const compileCommand = {
     command: "compile",
-    describe: "Build portable context agents can use and optionally run retry or self-improving compile loops",
-    builder: (yargs) => addExecutionProfileOptions(yargs).option("max-attempts", {
+    describe: "Prepare files and write Portable Context agents can use",
+    builder: (yargs) => addExecutionProfileOptions(yargs).option("preparation", {
+        type: "string",
+        describe: "Preparation id to compile when this Source Folder has more than one Preparation",
+    }).option("max-attempts", {
         type: "number",
-        describe: "Retry compile and test the same workflow until the dataset passes or reaches this total attempt limit",
+        describe: "Retry the prepare run and run saved readiness checks with the same Method until the Preparation is ready or reaches this total attempt limit",
     }).option("max-loops", {
         type: "number",
-        describe: "After retries fail, let Interf edit the workflow and test new workflow variations for this dataset up to this loop limit",
+        describe: "After retries fail, let Interf edit the Method and run saved readiness checks on new Method variations for this Preparation up to this loop limit",
     }).option("keep-stage-shells", {
         type: "boolean",
         default: false,
@@ -41,23 +47,24 @@ function readHintedSourcePath(argv) {
         ? argv.sourcePath.trim()
         : null;
 }
-function readRequestedDatasetName(argv) {
-    return typeof argv.dataset === "string" && argv.dataset.trim().length > 0
-        ? argv.dataset.trim()
+function readRequestedPreparationName(argv) {
+    const raw = argv.preparation;
+    return typeof raw === "string" && raw.trim().length > 0
+        ? raw.trim()
         : null;
 }
 function shouldSkipCompileConfirm(argv) {
     return argv.skipConfirm === true;
 }
-function shouldSkipDatasetBanner(argv) {
-    return argv.skipDatasetBanner === true;
+function shouldSkipPreparationBanner(argv) {
+    return argv.skipPreparationBanner === true;
 }
 function compileRunTests(options) {
     const checks = options.compiledConfig?.checks ?? [];
     if (checks.length === 0)
         return false;
-    const configuredMaxAttempts = resolveDatasetCompileMaxAttempts(options.compiledConfig ?? { max_attempts: undefined }, options.maxAttemptsOverride);
-    const maxLoops = resolveDatasetCompileMaxLoops(options.compiledConfig ?? { max_loops: undefined }, options.maxLoopsOverride);
+    const configuredMaxAttempts = resolvePreparationCompileMaxAttempts(options.compiledConfig ?? { max_attempts: undefined }, options.maxAttemptsOverride);
+    const maxLoops = resolvePreparationCompileMaxLoops(options.compiledConfig ?? { max_loops: undefined }, options.maxLoopsOverride);
     const maxAttempts = configuredMaxAttempts ?? (maxLoops != null ? 1 : null);
     return maxAttempts != null;
 }
@@ -69,20 +76,20 @@ export async function runCompileCommand(argv = {}, deps = {}) {
     let compiledPath = null;
     const hintedSourcePath = readHintedSourcePath(argv);
     const detected = hintedSourcePath ? null : helpers.detectInterf(process.cwd());
-    let sourcePath = hintedSourcePath ?? process.cwd();
+    let sourcePath = hintedSourcePath ?? resolveCommandControlPath();
     let compiledConfig = null;
-    const requestedDatasetName = readRequestedDatasetName(argv);
-    const hintedDatasetConfig = (argv.datasetConfig ?? null);
+    const requestedPreparationName = readRequestedPreparationName(argv);
+    const hintedPreparationConfig = (argv.preparationConfig ?? null);
     const skipConfirm = shouldSkipCompileConfirm(argv);
-    const skipDatasetBanner = shouldSkipDatasetBanner(argv);
+    const skipPreparationBanner = shouldSkipPreparationBanner(argv);
     if (detected) {
         compiledPath = detected.path;
         sourcePath = resolveSourceControlPath(detected.path);
-        compiledConfig = loadCompiledDatasetConfig(detected.path)
-            ?? sourceDatasetConfigFromInterfConfig(detected.config);
+        compiledConfig = loadCompiledPreparationConfig(detected.path)
+            ?? sourcePreparationConfigFromInterfConfig(detected.config);
         if (!skipConfirm && process.stdin.isTTY && process.stdout.isTTY) {
             const confirmed = await helpers.confirm({
-                message: `Compile dataset "${detected.config.name}" now?`,
+                message: `Prepare files for Preparation "${detected.config.name}" now?`,
                 initialValue: true,
             });
             if (p.isCancel(confirmed) || !confirmed)
@@ -90,33 +97,33 @@ export async function runCompileCommand(argv = {}, deps = {}) {
         }
     }
     else {
-        const selectedCompiled = requestedDatasetName || hintedDatasetConfig
-            ? resolveConfiguredDatasetSelection({
+        const selectedCompiled = requestedPreparationName || hintedPreparationConfig
+            ? resolveConfiguredPreparationSelection({
                 sourcePath,
-                requestedDatasetName,
-                hintedDatasetConfig,
+                requestedPreparationName,
+                hintedPreparationConfig,
             })
             : await helpers.chooseCompiledConfigToBuild({
                 sourcePath,
-                selectMessage: "Which source folder setup do you want to compile?",
+                selectMessage: "Which saved Preparation do you want to compile?",
             });
         if (selectedCompiled === undefined)
             return null;
         if (!selectedCompiled) {
             process.exitCode = 1;
-            if (requestedDatasetName) {
-                console.log(chalk.red(`  Setup "${requestedDatasetName}" is not set up in this project.`));
-                console.log(chalk.dim("  Run `interf list` to see the saved setups."));
+            if (requestedPreparationName) {
+                console.log(chalk.red(`  Preparation "${requestedPreparationName}" is not saved in this Source Folder.`));
+                console.log(chalk.dim("  Run `interf list` to see the saved Preparations."));
             }
             else {
-                console.log(chalk.red("  No saved setups are configured for this folder yet."));
+                console.log(chalk.red("  No saved Preparations are configured for this Source Folder yet."));
                 console.log(chalk.dim("  Start with `interf` or `interf init` to set up this folder."));
             }
             return null;
         }
         if (!skipConfirm && process.stdin.isTTY && process.stdout.isTTY) {
             const confirmed = await helpers.confirm({
-                message: `Compile dataset "${selectedCompiled.name}" now?`,
+                message: `Prepare files for Preparation "${selectedCompiled.name}" now?`,
                 initialValue: true,
             });
             if (p.isCancel(confirmed) || !confirmed)
@@ -124,8 +131,8 @@ export async function runCompileCommand(argv = {}, deps = {}) {
         }
         compiledConfig = selectedCompiled;
         compiledPath = helpers.ensureCompiledFromConfig(sourcePath, selectedCompiled);
-        if (!skipDatasetBanner) {
-            console.log(chalk.dim(`  Dataset: ${selectedCompiled.name}`));
+        if (!skipPreparationBanner) {
+            console.log(chalk.dim(`  Preparation: ${selectedCompiled.name}`));
         }
     }
     let maxAttemptsOverride = null;
@@ -155,6 +162,56 @@ export async function runCompileCommand(argv = {}, deps = {}) {
         maxAttemptsOverride,
         maxLoopsOverride,
     });
+    if (argv.skipService !== true && compiledConfig) {
+        const submitted = await submitCompileRunToLocalService({
+            projectPath: sourcePath,
+            request: {
+                preparation: compiledConfig.name,
+                ...(compiledConfig.method ? { method: compiledConfig.method } : {}),
+                ...(maxAttemptsOverride != null ? { max_attempts: maxAttemptsOverride } : {}),
+                ...(maxLoopsOverride != null ? { max_loops: maxLoopsOverride } : {}),
+                preserve_stage_shells: readStageShellRetentionMode(argv),
+            },
+        });
+        if (submitted) {
+            console.log(chalk.dim(`  Visible in Interf: ${submitted.serviceUrl}/`));
+            let lastStatus = "";
+            let lastStage = "";
+            const completed = await waitForLocalCompileRun({
+                serviceUrl: submitted.serviceUrl,
+                runId: submitted.resource.run.run_id,
+                onUpdate(resource) {
+                    const activeStage = resource.run.stages.find((stage) => stage.status === "running")
+                        ?? [...resource.run.stages].reverse().find((stage) => stage.status === "succeeded" || stage.status === "failed")
+                        ?? null;
+                    const statusKey = `${resource.run.status}:${activeStage?.stage_id ?? ""}:${activeStage?.status ?? ""}`;
+                    if (statusKey === `${lastStatus}:${lastStage}`)
+                        return;
+                    lastStatus = resource.run.status;
+                    lastStage = `${activeStage?.stage_id ?? ""}:${activeStage?.status ?? ""}`;
+                    if (activeStage) {
+                        console.log(chalk.dim(`  ${activeStage.stage_label ?? activeStage.stage_id}: ${activeStage.status}`));
+                    }
+                    else {
+                        console.log(chalk.dim(`  Prepare run: ${resource.run.status}`));
+                    }
+                },
+            });
+            if (completed.run.status !== "succeeded") {
+                process.exitCode = 1;
+                const failure = completed.run.stages.find((stage) => stage.status === "failed");
+                console.log(chalk.red(`  Prepare run ${completed.run.status}.`));
+                if (failure?.failure)
+                    console.log(chalk.red(`  ${failure.failure}`));
+                return null;
+            }
+            console.log(chalk.green("  Portable Context ready."));
+            return {
+                compiledPath: completed.run.portable_context_path,
+                testedDuringCompile,
+            };
+        }
+    }
     const executionProfile = executionProfileFromArgv(argv);
     const { executor, error } = await helpers.resolveOrConfigureLocalExecutor({
         executionProfile,
@@ -169,6 +226,7 @@ export async function runCompileCommand(argv = {}, deps = {}) {
     }
     const compiled = await helpers.runConfiguredCompiledCompile({
         executor,
+        testExecutor: executor,
         compiledPath,
         sourcePath,
         compiledConfig,
@@ -213,8 +271,8 @@ export async function resolveInteractiveCompileLoopOverrides(options) {
     }
     const savedCompiledConfig = options.compiledConfig
         ?? (currentConfig
-            ? (loadCompiledDatasetConfig(options.compiledPath)
-                ?? sourceDatasetConfigFromInterfConfig(currentConfig))
+            ? (loadCompiledPreparationConfig(options.compiledPath)
+                ?? sourcePreparationConfigFromInterfConfig(currentConfig))
             : null);
     if (!savedCompiledConfig) {
         return {
@@ -231,10 +289,10 @@ export async function resolveInteractiveCompileLoopOverrides(options) {
             initialMaxAttempts: savedCompiledConfig.max_attempts,
             initialMaxLoops: savedCompiledConfig.max_loops,
             intro: [
-                `Workflow: ${savedCompiledConfig.workflow ?? currentConfig?.workflow ?? "interf"}`,
-                "This selection applies to this compile run only. It does not change the saved dataset setup.",
+                `Method: ${resolveMethodId(savedCompiledConfig, resolveMethodId(currentConfig))}`,
+                "This selection applies to this prepare run only. It does not change the saved Preparation.",
             ],
-            message: "How should this compile run?",
+            message: "How should this prepare run work?",
         });
         if (overrideSelection === null)
             return null;
@@ -249,17 +307,17 @@ export async function resolveInteractiveCompileLoopOverrides(options) {
         };
     }
     const savedMode = await p.select({
-        message: "Which compile mode should this run use?",
+        message: "Which prepare mode should this run use?",
         options: [
             {
                 value: "saved",
-                label: "Use saved compile mode (Recommended)",
+                label: "Use saved prepare mode (Recommended)",
                 hint: `${savedCompiledConfig.max_loops ? "Self-improving" : savedCompiledConfig.max_attempts && savedCompiledConfig.max_attempts > 1 ? "Retry" : "Single attempt"} · ${formatCompileModeHint(savedCompiledConfig)}`,
             },
             {
                 value: "override",
                 label: "Change it for this run only",
-                hint: "Keep the saved dataset setup unchanged",
+                hint: "Keep the saved Preparation unchanged",
             },
         ],
     });
@@ -277,10 +335,10 @@ export async function resolveInteractiveCompileLoopOverrides(options) {
         initialMaxAttempts: savedCompiledConfig.max_attempts,
         initialMaxLoops: savedCompiledConfig.max_loops,
         intro: [
-            `Workflow: ${savedCompiledConfig.workflow ?? currentConfig?.workflow ?? "interf"}`,
-            "This applies to this compile run only. It does not change the saved dataset setup.",
+            `Method: ${resolveMethodId(savedCompiledConfig, resolveMethodId(currentConfig))}`,
+            "This applies to this prepare run only. It does not change the saved Preparation.",
         ],
-        message: "Override the compile mode for this run",
+        message: "Override the prepare mode for this run",
     });
     if (selection === null)
         return null;

package/dist/cli/commands/compiled-flow.d.ts

@@ -1,22 +1,25 @@
-import type { SourceDatasetConfig } from "../../packages/project-model/lib/schema.js";
-import { type StageShellRetentionMode, type CompiledCompileResult } from "../../packages/compiler/workflows.js";
-import type { WorkflowExecutor } from "../../packages/agents/lib/executors.js";
-export interface SavedDatasetEntry {
-    config: SourceDatasetConfig;
+import type { SourcePreparationConfig } from "../../packages/project-model/lib/schema.js";
+import { type StageShellRetentionMode, type CompiledCompileResult } from "../../packages/compiler/method-runs.js";
+import type { MethodExecutor } from "../../packages/agents/lib/executors.js";
+import type { RunEventSink } from "../../packages/execution/events.js";
+export interface SavedPreparationEntry {
+    config: SourcePreparationConfig;
     path: string | null;
     localDraft: boolean;
 }
-export declare function listSavedCompiledEntries(sourcePath: string): SavedDatasetEntry[];
+export declare function listSavedPreparationEntries(sourcePath: string): SavedPreparationEntry[];
 export declare function findBuiltCompiledPath(sourcePath: string, compiledName: string): string | null;
-export declare function findSavedCompiledConfig(sourcePath: string, compiledName: string): SourceDatasetConfig | null;
+export declare function findSavedCompiledConfig(sourcePath: string, compiledName: string): SourcePreparationConfig | null;
 export declare function chooseCompiledConfigToBuild(options: {
     sourcePath: string;
     selectMessage: string;
-}): Promise<SourceDatasetConfig | null | undefined>;
-export declare function createCompiledFromConfig(sourcePath: string, datasetConfig: SourceDatasetConfig): string;
-export declare function ensureCompiledFromConfig(sourcePath: string, datasetConfig: SourceDatasetConfig): string;
-export declare function compileCompiledWithReporter(executor: WorkflowExecutor, compiledPath: string, options?: {
+}): Promise<SourcePreparationConfig | null | undefined>;
+export declare function createCompiledFromConfig(sourcePath: string, preparationConfig: SourcePreparationConfig): string;
+export declare function ensureCompiledFromConfig(sourcePath: string, preparationConfig: SourcePreparationConfig): string;
+export declare function compileCompiledWithReporter(executor: MethodExecutor, compiledPath: string, options?: {
     heading?: string;
     successMessage?: string;
     preserveStageShells?: StageShellRetentionMode;
+    runId?: string;
+    events?: RunEventSink;
 }): Promise<CompiledCompileResult>;

package/dist/cli/commands/compiled-flow.js

@@ -1,32 +1,33 @@
 import chalk from "chalk";
 import * as p from "@clack/prompts";
-import { listCompiledDatasetsForSourceFolder } from "../../packages/project-model/interf.js";
-import { listSourceDatasetConfigs, loadCompiledDatasetConfig, loadSourceFolderConfig, resolveSourceDatasetPath, sourceDatasetConfigFromInterfConfig, syncCompiledInterfConfigFromSourceDatasetConfig, } from "../../packages/project-model/source-config.js";
-import { compileCompiled, createCompiled, } from "../../packages/compiler/workflows.js";
-import { formatWorkflowExecutionProfile } from "../../packages/agents/lib/execution-profile.js";
-function formatSavedDatasetHint(entry) {
+import { ensurePortableContextScaffold, listPortableContextsForSourceFolder, } from "../../packages/project-model/interf.js";
+import { listSourcePreparationConfigs, loadCompiledPreparationConfig, loadSourceFolderConfig, resolveSourcePreparationPath, sourcePreparationConfigFromInterfConfig, syncCompiledInterfConfigFromSourcePreparationConfig, } from "../../packages/project-model/source-config.js";
+import { compileCompiled, createCompiled, } from "../../packages/compiler/method-runs.js";
+import { formatMethodExecutionProfile } from "../../packages/agents/lib/execution-profile.js";
+import { resolveMethodId } from "../../packages/methods/method-resolution.js";
+function formatSavedPreparationHint(entry) {
     const config = entry.config;
     const checkCount = config.checks.length;
-    const workflowHint = `workflow ${config.workflow ?? "interf"}${entry.localDraft ? " (local draft)" : ""}`;
+    const methodHint = `Method ${resolveMethodId(config)}${entry.localDraft ? " (local draft)" : ""}`;
     if (config.about)
-        return `${config.path} · ${config.about} · ${workflowHint}`;
+        return `${config.path} · ${config.about} · ${methodHint}`;
     if (checkCount === 0)
-        return `${config.path} · No questions yet · ${workflowHint}`;
-    return `${config.path} · ${checkCount} question${checkCount === 1 ? "" : "s"} · ${workflowHint}`;
+        return `${config.path} · No readiness checks yet · ${methodHint}`;
+    return `${config.path} · ${checkCount} readiness check${checkCount === 1 ? "" : "s"} · ${methodHint}`;
 }
-export function listSavedCompiledEntries(sourcePath) {
+export function listSavedPreparationEntries(sourcePath) {
     const builtEntries = new Map();
-    for (const builtCompiled of listCompiledDatasetsForSourceFolder(sourcePath)) {
-        const datasetConfig = loadCompiledDatasetConfig(builtCompiled.path)
-            ?? sourceDatasetConfigFromInterfConfig(builtCompiled.config);
+    for (const builtCompiled of listPortableContextsForSourceFolder(sourcePath)) {
+        const preparationConfig = loadCompiledPreparationConfig(builtCompiled.path)
+            ?? sourcePreparationConfigFromInterfConfig(builtCompiled.config);
         builtEntries.set(builtCompiled.config.name, {
-            config: datasetConfig,
+            config: preparationConfig,
             path: builtCompiled.path,
-            localDraft: builtCompiled.config.workflow_origin?.local_draft === true,
+            localDraft: builtCompiled.config.method_origin?.local_draft === true,
         });
     }
     const entries = new Map();
-    for (const config of listSourceDatasetConfigs(loadSourceFolderConfig(sourcePath))) {
+    for (const config of listSourcePreparationConfigs(loadSourceFolderConfig(sourcePath))) {
         const built = builtEntries.get(config.name);
         entries.set(config.name, {
             config,
@@ -37,13 +38,13 @@ export function listSavedCompiledEntries(sourcePath) {
     return Array.from(entries.values()).sort((left, right) => left.config.name.localeCompare(right.config.name));
 }
 export function findBuiltCompiledPath(sourcePath, compiledName) {
-    return listSavedCompiledEntries(sourcePath).find((entry) => entry.config.name === compiledName)?.path ?? null;
+    return listSavedPreparationEntries(sourcePath).find((entry) => entry.config.name === compiledName)?.path ?? null;
 }
 export function findSavedCompiledConfig(sourcePath, compiledName) {
-    return listSavedCompiledEntries(sourcePath).find((entry) => entry.config.name === compiledName)?.config ?? null;
+    return listSavedPreparationEntries(sourcePath).find((entry) => entry.config.name === compiledName)?.config ?? null;
 }
 export async function chooseCompiledConfigToBuild(options) {
-    const savedEntries = listSavedCompiledEntries(options.sourcePath);
+    const savedEntries = listSavedPreparationEntries(options.sourcePath);
     if (savedEntries.length === 0) {
         return null;
     }
@@ -56,8 +57,8 @@ export async function chooseCompiledConfigToBuild(options) {
             value: entry.config.name,
             label: entry.config.name,
             hint: [
-                formatSavedDatasetHint(entry),
-                entry.path ? "built" : "not built yet",
+                formatSavedPreparationHint(entry),
+                entry.path ? "Portable Context available" : "Portable Context not built yet",
             ].join(" · "),
         })),
     });
@@ -65,25 +66,27 @@ export async function chooseCompiledConfigToBuild(options) {
         return undefined;
     return savedEntries.find((entry) => entry.config.name === selected)?.config ?? null;
 }
-export function createCompiledFromConfig(sourcePath, datasetConfig) {
-    const workflowId = datasetConfig.workflow ?? "interf";
-    const datasetSourcePath = resolveSourceDatasetPath(sourcePath, datasetConfig);
-    const compiledPath = createCompiled(datasetConfig.name, sourcePath, workflowId, datasetConfig.about, datasetSourcePath);
-    syncCompiledInterfConfigFromSourceDatasetConfig(compiledPath, datasetConfig);
+export function createCompiledFromConfig(sourcePath, preparationConfig) {
+    const methodId = resolveMethodId(preparationConfig);
+    const sourceFolderPath = resolveSourcePreparationPath(sourcePath, preparationConfig);
+    const compiledPath = createCompiled(preparationConfig.name, sourcePath, methodId, preparationConfig.about, sourceFolderPath);
+    syncCompiledInterfConfigFromSourcePreparationConfig(compiledPath, preparationConfig);
     return compiledPath;
 }
-export function ensureCompiledFromConfig(sourcePath, datasetConfig) {
-    const existingPath = findBuiltCompiledPath(sourcePath, datasetConfig.name);
+export function ensureCompiledFromConfig(sourcePath, preparationConfig) {
+    const methodId = resolveMethodId(preparationConfig);
+    const existingPath = findBuiltCompiledPath(sourcePath, preparationConfig.name);
     if (existingPath) {
-        syncCompiledInterfConfigFromSourceDatasetConfig(existingPath, datasetConfig);
+        ensurePortableContextScaffold(sourcePath, preparationConfig.name, methodId);
+        syncCompiledInterfConfigFromSourcePreparationConfig(existingPath, preparationConfig);
         return existingPath;
     }
-    return createCompiledFromConfig(sourcePath, datasetConfig);
+    return createCompiledFromConfig(sourcePath, preparationConfig);
 }
 export async function compileCompiledWithReporter(executor, compiledPath, options = {}) {
     console.log();
-    console.log(chalk.bold(`  ${options.heading ?? "Building portable context..."}`));
-    const profileLabel = formatWorkflowExecutionProfile(executor.executionProfile);
+    console.log(chalk.bold(`  ${options.heading ?? "Building Portable Context..."}`));
+    const profileLabel = formatMethodExecutionProfile(executor.executionProfile);
     if (profileLabel) {
         console.log(chalk.dim(`  Execution profile: ${profileLabel}`));
     }
@@ -97,11 +100,13 @@ export async function compileCompiledWithReporter(executor, compiledPath, option
         compiledPath,
         reporter,
         preserveStageShells: options.preserveStageShells,
+        runId: options.runId,
+        events: options.events,
     });
     if (!result.ok) {
         return result;
     }
     console.log();
-    console.log(chalk.green(`  ✓ ${options.successMessage ?? "Portable context ready."}`));
+    console.log(chalk.green(`  ✓ ${options.successMessage ?? "Portable Context ready."}`));
     return result;
 }

package/dist/cli/commands/control-path.d.ts

@@ -0,0 +1,11 @@
+export declare function hasInterfInstanceConfig(controlPath: string): boolean;
+export declare function findNearestInterfInstanceConfig(cwd?: string): string | null;
+export declare function defaultInterfInstanceRoot(sourceFolderPath: string): string;
+export declare function resolveCommandControlPath(cwd?: string): string;
+export interface InterfInstanceContext {
+    controlPath: string;
+    defaultSourceFolderPath: string | null;
+    defaultPreparationPath: string | null;
+}
+export declare function relativeSourceFolderPath(controlPath: string, sourceFolderPath: string): string;
+export declare function resolveInterfInstanceContext(cwd?: string): InterfInstanceContext;

package/dist/cli/commands/control-path.js

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { assertCompiledContainer } from "../../packages/project-model/interf.js";
+import { sourceFolderConfigPath } from "../../packages/project-model/source-config.js";
+function canUseInterfInstanceRoot(controlPath) {
+    try {
+        assertCompiledContainer(controlPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function hasInterfInstanceConfig(controlPath) {
+    return existsSync(sourceFolderConfigPath(controlPath)) && canUseInterfInstanceRoot(controlPath);
+}
+export function findNearestInterfInstanceConfig(cwd = process.cwd()) {
+    let cursor = resolve(cwd);
+    while (true) {
+        if (hasInterfInstanceConfig(cursor))
+            return cursor;
+        const parentPath = dirname(cursor);
+        if (parentPath === cursor)
+            return null;
+        cursor = parentPath;
+    }
+}
+function fallbackInterfInstanceRoot(sourceFolderPath) {
+    return join(homedir(), ".interf", basename(sourceFolderPath) || "source-folder");
+}
+export function defaultInterfInstanceRoot(sourceFolderPath) {
+    const parentPath = dirname(sourceFolderPath);
+    if (parentPath !== sourceFolderPath && canUseInterfInstanceRoot(parentPath)) {
+        return parentPath;
+    }
+    return fallbackInterfInstanceRoot(sourceFolderPath);
+}
+export function resolveCommandControlPath(cwd = process.cwd()) {
+    const currentPath = resolve(cwd);
+    return findNearestInterfInstanceConfig(currentPath) ?? currentPath;
+}
+export function relativeSourceFolderPath(controlPath, sourceFolderPath) {
+    const relativePath = relative(controlPath, sourceFolderPath).split(sep).join("/") || ".";
+    if (relativePath.startsWith(".."))
+        return sourceFolderPath;
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+export function resolveInterfInstanceContext(cwd = process.cwd()) {
+    const currentPath = resolve(cwd);
+    const existingControlPath = findNearestInterfInstanceConfig(currentPath);
+    if (existingControlPath) {
+        if (existingControlPath !== currentPath) {
+            return {
+                controlPath: existingControlPath,
+                defaultSourceFolderPath: currentPath,
+                defaultPreparationPath: relativeSourceFolderPath(existingControlPath, currentPath),
+            };
+        }
+        return {
+            controlPath: currentPath,
+            defaultSourceFolderPath: null,
+            defaultPreparationPath: null,
+        };
+    }
+    const controlPath = defaultInterfInstanceRoot(currentPath);
+    return {
+        controlPath,
+        defaultSourceFolderPath: currentPath,
+        defaultPreparationPath: relativeSourceFolderPath(controlPath, currentPath),
+    };
+}

package/dist/cli/commands/create-method-wizard.d.ts

@@ -0,0 +1,76 @@
+import { resolveOrConfigureLocalExecutor } from "./executor-flow.js";
+import { runMethodAuthoringDraft } from "../../packages/method-authoring/method-authoring.js";
+import type { SourcePreparationConfig } from "../../packages/project-model/lib/schema.js";
+import type { MethodExecutionProfile } from "../../packages/agents/lib/executors.js";
+export interface MethodWizardPrompts {
+    intro(message: string): void;
+    select(options: {
+        message: string;
+        options: Array<{
+            value: string;
+            label: string;
+            hint?: string;
+        }>;
+    }): Promise<string | symbol>;
+    text(options: {
+        message: string;
+        placeholder?: string;
+        initialValue?: string;
+        validate?: (value: string) => string | undefined;
+    }): Promise<string | symbol>;
+    isCancel(value: unknown): value is symbol;
+    log: {
+        info(message: string): void;
+        error?(message: string): void;
+    };
+}
+export interface MethodWizardPreparationContext {
+    config: SourcePreparationConfig;
+    sourceFolderPath: string;
+}
+export declare const clackMethodPrompts: MethodWizardPrompts;
+type MethodCreationMode = "draft-from-scratch" | "fork-existing" | "draft" | "manual";
+export declare function formatMethodLabel(method: {
+    id: string;
+    label: string;
+    hint: string;
+    scope?: "builtin" | "local";
+}): {
+    value: string;
+    label: string;
+    hint: string;
+};
+export declare function buildCompiledMethodOptions(sourcePath: string): {
+    value: string;
+    label: string;
+    hint: string;
+}[];
+export declare function chooseCompiledMethod(sourcePath: string, options?: {
+    currentMethodId?: string;
+    message?: string;
+}): Promise<string | symbol>;
+export declare function chooseOrCreateCompiledMethodForPreparation(sourcePath: string, preparationConfig: SourcePreparationConfig, options?: {
+    currentMethodId?: string;
+    executionProfile?: MethodExecutionProfile;
+    resolveExecutor?: typeof resolveOrConfigureLocalExecutor;
+    runDraft?: typeof runMethodAuthoringDraft;
+}, prompts?: MethodWizardPrompts): Promise<string | symbol | null>;
+export declare function createMethodWizard(options?: {
+    intro?: boolean;
+    sourcePath?: string;
+    executionProfile?: MethodExecutionProfile;
+    baseMethodId?: string;
+    creationMode?: MethodCreationMode;
+    preparationContext?: MethodWizardPreparationContext;
+    resolveExecutor?: typeof resolveOrConfigureLocalExecutor;
+    runDraft?: typeof runMethodAuthoringDraft;
+}, prompts?: MethodWizardPrompts): Promise<string | symbol | null>;
+export declare function createCompiledMethodWizard(sourcePath: string, prompts?: MethodWizardPrompts, options?: {
+    executionProfile?: MethodExecutionProfile;
+    baseMethodId?: string;
+    creationMode?: MethodCreationMode;
+    preparationContext?: MethodWizardPreparationContext;
+    resolveExecutor?: typeof resolveOrConfigureLocalExecutor;
+    runDraft?: typeof runMethodAuthoringDraft;
+}): Promise<string | symbol | null>;
+export {};