@interf/compiler 0.22.0 → 0.33.0

package/README.md

@@ -0,0 +1,268 @@
+# Interf
+
+**Interf prepares data for agents.**
+
+This npm package ships the `interf` CLI and local Interf runtime for building
+task-specific Context Graphs from files.
+
+Agents miss things in files. When agents answer from a folder, they first have
+to discover what is in it, decide what matters, extract evidence, and connect
+facts across files. That file-to-context step is hidden, inconsistent, and hard
+to inspect.
+
+Interf separates that step. It makes users' agents build a Context Graph from
+their files. It has source coverage summaries, task-aware knowledge, artifact
+handoffs, and links back to sources. Your agent uses the prepared map instead
+of rediscovering the files during the task.
+
+```text
+Source files                        Context Graph agents use
+
+bristol-office-market/              <context-graph>/
+  q4-market-report.pdf                AGENTS.md
+  lease-comps.xlsx                    home.md
+  planning-notes.md                   summaries/
+  exports/availability.csv            knowledge/
+                                      artifacts/
+                                      traces/
+```
+
+## What a Build Produces
+
+A Build produces a Context Graph. The Context Graph is source-backed context
+built from files so agents can use prepared context instead of partial file
+reads.
+
+For a local Build, the Context Graph is an inspectable folder:
+
+```text
+<context-graph>/
+  AGENTS.md              # agent guidance
+  home.md                # overview and routes
+  artifacts/             # task-specific agent handoffs
+  summaries/             # source coverage proof
+  knowledge/             # navigation and drilldown
+  traces/                # links back to sources
+```
+
+The output is not an answer. It is a prepared map over the Source: artifact
+handoffs, summaries, knowledge notes, and links back to sources. The Source
+remains the ground truth. Agents start from `artifacts/`, use `summaries/` for
+coverage proof and `knowledge/` for drilldown, then follow source links when
+exact wording, table values, chart reads, or provenance-sensitive claims matter.
+
+## Design Choices
+
+- `Project-scoped`: every Project starts from a specific Source and selected
+  Build Plan, not a generic index over every file.
+- `Inspectable`: Interf records what was built, which requested Artifacts exist,
+  and where source-backed traces live.
+- `Local-first`: local Builds keep Source files on your machine and read-only.
+- `Bring your own agent`: use Claude Code, Codex, or another registered
+  command-line agent.
+- `File over hidden index`: local Builds expose the Context Graph as a folder
+  agents can inspect.
+- `Context Checks you control`: every Build can be checked against
+  plain-English conditions such as "Every page is covered" or "Every figure
+  cites a source page."
+
+## Why Not Just Ask Your Agent?
+
+You can. Interf can use Claude Code, Codex, or another registered local agent
+while it builds the Context Graph.
+
+A one-off preprocessing prompt gives you another answer to trust. Interf puts
+the preparation step inside a Build Plan you can inspect: requested Artifacts,
+declared stages, Build evidence, Context Checks, and traces.
+
+The agent can still execute the stages. Interf shows what was covered, what was
+produced, and whether the Context Graph is ready for the task.
+
+## Install
+
+```bash
+npm install -g @interf/compiler
+interf            # opens the wizard
+```
+
+Requires Node.js 20+ and a local agent CLI such as Claude Code, Codex, or
+another registered command-line agent. Run `interf doctor --live` if the
+executor is not detected.
+
+## Quick Start
+
+```bash
+# terminal 1: start the local Interf runtime
+interf runtime
+
+# terminal 2: create a Project from a local Source
+interf project create bristol --source ./bristol-office-market
+
+# draft the Build Plan for review
+interf plan draft bristol \
+  --intent "Bristol annual take-up and availability chart lookup" \
+  --artifacts "Guide to the report; annual take-up figures with source references" \
+  --ready-when "Every page is listed and every figure has a source reference."
+
+# select the reviewed Build Plan
+interf plan select bristol <build-plan-id>
+
+# build the Context Graph
+interf build bristol
+
+# optional: benchmark/evaluate answers from the Source baseline, Context Graph, or both
+interf benchmark bristol
+```
+
+`interf runtime` starts the local runtime in the foreground and writes the
+active connection record so subsequent CLI commands can connect. Agents can use
+`interf runtime start` for an explicit managed background runtime, then
+`interf runtime stop` when their task is done.
+
+Mutating commands never implicitly auto-start a runtime. If no instance is
+connected, they exit with a hint pointing at `interf runtime`,
+`interf runtime start`, or `interf login`.
+
+`interf build` returns the Context Graph locator on success. For local Builds,
+that locator points to a folder agents can inspect and continue from. There is
+no `--out` flag and no implicit copy of your Source folder.
+
+## Context Graph
+
+The Context Graph is the output Interf builds from your files for agents. It is
+a knowledge map over the Source, not a replacement for the Source.
+
+It gives agents structure and source-backed routes for navigating files. For
+the built-in `interf-default`, it includes:
+
+```text
+<context-graph>/
+  AGENTS.md       # agent-facing guidance and source-checking rules
+  CLAUDE.md       # same guidance for Claude Code
+  home.md         # graph index
+  artifacts/      # task-specific handoffs for agents
+  summaries/      # one source-named folder per source file
+  knowledge/      # linked notes built from summaries and source refs
+  traces/         # source provenance for claims and checks
+```
+
+The source files stay the source of truth. Interf writes generated state inside
+the instance data directory and does not modify the Source.
+
+`AGENTS.md` tells agents how to use the Context Graph: start from the prepared
+outputs, follow the prepared routes, and use the recorded source references
+when exact source evidence matters.
+
+## Build Plans
+
+A Build Plan tells Interf how to build requested Artifacts from your Source for
+the agent task. It also states the Context Checks the user can review before the
+Build.
+
+The built-in `interf-default` Build Plan ships with `interf`. Save your own
+local Build Plan with `interf plan save <path>`; draft new ones with
+`interf plan draft <project-id>`.
+
+```text
+<build-plan-folder>/
+  build-plan.json         # Build Plan definition: artifacts, stages, build rules
+  build-plan.schema.json  # output contract: required Context Graph files/folders
+  README.md               # what this Build Plan is for
+  build/
+    stages/
+      summarize/          # stage instructions Interf runs during the Build
+      structure/
+      shape/
+  use/
+    query/                # how agents read the Context Graph
+  improve/                # how Interf revises the plan if checks still fail
+```
+
+- `build-plan.json` is the technical filename for the Build Plan definition:
+  requested Artifacts, stages, and how the files should be built.
+- `build-plan.schema.json` describes the output contract: what the Context Graph
+  must contain.
+- `build/stages/<stage>/` is where you author one folder per stage.
+- `use/query/` holds the instructions agents follow when they read the Context
+  Graph for the task.
+- `improve/` holds the instructions Interf follows when the first Build misses
+  and the Build Plan itself needs editing.
+
+## Build Plan Improvement
+
+When the first Build is `not ready`, Interf can edit the Build Plan and build
+again. Same Source, same checks, improved Build Plan and Context Graph.
+
+```bash
+interf plan improve <project-id>
+```
+
+Interf records Build Plan improvement as a Run with the revised Build Plan,
+Build evidence, and resulting Context Graph.
+
+## Context Checks And Benchmarks
+
+Context Checks are plain-English promises the user reviews before a Build.
+Requested Artifacts back those checks.
+
+Examples:
+
+- every file in scope was processed
+- required pages or slides were inventoried
+- required outputs exist
+- every figure cites a source page
+- the Source has not changed since the Build
+
+Benchmarks are different. A benchmark asks saved questions and measures answer
+accuracy against an agent source-access baseline, the Context Graph, or both.
+
+```bash
+interf benchmark bristol
+interf benchmark bristol --target source-files
+interf benchmark bristol --target context-graph
+```
+
+`interf benchmark` is optional evaluation. It is not the main readiness surface.
+
+## What Interf Is Not
+
+- Not a second brain or memory product. One Project starts from one Source and
+  agent task.
+- Not a vector store or hosted RAG server. The Context Graph is structured
+  source-backed context agents can inspect.
+- Not a hosted data platform by default. Local Builds run on your machine.
+- Not a generic agent task orchestrator. Interf prepares files into Context
+  Graphs for agents.
+
+## Useful Commands
+
+- `interf` / `interf init` - open the interactive wizard.
+- `interf runtime` - run the local Interf runtime in the foreground.
+- `interf runtime start` - start a managed background local runtime.
+- `interf runtime stop` - stop the running local runtime.
+- `interf project ls / create / show / rm` - manage Projects.
+- `interf plan list / show / save / draft / select / improve` - manage Build
+  Plans.
+- `interf build <project-id>` - Build the Context Graph for a Project.
+- `interf graphs ls --project <id>` / `show <graph-id> --project <id>` - inspect
+  Context Graphs.
+- `interf traces ls --project <id>` / `show <trace-kind> --project <id>` -
+  inspect Context Graph traces.
+- `interf runs ls --project <id>` / `status <run-id>` - inspect Runs.
+- `interf benchmark <project-id>` - run an optional benchmark/evaluation pass.
+- `interf agents ls / use / register / unregister / map / unmap` - configure
+  local agents and role mapping.
+- `interf login / logout` - connect the CLI to another Interf instance.
+- `interf status` - show the active connection and Project summary.
+- `interf doctor --live` - check the local executor before a Build.
+
+## Public Assets
+
+- [skills/interf](./skills/interf/) - bundled agent Skill for Interf.
+- [build-plans/interf-default](./build-plans/interf-default/) - default Build
+  Plan that ships with `interf`.
+
+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/dist/bin-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin-mcp.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { startInterfMcpServer, } from "./cli/commands/mcp.js";
+function readOptionValue(argv, index, flag) {
+    const current = argv[index];
+    const inlinePrefix = `${flag}=`;
+    if (current?.startsWith(inlinePrefix)) {
+        return { value: current.slice(inlinePrefix.length), nextIndex: index };
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`Missing value for ${flag}.`);
+    }
+    return { value, nextIndex: index + 1 };
+}
+function parseArgs(argv) {
+    const args = { profile: "app", transport: "stdio" };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h") {
+            process.stderr.write("usage: interf-mcp [--url <url>] [--token <token>]\n");
+            process.exit(0);
+        }
+        if (arg === "--profile" || arg?.startsWith("--profile=")) {
+            const parsed = readOptionValue(argv, index, "--profile");
+            if (parsed.value !== "app" && parsed.value !== "headless") {
+                throw new Error("--profile must be app or headless.");
+            }
+            args.profile = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--transport" || arg?.startsWith("--transport=")) {
+            const parsed = readOptionValue(argv, index, "--transport");
+            if (parsed.value !== "stdio") {
+                throw new Error("Only stdio transport is supported by the local Interf MCP server.");
+            }
+            args.transport = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--url" || arg?.startsWith("--url=")) {
+            const parsed = readOptionValue(argv, index, "--url");
+            args.url = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--token" || arg?.startsWith("--token=")) {
+            const parsed = readOptionValue(argv, index, "--token");
+            args.token = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        throw new Error(`Unknown MCP server option: ${arg ?? ""}`);
+    }
+    return args;
+}
+try {
+    await startInterfMcpServer(parseArgs(process.argv.slice(2)));
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}

