@interf/compiler 0.9.4 → 0.13.0

package/dist/packages/local-service/client.js

@@ -1,7 +1,29 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { CompileRunCreateRequestSchema, CompileRunListResponseSchema, CompileRunResourceSchema, LocalServiceInstancePointerSchema, LocalJobEventAppendRequestSchema, LocalJobRunCreateRequestSchema, LocalJobRunListResponseSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ReadinessListResponseSchema, TestRunCreateRequestSchema, TestRunListResponseSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
-import { LOCAL_SERVICE_INSTANCE_POINTER_PATH, LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, } from "./routes.js";
+import { CompileRunCreateRequestSchema, CompileRunResourceSchema, ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, ResetRequestSchema, ResetResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, } from "./lib/schema.js";
+import { LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, preparationSubresourcePath, } from "./routes.js";
+import { readActiveConnection } from "./connection-config.js";
+async function connectOrNull(options = {}) {
+    const conn = readActiveConnection({
+        urlOverride: options.url ?? null,
+        authTokenOverride: options.authToken ?? null,
+    });
+    if (!conn)
+        return null;
+    // Probe the engine; we expose the LocalServiceHealth-shaped object the
+    // legacy callers expect so submitCompileRun et al. keep compiling.
+    try {
+        const headers = {};
+        if (conn.auth_token)
+            headers["authorization"] = `Bearer ${conn.auth_token}`;
+        const response = await fetch(`${conn.url.replace(/\/+$/, "")}/health`, { headers });
+        if (response.status !== 200)
+            return null;
+        const health = (await response.json());
+        return { serviceUrl: conn.url, health, authToken: conn.auth_token ?? null };
+    }
+    catch {
+        return null;
+    }
+}
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
@@ -11,26 +33,17 @@ export function configuredLocalServiceUrl() {
         return trimTrailingSlash(explicit);
     return buildLocalServiceUrl();
 }
-function projectLocalServiceUrl(projectPath) {
-    const pointerPath = join(projectPath, ...LOCAL_SERVICE_INSTANCE_POINTER_PATH);
-    if (!existsSync(pointerPath))
-        return null;
-    try {
-        const pointer = LocalServiceInstancePointerSchema.parse(JSON.parse(readFileSync(pointerPath, "utf8")));
-        return trimTrailingSlash(pointer.service_url);
-    }
-    catch {
-        return null;
-    }
-}
-function localServiceUrlCandidates(projectPath) {
-    const explicit = process.env.INTERF_SERVICE_URL?.trim();
+/**
+ * Resolve the bearer token for the active connection. In 0.13 there is
+ * exactly one source of truth: `~/.interf/connection.json` (or the
+ * `INTERF_SERVICE_TOKEN` env override).
+ */
+export function resolveLocalServiceAuthToken() {
+    const explicit = process.env.INTERF_SERVICE_TOKEN?.trim();
     if (explicit)
-        return [trimTrailingSlash(explicit)];
-    return Array.from(new Set([
-        projectLocalServiceUrl(projectPath),
-        buildLocalServiceUrl(),
-    ].filter((value) => Boolean(value))));
+        return explicit;
+    const conn = readActiveConnection();
+    return conn?.auth_token ?? null;
 }
 async function fetchJson(url, options = {}) {
     const controller = new AbortController();
@@ -54,40 +67,35 @@ async function fetchJson(url, options = {}) {
         clearTimeout(timeout);
     }
 }
-function healthMatchesProject(health, projectPath, explicitServiceUrl) {
-    if (explicitServiceUrl)
-        return true;
-    if (!health.control_path)
-        return true;
-    return resolve(health.control_path) === resolve(projectPath);
+/**
+ * Resolve a connection. In 0.13 this is the only path to the engine — read
+ * `~/.interf/connection.json` (written by `interf web`) or honor the
+ * `INTERF_SERVICE_URL` / `INTERF_SERVICE_TOKEN` env overrides.
+ */
+export async function findLocalService(options = {}) {
+    void options.timeoutMs;
+    return connectOrNull();
 }
-export async function findLocalService(options) {
-    const explicitServiceUrl = Boolean(process.env.INTERF_SERVICE_URL?.trim());
-    for (const serviceUrl of localServiceUrlCandidates(options.projectPath)) {
-        try {
-            const health = LocalServiceHealthSchema.parse(await fetchJson(`${serviceUrl}${LOCAL_SERVICE_ROUTES.health}`, {
-                method: "GET",
-                timeoutMs: options.timeoutMs,
-            }));
-            if (!healthMatchesProject(health, options.projectPath, explicitServiceUrl)) {
-                continue;
-            }
-            return { serviceUrl, health };
-        }
-        catch {
-            continue;
-        }
-    }
-    return null;
+function authHeaders(authToken) {
+    return authToken ? { authorization: `Bearer ${authToken}` } : {};
 }
+// ─────────────────────────────────────────────────────────────────────────
+// Preparation-keyed run submission helpers (0.13)
+// ─────────────────────────────────────────────────────────────────────────
 export async function submitCompileRunToLocalService(options) {
-    const connection = await findLocalService({ projectPath: options.projectPath });
+    const connection = await connectOrNull();
     if (!connection)
         return null;
     const request = CompileRunCreateRequestSchema.parse(options.request);
-    const resource = CompileRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.compileRuns}`, {
+    const headers = {
+        ...authHeaders(connection.authToken),
+        ...(options.idempotencyKey ? { "x-interf-idempotency-key": options.idempotencyKey } : {}),
+    };
+    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "compileRuns")}`;
+    const resource = CompileRunResourceSchema.parse(await fetchJson(url, {
         method: "POST",
         body: JSON.stringify(request),
+        headers,
     }));
     return {
         serviceUrl: connection.serviceUrl,
@@ -95,19 +103,82 @@ export async function submitCompileRunToLocalService(options) {
     };
 }
 export async function submitTestRunToLocalService(options) {
-    const connection = await findLocalService({ projectPath: options.projectPath });
+    const connection = await connectOrNull();
     if (!connection)
         return null;
     const request = TestRunCreateRequestSchema.parse(options.request);
-    const resource = TestRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.testRuns}`, {
+    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "testRuns")}`;
+    const resource = TestRunResourceSchema.parse(await fetchJson(url, {
+        method: "POST",
+        body: JSON.stringify(request),
+        headers: authHeaders(connection.authToken),
+    }));
+    return {
+        serviceUrl: connection.serviceUrl,
+        resource,
+    };
+}
+export async function submitResetToLocalService(options) {
+    const connection = await connectOrNull();
+    if (!connection)
+        return null;
+    const request = ResetRequestSchema.parse(options.request);
+    const url = `${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "reset")}`;
+    const result = ResetResultSchema.parse(await fetchJson(url, {
+        method: "POST",
+        body: JSON.stringify(request),
+        headers: authHeaders(connection.authToken),
+    }));
+    return {
+        serviceUrl: connection.serviceUrl,
+        result,
+    };
+}
+export async function createActionProposalInLocalService(options) {
+    const connection = await connectOrNull();
+    if (!connection)
+        return null;
+    const request = ActionProposalCreateRequestSchema.parse(options.request);
+    const resource = ActionProposalResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.actionProposals}`, {
+        method: "POST",
+        body: JSON.stringify(request),
+        headers: authHeaders(connection.authToken),
+    }));
+    return {
+        serviceUrl: connection.serviceUrl,
+        resource,
+    };
+}
+export async function decideActionProposalInLocalService(options) {
+    const connection = options.serviceUrl
+        ? { serviceUrl: options.serviceUrl, authToken: options.authToken ?? resolveLocalServiceAuthToken() }
+        : (await connectOrNull());
+    if (!connection)
+        return null;
+    const request = ActionProposalApprovalRequestSchema.parse(options.request);
+    const resource = ActionProposalResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.actionProposals}/${encodeURIComponent(options.proposalId)}/decision`, {
         method: "POST",
         body: JSON.stringify(request),
+        headers: authHeaders(connection.authToken ?? null),
     }));
     return {
         serviceUrl: connection.serviceUrl,
         resource,
     };
 }
