@interf/compiler 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+Interf follows practical release notes: what changed, why it matters, and what
+still needs cleanup. Dates use the local release date.
+
+## 0.9.5 - 2026-05-02
+
+### Changed
+
+- Made the local service the execution gate for observable work. Prepare runs,
+  readiness-check runs, and agent-backed work now route through service-owned
+  run resources so CLI and UI see the same status.
+- Centralized user action definitions under the local-service package. UI
+  dialogs and CLI flows should render the same TypeScript/Zod-backed action
+  contract instead of carrying duplicate labels, prompts, and request fields.
+- Separated structured UI controls from freeform chat. Buttons submit typed
+  service requests; chat remains an explicit proposal surface.
+- Tightened Method removal. Removing a Method clears stale saved Preparation
+  selections instead of blocking on old references; preparing still requires an
+  explicit Method.
+- Expanded smoke coverage around CLI behavior, service-backed actions,
+  Method mutations, run visibility, and package boundary rules.
+
+### Fixed
+
+- Removed the UI path that pasted prepare prompts into chat instead of running
+  the typed prepare action.
+- Fixed action dialog/menu event handling so form input focus does not close the
+  parent row menu.
+- Fixed service and CLI behavior that could hide observable work in package
+  calls instead of a visible run.
+
+### Still To Watch
+
+- `apps/compiler-ui/app/page.tsx` and `src/packages/local-service/runtime.ts`
+  are still too large. Future cleanup should split them only when it reduces
+  reader trace depth or state in memory.
+- Some lower-level tests and package helpers still call package primitives
+  directly. That is correct for unit tests and package oracles; it is wrong for
+  user-visible prepare/check/Method actions.
+- Any remaining compatibility path for old product nouns should be listed for
+  founder review before removal. Do not add new compatibility shims unless the
+  current product contract requires them.
+
+## 0.9.4 - 2026-05-01
+
+### Changed
+
+- Kept setup separate from prepare runs. Creating or editing a Preparation is a
+  deterministic config action; preparing files is a visible run.
+- Simplified retry behavior by removing the partial stage-retry path. A prepare
+  run should be understandable from one run record and one filesystem state.
+- Stabilized trace rendering for active and failed runs, including failed-stage
+  layout and pending-run navigation.
+- Improved portable-context status and expected-output display so the UI
+  distinguishes current output from Method-planned output.
+
+### Fixed
+
+- Repaired missing local Method packages before prepare runs when the selected
+  Method can be reseeded from the current Interf Workspace.
+- Fixed packaged UI availability after local builds.
+- Accepted relative portable-context wikilinks and markdown-source summary links
+  during validation.
+- Stabilized the publish smoke gate environment.
+
+## 0.9.3 - 2026-04-30
+
+### Changed
+
+- Completed the public Preparation/Method vocabulary pass across CLI, service,
+  UI state, runtime records, docs, and tests.
+- Removed legacy 0.8 compatibility surfaces and project-model compiler shims
+  that forced readers to translate old product terms.
+- Moved package boundaries toward one owner per primitive: contracts for shared
+  schemas, project-model for Interf Workspace config, compiler for portable
+  context writes, testing for readiness-check runs, and local-service for read
+  models.
+- Added the source reader map in `src/README.md` so contributors can trace
+  `interf compile` without grepping through the whole repo first.
+- Expanded public CLI smoke coverage and release acceptance checks.
+
+### Fixed
+
+- Fixed release readiness blockers around CLI parsing, status output,
+  verification, UI layout, executor acceptance, and package metadata.
+- Served Interf Compiler UI from the static export used by `interf web`.
+
+### Cleanup Principle
+
+Every 0.9 patch is judged by one rubric: reduce the number of files a reader
+must trace, or reduce the number of facts a reader must hold in memory. If a
+change does neither, it should not be part of the cleanup.

package/README.md

@@ -244,7 +244,7 @@ A maintained public test example in this repo stores them like this:
 ## Useful Commands
 
 - `interf` or `interf init` — set up the Interf Workspace or manage Preparations
-- `interf web` — start Interf Compiler UI and the local API for this Workspace
+- `interf web` — start Interf Compiler UI and the local service for this Workspace
 - `interf compile` — build portable context agents can use
 - `interf test` — run readiness checks against source files and/or portable context
 - `interf create method` — draft a reusable Method