package/dist/bin-runtime.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin-runtime.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { runRuntimeForeground, runRuntimeStatus, } from "./cli/commands/runtime.js";
+import { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, } from "./packages/runtime/service/routes.js";
+function optionValue(argv, index, flag) {
+    const current = argv[index];
+    const inlinePrefix = `${flag}=`;
+    if (current?.startsWith(inlinePrefix)) {
+        return { value: current.slice(inlinePrefix.length), nextIndex: index };
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`Missing value for ${flag}.`);
+    }
+    return { value, nextIndex: index + 1 };
+}
+function parseNumber(raw, flag) {
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${flag} must be a positive integer.`);
+    }
+    return value;
+}
+function parseForegroundArgs(argv) {
+    const args = {
+        host: LOCAL_SERVICE_DEFAULT_HOST,
+        port: LOCAL_SERVICE_DEFAULT_PORT,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h") {
+            process.stderr.write("usage: interf-runtime [--host <host>] [--port <port>] [--app-owned] [--parent-pid <pid>]\n");
+            process.exit(0);
+        }
+        if (arg === "--host" || arg?.startsWith("--host=")) {
+            const parsed = optionValue(argv, index, "--host");
+            args.host = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--port" || arg?.startsWith("--port=")) {
+            const parsed = optionValue(argv, index, "--port");
+            args.port = parseNumber(parsed.value, "--port");
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--app-owned") {
+            args.appOwned = true;
+            continue;
+        }
+        if (arg === "--parent-pid" || arg?.startsWith("--parent-pid=")) {
+            const parsed = optionValue(argv, index, "--parent-pid");
+            args.parentPid = parseNumber(parsed.value, "--parent-pid");
+            index = parsed.nextIndex;
+            continue;
+        }
+        throw new Error(`Unknown runtime option: ${arg ?? ""}`);
+    }
+    return args;
+}
+function parseStatusArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h") {
+            process.stderr.write("usage: interf-runtime status [--url <url>] [--token <token>] [--require-owner-kind <kind>] [--require-owner-pid <pid>]\n");
+            process.exit(0);
+        }
+        if (arg === "--url" || arg?.startsWith("--url=")) {
+            const parsed = optionValue(argv, index, "--url");
+            args.url = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--token" || arg?.startsWith("--token=")) {
+            const parsed = optionValue(argv, index, "--token");
+            args.token = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--require-owner-kind" || arg?.startsWith("--require-owner-kind=")) {
+            const parsed = optionValue(argv, index, "--require-owner-kind");
+            if (parsed.value !== "desktop-app" && parsed.value !== "headless") {
+                throw new Error("--require-owner-kind must be desktop-app or headless.");
+            }
+            args.requireOwnerKind = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (arg === "--require-owner-pid" || arg?.startsWith("--require-owner-pid=")) {
+            const parsed = optionValue(argv, index, "--require-owner-pid");
+            args.requireOwnerPid = parseNumber(parsed.value, "--require-owner-pid");
+            index = parsed.nextIndex;
+            continue;
+        }
+        throw new Error(`Unknown runtime status option: ${arg ?? ""}`);
+    }
+    return args;
+}
+try {
+    const [subcommand, ...rest] = process.argv.slice(2);
+    if (subcommand === "status") {
+        await runRuntimeStatus(parseStatusArgs(rest));
+    }
+    else {
+        await runRuntimeForeground(parseForegroundArgs(process.argv.slice(2)));
+    }
+}
+catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}

package/dist/cli/commands/agents.js

@@ -1,5 +1,5 @@
 /**
- * `interf agents` — manage connected agents + role mapping.
+ * `interf agents` — manage execution agents + role mapping.
  *
  *   interf agents ls                                # list registered + detected
  *   interf agents use <name>                        # set active agent
@@ -12,7 +12,7 @@
  * `~/.interf/agents.json` directly — the service is the source of truth.
  */
 import chalk from "chalk";
-import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/runtime/connection-config.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -62,7 +62,7 @@ function printRegistry(registry) {
         return;
     }
     console.log();
-    console.log(chalk.bold("  Connected agents"));
+    console.log(chalk.bold("  Execution agents"));
     for (const agent of registry.agents) {
         console.log(formatAgentLine(agent, registry));
     }
@@ -77,7 +77,7 @@ function printRegistry(registry) {
 }
 export const agentsCommand = {
     command: "agents <subcommand>",
-    describe: "Manage connected agents and role mapping",
+    describe: "Manage execution agents and role mapping",
     builder: (yargs) => yargs
         .option("url", { type: "string", describe: "Override the active connection URL" })
         .option("token", { type: "string", describe: "Override the active bearer token" })

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

@@ -0,0 +1,20 @@
+import type { CommandModule } from "yargs";
+/**
+ * `interf auth` — local user session for the service.
+ *
+ * `login` drives WorkOS AuthKit PKCE in the browser: spawns a loopback
+ * callback server, asks AuthKit for an authorize URL, opens the browser,
+ * exchanges the returned code for tokens, persists the refresh token in
+ * the system keychain, and writes `~/.interf/auth/session.json` so the
+ * service reads the identity on boot.
+ *
+ * `--dev-stub <email>` keeps the local-only fast path for CI / tests /
+ * pre-WorkOS-configuration developer machines. It writes a `local_<email>`
+ * session straight to disk without any network hop.
+ *
+ * The plan tier comes from the cloud control plane (`GET /v1/me`) in a
+ * follow-up; today every fresh PKCE login lands as `free` and the
+ * entitlements gate on local quotas. The dev stub takes `--plan` so
+ * tests can simulate Pro.
+ */
+export declare const authCommand: CommandModule;

package/dist/cli/commands/auth.js

@@ -0,0 +1,161 @@
+import chalk from "chalk";
+import { clearSession, readSession, writeSession, } from "../../packages/runtime/auth/session-store.js";
+import { entitlementsForPlan } from "../../packages/runtime/auth/account-context.js";
+import { defaultPkceTransport, runPkceFlow, AuthFlowError, } from "../../packages/runtime/auth/auth-flow.js";
+import { deleteRefreshToken, setRefreshToken, } from "../../packages/runtime/auth/keychain.js";
+import { WorkOSConfigError } from "../../packages/runtime/auth/workos-client.js";
+/**
+ * `interf auth` — local user session for the service.
+ *
+ * `login` drives WorkOS AuthKit PKCE in the browser: spawns a loopback
+ * callback server, asks AuthKit for an authorize URL, opens the browser,
+ * exchanges the returned code for tokens, persists the refresh token in
+ * the system keychain, and writes `~/.interf/auth/session.json` so the
+ * service reads the identity on boot.
+ *
+ * `--dev-stub <email>` keeps the local-only fast path for CI / tests /
+ * pre-WorkOS-configuration developer machines. It writes a `local_<email>`
+ * session straight to disk without any network hop.
+ *
+ * The plan tier comes from the cloud control plane (`GET /v1/me`) in a
+ * follow-up; today every fresh PKCE login lands as `free` and the
+ * entitlements gate on local quotas. The dev stub takes `--plan` so
+ * tests can simulate Pro.
+ */
+export const authCommand = {
+    command: "auth <action>",
+    describe: "Manage Interf account session (login / logout / whoami)",
+    builder: (y) => y
+        .positional("action", {
+        type: "string",
+        choices: ["login", "logout", "whoami"],
+        demandOption: true,
+        describe: "auth action",
+    })
+        .option("dev-stub", {
+        type: "string",
+        describe: "Skip PKCE and write a local-only session for <email>",
+    })
+        .option("plan", {
+        type: "string",
+        choices: ["free", "pro", "enterprise"],
+        default: "free",
+        describe: "Tier to associate with --dev-stub sessions (dev only)",
+    })
+        .option("no-browser", {
+        type: "boolean",
+        default: false,
+        describe: "Print the AuthKit URL instead of opening the browser",
+    })
+        .option("login-hint", {
+        type: "string",
+        describe: "Prefill the AuthKit email field",
+    }),
+    handler: async (args) => {
+        const action = args.action;
+        if (action === "whoami") {
+            await handleWhoami();
+            return;
+        }
+        if (action === "logout") {
+            await handleLogout();
+            return;
+        }
+        if (action === "login") {
+            await handleLogin(args);
+            return;
+        }
+    },
+};
+async function handleWhoami() {
+    const session = readSession();
+    if (!session) {
+        console.log(chalk.dim("Not signed in. Run `interf auth login`."));
+        return;
+    }
+    console.log(chalk.bold(session.email));
+    console.log(chalk.dim(`  user_id: ${session.user_id}`));
+    console.log(chalk.dim(`  plan:    ${session.plan}`));
+    const cap = session.entitlements.max_active_projects;
+    console.log(chalk.dim(`  project cap: ${Number.isFinite(cap) ? cap : "unlimited"}`));
+    console.log(chalk.dim(`  refreshed_at: ${session.refreshed_at}`));
+}
+async function handleLogout() {
+    const session = readSession();
+    if (session) {
+        try {
+            await deleteRefreshToken(session.user_id);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(chalk.yellow(`  Warning: could not clear keychain entry (${message}).`));
+        }
+    }
+    clearSession();
+    console.log(chalk.green("Signed out. Session cleared."));
+}
+async function handleLogin(args) {
+    const devStubEmail = args["dev-stub"];
+    if (devStubEmail) {
+        writeStubSession(devStubEmail, args.plan ?? "free");
+        return;
+    }
+    try {
+        const result = await runPkceFlow(defaultPkceTransport(), {
+            autoOpenBrowser: !args["no-browser"],
+            ...(args["login-hint"] ? { loginHint: args["login-hint"] } : {}),
+        });
+        try {
+            await setRefreshToken(result.user.id, result.refreshToken);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(chalk.yellow(`  Warning: could not persist refresh token (${message}). ` +
+                "You may need to re-run `interf auth login` after the next service restart."));
+        }
+        const refreshedAt = new Date().toISOString();
+        const plan = "free";
+        const displayName = [result.user.firstName, result.user.lastName]
+            .filter((part) => typeof part === "string" && part.length > 0)
+            .join(" ") || null;
+        writeSession({
+            user_id: result.user.id,
+            email: result.user.email,
+            display_name: displayName,
+            plan,
+            entitlements: entitlementsForPlan(plan),
+            refreshed_at: refreshedAt,
+        });
+        console.log(chalk.green(`Signed in as ${result.user.email}.`));
+        console.log(chalk.dim("  Session written to ~/.interf/auth/session.json."));
+        console.log(chalk.dim("  Restart `interf runtime` to pick up the new account context."));
+        return;
+    }
+    catch (error) {
+        if (error instanceof WorkOSConfigError) {
+            console.error(chalk.red(error.message));
+            process.exit(2);
+        }
+        if (error instanceof AuthFlowError) {
+            console.error(chalk.red(`Sign-in failed: ${error.message}`));
+            process.exit(1);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Sign-in failed: ${message}`));
+        process.exit(1);
+    }
+}
+function writeStubSession(email, plan) {
+    const refreshedAt = new Date().toISOString();
+    writeSession({
+        user_id: `local_${email.replace(/[^a-zA-Z0-9_-]/g, "_")}`,
+        email,
+        display_name: email.split("@")[0] ?? null,
+        plan,
+        entitlements: entitlementsForPlan(plan),
+        refreshed_at: refreshedAt,
+    });
+    console.log(chalk.green(`Signed in as ${email} (${plan}) [dev stub].`));
+    console.log(chalk.dim("  Local session written to ~/.interf/auth/session.json."));
+    console.log(chalk.dim("  No network hop; this bypass is for CI / local testing only."));
+}

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

@@ -0,0 +1,10 @@
+import type { CommandModule } from "yargs";
+type BenchmarkTarget = "context-graph" | "source-files" | "both";
+interface BenchmarkArgs {
+    projectId: string;
+    target?: BenchmarkTarget;
+    url?: string;
+    token?: string;
+}
+export declare const benchmarkCommand: CommandModule<unknown, BenchmarkArgs>;
+export {};