+export async function approveActionProposalInLocalService(options) {
+    const proposal = await createActionProposalInLocalService(options);
+    if (!proposal)
+        return null;
+    if (proposal.resource.status !== "awaiting_approval")
+        return proposal;
+    const decided = await decideActionProposalInLocalService({
+        proposalId: proposal.resource.proposal_id,
+        request: { approved: true },
+        serviceUrl: proposal.serviceUrl,
+    });
+    return decided ?? proposal;
+}
 function isTerminalJobStatus(status) {
     return status === "succeeded" || status === "failed" || status === "cancelled";
 }
@@ -115,85 +186,88 @@ function isTerminalRunStatus(status) {
     return status === "succeeded" || status === "failed" || status === "cancelled";
 }
 export async function getLocalCompileRun(options) {
-    return CompileRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.compileRuns}/${encodeURIComponent(options.runId)}`, {
+    return CompileRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/compile-runs/${encodeURIComponent(options.runId)}`, {
         method: "GET",
         timeoutMs: 2000,
+        headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
     }));
 }
-export async function listLocalCompileRuns(options) {
-    return CompileRunListResponseSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.compileRuns}`, {
-        method: "GET",
-        timeoutMs: options.timeoutMs ?? 2000,
-    }));
-}
-export async function listLocalReadiness(options) {
-    return ReadinessListResponseSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.readiness}`, {
-        method: "GET",
+/**
+ * Ask the local service to cancel a running compile run by id. Resolves
+ * with the typed cancel result on success and throws when the service
+ * returns 404 (unknown run id) or any non-2xx status.
+ */
+export async function cancelLocalCompileRun(options) {
+    const value = await fetchJson(`${options.serviceUrl}/v1/compile-runs/${encodeURIComponent(options.runId)}/cancel`, {
+        method: "POST",
         timeoutMs: options.timeoutMs ?? 2000,
-    }));
+        headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
+    });
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Local service returned an unexpected cancel response.");
+    }
+    const record = value;
+    const cancelled = record.cancelled === true;
+    const reason = typeof record.reason === "string" && record.reason.trim().length > 0
+        ? record.reason.trim()
+        : undefined;
+    return reason ? { cancelled, reason } : { cancelled };
 }
 export async function waitForLocalCompileRun(options) {
-    const pollMs = options.pollMs ?? 1000;
+    // Exponential backoff: start at 250ms (responsive for short runs) and
+    // double up to 4s (don't hammer the local service for long compile
+    // runs). When the caller passes an explicit `pollMs`, honor it as a
+    // fixed interval to keep the previous opt-out path.
+    const explicit = options.pollMs;
+    let delay = explicit ?? 250;
     while (true) {
         const resource = await getLocalCompileRun({
             serviceUrl: options.serviceUrl,
             runId: options.runId,
+            authToken: options.authToken ?? null,
         });
         options.onUpdate?.(resource);
         if (isTerminalRunStatus(resource.run.status))
             return resource;
-        await new Promise((resolveWait) => setTimeout(resolveWait, pollMs));
+        await new Promise((resolveWait) => setTimeout(resolveWait, delay));
+        if (explicit === undefined) {
+            delay = Math.min(delay * 2, 4000);
+        }
     }
 }
 export async function getLocalTestRun(options) {
-    return TestRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.testRuns}/${encodeURIComponent(options.runId)}`, {
+    return TestRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/test-runs/${encodeURIComponent(options.runId)}`, {
         method: "GET",
         timeoutMs: 2000,
-    }));
-}
-export async function listLocalTestRuns(options) {
-    return TestRunListResponseSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.testRuns}`, {
-        method: "GET",
-        timeoutMs: options.timeoutMs ?? 2000,
+        headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
     }));
 }
 export async function waitForLocalTestRun(options) {
-    const pollMs = options.pollMs ?? 1000;
+    // Same exponential backoff as `waitForLocalCompileRun`.
+    const explicit = options.pollMs;
+    let delay = explicit ?? 250;
     while (true) {
         const resource = await getLocalTestRun({
             serviceUrl: options.serviceUrl,
             runId: options.runId,
+            authToken: options.authToken ?? null,
         });
         options.onUpdate?.(resource);
         if (isTerminalRunStatus(resource.status))
             return resource;
-        await new Promise((resolveWait) => setTimeout(resolveWait, pollMs));
+        await new Promise((resolveWait) => setTimeout(resolveWait, delay));
+        if (explicit === undefined) {
+            delay = Math.min(delay * 2, 4000);
+        }
     }
 }
 export async function getLocalJobRun(options) {
-    return LocalJobRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.jobs}/${encodeURIComponent(options.runId)}`, {
+    return LocalJobRunResourceSchema.parse(await fetchJson(`${options.serviceUrl}/v1/jobs/${encodeURIComponent(options.runId)}`, {
         method: "GET",
         timeoutMs: 2000,
+        headers: authHeaders(options.authToken ?? resolveLocalServiceAuthToken()),
     }));
 }