@@ -252,6 +252,7 @@ A maintained public test example in this repo stores them like this:
 
 ## Maintainer Docs
 
+- [CHANGELOG.md](./CHANGELOG.md) - 0.9 release notes and cleanup status
 - [src/packages/README.md](./src/packages/README.md) - package boundaries
 - [src/cli/README.md](./src/cli/README.md) - CLI orchestration
 - [apps/compiler-ui/README.md](./apps/compiler-ui/README.md) - Interf Compiler UI

package/agent-skills/interf-actions/SKILL.md

@@ -7,7 +7,7 @@ description: Use when an agent needs to operate Interf from natural language: in
 
 Interf prepares data for agent work. It runs locally, processes source files, shows evidence that the data is ready, and writes portable context: a local folder with verifiable outputs agents can use.
 
-Use the installed CLI as the source of truth. Outside Interf Compiler UI proposal mode, inspect the current command surface when needed:
+The Interf local service owns the typed action contract and run observability. For agents, the installed CLI is the supported facade over that contract. Outside Interf Compiler UI freeform proposal mode, inspect the current command surface when needed:
 
 ```sh
 interf --help
@@ -18,32 +18,39 @@ interf doctor
 
 For command-specific flags, run `interf <command> --help`.
 
-In Interf Compiler UI proposal mode, do not run CLI commands. Use `references/cli.md` instead. It is a generated snapshot of the current Interf CLI help and is checked against the built package in the repo test suite.
+In Interf Compiler UI freeform proposal mode, do not run CLI commands. Use `references/cli.md` instead. It is a generated snapshot of the current Interf CLI help and is checked against the built package in the repo test suite.
 
 ## Operating Rules
 
 - Use exact Preparation ids from `interf list` or `interf/interf.json`.
 - Prefer the selected Preparation only when it is explicit or there is one obvious Preparation.
 - Do not invent readiness checks, Method ids, paths, or executor names.
-- If the local service is running, `interf compile` and `interf test` submit visible runs to Interf Compiler UI.
+- Interf CLI actions should run through a connected local service so status and runs are visible in Interf. If the service is not running, tell the user to start `interf web` for the Workspace before running write actions.
+- Do not call the local HTTP API directly unless Interf explicitly gives an API integration task. Use CLI commands for normal agent work.
 - Propose the command first and wait for approval before running commands that write files, start runs, create Method packages, build portable context, or run readiness checks.
 - If the request names an existing Preparation and asks to prepare, build, or refresh portable context, use `interf compile --preparation <name>`. The saved Preparation and selected Method are the source of truth.
 - If the request is ambiguous, ask one concise clarification instead of guessing.
 
-## Interf Compiler UI Proposal Mode
+## Interf Compiler UI Freeform Proposal Mode
 
-When Interf Compiler UI asks for a proposal, do not run CLI commands. Write a single JSON object to the requested output path.
+When Interf Compiler UI asks for a proposal, do not run CLI commands. Write a
+single JSON object to the requested output path. Structured UI controls call the
+local service directly; this mode is only for freeform planning.
 
 Use these action types:
 
-- `preparation-setup`
 - `compile`
 - `test`
 - `readiness-check-draft`
 - `method-authoring`
+- `method-improvement`
 - `clarification`
 
-Use `preparation-setup` when no Preparation is saved yet or when the user asks to initialize/add a source folder. Set `values.path` to a visible source folder path such as `./Reports`, set `preparation` or `values.name` to the Preparation id, and set `values.about` to the agent work the source folder should support. CLI equivalent: `interf init` or `interf create preparation`.
+Do not propose deterministic Preparation or Method mutations from this mode.
+Create, select, duplicate, and remove actions go through direct service
+endpoints in the UI or through the CLI for agent work. If freeform chat asks for
+one of those actions, return `clarification` and tell the caller to use the
+direct page control or CLI.
 
 Use `compile` when the user asks to prepare, build, or refresh portable context for an existing Preparation. Do not ask what "prepare" means when the Preparation exists. Set `preparation` to the selected or mentioned Preparation id. CLI equivalent: `interf compile --preparation <name>`.
 
@@ -57,17 +64,16 @@ Return this shape:
 
 ```json
 {
-  "action_type": "preparation-setup",
+  "action_type": "compile",
   "preparation": "preparation-id",
   "method": "method-id if applicable",
   "values": {
-    "path": "./source-folder",
-    "about": "agent work this source folder should support"
+    "mode": "both if applicable"
   },
   "title": "short approval card title",
   "summary": "one sentence describing what will run",
   "assistant_message": "concise explanation for the user",
-  "command_preview": "interf init # source: ./source-folder"
+  "command_preview": "interf compile --preparation preparation-id"
 }
 ```
 

package/agent-skills/interf-actions/references/cli.md

@@ -18,7 +18,7 @@ Commands:
   interf list                      List saved Preparations in this Source Folder
   interf status                    Show deterministic health for the Portable Context agents use
   interf verify <check> [stageId]  Run deterministic verification checks
-  interf web                       Start Interf UI and the local Interf API
+  interf web                       Start Interf Compiler UI and the local Interf service
   interf reset <scope>             Reset generated Portable Context state while keeping source files and the local Method package
 
 Options:
@@ -49,12 +49,8 @@ Positionals:
   type  Type to create (`preparation` or `method`)                                                                                                      [string]
 
 Options:
-  --help        Show help                                                                                                                              [boolean]
-  --version     Show version number                                                                                                                    [boolean]
-  --model       Override the local executor model for this run                                                                                          [string]
-  --profile     Executor-specific profile override for this run                                                                                         [string]
-  --effort      Override the model reasoning effort for this run                                                                                        [string]
-  --timeout-ms  Interrupt the local executor after this much inactivity                                                                                 [number]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
 ```
 
 ## interf compile
