npm - @interf/compiler - Versions diffs - 0.18.0 → 0.22.0 - Mend

@interf/compiler 0.18.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (369) hide show

package/README.md DELETED Viewed

@@ -1,311 +0,0 @@
-# Interf
-**Prepare your data for AI agents. With proof.**
-Interf prepares data for agent work. It runs locally, processes your files, shows evidence that your data is ready, and writes portable context: a local folder with verifiable outputs agents can use.
-**Hallucinations aren't an agent problem. They're a data preparation problem.**
-When agents start from source files, they have to discover the full picture while they work. That discovery is hidden: you cannot see which files were processed, which evidence was used, or which connections were found.
-Interf replaces that hidden discovery with a visible Method run over your source files. You connect to a local instance, name a Preparation against your Source Folder and a Method, run compile, and read the portable context Interf returns. Interf records source references, runs the Method locally, and writes the portable context: evidence, structure, and cross-file connections for agents.
-```text
-Source Folder                       Portable context agents read
-bristol-office-market/              ~/.interf/preparations/bristol/portable-context/
-  q4-market-report.pdf                AGENTS.md
-  lease-comps.xlsx                    .interf/runtime/source-snapshot.json
-  planning-notes.md                   home.md
-  exports/availability.csv            summaries/
-                                      knowledge/
-```
-## What a Method Run Produces
-A Method run produces portable context plus proof of work. The portable context is the folder agents read. The proof shows which source files were assigned, which Method stages ran, what each stage wrote, and whether required outputs exist.
-For the built-in `interf-default` Method, a compile run looks like this:
-```text
-Source Files: bristol-office-market
-Method: interf-default
-compile run
-  record source references
-  summarize -> summaries/
-  structure -> knowledge/
-  shape -> home.md and agent entrypoints
-  record proof -> processed files, stage outputs, required artifacts
-output
-  portable context -> { kind: "local-path", value: "/Users/me/.interf/preparations/bristol/portable-context" }
-```
-The output is not an answer. It is a prepared local folder with routes, summaries, linked notes, source snapshots, and agent instructions. Your runtime agent reads that folder when it does the actual agent work.
-## Design Choices
-- `Method-scoped`: every Method is for one specific kind of agent work over source files, not a generic index over your Source Folder.
-- `Deterministic`: Interf runs each stage, an ordered phase of a Method, and shows stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs exist. Agents do not have to rebuild the full picture while they work.
-- `Local-first and private`: your files, readiness checks, and agent runs stay on your machine. No cloud, no uploads, no telemetry.
-- `Bring your own AI`: use Claude Code, Codex, or another local agent.
-- `File over app`: the portable context is a real local folder owned by the instance — no hidden store, no hidden index. Inspect it, diff it, version it.
-- `Readiness checks you control`: every build can be checked against gates you wrote from the files. If the portable context is `not ready`, `interf test` shows the readiness evidence behind that status.
-## Why Not Just Ask Your Agent?
-You can. Interf can use Claude Code, Codex, or another local agent while it builds the portable context.
-A one-off preprocessing prompt gives you another agent answer to trust. Interf puts that work inside a Method you can inspect: declared stages, required outputs, stage-by-stage proof of work, and readiness checks that decide whether the portable context is `ready` or `not ready`.
-The agent can still do the processing. Interf shows what ran, which files were processed, what evidence was produced, and whether the result is ready for the agent work.
-## Install
-```bash
-npm install -g @interf/compiler
-interf            # opens the wizard; start or connect an engine when needed
-```
-Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run `interf doctor --live` if the executor is not detected.
-## Quick Start
-```bash
-interf web                                      # terminal 1: start the local engine
-interf prep create bristol \                    # terminal 2: name the unit of work
-  --source ./bristol-office-market \
-  --method interf-default
-interf compile bristol                          # build portable context, returns the locator
-interf test bristol                             # check readiness
-```
-`interf web` starts the engine in the foreground and writes
-`~/.interf/connection.json` so subsequent CLI commands can connect. The
-interactive `interf` wizard can ask whether to start `interf web` or connect a
-remote engine. Mutating commands never auto-start an engine — if no instance is
-connected, they exit with a hint pointing at `interf web` (local) or
-`interf login` (future cloud).
-`interf compile` returns the artifact locator on success — for a local
-engine that's a `local-path` you can open with any tool. Point your agent at
-that path. There's no `--out` flag, no implicit copy, no hidden store: the
-instance owns the bytes and the API tells you where they are.
-If you want a baseline before preparing, run `interf test bristol --target source-files`. It is optional proof, not the main path.
-## Portable Context
-The portable context is the local folder Interf writes from your files. The instance owns its location — `~/.interf/preparations/<prep-id>/portable-context/` for a local engine, a signed remote URL for a cloud engine. The API returns a typed locator (`{ kind: "local-path" | "remote-url", value }`); your agent reads from there.
-It gives agents evidence, structure, and cross-file connections for navigating the files. It is not a replacement for your files. For the built-in `interf-default`, it includes:
-```text
-~/.interf/preparations/bristol/portable-context/
-  AGENTS.md       # agent-facing entry point and source-checking rules
-  CLAUDE.md       # same guidance for Claude Code
-  .interf/
-    runtime/
-      source-snapshot.json  # source references captured for the latest run
-      stages/               # per-stage source input lists
-  home.md         # overview and routes for agents
-  summaries/      # one note per source file
-  knowledge/      # linked notes built from the files
-```
-The source files stay the source of truth. Interf writes portable context inside the instance's data dir; it does not modify the Source Folder.
-`AGENTS.md` tells agents how to use the portable context: start from the prepared outputs, follow the prepared routes, and use the recorded source references when exact source evidence matters.
-Interf also records stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs were created.
-The portable context carries source references, not a mandatory copy of every source file. The source files remain where you keep them; Interf records which sources were assigned and what artifacts were produced from them.
-## Methods
-A Method tells Interf how to process your files for the job agents need to do. When you create one, describe three things: what data is in the Source Folder, what the portable context should contain, and what evidence should show the portable context is `ready`. The built-in `interf-default` Method ships with `@interf/compiler`. Install your own with `interf method install <path>`; draft new ones with `interf method draft <prep-id>`.
-```text
-~/.interf/methods/interf-default/
-  method.json         # Method: source data, stages, and processing rules
-  method.schema.json  # output contract: required portable-context files and folders
-  README.md             # what this Method is for, for humans and agents
-  compile/
-    stages/
-      summarize/        # stage instructions Interf runs during compile
-      structure/
-      shape/
-  use/
-    query/              # how agents read the portable context
-  improve/              # how Interf revises this Method if readiness checks still fail
-```
-- `method.json` describes the Method: source data, stages, and how the files should be processed.
-- `method.schema.json` describes the output contract: what the portable context must contain. Interf enforces it when you run `interf compile`.
-- `compile/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; Interf runs them during compile.
-- `use/query/` holds the instructions agents follow when they read the portable context for live agent work.
-- `improve/` holds the instructions Interf follows when the first build misses and the Method itself needs editing.
-A Method defines the stages, output contract, proof requirements, and improvement instructions Interf runs on your files. Technically, each Method is stored as a Method package with `method.json` and `method.schema.json`. The result is portable context your agents can read.
-## Method Improvement
-When the first compile run still misses readiness checks, Interf edits the Method itself and compiles again. Same files, same checks, improved Method and portable context. Run `interf method improve <prep-id>` to invoke that loop manually.
-Interf saves every readiness-check run inside the preparation's portable context under `.interf/tests/`. You can inspect what changed and why a later compile run did better.
-## How Interf Compiles
-You don't need to think about roles. By default Interf uses your active agent for every stage of every compile run, the same way 0.14 did. Roles are available for advanced users who want different agents per stage; defaults are good and stable.
-Interf treats connected agents as a first-class primitive and uses a small role taxonomy internally to route stages between them. The default behavior is single-active-agent — one installed agent runs everything — but you can opt into per-role specialization without changing any Method.
-```text
-Connected agents             Role map (per-instance)
-  claude-code (active)         extractor   → claude-code
-  codex                        summarizer  → claude-code
-  pdf-extract (custom)         structurer  → claude-code
-                               verifier    → claude-code
-                               general     → claude-code
-A Method compile run
-  for each stage in the Method
-    look up the stage's role in the role map
-    invoke the mapped agent on the prepared shell
-    record which agent ran which stage
-```
-Methods declare an optional `role` per stage — one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Custom role names are allowed; unknown roles fall through to `general`.
-The role map lives in `~/.interf/agents.json`. On a fresh install with one agent installed, every role maps to that agent and you get the same single-active-agent behavior 0.14 had. To change which agent runs which role:
-```bash
-interf agents ls
-interf agents register opencode --command "opencode --prompt"
-interf agents map structurer codex
-interf agents use claude-code   # set the active agent
-interf agents unmap structurer  # fall back to active
-```
-Or use the **Agents** tab in Interf Compiler UI. Either surface mutates the same `~/.interf/agents.json` through the local service.
-Verify runs always resolve to the `verifier` role. Method-authoring runs ask the authoring agent to propose a `role` per stage based on the prompt content; missing roles default to `general`.
-## How the Pieces Fit
-The instance owns preparation state. A preparation declares a source binding (`{ kind: "local-folder", locator: <path> }`) and a method id; the instance stores its config at `~/.interf/preparations/<prep-id>/config.json` and writes portable context to `~/.interf/preparations/<prep-id>/portable-context/`. A compile run processes the selected source files and produces the artifact locator the API returns. `interf test` checks Source Folder files and portable context against the same readiness checks.
-Readiness is one `ready` / `not ready` status, not a separate score. Interf builds it from evidence primitives: Method Artifact checks, proof records, file coverage, artifact validation, and readiness checks.
-`interf web` runs the local Interf instance and serves Interf Compiler UI. The UI reads local-service resources: Source Files, Methods, runs, stages, proof, artifacts, readiness checks, and whether portable context is `ready` or `not ready`. It renders local instance state; it does not own compiler, Method, or readiness semantics.
-Everywhere Interf shows a resource — Source Folder, portable context, Method files, run artifacts — the API returns a single locator shape: `{ kind, value }`. `local-path` means the engine has filesystem access to the same host as the user; `remote-url` is a signed URL the UI opens in a browser tab; `api-served` is a relative API route the UI fetches and renders inline. Local engines today return `local-path`; the same shape carries forward unchanged when a remote instance fronts the API.
-## CLI Connection
-The CLI is a thin authorized client of one connected instance. It carries one piece of state — `~/.interf/connection.json`:
-```text
-{
-  "url": "http://127.0.0.1:4873",
-  "auth_token": null
-}
-```
-`interf web` writes that record on startup. `interf login --url <remote>` writes a remote one (the cloud backend ships in a future release; the wire shape and config layer ship now). `interf logout` clears it.
-If the connection is unreachable, every mutating command exits non-zero with:
-```text
-Not connected to any Interf instance.
-Start one with `interf web`, or set --url / `interf login` for a remote one.
-```
-There is no auto-start. There is no per-folder pointer file. One mental model: client connects to instance, or doesn't.
-## Readiness Checks
-There are two checks in the system, and they answer different questions.
-Method Artifact checks check the build: did the Method produce the files, folders, Artifacts, and stage outputs it promised? Interf checks those while it compiles.
-Readiness checks check the Method output: is this portable context good enough for the specific agent work? They are the confidence layer on top of the portable context, not the product output.
-In the setup flow, readiness checks often look like plain question-and-answer pairs. On the API, they live under each preparation's `checks[]`. They help define whether the portable context is `ready` or `not ready`. A check should be a small, verifiable fact or condition you already know from the files:
-- one exact number from a chart, table, or filing
-- one short statement that should be true or false
-- one comparison across years, files, or sections
-Interf proposes an initial set from the files and the description of the job agents need to do. You confirm, edit, or replace them. `interf test` runs those checks through the configured local agent against Source Folder files, portable context, or both. The portable context itself does not answer; the agent answers while using it.
-A maintained readiness example in this repo uses one market report, two readiness checks, and two agents:
-<!-- PUBLIC_BENCHMARK_TABLE:START -->
-| Agent | Source files | Portable context |
-| --- | --- | --- |
-| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
-| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
-<!-- PUBLIC_BENCHMARK_TABLE:END -->
-Codex passed from the Source Folder files; Claude Code only passed when working from Interf's portable context. Both numbers come from the same readiness-check pass. That is evidence about whether this Method output is `ready` for this agent work.
-A maintained public test example uses this preparation:
-<!-- PUBLIC_TEST_CHECKS:START -->
-```text
-{
-  "id": "cbre-chart-sanity",
-  "source": { "kind": "local-folder", "locator": "./task-files" },
-  "method_id": "interf-default",
-  "about": "Bristol historical take-up and availability chart lookup.",
-  "checks": [
-    {
-      "question": "What were Bristol's annual take-up values in 2018 and 2016?",
-      "answer": "Around half a million sq ft in 2018, roughly 0.45 to 0.6 million sq ft, and about 0.7 to 0.8 million sq ft in 2016. These are approximate chart-derived reads."
-    },
-    {
-      "question": "What were Bristol's availability values in 2018 and 2016?",
-      "answer": "About 0.55 to 0.6 million sq ft in 2018 and about 1.2 to 1.3 million sq ft in 2016. These are approximate chart-derived reads."
-    }
-  ]
-}
-```
-<!-- PUBLIC_TEST_CHECKS:END -->
-## What Interf Is Not
-- Not a second brain or memory product. One preparation per agent job; nothing global.
-- Not a vector store or RAG server. The portable context is plain files.
-- Not a hosted data platform. The local instance runs on your machine; your bytes never leave it.
-- Not an agent harness. Interf prepares the data; your existing agent reads the portable context.
-## Useful Commands
-- `interf web` — run the local engine in the foreground (Compiler UI + API)
-- `interf web stop` — kill the running local engine
-- `interf prep ls / create / show / rm` — manage preparations
-- `interf compile <prep-id>` — build portable context, returns the artifact locator
-- `interf test <prep-id>` — run readiness checks against source files and/or portable context
-- `interf method ls / install / draft / improve` — manage Method packages
-- `interf agents ls / use / register / unregister / map / unmap` — manage connected agents and the role map
-- `interf runs ls / status / watch / cancel / fetch` — inspect runs
-- `interf login / logout` — manage `~/.interf/connection.json` (remote backend ships in a future release)
-- `interf status` — show the active connection and a preparation summary
-- `interf doctor --live` — verify the local executor
-## Maintainer Docs
-- [src/README.md](./src/README.md) - source tree index
-- [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
-- [apps/compiler-ui/DESIGN.md](./apps/compiler-ui/DESIGN.md) - UI design source of truth
-- [scripts/README.md](./scripts/README.md) - maintainer automation
-- [AGENTS.md](./AGENTS.md) / [CLAUDE.md](./CLAUDE.md) - maintainer compass + navigation index for agent sessions
-Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
-License: see [LICENSE.md](./LICENSE.md). © 2026 Interf Inc. All rights reserved.
-Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).

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

@@ -1,185 +0,0 @@
----
-name: interf-actions
-description: Use when an agent needs to operate Interf from natural language: connect to an instance, manage preparations, compile a Method against a Source Folder, propose safe CLI commands, or write action proposals for Interf Compiler UI.
----
-# Interf Actions
-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 agents can read from.
-The model in 0.13 is **instance + preparation**:
-- **Instance** = the engine (a local `interf web` process, or a future cloud endpoint). Owns all preparation state. Same wire shape both ends.
-- **Method** = reusable recipe (`method.json` + stage docs). A package, no runtime state. Lives bundled with `@interf/compiler` or installed in the user library at `~/.interf/methods/<id>/`.
-- **Preparation** = a unit of work — `id + source binding + method + readiness checks + run history`. The project-level identifier the agent names. Lives inside an instance.
-- **Compile run** = one execution of a Preparation. Append-only. Produces portable context.
-A **Source Folder** is the agent's input — files Interf scans by reference, not by copy. The agent's executor reads them; Interf never copies.
-There is **no workspace concept** in 0.13. The CLI carries one piece of state: the active connection at `~/.interf/connection.json`.
-## Connection model
-The CLI is a thin authorized client of one connected instance. Every mutating command requires a reachable connection. If `~/.interf/connection.json` is missing or unreachable, the command exits non-zero with:
-```text
-Not connected to any Interf instance.
-Start one with `interf web`, or set --url / `interf login` for a remote one.
-```
-There is **no auto-start**. Agents must verify a connection exists before running mutating commands. To set up a connection:
-```sh
-interf web              # local: starts the engine in the foreground (blocks)
-interf login --url <…>  # remote: writes connection.json
-```
-## Agent flow
-1. **Confirm a connection** — call `interf status` or `interf prep ls`. If they return `Not connected…`, ask the user to start an instance.
-2. **List or create a preparation** —
-   ```sh
-   interf prep ls                                                    # see what exists
-   interf prep create <id> --source <path> --method <method-id>      # create one
-   ```
-3. **Compile** — preparation id is positional:
-   ```sh
-   interf compile <prep-id> [--watch] [--quiet] [--idempotency-key <key>]
-   ```
-   Default is async-return: prints `run id`, the artifact `locator`, and current readiness. With `--quiet`, only the locator is printed (suitable for `$(interf compile bristol --quiet)/home.md`). With `--watch`, the CLI tails events until the run reaches a terminal state.
-4. **Inspect runs** —
-   ```sh
-   interf runs status <run-id>
-   interf runs watch <run-id>
-   interf runs ls [--prep <id>]
-   interf runs fetch <run-id> --to <abs-path>
-   interf runs cancel <run-id>
-   ```
-5. **Read the portable context** — for a local engine the locator is a `local-path` you can open directly with any tool. For a remote engine it is a signed `remote-url`; `interf runs fetch` localizes it.
-6. **On `not ready`**, propose method improvement:
-   ```sh
-   interf method improve <prep-id>
-   ```
-## Connected agents and the role map
-Interf treats the agents it can shell out to (Claude Code, Codex, custom CLIs) as a first-class primitive. `GET /v1/instance` reports `agent_count` and `default_agent`; if `agent_count` is `0`, **`interf compile` and `interf verify` will hard-error** — install one or register a custom CLI before retrying.
-```sh
-interf agents ls                                       # list registered + detected agents
-interf agents use <name>                               # set the active agent (sweeps role map)
-interf agents register <name> --command "<cmd>"        # register a custom CLI
-interf agents unregister <name>                        # remove a custom CLI
-interf agents map <role> <agent>                       # pin a role to an agent
-interf agents unmap <role>                             # fall back to the active agent
-```
-Roles are: `extractor`, `summarizer`, `structurer`, `verifier`, `general` (Methods may declare custom names; the engine treats unknown roles as `general`). Default behavior is single-active-agent — every role maps to the same agent — so existing agent flows do not change unless the user opts into per-role specialization.
-## Agent contract — flags every CLI run uses
-| Flag | What it controls | When the agent passes it |
-|---|---|---|
-| `--url <url>` | Override the active connection URL for one call. | When the user has multiple instances and wants to target a specific one without rewriting `~/.interf/connection.json`. |
-| `--token <token>` | Override the active bearer token for one call. | Cloud / non-loopback connections only. |
-| `--watch` | Block until the run finishes and tail stages. | Only when the agent must wait inline. Default is async return-with-id. |
-| `--quiet` | Print only the artifact locator on success. | Scripting (`$(interf compile bristol --quiet)`). |
-| `--idempotency-key <key>` | Sent as `X-Interf-Idempotency-Key`. The instance caches the key for an hour and returns the original run id on retries instead of starting a fresh run. | Whenever the agent might retry the same compile. |
-| `--to <abs-path>` | (`interf runs fetch`) Absolute destination to copy portable context into. Must be empty or non-existent unless `--overwrite` is set. | When the agent needs portable context outside the instance. |
-| `--overwrite` | (`interf runs fetch`) Allow copying into a destination that already has files. | Only when the agent wants to replace existing files. |
-## Operating rules
-- Use exact preparation ids and Method ids returned by the API. Do not invent ids.
-- Always confirm a connection exists before running mutating commands. Agents must not call `interf web` themselves — that command blocks the foreground; running it inside an agent loop hangs the loop.
-- For long-running work, use the async default and check status by id (`interf runs status <id>`). Only use `--watch` when the agent must wait inline.
-- 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 is ambiguous, ask one concise clarification instead of guessing.
-## Show your work — always print the run URL
-Interf Compiler UI is the user's verification surface. The agent does
-the work; the user clicks a URL to see live trace, events, readiness,
-and proof. **Whenever you kick off a run, print a deep-link to the run
-page in the same message as the run id.** The user should never have
-to navigate the UI manually to find what you just started.
-The base URL is whatever `interf status` reports as the connected
-instance (e.g. `http://127.0.0.1:4873` for a local engine,
-`https://api.interf.cloud/...` for cloud). Append query params:
-| Param | Value |
-|---|---|
-| `preparation` | the preparation id |
-| `run` | the run id returned by the CLI |
-| `runTab` | optional: `trace` (default), `events`, or `readiness` |
-**Example output after `interf compile serge`:**
-```text
-Started compile run compile_8x2abc...
-Watch live: http://127.0.0.1:4873/?preparation=serge&run=compile_8x2abc...
-I'll check status in a moment with `interf runs status compile_8x2abc...`.
-```
-The same pattern applies to verify, method-improvement, and method-authoring
-runs. When a run finishes, print the same URL with `runTab=readiness` so the
-user can click through to the readiness summary.
-The agent stays the executor; the URL is the user's "I can see what's
-happening" handle. It also makes failures self-explanatory — when a run
-errors, the user clicks through to the same trace the agent is reading.
-## Reading the artifact locator
-`interf compile <prep-id>` prints a short multi-line block by default. The portable-context locator looks like one of:
-```text
-Portable context: /Users/me/.interf/preparations/bristol/portable-context
-```
-```text
-Portable context: https://api.interf.cloud/v1/runs/run_2x4abc.../portable-context
-```
-For `local-path`, use the agent's filesystem tools to read the directory. For `remote-url`, use HTTP or `interf runs fetch <run-id> --to <path>`.
-## 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. Structured UI controls call the local service directly; this mode is only for freeform planning.
-Use these action types:
-- `compile`
-- `test`
-- `readiness-check-draft`
-- `method-authoring`
-- `method-improvement`
-- `clarification`
-Use `compile` when the user asks to prepare, build, or refresh portable context. Set `method` to the Method id and, if the request named one, `preparation` to the preparation id. CLI equivalent: `interf compile --method`.
-Readiness-check proposals always run against the compiled portable context in 0.15+. The legacy `values.mode` field is gone — omit it from `test` proposals.
-Return this shape:
-```json
-{
-  "action_type": "compile",
-  "method": "method-id",
-  "preparation": "prep-id",
-  "values": { "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 compile --method method-id"
-}
-```
-Use `clarification` only when the request cannot be mapped safely to one Interf action.
-## Reference
-For the full CLI surface and per-command flags, see [`references/cli.md`](./references/cli.md). It is a generated snapshot of `interf <command> --help` and is checked against the built package in the repo test suite. The installed `interf` command remains the source of truth when available.