-export async function listLocalJobRuns(options) {
-    return LocalJobRunListResponseSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.jobs}`, {
-        method: "GET",
-        timeoutMs: options.timeoutMs ?? 2000,
-    }));
-}
-export async function readLocalServiceRunSnapshot(options) {
-    const [jobs, compileRuns, testRuns] = await Promise.all([
-        listLocalJobRuns(options),
-        listLocalCompileRuns(options),
-        listLocalTestRuns(options),
-    ]);
-    return {
-        jobs: jobs.jobs,
-        compileRuns: compileRuns.compile_runs,
-        testRuns: testRuns.test_runs,
-    };
-}
 export async function waitForLocalJobRun(options) {
     const startedAt = Date.now();
     const pollMs = options.pollMs ?? 1000;
@@ -201,6 +275,7 @@ export async function waitForLocalJobRun(options) {
         const job = await getLocalJobRun({
             serviceUrl: options.serviceUrl,
             runId: options.runId,
+            authToken: options.authToken ?? null,
         });
         options.onUpdate?.(job);
         if (isTerminalJobStatus(job.status))
@@ -220,13 +295,14 @@ function resultError(job, defaultMessage) {
     return job.error ?? defaultMessage;
 }
 export async function submitReadinessCheckDraftToLocalService(options) {
-    const connection = await findLocalService({ projectPath: options.projectPath });
+    const connection = await connectOrNull();
     if (!connection)
         return null;
     const request = ReadinessCheckDraftCreateRequestSchema.parse(options.request);
-    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.readinessCheckDrafts}`, {
+    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "readinessCheckDrafts")}`, {
         method: "POST",
         body: JSON.stringify(request),
+        headers: authHeaders(connection.authToken),
     }));
     options.onSubmitted?.({
         serviceUrl: connection.serviceUrl,
@@ -235,6 +311,7 @@ export async function submitReadinessCheckDraftToLocalService(options) {
     const job = await waitForLocalJobRun({
         serviceUrl: connection.serviceUrl,
         runId: initialJob.run_id,
+        authToken: connection.authToken,
         onUpdate: options.onUpdate,
     });
     if (job.status !== "succeeded") {
@@ -242,7 +319,7 @@ export async function submitReadinessCheckDraftToLocalService(options) {
             serviceUrl: connection.serviceUrl,
             job,
             result: null,
-            error: resultError(job, "Readiness-check drafting failed in the local Interf service."),
+            error: resultError(job, "Drafting readiness checks failed in the local Interf service."),
         };
     }
     const parsed = ReadinessCheckDraftResultSchema.safeParse(job.result);
@@ -251,7 +328,7 @@ export async function submitReadinessCheckDraftToLocalService(options) {
             serviceUrl: connection.serviceUrl,
             job,
             result: null,
-            error: "Readiness-check drafting finished without a valid result.",
+            error: "Drafting readiness checks finished without a valid result.",
         };
     }
     return {
@@ -261,13 +338,14 @@ export async function submitReadinessCheckDraftToLocalService(options) {
     };
 }
 export async function submitMethodAuthoringRunToLocalService(options) {
-    const connection = await findLocalService({ projectPath: options.projectPath });
+    const connection = await connectOrNull();
     if (!connection)
         return null;
     const request = MethodAuthoringCreateRequestSchema.parse(options.request);
-    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.methodAuthoringRuns}`, {
+    const initialJob = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${preparationSubresourcePath(options.preparationId, "methodAuthoringRuns")}`, {
         method: "POST",
         body: JSON.stringify(request),
+        headers: authHeaders(connection.authToken),
     }));
     options.onSubmitted?.({
         serviceUrl: connection.serviceUrl,
@@ -276,6 +354,7 @@ export async function submitMethodAuthoringRunToLocalService(options) {
     const job = await waitForLocalJobRun({
         serviceUrl: connection.serviceUrl,
         runId: initialJob.run_id,
+        authToken: connection.authToken,
         onUpdate: options.onUpdate,
     });
     if (job.status !== "succeeded") {
@@ -301,56 +380,12 @@ export async function submitMethodAuthoringRunToLocalService(options) {
         result: parsed.data,
     };
 }
-export async function appendLocalJobRunEvent(options) {
-    const connection = await findLocalService({ projectPath: options.projectPath });
-    if (!connection)
-        return null;
-    const event = LocalJobEventAppendRequestSchema.parse(options.event);
-    return LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.jobs}/${encodeURIComponent(options.runId)}/events`, {
-        method: "POST",
-        body: JSON.stringify(event),
-    }));
-}
-export async function startLocalJobRun(options) {
-    const connection = await findLocalService({ projectPath: options.projectPath });
-    if (!connection)
-        return null;
-    const request = LocalJobRunCreateRequestSchema.parse(options.request);
-    const resource = LocalJobRunResourceSchema.parse(await fetchJson(`${connection.serviceUrl}${LOCAL_SERVICE_ROUTES.jobs}`, {
-        method: "POST",
-        body: JSON.stringify(request),
+/**
+ * Fetch the engine instance health/status.
+ */
+export async function getLocalServiceHealth(options) {
+    return LocalServiceHealthSchema.parse(await fetchJson(`${options.serviceUrl}${LOCAL_SERVICE_ROUTES.health}`, {
+        method: "GET",
+        timeoutMs: options.timeoutMs ?? 2000,
     }));
-    const emit = (event) => {
-        void appendLocalJobRunEvent({
-            projectPath: options.projectPath,
-            runId: resource.run_id,
-            event,
-        }).catch(() => { });
-    };
-    return {
-        serviceUrl: connection.serviceUrl,
-        runId: resource.run_id,
-        resource,
-        emit,
-        complete: async (message) => {
-            await appendLocalJobRunEvent({
-                projectPath: options.projectPath,
-                runId: resource.run_id,
-                event: {
-                    type: "job.completed",
-                    ...(message ? { message } : {}),
-                },
-            });
-        },
-        fail: async (message) => {
-            await appendLocalJobRunEvent({
-                projectPath: options.projectPath,
-                runId: resource.run_id,
-                event: {
-                    type: "job.failed",
-                    message,
-                },
-            });
-        },
-    };
 }

package/dist/packages/local-service/connection-config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Single CLI connection record at `~/.interf/connection.json`.
+ *
+ * The CLI is a thin authorized client of one connected instance. Switch by
+ * starting `interf web` (writes a local connection), `interf login` (writes a
+ * remote connection), or by passing `--url` / env vars to override per-call.
+ *
+ * No per-folder pointer files. No registry of multiple connections.
+ */
+import { z } from "zod";
+export declare const ConnectionRecordSchema: z.ZodObject<{
+    url: z.ZodString;
+    auth_token: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ConnectionRecord = z.infer<typeof ConnectionRecordSchema>;
+export declare const INTERF_SERVICE_URL_ENV = "INTERF_SERVICE_URL";
+export declare const INTERF_AUTH_TOKEN_ENV = "INTERF_AUTH_TOKEN";
+/**
+ * Resolve the active connection.
+ *
+ * Order of precedence:
+ *   1. Explicit `urlOverride` argument (e.g. CLI --url flag).
+ *   2. `INTERF_SERVICE_URL` / `INTERF_AUTH_TOKEN` env vars.
+ *   3. `~/.interf/connection.json`.
+ *   4. null — caller must error with the connect-or-error hint.
+ */
+export declare function readActiveConnection(options?: {
+    urlOverride?: string | null;
+    authTokenOverride?: string | null;
+}): ConnectionRecord | null;
+/** Write a new connection record. Overwrites any existing record. */
+export declare function writeConnection(record: ConnectionRecord): void;
+/** Clear the connection record. No-op if missing. */
+export declare function clearConnection(): void;
+/** Ensure `~/.interf/` exists and is a directory. */
+export declare function ensureInterfHome(): void;
+/** Canonical message printed when a CLI command needs a connection but has none. */
+export declare const CONNECT_OR_ERROR_HINT: string;

package/dist/packages/local-service/connection-config.js

@@ -0,0 +1,75 @@
+/**
+ * Single CLI connection record at `~/.interf/connection.json`.
+ *
+ * The CLI is a thin authorized client of one connected instance. Switch by
+ * starting `interf web` (writes a local connection), `interf login` (writes a
+ * remote connection), or by passing `--url` / env vars to override per-call.
+ *
+ * No per-folder pointer files. No registry of multiple connections.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { connectionConfigPath, interfHomeRoot } from "./instance-paths.js";
+export const ConnectionRecordSchema = z.object({
+    url: z.string().url(),
+    /** Bearer token for non-loopback connections. Null for loopback. */
+    auth_token: z.string().min(1).nullable().default(null),
+}).strict();
+export const INTERF_SERVICE_URL_ENV = "INTERF_SERVICE_URL";
+export const INTERF_AUTH_TOKEN_ENV = "INTERF_AUTH_TOKEN";
+/**
+ * Resolve the active connection.
+ *
+ * Order of precedence:
+ *   1. Explicit `urlOverride` argument (e.g. CLI --url flag).
+ *   2. `INTERF_SERVICE_URL` / `INTERF_AUTH_TOKEN` env vars.
+ *   3. `~/.interf/connection.json`.
+ *   4. null — caller must error with the connect-or-error hint.
+ */
+export function readActiveConnection(options = {}) {
+    const overrideUrl = options.urlOverride?.trim();
+    if (overrideUrl) {
+        return ConnectionRecordSchema.parse({
+            url: overrideUrl,
+            auth_token: options.authTokenOverride?.trim() || null,
+        });
+    }
+    const envUrl = process.env[INTERF_SERVICE_URL_ENV]?.trim();
+    if (envUrl) {
+        return ConnectionRecordSchema.parse({
+            url: envUrl,
+            auth_token: process.env[INTERF_AUTH_TOKEN_ENV]?.trim() || null,
+        });
+    }
+    const configPath = connectionConfigPath();
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const raw = readFileSync(configPath, "utf8");
+        return ConnectionRecordSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+/** Write a new connection record. Overwrites any existing record. */
+export function writeConnection(record) {
+    const validated = ConnectionRecordSchema.parse(record);
+    const configPath = connectionConfigPath();
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(validated, null, 2)}\n`);
+}
+/** Clear the connection record. No-op if missing. */
+export function clearConnection() {
+    const configPath = connectionConfigPath();
+    if (existsSync(configPath))
+        rmSync(configPath, { force: true });
+}
+/** Ensure `~/.interf/` exists and is a directory. */
+export function ensureInterfHome() {
+    mkdirSync(interfHomeRoot(), { recursive: true });
+}
+/** Canonical message printed when a CLI command needs a connection but has none. */
+export const CONNECT_OR_ERROR_HINT = "Not connected to any Interf instance.\n" +
+    "Start one with `interf web`, or set --url / `interf login` for a remote one.";

package/dist/packages/local-service/index.d.ts

@@ -1,15 +1,22 @@
 export * as schema from "./lib/schema.js";
 export * as actionValues from "./action-values.js";
+export * as actionDefinitions from "./action-definitions.js";
 export * as routes from "./routes.js";
 export * as client from "./client.js";
 export * as runtime from "./runtime.js";
 export * as server from "./server.js";
-export type { CompileRunCreateRequest, CompileRunResource, CompileRunSummary, LocalServiceDiscovery, PortableContextMapping, PreparationReadinessState, PreparationRunLinkage, PreparationResource, MethodResource, LocalJobAgent, LocalJobEvent, LocalJobEventAppendRequest, LocalJobEventType, LocalJobRunCreateRequest, LocalJobRunListResponse, LocalJobRunResource, LocalJobStatus, LocalRunHandlerResult, LocalJobStep, LocalJobType, LocalServiceConfig, LocalServiceHealth, LocalServiceInstancePointer, LocalServiceResource, LocalExecutorStatus, ActionProposalApproval, ActionProposalApprovalRequest, ActionProposalCreateRequest, ActionProposalListResponse, ActionProposalPlan, ActionProposalResource, ActionProposalStatus, ActionProposalType, PreparationSetupCreateRequest, PortableContextResource, ReadinessListResponse, ReadinessResource, SourceFileResource, WorkspaceFileResource, ReadinessCheckDraftCreateRequest, ReadinessCheckDraftResult, TestRunCreateRequest, TestRunResource, TestRunStatus, RunCreateRequest, RunObservabilityListResponse, RunObservabilityResource, MethodAuthoringCreateRequest, MethodAuthoringResult, PreparationListResponse, MethodListResponse, CompileRunListResponse, TestRunListResponse, PortableContextListResponse, SourceFileListResponse, WorkspaceFileListResponse, OpenPathRequest, OpenPathResponse, } from "./lib/schema.js";
-export { CompileRunCreateRequestSchema, CompileRunResourceSchema, CompileRunSummarySchema, LocalServiceDiscoverySchema, PortableContextMappingSchema, PreparationReadinessStateSchema, PreparationRunLinkageSchema, PreparationResourceSchema, MethodResourceSchema, LocalJobAgentSchema, LocalJobEventAppendRequestSchema, LocalJobEventSchema, LocalJobEventTypeSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, LocalJobStatusSchema, LocalRunHandlerResultSchema, LocalJobStepSchema, LocalJobTypeSchema, LocalServiceConfigSchema, LocalServiceHealthSchema, LocalServiceInstancePointerSchema, LocalServiceResourceSchema, PortableContextResourceSchema, ReadinessResourceSchema, SourceFileResourceSchema, WorkspaceFileResourceSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, TestRunStatusSchema, RunCreateRequestSchema, RunObservabilityResourceSchema, RunObservabilityListResponseSchema, LocalExecutorStatusSchema, ActionProposalApprovalRequestSchema, ActionProposalApprovalSchema, ActionProposalCreateRequestSchema, ActionProposalListResponseSchema, ActionProposalPlanSchema, ActionProposalResourceSchema, ActionProposalStatusSchema, ActionProposalTypeSchema, PreparationSetupCreateRequestSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, PreparationListResponseSchema, MethodListResponseSchema, CompileRunListResponseSchema, LocalJobRunListResponseSchema, TestRunListResponseSchema, PortableContextListResponseSchema, ReadinessListResponseSchema, SourceFileListResponseSchema, WorkspaceFileListResponseSchema, OpenPathRequestSchema, OpenPathResponseSchema, } from "./lib/schema.js";
-export { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, LOCAL_SERVICE_INSTANCE_POINTER_PATH, LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, } from "./routes.js";
-export type { LocalServiceJobSubmission, LocalServiceJobSubmitted, LocalServiceConnection, LocalServiceRunSnapshot, LocalJobTracker, } from "./client.js";
-export { appendLocalJobRunEvent, configuredLocalServiceUrl, findLocalService, getLocalJobRun, getLocalCompileRun, getLocalTestRun, listLocalCompileRuns, listLocalJobRuns, listLocalTestRuns, readLocalServiceRunSnapshot, startLocalJobRun, submitCompileRunToLocalService, submitReadinessCheckDraftToLocalService, submitTestRunToLocalService, submitMethodAuthoringRunToLocalService, waitForLocalJobRun, waitForLocalCompileRun, waitForLocalTestRun, } from "./client.js";
-export type { LocalServiceActionPlanningContext, LocalServiceCompileRunContext, LocalServiceJobRunContext, LocalServiceRunHandlers, LocalServiceRuntimeOptions, LocalServiceTestRunContext, } from "./runtime.js";
+export type { CompileRunCreateRequest, CompileRunResource, CompileRunSummary, LocalServiceDiscovery, PortableContextMapping, PreparationRunLinkage, PreparationResource, MethodResource, LocalJobAgent, LocalJobEvent, LocalJobEventAppendRequest, LocalJobEventType, LocalJobRunCreateRequest, LocalJobRunResource, LocalJobStatus, LocalRunHandlerResult, LocalJobStep, LocalJobType, LocalServiceConfig, LocalServiceError, LocalServiceHealth, LocalExecutorStatus, ActionClientOrigin, ActionProposalApproval, ActionProposalApprovalRequest, ActionProposalCreateRequest, ActionProposalListResponse, ActionProposalPlan, ActionProposalPlanActionType, ActionProposalResource, ActionProposalStatus, ActionProposalType, MethodChangeResult, PreparationChangeResult, PreparationSetupResult, ResetRequest, ResetResult, PortableContextResource, ReadinessResource, SourceFileResource, ReadinessCheckDraftCreateRequest, ReadinessCheckDraftResult, TestRunCreateRequest, TestRunResource, TestRunStatus, RunObservabilityListResponse, RunObservabilityResource, MethodAuthoringCreateRequest, MethodAuthoringResult, PreparationListResponse, MethodListResponse, PortableContextListResponse, SourceFileListResponse, OpenPathRequest, OpenPathResponse, WorkspaceFileResource, } from "./lib/schema.js";
+export { CompileRunCreateRequestSchema, CompileRunResourceSchema, CompileRunSummarySchema, LocalServiceDiscoverySchema, PortableContextMappingSchema, PreparationRunLinkageSchema, PreparationResourceSchema, MethodResourceSchema, LocalJobAgentSchema, LocalJobEventAppendRequestSchema, LocalJobEventSchema, LocalJobEventTypeSchema, LocalJobRunCreateRequestSchema, LocalJobRunResourceSchema, LocalJobStatusSchema, LocalRunHandlerResultSchema, LocalJobStepSchema, LocalJobTypeSchema, LocalServiceConfigSchema, LocalServiceErrorSchema, LocalServiceHealthSchema, PortableContextResourceSchema, ReadinessResourceSchema, SourceFileResourceSchema, ReadinessCheckDraftCreateRequestSchema, ReadinessCheckDraftResultSchema, TestRunCreateRequestSchema, TestRunResourceSchema, TestRunStatusSchema, RunObservabilityResourceSchema, RunObservabilityListResponseSchema, LocalExecutorStatusSchema, ActionClientOriginSchema, ActionProposalApprovalRequestSchema, ActionProposalApprovalSchema, ActionProposalCreateRequestSchema, ActionProposalListResponseSchema, ActionProposalPlanSchema, ActionProposalPlanActionTypeSchema, ActionProposalResourceSchema, ActionProposalStatusSchema, ActionProposalTypeSchema, ResetRequestSchema, ResetResultSchema, MethodAuthoringCreateRequestSchema, MethodAuthoringResultSchema, PreparationListResponseSchema, MethodListResponseSchema, PortableContextListResponseSchema, SourceFileListResponseSchema, OpenPathRequestSchema, OpenPathResponseSchema, } from "./lib/schema.js";
+export { LOCAL_SERVICE_DEFAULT_HOST, LOCAL_SERVICE_DEFAULT_PORT, LOCAL_SERVICE_ROUTES, buildLocalServiceUrl, } from "./routes.js";
+export type { ServiceRegistry, ServiceRegistryEntry, ServiceRegistryWorkspace, } from "./lib/schema.js";
+export { ServiceRegistrySchema, ServiceRegistryEntrySchema, ServiceRegistryWorkspaceSchema, } from "./lib/schema.js";
+export { readServiceRegistry, registerServiceLocally, unregisterService, writeServiceRegistry, serviceRegistryPath, } from "./service-registry.js";
+export type { LocalServiceJobSubmission, LocalServiceJobSubmitted, LocalServiceConnection, } from "./client.js";
+export type { LocalCompileRunCancelResult, } from "./client.js";
+export { approveActionProposalInLocalService, cancelLocalCompileRun, configuredLocalServiceUrl, resolveLocalServiceAuthToken, createActionProposalInLocalService, decideActionProposalInLocalService, findLocalService, getLocalJobRun, getLocalCompileRun, getLocalServiceHealth, getLocalTestRun, submitCompileRunToLocalService, submitReadinessCheckDraftToLocalService, submitResetToLocalService, submitTestRunToLocalService, submitMethodAuthoringRunToLocalService, waitForLocalJobRun, waitForLocalCompileRun, waitForLocalTestRun, } from "./client.js";
+export type { LocalServiceActionPlanningContext, LocalServiceCompileRunContext, LocalServiceJobRunContext, LocalServiceRunHandlers, LocalServiceRuntimeOptions, LocalServiceTestRunContext, PreparationContext, } from "./runtime.js";
 export { LocalServiceRuntime, createLocalServiceRuntime, } from "./runtime.js";
 export type { StartedLocalService, StartLocalServiceOptions, } from "./server.js";
-export { createLocalServiceServer, startLocalService, } from "./server.js";
+export { createLocalServiceServer, createLocalServiceAuthToken, startLocalService, } from "./server.js";
+export type { NativeLocalServiceRunHandlerOptions, } from "./native-run-handlers.js";
+export { createNativeLocalServiceRunHandlers, } from "./native-run-handlers.js";