@@ -67,10 +63,6 @@ Prepare files and write Portable Context agents can use
 Options:
   --help               Show help                                                                                                                       [boolean]
   --version            Show version number                                                                                                             [boolean]
-  --model              Override the local executor model for this run                                                                                   [string]
-  --profile            Executor-specific profile override for this run                                                                                  [string]
-  --effort             Override the model reasoning effort for this run                                                                                 [string]
-  --timeout-ms         Interrupt the local executor after this much inactivity                                                                          [number]
   --preparation        Preparation id to compile when this Source Folder has more than one Preparation                                                  [string]
   --max-attempts       Retry the prepare run and run saved readiness checks with the same Method until the Preparation is ready or reaches this total attempt li
                        mit                                                                                                                              [number]
@@ -88,17 +80,11 @@ interf test
 Run readiness checks against source files and Portable Context
 
 Options:
-  --help            Show help                                                                                                                          [boolean]
-  --version         Show version number                                                                                                                [boolean]
-  --model           Override the local executor model for this run                                                                                      [string]
-  --profile         Executor-specific profile override for this run                                                                                     [string]
-  --effort          Override the model reasoning effort for this run                                                                                    [string]
-  --timeout-ms      Interrupt the local executor after this much inactivity                                                                             [number]
-  --preparation     Preparation id to check when this Source Folder has more than one Preparation                                                       [string]
-  --target          Check source files, Portable Context, or both. Default: both when Portable Context exists, otherwise source files.
+  --help         Show help                                                                                                                             [boolean]
+  --version      Show version number                                                                                                                   [boolean]
+  --preparation  Preparation id to check when this Source Folder has more than one Preparation                                                          [string]
+  --target       Check source files, Portable Context, or both. Default: both when Portable Context exists, otherwise source files.
                                                                                                            [choices: "both", "source-files", "portable-context"]
-  --keep-sandboxes  Keep every readiness-check sandbox for review instead of pruning successful ones                                  [boolean] [default: false]
-  --agents          Comma-separated local agents to use for readiness checks, or `all`. Example: --agents claude-code,codex                             [string]
 ```
 
 ## interf web
@@ -106,7 +92,7 @@ Options:
 ```text
 interf web
 
-Start Interf UI and the local Interf API
+Start Interf Compiler UI and the local Interf service
 
 Options:
   --help           Show help                                                                                                                           [boolean]

package/dist/cli/commands/action-input-cli.d.ts

@@ -0,0 +1,25 @@
+import type { ActionInputDefinition, ActionInputValues } from "../../packages/local-service/action-definitions.js";
+export interface ActionInputPrompts {
+    select(options: {
+        message: string;
+        options: Array<{
+            value: string;
+            label: string;
+            hint?: string;
+        }>;
+        initialValue?: 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;
+}
+export declare const clackActionInputPrompts: ActionInputPrompts;
+export declare function promptActionInputValues(definition: ActionInputDefinition, options?: {
+    includeAdvanced?: boolean;
+    omitFields?: Set<string>;
+    prompts?: ActionInputPrompts;
+}): Promise<ActionInputValues | null>;

package/dist/cli/commands/action-input-cli.js

@@ -0,0 +1,73 @@
+import * as p from "@clack/prompts";
+export const clackActionInputPrompts = {
+    select: (options) => p.select(options),
+    text: (options) => p.text(options),
+    isCancel: p.isCancel,
+};
+function fieldInitialValue(values, field) {
+    return values[field.name] ?? "";
+}
+function fieldPromptMessage(field) {
+    return field.label;
+}
+export async function promptActionInputValues(definition, options = {}) {
+    const prompts = options.prompts ?? clackActionInputPrompts;
+    let values = { ...definition.initialValues };
+    const fields = definition.fields.filter((field) => {
+        if (field.readOnly)
+            return false;
+        if (options.omitFields?.has(field.name))
+            return false;
+        if (field.advanced && options.includeAdvanced !== true)
+            return false;
+        return true;
+    });
+    for (const field of fields) {
+        const initialValue = fieldInitialValue(values, field);
+        const validate = (value) => {
+            const nextValues = {
+                ...values,
+                [field.name]: value,
+            };
+            const normalizedValues = definition.normalizeValues?.(nextValues) ?? nextValues;
+            const parsed = definition.schema.safeParse(normalizedValues);
+            if (!parsed.success) {
+                const issue = parsed.error.issues.find((candidate) => candidate.path[0] === field.name);
+                if (issue)
+                    return issue.message;
+            }
+            const requestErrors = definition.validateRequest?.(normalizedValues) ?? {};
+            return requestErrors[field.name];
+        };
+        const answer = field.type === "select"
+            ? await prompts.select({
+                message: fieldPromptMessage(field),
+                options: field.options ?? [],
+                ...(initialValue ? { initialValue } : {}),
+            })
+            : await prompts.text({
+                message: fieldPromptMessage(field),
+                placeholder: field.placeholder,
+                initialValue,
+                validate,
+            });
+        if (prompts.isCancel(answer))
+            return null;
+        values = {
+            ...values,
+            [field.name]: String(answer),
+        };
+    }
+    const normalizedValues = definition.normalizeValues?.(values) ?? values;
+    const parsed = definition.schema.safeParse(normalizedValues);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(issue?.message ?? `${definition.title} input is invalid.`);
+    }
+    const requestErrors = definition.validateRequest?.(parsed.data) ?? {};
+    const firstRequestError = Object.values(requestErrors)[0];
+    if (firstRequestError) {
+        throw new Error(firstRequestError);
+    }
+    return parsed.data;
+}

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

@@ -2,19 +2,13 @@ import * as p from "@clack/prompts";
 import { detectInterf } from "../../packages/project-model/interf.js";
 import type { SourcePreparationConfig } from "../../packages/project-model/lib/schema.js";
 import type { CommandModule } from "yargs";
-import { chooseCompiledConfigToBuild, ensureCompiledFromConfig } from "./compiled-flow.js";
-import { resolveOrConfigureLocalExecutor } from "./executor-flow.js";
-import { runConfiguredCompiledCompile } from "./compile-controller.js";
-export { runConfiguredCompiledCompile } from "./compile-controller.js";
+import { choosePreparationConfig } from "./preparation-picker.js";
 export declare const compileCommand: CommandModule;
 interface CompileCommandDeps {
-    chooseCompiledConfigToBuild: typeof chooseCompiledConfigToBuild;
+    choosePreparationConfig: typeof choosePreparationConfig;
     confirm: typeof p.confirm;
     detectInterf: typeof detectInterf;
-    ensureCompiledFromConfig: typeof ensureCompiledFromConfig;
     resolveInteractiveCompileLoopOverrides: typeof resolveInteractiveCompileLoopOverrides;
-    resolveOrConfigureLocalExecutor: typeof resolveOrConfigureLocalExecutor;
-    runConfiguredCompiledCompile: typeof runConfiguredCompiledCompile;
 }
 export interface CompileCommandResult {
     compiledPath: string;
@@ -31,3 +25,4 @@ export declare function resolveInteractiveCompileLoopOverrides(options: {
     maxAttemptsOverride: number | null;
     maxLoopsOverride: number | null;
 } | null>;
+export {};

package/dist/cli/commands/compile.js

@@ -2,20 +2,17 @@ import chalk from "chalk";
 import * as p from "@clack/prompts";
 import { detectInterf, readInterfConfig, resolveSourceControlPath, } from "../../packages/project-model/interf.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 { portableContextPath, } from "../../packages/project-model/project-paths.js";
+import { choosePreparationConfig, } from "./preparation-picker.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: "Prepare files and write Portable Context agents can use",
-    builder: (yargs) => addExecutionProfileOptions(yargs).option("preparation", {
+    builder: (yargs) => yargs.option("preparation", {
         type: "string",
         describe: "Preparation id to compile when this Source Folder has more than one Preparation",
     }).option("max-attempts", {
@@ -34,13 +31,10 @@ export const compileCommand = {
     },
 };
 const defaultCompileCommandDeps = {
-    chooseCompiledConfigToBuild,
+    choosePreparationConfig,
     confirm: p.confirm,
     detectInterf,
-    ensureCompiledFromConfig,
     resolveInteractiveCompileLoopOverrides,
-    resolveOrConfigureLocalExecutor,
-    runConfiguredCompiledCompile,
 };
 function readHintedSourcePath(argv) {
     return typeof argv.sourcePath === "string" && argv.sourcePath.trim().length > 0
@@ -103,7 +97,7 @@ export async function runCompileCommand(argv = {}, deps = {}) {
                 requestedPreparationName,
                 hintedPreparationConfig,
             })
-            : await helpers.chooseCompiledConfigToBuild({
+            : await helpers.choosePreparationConfig({
                 sourcePath,
                 selectMessage: "Which saved Preparation do you want to compile?",
             });
@@ -130,7 +124,7 @@ export async function runCompileCommand(argv = {}, deps = {}) {
                 return null;
         }
         compiledConfig = selectedCompiled;
-        compiledPath = helpers.ensureCompiledFromConfig(sourcePath, selectedCompiled);
+        compiledPath = portableContextPath(sourcePath, selectedCompiled.name);
         if (!skipPreparationBanner) {
             console.log(chalk.dim(`  Preparation: ${selectedCompiled.name}`));
         }
@@ -162,7 +156,7 @@ export async function runCompileCommand(argv = {}, deps = {}) {
         maxAttemptsOverride,
         maxLoopsOverride,
     });
-    if (argv.skipService !== true && compiledConfig) {
+    if (compiledConfig) {
         const submitted = await submitCompileRunToLocalService({
             projectPath: sourcePath,
             request: {
@@ -211,37 +205,15 @@ export async function runCompileCommand(argv = {}, deps = {}) {
                 testedDuringCompile,
             };
         }
-    }
-    const executionProfile = executionProfileFromArgv(argv);
-    const { executor, error } = await helpers.resolveOrConfigureLocalExecutor({
-        executionProfile,
-        purpose: "compile",
-    });
-    if (!executor && !error)
-        return null;
-    if (!executor) {
         process.exitCode = 1;
-        console.log(chalk.red(error ?? "No coding agent detected."));
+        console.log(chalk.red("  Interf local service is not running for this Workspace."));
+        console.log(chalk.dim("  Start it with `interf web`, then rerun `interf compile` so the prepare run is visible in Interf."));
         return null;
     }
-    const compiled = await helpers.runConfiguredCompiledCompile({
-        executor,
-        testExecutor: executor,
-        compiledPath,
-        sourcePath,
-        compiledConfig,
-        executionProfile,
-        maxAttemptsOverride,
-        maxLoopsOverride,
-        preserveStageShells: readStageShellRetentionMode(argv),
-    });
-    if (!compiled) {
-        return null;
-    }
-    return {
-        compiledPath,
-        testedDuringCompile,
-    };
+    process.exitCode = 1;
+    console.log(chalk.red("  Interf could not resolve a saved Preparation for this prepare run."));
+    console.log(chalk.dim("  Run `interf list` to inspect saved Preparations, then rerun `interf compile --preparation <id>`."));
+    return null;
 }
 export async function resolveInteractiveCompileLoopOverrides(options) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {

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

@@ -1,7 +1,4 @@
-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: {
@@ -51,26 +48,17 @@ export declare function chooseCompiledMethod(sourcePath: string, options?: {
 }): 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 {};