@devfn/config 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @devfn/config
+
+Validated DevFn project manifests and organization port-policy contracts. Every manifest can declare lifecycle commands and must be reviewed and explicitly trusted before the DevFn CLI loads its exact digest; executable manifests additionally must be self-contained.

package/dist/discovery.d.ts

@@ -0,0 +1,3 @@
+import type { DetectionFinding, DevFnConfig, DiscoveryResult } from "./types.js";
+export declare function discoverProject(root?: string): Promise<DiscoveryResult>;
+export declare function renderDevFnConfig(config: DevFnConfig, findings: readonly DetectionFinding[]): string;

package/dist/discovery.js

@@ -0,0 +1,99 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project";
+}
+async function readPackage(root) {
+    try {
+        return JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function discoverProject(root = process.cwd()) {
+    const resolvedRoot = path.resolve(root);
+    const findings = [];
+    const processes = {};
+    const packageJson = await readPackage(resolvedRoot);
+    const baseName = path.basename(resolvedRoot);
+    const declaredManager = typeof packageJson?.packageManager === "string" ? packageJson.packageManager : "";
+    const unsupportedManager = await exists(path.join(resolvedRoot, "yarn.lock")) || /^yarn(?:@|$)/.test(declaredManager) ? "yarn"
+        : await exists(path.join(resolvedRoot, "bun.lockb")) || await exists(path.join(resolvedRoot, "bun.lock")) || /^bun(?:@|$)/.test(declaredManager) ? "bun"
+            : undefined;
+    let packageManager = unsupportedManager ? undefined : "npm";
+    if (!unsupportedManager) {
+        if (await exists(path.join(resolvedRoot, "pnpm-lock.yaml")))
+            packageManager = "pnpm";
+        else if (/^pnpm(?:@|$)/.test(declaredManager))
+            packageManager = "pnpm";
+    }
+    findings.push({
+        kind: "package-manager",
+        confidence: unsupportedManager ? "proposed" : packageJson ? "confirmed" : "proposed",
+        source: packageJson ? "package.json" : "directory contents",
+        detail: unsupportedManager ? `${unsupportedManager} is detected but has no native adapter; add an explicit command.` : packageManager,
+    });
+    const scripts = packageJson && packageJson.scripts && typeof packageJson.scripts === "object" ? packageJson.scripts : {};
+    for (const candidate of ["dev", "start"]) {
+        if (packageManager && typeof scripts[candidate] === "string") {
+            processes.app = { adapter: packageManager, script: candidate, ports: ["app"] };
+            findings.push({ kind: "process", confidence: "confirmed", source: `package.json#scripts.${candidate}`, detail: `${packageManager} run ${candidate}` });
+            break;
+        }
+    }
+    const entries = await readdir(resolvedRoot).catch(() => []);
+    const composeFile = ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"].find((name) => entries.includes(name));
+    if (composeFile)
+        findings.push({ kind: "compose", confidence: "confirmed", source: composeFile, detail: "Compose file detected; service selection requires review." });
+    const wranglerFile = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"].find((name) => entries.includes(name));
+    if (wranglerFile)
+        findings.push({ kind: "wrangler", confidence: "confirmed", source: wranglerFile, detail: "Wrangler configuration detected; binding and health settings require review." });
+    if (entries.some((name) => name.endsWith(".xcodeproj") || name.endsWith(".xcworkspace"))) {
+        findings.push({ kind: "xcode", confidence: "confirmed", source: "repository root", detail: "Xcode project/workspace detected; scheme and simulator require review." });
+    }
+    if (await exists(path.join(resolvedRoot, "manifest.json")) || await exists(path.join(resolvedRoot, "public", "manifest.json"))) {
+        findings.push({ kind: "extension", confidence: "proposed", source: "manifest.json", detail: "Possible browser extension; ExtFn workflow requires review." });
+    }
+    if (Object.keys(processes).length === 0) {
+        findings.push({ kind: "process", confidence: "proposed", source: "no supported script detected", detail: "Add an explicit process command before running devfn up." });
+    }
+    if (Object.keys(processes).length > 0) {
+        findings.push({ kind: "process", confidence: "proposed", source: "framework default", detail: "The initial app port 3000 is a proposal and must be checked against the actual development server." });
+    }
+    const config = {
+        version: 1,
+        project: { id: slug(typeof packageJson?.name === "string" ? packageJson.name : baseName), name: typeof packageJson?.name === "string" ? packageJson.name : baseName },
+        defaultProfile: "default",
+        runtimeDir: ".devfn",
+        ports: Object.keys(processes).length ? { app: { preferred: 3000, range: [3000, 3099], env: "PORT" } } : {},
+        processes,
+        profiles: { default: { processes: Object.keys(processes), services: [] } },
+        prerequisites: Object.keys(processes).length && packageManager ? [{ command: packageManager, version: packageManager === "pnpm" ? "project-pinned" : undefined }] : [],
+        environmentOutputs: [{ path: ".devfn/runtime.env", format: "dotenv", mode: 0o600 }],
+    };
+    return { root: resolvedRoot, findings, config };
+}
+function quote(value, indent = 0) {
+    const json = JSON.stringify(value, null, 2).replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+    return json.split("\n").map((line, index) => index === 0 ? line : `${" ".repeat(indent)}${line}`).join("\n");
+}
+export function renderDevFnConfig(config, findings) {
+    const uncertain = findings.filter((finding) => finding.confidence === "proposed");
+    const header = [
+        "// Generated by devfn init. Review every command before trusting this repository.",
+        "// Keep executable DevFn manifests self-contained; imports and require() are rejected.",
+        ...(uncertain.length ? uncertain.map((finding) => `// REVIEW: ${finding.detail} (${finding.source})`) : []),
+        "export default ",
+    ];
+    return `${header.join("\n")}${quote(config, 2)} as const;\n`;
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export type ConfigErrorCode = "DEVFN_CONFIG_INVALID" | "DEVFN_CONFIG_NOT_FOUND" | "DEVFN_CONFIG_PATH_ESCAPE";
+export declare class DevFnConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    readonly path?: string;
+    constructor(code: ConfigErrorCode, message: string, path?: string);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+export class DevFnConfigError extends Error {
+    code;
+    path;
+    constructor(code, message, path) {
+        super(message);
+        this.name = "DevFnConfigError";
+        this.code = code;
+        this.path = path;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { DevFnConfigError, type ConfigErrorCode } from "./errors.js";
+export { discoverProject, renderDevFnConfig } from "./discovery.js";
+export { DEVFN_CONFIG_CANDIDATES, findDevFnRoot, loadDevFnConfig, loadDevFnPolicy, loadTrustedDevFnConfig, resolveDevFnManifestPath } from "./load.js";
+export { resolveContainedPath } from "./paths.js";
+export { matchesProcessIdentity, processBirthSignature, processExists } from "./process-identity.js";
+export { validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
+export { configDigest, defaultStateDir, isProjectTrusted, readTrustedManifest, trustProject } from "./trust.js";
+export type * from "./types.js";
+export declare function defineDevFnConfig<T extends import("./types.js").DevFnConfig>(config: T): T;
+export declare function defineDevFnPolicy<T extends import("./types.js").DevFnPolicy>(policy: T): T;

package/dist/index.js

@@ -0,0 +1,9 @@
+export { DevFnConfigError } from "./errors.js";
+export { discoverProject, renderDevFnConfig } from "./discovery.js";
+export { DEVFN_CONFIG_CANDIDATES, findDevFnRoot, loadDevFnConfig, loadDevFnPolicy, loadTrustedDevFnConfig, resolveDevFnManifestPath } from "./load.js";
+export { resolveContainedPath } from "./paths.js";
+export { matchesProcessIdentity, processBirthSignature, processExists } from "./process-identity.js";
+export { validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
+export { configDigest, defaultStateDir, isProjectTrusted, readTrustedManifest, trustProject } from "./trust.js";
+export function defineDevFnConfig(config) { return config; }
+export function defineDevFnPolicy(policy) { return policy; }

package/dist/load.d.ts

@@ -0,0 +1,31 @@
+import type { DevFnConfig, DevFnPolicy } from "./types.js";
+export declare const DEVFN_CONFIG_CANDIDATES: readonly ["devfn.config.ts", "devfn.config.js", "devfn.config.mjs", "devfn.config.cjs", "devfn.config.json"];
+export declare function findDevFnRoot(start?: string): Promise<string>;
+export declare function resolveDevFnManifestPath(options?: {
+    cwd?: string;
+    configPath?: string;
+}): Promise<{
+    root: string;
+    path: string;
+}>;
+export declare function loadDevFnConfig(options?: {
+    cwd?: string;
+    configPath?: string;
+}): Promise<{
+    config: DevFnConfig;
+    path: string;
+    root: string;
+}>;
+export declare function loadTrustedDevFnConfig(options?: {
+    cwd?: string;
+    configPath?: string;
+    stateDir?: string;
+}): Promise<{
+    config: DevFnConfig;
+    path: string;
+    root: string;
+}>;
+export declare function loadDevFnPolicy(root: string, configuredPath?: string): Promise<{
+    policy: DevFnPolicy;
+    path: string;
+} | null>;

package/dist/load.js

@@ -0,0 +1,153 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { createContext, Script } from "node:vm";
+import { ConfigLoaderError, loadConfig } from "@clifn/core";
+import ts from "typescript";
+import { DevFnConfigError } from "./errors.js";
+import { resolveContainedPath } from "./paths.js";
+import { validateDevFnConfig, validateDevFnPolicy } from "./schema.js";
+import { defaultStateDir, readTrustedManifest } from "./trust.js";
+export const DEVFN_CONFIG_CANDIDATES = [
+    "devfn.config.ts",
+    "devfn.config.js",
+    "devfn.config.mjs",
+    "devfn.config.cjs",
+    "devfn.config.json",
+];
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function findDevFnRoot(start = process.cwd()) {
+    let current = path.resolve(start);
+    while (true) {
+        for (const candidate of DEVFN_CONFIG_CANDIDATES) {
+            if (await exists(path.join(current, candidate)))
+                return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new DevFnConfigError("DEVFN_CONFIG_NOT_FOUND", `No DevFn manifest found from ${start}.`);
+        }
+        current = parent;
+    }
+}
+export async function resolveDevFnManifestPath(options = {}) {
+    if (options.configPath) {
+        const resolved = path.resolve(options.cwd ?? process.cwd(), options.configPath);
+        if (!await exists(resolved))
+            throw new DevFnConfigError("DEVFN_CONFIG_NOT_FOUND", `Config file not found: ${resolved}`);
+        return { root: path.dirname(resolved), path: resolved };
+    }
+    const root = await findDevFnRoot(options.cwd);
+    for (const candidate of DEVFN_CONFIG_CANDIDATES) {
+        const resolved = path.join(root, candidate);
+        if (await exists(resolved))
+            return { root, path: resolved };
+    }
+    throw new DevFnConfigError("DEVFN_CONFIG_NOT_FOUND", `No DevFn manifest found from ${options.cwd ?? process.cwd()}.`);
+}
+export async function loadDevFnConfig(options = {}) {
+    try {
+        const resolved = await resolveDevFnManifestPath(options);
+        const root = resolved.root;
+        const loaded = await loadConfig({
+            cwd: root,
+            configPath: resolved.path,
+            candidates: DEVFN_CONFIG_CANDIDATES,
+            exportNames: ["config", "devfnConfig"],
+            validate: validateDevFnConfig,
+        });
+        return { ...loaded, root };
+    }
+    catch (error) {
+        if (error instanceof DevFnConfigError)
+            throw error;
+        if (error instanceof ConfigLoaderError) {
+            throw new DevFnConfigError(error.code === "CLIFN_CONFIG_NOT_FOUND" ? "DEVFN_CONFIG_NOT_FOUND" : "DEVFN_CONFIG_INVALID", error.message);
+        }
+        throw error;
+    }
+}
+export async function loadTrustedDevFnConfig(options = {}) {
+    const resolved = await resolveDevFnManifestPath(options);
+    const snapshot = await readTrustedManifest(resolved.root, resolved.path, options.stateDir ?? defaultStateDir());
+    const source = snapshot.bytes.toString("utf8");
+    if (resolved.path.endsWith(".json")) {
+        try {
+            return { config: validateDevFnConfig(JSON.parse(source)), path: resolved.path, root: resolved.root };
+        }
+        catch (error) {
+            if (error instanceof DevFnConfigError)
+                throw error;
+            throw new DevFnConfigError("DEVFN_CONFIG_INVALID", `Unable to parse trusted JSON manifest ${resolved.path}.`);
+        }
+    }
+    if (hasExternalModuleSyntax(source)) {
+        throw new DevFnConfigError("DEVFN_CONFIG_INVALID", "Executable DevFn manifests must be self-contained; imports and require() are not permitted.");
+    }
+    try {
+        return { config: validateDevFnConfig(evaluateTrustedManifest(source, resolved.path)), path: resolved.path, root: resolved.root };
+    }
+    catch (error) {
+        if (error instanceof DevFnConfigError)
+            throw error;
+        throw new DevFnConfigError("DEVFN_CONFIG_INVALID", `Unable to evaluate trusted manifest ${resolved.path} in the restricted context.`);
+    }
+}
+function evaluateTrustedManifest(source, filename) {
+    const transpiled = ts.transpileModule(source, {
+        fileName: filename,
+        reportDiagnostics: true,
+        compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022, esModuleInterop: false },
+    });
+    const diagnostic = transpiled.diagnostics?.find((item) => item.category === ts.DiagnosticCategory.Error);
+    if (diagnostic)
+        throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
+    const context = createContext(Object.create(null), { name: "devfn-trusted-manifest", codeGeneration: { strings: false, wasm: false }, microtaskMode: "afterEvaluate" });
+    const serialized = new Script(`(() => { const module = { exports: {} }; const exports = module.exports;\n${transpiled.outputText}\nconst value = module.exports; return JSON.stringify(value?.default ?? value?.config ?? value?.devfnConfig ?? value); })()`, { filename }).runInContext(context, { timeout: 1000 });
+    if (typeof serialized !== "string")
+        throw new Error("Trusted manifest did not export a serializable configuration.");
+    return JSON.parse(serialized);
+}
+function hasExternalModuleSyntax(source) {
+    const file = ts.createSourceFile("devfn.config.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let forbidden = false;
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) || ts.isImportEqualsDeclaration(node) || ts.isImportTypeNode(node) || (ts.isExportDeclaration(node) && Boolean(node.moduleSpecifier)))
+            forbidden = true;
+        if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === "require")))
+            forbidden = true;
+        if (ts.isPropertyAccessExpression(node) && node.name.text === "require")
+            forbidden = true;
+        if (ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) && node.argumentExpression.text === "require")
+            forbidden = true;
+        if (!forbidden)
+            ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return forbidden;
+}
+export async function loadDevFnPolicy(root, configuredPath) {
+    const candidate = configuredPath ?? "devfn.policy.json";
+    try {
+        const policyPath = await resolveContainedPath(root, candidate, "policy");
+        if (!await exists(policyPath)) {
+            if (configuredPath)
+                throw new DevFnConfigError("DEVFN_CONFIG_NOT_FOUND", `Configured policy file not found: ${policyPath}.`, "policy");
+            return null;
+        }
+        const raw = await readFile(policyPath, "utf8");
+        return { policy: validateDevFnPolicy(JSON.parse(raw)), path: policyPath };
+    }
+    catch (error) {
+        if (error instanceof DevFnConfigError)
+            throw error;
+        throw new DevFnConfigError("DEVFN_CONFIG_INVALID", `Unable to read or parse policy ${candidate}.`);
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1 @@
+export declare function resolveContainedPath(root: string, candidate: string, field?: string): Promise<string>;

package/dist/paths.js

@@ -0,0 +1,33 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { DevFnConfigError } from "./errors.js";
+async function nearestExistingParent(candidate) {
+    let current = candidate;
+    while (true) {
+        try {
+            await lstat(current);
+            return current;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(current);
+            if (parent === current)
+                throw error;
+            current = parent;
+        }
+    }
+}
+export async function resolveContainedPath(root, candidate, field = "path") {
+    const resolvedRoot = await realpath(root);
+    const resolved = path.resolve(resolvedRoot, candidate);
+    if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new DevFnConfigError("DEVFN_CONFIG_PATH_ESCAPE", `${field} must stay inside the repository.`, field);
+    }
+    const existingParent = await nearestExistingParent(resolved);
+    const canonicalParent = await realpath(existingParent);
+    if (canonicalParent !== resolvedRoot && !canonicalParent.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new DevFnConfigError("DEVFN_CONFIG_PATH_ESCAPE", `${field} resolves outside the repository through a symlink.`, field);
+    }
+    return resolved;
+}

package/dist/process-identity.d.ts

@@ -0,0 +1,3 @@
+export declare function processBirthSignature(pid: number): Promise<string | undefined>;
+export declare function processExists(pid: number): boolean;
+export declare function matchesProcessIdentity(pid: number, signature?: string): Promise<boolean>;

package/dist/process-identity.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function processBirthSignature(pid) {
+    try {
+        if (process.platform === "linux") {
+            const stat = await import("node:fs/promises").then((fs) => fs.readFile(`/proc/${pid}/stat`, "utf8"));
+            const afterCommand = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+            const startTime = afterCommand[19];
+            return startTime ? `linux:${startTime}` : undefined;
+        }
+        if (process.platform === "darwin") {
+            const { stdout } = await execFileAsync("ps", ["-o", "lstart=", "-p", String(pid)]);
+            return `darwin:${stdout.trim()}`;
+        }
+        if (process.platform === "win32") {
+            const { stdout } = await execFileAsync("powershell", ["-NoProfile", "-Command", `(Get-Process -Id ${pid}).StartTime.ToUniversalTime().ToString('O')`]);
+            return `win32:${stdout.trim()}`;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+export async function matchesProcessIdentity(pid, signature) {
+    if (!processExists(pid))
+        return false;
+    if (!signature)
+        return false;
+    return await processBirthSignature(pid) === signature;
+}

package/dist/schema.d.ts

@@ -0,0 +1,3 @@
+import type { DevFnConfig, DevFnPolicy } from "./types.js";
+export declare function validateDevFnConfig(value: unknown): DevFnConfig;
+export declare function validateDevFnPolicy(value: unknown): DevFnPolicy;

package/dist/schema.js

@@ -0,0 +1,412 @@
+import path from "node:path";
+import { DevFnConfigError } from "./errors.js";
+const SENSITIVE_KEY = /(authorization|token|secret|password|cookie|api[-_]?key|session[-_]?id|access[-_]?key|refresh[-_]?token)/i;
+function fail(message, field) {
+    throw new DevFnConfigError("DEVFN_CONFIG_INVALID", message, field);
+}
+function record(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(`${field} must be an object.`, field);
+    return value;
+}
+function string(value, field) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail(`${field} must be a non-empty string.`, field);
+    return value;
+}
+function optionalString(value, field) {
+    return value === undefined ? undefined : string(value, field);
+}
+function optionalBoolean(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        fail(`${field} must be a boolean.`, field);
+    return value;
+}
+function stringArray(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        fail(`${field} must be an array.`, field);
+    return value.map((item, index) => string(item, `${field}[${index}]`));
+}
+function stringMap(value, field) {
+    if (value === undefined)
+        return undefined;
+    return Object.fromEntries(Object.entries(record(value, field)).map(([key, item]) => [key, string(item, `${field}.${key}`)]));
+}
+function integer(value, field, min = 1, max = 65535) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        fail(`${field} must be an integer between ${min} and ${max}.`, field);
+    }
+    return value;
+}
+function range(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length !== 2)
+        fail(`${field} must be a two-item port range.`, field);
+    const start = integer(value[0], `${field}[0]`);
+    const end = integer(value[1], `${field}[1]`);
+    if (start > end)
+        fail(`${field} must be ascending.`, field);
+    return [start, end];
+}
+function relativePath(value, field) {
+    const result = string(value, field);
+    if (path.isAbsolute(result) || result.split(/[\\/]+/).includes("..")) {
+        throw new DevFnConfigError("DEVFN_CONFIG_PATH_ESCAPE", `${field} must stay inside the repository.`, field);
+    }
+    return result;
+}
+function healthTimeout(input, field) {
+    const timeoutMs = input.timeoutMs === undefined ? undefined : integer(input.timeoutMs, `${field}.timeoutMs`, 1, 3_600_000);
+    return timeoutMs === undefined ? {} : { timeoutMs };
+}
+function httpHealth(input, field) {
+    if (input.url === undefined && input.port === undefined)
+        fail(`${field} requires url or port.`, field);
+    const url = optionalString(input.url, `${field}.url`);
+    const port = optionalString(input.port, `${field}.port`);
+    const healthPath = optionalString(input.path, `${field}.path`);
+    return { type: "http", ...(url ? { url } : {}), ...(port ? { port } : {}), ...(healthPath ? { path: healthPath } : {}), ...(input.expectedStatus === undefined ? {} : { expectedStatus: integer(input.expectedStatus, `${field}.expectedStatus`, 100, 599) }), ...healthTimeout(input, field) };
+}
+function commandHealth(input, field) {
+    const command = stringArray(input.command, `${field}.command`);
+    if (!command?.length)
+        fail(`${field}.command cannot be empty.`, `${field}.command`);
+    return { type: "command", command, ...healthTimeout(input, field) };
+}
+function health(value, field) {
+    if (value === undefined)
+        return undefined;
+    const input = record(value, field);
+    switch (string(input.type, `${field}.type`)) {
+        case "http": return httpHealth(input, field);
+        case "tcp": return { type: "tcp", port: string(input.port, `${field}.port`), ...healthTimeout(input, field) };
+        case "command": return commandHealth(input, field);
+        case "log": return { type: "log", pattern: string(input.pattern, `${field}.pattern`), ...healthTimeout(input, field) };
+        default: return fail(`${field}.type is unsupported.`, `${field}.type`);
+    }
+}
+function portSpec(value, field) {
+    const input = record(value, field);
+    const preferred = input.preferred === undefined ? undefined : integer(input.preferred, `${field}.preferred`);
+    const configuredRange = range(input.range, `${field}.range`);
+    const ephemeral = optionalBoolean(input.ephemeral, `${field}.ephemeral`) ?? false;
+    const exact = optionalBoolean(input.exact, `${field}.exact`) ?? false;
+    const block = optionalString(input.block, `${field}.block`);
+    if (exact && preferred === undefined)
+        fail(`${field}.preferred is required when exact is true.`, field);
+    if (ephemeral && (preferred !== undefined || configuredRange !== undefined || exact || block !== undefined)) {
+        fail(`${field} ephemeral ports cannot also be preferred, ranged, exact, or part of a block.`, field);
+    }
+    const protocol = input.protocol === undefined ? "tcp" : string(input.protocol, `${field}.protocol`);
+    if (protocol !== "tcp" && protocol !== "udp")
+        fail(`${field}.protocol must be tcp or udp.`, `${field}.protocol`);
+    const exposure = input.exposure === undefined ? "loopback" : string(input.exposure, `${field}.exposure`);
+    if (exposure !== "loopback" && exposure !== "public")
+        fail(`${field}.exposure must be loopback or public.`, `${field}.exposure`);
+    return {
+        protocol,
+        exposure,
+        ...(preferred === undefined ? {} : { preferred }),
+        ...(configuredRange === undefined ? {} : { range: configuredRange }),
+        ...(exact ? { exact } : {}),
+        ...(ephemeral ? { ephemeral } : {}),
+        ...(input.internal === undefined ? {} : { internal: integer(input.internal, `${field}.internal`) }),
+        ...(block ? { block } : {}),
+        ...(optionalString(input.env, `${field}.env`) ? { env: optionalString(input.env, `${field}.env`) } : {}),
+    };
+}
+function environmentFields(input, field) {
+    const env = stringMap(input.env, `${field}.env`);
+    const envAllowlist = stringArray(input.envAllowlist, `${field}.envAllowlist`);
+    const secretEnv = stringArray(input.secretEnv, `${field}.secretEnv`);
+    for (const key of Object.keys(env ?? {}))
+        if (SENSITIVE_KEY.test(key))
+            fail(`${field}.env.${key} must not contain a literal secret; inherit it through envAllowlist and declare it in secretEnv.`, `${field}.env.${key}`);
+    for (const key of secretEnv ?? [])
+        if (!envAllowlist?.includes(key))
+            fail(`${field}.secretEnv contains ${key}, which is not present in envAllowlist.`, `${field}.secretEnv`);
+    for (const key of envAllowlist ?? [])
+        if (SENSITIVE_KEY.test(key) && !secretEnv?.includes(key))
+            fail(`${field}.envAllowlist contains sensitive key ${key}; declare it in secretEnv for log redaction.`, `${field}.envAllowlist`);
+    return { ...(env ? { env } : {}), ...(envAllowlist ? { envAllowlist } : {}), ...(secretEnv ? { secretEnv } : {}) };
+}
+function processSpec(value, field) {
+    const input = record(value, field);
+    const adapter = string(input.adapter, `${field}.adapter`);
+    if (!["command", "npm", "pnpm", "turbo", "wrangler", "xcode", "extfn"].includes(adapter)) {
+        fail(`${field}.adapter is unsupported.`, `${field}.adapter`);
+    }
+    const command = stringArray(input.command, `${field}.command`);
+    const script = optionalString(input.script, `${field}.script`);
+    if (adapter === "command" && !command?.length)
+        fail(`${field}.command is required for command adapters.`, field);
+    if ((adapter === "npm" || adapter === "pnpm") && !script)
+        fail(`${field}.script is required for ${adapter}.`, field);
+    const exposure = input.exposure === undefined ? "local" : string(input.exposure, `${field}.exposure`);
+    if (exposure !== "local" && exposure !== "public")
+        fail(`${field}.exposure must be local or public.`, `${field}.exposure`);
+    const ports = stringArray(input.ports, `${field}.ports`);
+    const dependsOn = stringArray(input.dependsOn, `${field}.dependsOn`);
+    const parsedHealth = health(input.health, `${field}.health`);
+    return {
+        adapter,
+        exposure,
+        ...(command ? { command } : {}),
+        ...(script ? { script } : {}),
+        ...(input.cwd === undefined ? {} : { cwd: relativePath(input.cwd, `${field}.cwd`) }),
+        ...environmentFields(input, field),
+        ...(ports ? { ports } : {}),
+        ...(dependsOn ? { dependsOn } : {}),
+        ...(parsedHealth ? { health: parsedHealth } : {}),
+        ...(input.shutdownTimeoutMs === undefined ? {} : { shutdownTimeoutMs: integer(input.shutdownTimeoutMs, `${field}.shutdownTimeoutMs`, 1, 3_600_000) }),
+    };
+}
+function serviceSpec(value, field) {
+    const input = record(value, field);
+    if (input.adapter !== "compose")
+        fail(`${field}.adapter must be compose.`, `${field}.adapter`);
+    const ports = input.ports === undefined ? undefined : Object.fromEntries(Object.entries(record(input.ports, `${field}.ports`)).map(([name, internal]) => [name, integer(internal, `${field}.ports.${name}`)]));
+    const dependsOn = stringArray(input.dependsOn, `${field}.dependsOn`);
+    const parsedHealth = health(input.health, `${field}.health`);
+    return {
+        adapter: "compose",
+        service: string(input.service, `${field}.service`),
+        ...(input.file === undefined ? {} : { file: relativePath(input.file, `${field}.file`) }),
+        ...(optionalString(input.projectName, `${field}.projectName`) ? { projectName: optionalString(input.projectName, `${field}.projectName`) } : {}),
+        ...(ports ? { ports } : {}),
+        ...(dependsOn ? { dependsOn } : {}),
+        ...(parsedHealth ? { health: parsedHealth } : {}),
+        ...(input.persistent === undefined ? {} : { persistent: input.persistent === true }),
+        ...environmentFields(input, field),
+    };
+}
+function profileSpec(value, field) {
+    const input = record(value, field);
+    const environment = stringMap(input.environment, `${field}.environment`);
+    const proxy = optionalBoolean(input.proxy, `${field}.proxy`);
+    for (const key of Object.keys(environment ?? {}))
+        if (SENSITIVE_KEY.test(key))
+            fail(`${field}.environment.${key} must not contain a secret. Use process envAllowlist and secretEnv.`, `${field}.environment.${key}`);
+    return {
+        ...(stringArray(input.processes, `${field}.processes`) ? { processes: stringArray(input.processes, `${field}.processes`) } : {}),
+        ...(stringArray(input.services, `${field}.services`) ? { services: stringArray(input.services, `${field}.services`) } : {}),
+        ...(environment ? { environment } : {}),
+        ...(proxy === undefined ? {} : { proxy }),
+    };
+}
+function hostnameSpec(value, field) {
+    const input = record(value, field);
+    const tls = input.tls === undefined ? "off" : string(input.tls, `${field}.tls`);
+    if (tls !== "off" && tls !== "internal")
+        fail(`${field}.tls must be off or internal.`, `${field}.tls`);
+    const hostname = optionalString(input.hostname, `${field}.hostname`);
+    const expandedHostname = hostname?.replaceAll("{project}", "project").replaceAll("{instance}", "instance");
+    if (hostname && (expandedHostname?.includes("{") || expandedHostname?.includes("}") || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+localhost$/i.test(expandedHostname))) {
+        fail(`${field}.hostname must be a .localhost hostname using only {project} and {instance} placeholders.`, `${field}.hostname`);
+    }
+    return {
+        target: string(input.target, `${field}.target`),
+        ...(hostname ? { hostname } : {}),
+        tls,
+        ...(stringArray(input.profiles, `${field}.profiles`) ? { profiles: stringArray(input.profiles, `${field}.profiles`) } : {}),
+    };
+}
+function prerequisites(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        fail("prerequisites must be an array.", "prerequisites");
+    return value.map((item, index) => {
+        const input = record(item, `prerequisites[${index}]`);
+        const optional = optionalBoolean(input.optional, `prerequisites[${index}].optional`);
+        return {
+            command: string(input.command, `prerequisites[${index}].command`),
+            ...(optionalString(input.version, `prerequisites[${index}].version`) ? { version: optionalString(input.version, `prerequisites[${index}].version`) } : {}),
+            ...(optional === undefined ? {} : { optional }),
+            ...(stringArray(input.profiles, `prerequisites[${index}].profiles`) ? { profiles: stringArray(input.profiles, `prerequisites[${index}].profiles`) } : {}),
+        };
+    });
+}
+function environmentOutputs(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        fail("environmentOutputs must be an array.", "environmentOutputs");
+    return value.map((item, index) => {
+        const input = record(item, `environmentOutputs[${index}]`);
+        const format = input.format === undefined ? "dotenv" : string(input.format, `environmentOutputs[${index}].format`);
+        if (format !== "dotenv" && format !== "json")
+            fail("Environment output format must be dotenv or json.");
+        return {
+            path: relativePath(input.path, `environmentOutputs[${index}].path`),
+            format,
+            ...(input.mode === undefined ? {} : { mode: (() => {
+                    const mode = integer(input.mode, `environmentOutputs[${index}].mode`, 0, 0o777);
+                    if ((mode & 0o077) !== 0)
+                        fail(`environmentOutputs[${index}].mode must not grant group or other permissions.`, `environmentOutputs[${index}].mode`);
+                    return mode;
+                })() }),
+        };
+    });
+}
+function named(value, field, parser) {
+    return Object.fromEntries(Object.entries(record(value, field)).map(([name, item]) => [name, parser(item, `${field}.${name}`)]));
+}
+function validateProcessReferences(config, ports, nodes) {
+    for (const [name, process] of Object.entries(config.processes ?? {})) {
+        for (const port of process.ports ?? [])
+            if (!ports.has(port))
+                fail(`processes.${name} references unknown port ${port}.`);
+        const healthPort = process.health && (process.health.type === "http" || process.health.type === "tcp") ? process.health.port : undefined;
+        if (healthPort && (!ports.has(healthPort) || !process.ports?.includes(healthPort)))
+            fail(`processes.${name}.health references port ${healthPort}, which must also appear in processes.${name}.ports.`);
+        if (healthPort && config.ports?.[healthPort]?.protocol === "udp")
+            fail(`processes.${name}.health requires TCP port ${healthPort}, but that allocation uses UDP.`);
+        for (const dependency of process.dependsOn ?? [])
+            if (!nodes.has(dependency))
+                fail(`processes.${name} references unknown dependency ${dependency}.`);
+    }
+}
+function validateServiceReferences(config, ports, nodes) {
+    for (const [name, service] of Object.entries(config.services ?? {})) {
+        for (const port of Object.keys(service.ports ?? {}))
+            if (!ports.has(port))
+                fail(`services.${name} references unknown port ${port}.`);
+        const healthPort = service.health && (service.health.type === "http" || service.health.type === "tcp") ? service.health.port : undefined;
+        if (healthPort && (!ports.has(healthPort) || service.ports?.[healthPort] === undefined))
+            fail(`services.${name}.health references port ${healthPort}, which must also appear in services.${name}.ports.`);
+        if (healthPort && config.ports?.[healthPort]?.protocol === "udp")
+            fail(`services.${name}.health requires TCP port ${healthPort}, but that allocation uses UDP.`);
+        for (const dependency of service.dependsOn ?? [])
+            if (!nodes.has(dependency))
+                fail(`services.${name} references unknown dependency ${dependency}.`);
+    }
+}
+function validateSelectionReferences(config, ports, processes, services) {
+    for (const [name, profile] of Object.entries(config.profiles)) {
+        for (const process of profile.processes ?? [])
+            if (!processes.has(process))
+                fail(`profiles.${name} references unknown process ${process}.`);
+        for (const service of profile.services ?? [])
+            if (!services.has(service))
+                fail(`profiles.${name} references unknown service ${service}.`);
+    }
+    for (const [name, hostname] of Object.entries(config.hostnames ?? {})) {
+        if (!ports.has(hostname.target))
+            fail(`hostnames.${name} references unknown port ${hostname.target}.`);
+        for (const profile of hostname.profiles ?? [])
+            if (!config.profiles[profile])
+                fail(`hostnames.${name} references unknown profile ${profile}.`);
+        const activeProfiles = hostname.profiles ?? Object.keys(config.profiles);
+        if (config.ports?.[hostname.target]?.protocol === "udp" && activeProfiles.some((profile) => config.profiles[profile]?.proxy)) {
+            fail(`hostnames.${name} cannot target UDP port ${hostname.target} from a proxy-enabled profile.`, `hostnames.${name}.target`);
+        }
+    }
+    if (config.defaultProfile && !config.profiles[config.defaultProfile])
+        fail(`defaultProfile references unknown profile ${config.defaultProfile}.`);
+}
+function validateReferences(config) {
+    const ports = new Set(Object.keys(config.ports ?? {}));
+    const processes = new Set(Object.keys(config.processes ?? {}));
+    const services = new Set(Object.keys(config.services ?? {}));
+    for (const name of [...processes, ...services])
+        if (!/^[A-Za-z0-9_.-]+$/.test(name) || name !== name.trim())
+            fail(`Lifecycle node ${name} must use only letters, numbers, dots, underscores, and hyphens.`);
+    for (const name of ports)
+        if (!/^[A-Za-z0-9_.-]+$/.test(name) || name !== name.trim())
+            fail(`Port name ${JSON.stringify(name)} must use only letters, numbers, dots, underscores, and hyphens.`);
+    const collision = [...processes].find((name) => services.has(name));
+    if (collision)
+        fail(`Lifecycle node ${collision} cannot be both a process and a service.`);
+    const nodes = new Set([...processes, ...services]);
+    validateProcessReferences(config, ports, nodes);
+    validateServiceReferences(config, ports, nodes);
+    validateSelectionReferences(config, ports, processes, services);
+    const environmentOwners = new Map();
+    for (const [name, spec] of Object.entries(config.ports ?? {})) {
+        if (spec.env?.startsWith("DEVFN_"))
+            fail(`ports.${name}.env cannot use reserved DEVFN_ runtime variables.`, `ports.${name}.env`);
+        const generated = `DEVFN_PORT_${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+        for (const environmentName of new Set([generated, ...(spec.env ? [spec.env] : [])])) {
+            const owner = environmentOwners.get(environmentName);
+            if (owner !== undefined && owner !== name)
+                fail(`Ports ${owner} and ${name} both emit environment variable ${environmentName}.`, `ports.${name}`);
+            environmentOwners.set(environmentName, name);
+        }
+    }
+    for (const [name, spec] of Object.entries(config.hostnames ?? {})) {
+        const expanded = (spec.hostname ?? `${name}-{instance}.localhost`).replaceAll("{instance}", "instance").replaceAll("{project}", config.project.id);
+        if (!/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+localhost$/i.test(expanded))
+            fail(`hostnames.${name}.hostname resolves to an invalid .localhost hostname for project ${config.project.id}.`, `hostnames.${name}.hostname`);
+    }
+}
+export function validateDevFnConfig(value) {
+    const input = record(value, "config");
+    if (input.version !== 1)
+        fail("config.version must be 1.", "version");
+    const project = record(input.project, "project");
+    const profiles = named(input.profiles, "profiles", profileSpec);
+    if (Object.keys(profiles).length === 0)
+        fail("At least one profile is required.", "profiles");
+    const config = {
+        version: 1,
+        project: { id: string(project.id, "project.id"), ...(optionalString(project.name, "project.name") ? { name: optionalString(project.name, "project.name") } : {}) },
+        profiles,
+        ...(optionalString(input.defaultProfile, "defaultProfile") ? { defaultProfile: optionalString(input.defaultProfile, "defaultProfile") } : {}),
+        ...(input.runtimeDir === undefined ? {} : { runtimeDir: relativePath(input.runtimeDir, "runtimeDir") }),
+        ...(input.ports === undefined ? {} : { ports: named(input.ports, "ports", portSpec) }),
+        ...(input.processes === undefined ? {} : { processes: named(input.processes, "processes", processSpec) }),
+        ...(input.services === undefined ? {} : { services: named(input.services, "services", serviceSpec) }),
+        ...(input.hostnames === undefined ? {} : { hostnames: named(input.hostnames, "hostnames", hostnameSpec) }),
+        ...(prerequisites(input.prerequisites) ? { prerequisites: prerequisites(input.prerequisites) } : {}),
+        ...(environmentOutputs(input.environmentOutputs) ? { environmentOutputs: environmentOutputs(input.environmentOutputs) } : {}),
+        ...(input.policy === undefined ? {} : { policy: relativePath(input.policy, "policy") }),
+    };
+    if (!config.defaultProfile && !config.profiles.default) {
+        fail("profiles.default is required when defaultProfile is omitted.", "profiles.default");
+    }
+    validateReferences(config);
+    return config;
+}
+function policyEntry(value, field) {
+    const input = record(value, field);
+    const kind = string(input.kind, `${field}.kind`);
+    if (!["protected", "preferred", "excluded"].includes(kind))
+        fail(`${field}.kind is unsupported.`);
+    const configuredRange = range(input.range, `${field}.range`);
+    const port = input.port === undefined ? undefined : integer(input.port, `${field}.port`);
+    if ((port === undefined) === (configuredRange === undefined))
+        fail(`${field} requires exactly one of port or range.`);
+    return {
+        name: string(input.name, `${field}.name`),
+        kind: kind,
+        ...(port === undefined ? {} : { port }),
+        ...(configuredRange === undefined ? {} : { range: configuredRange }),
+        ...(optionalString(input.project, `${field}.project`) ? { project: optionalString(input.project, `${field}.project`) } : {}),
+        ...(optionalString(input.description, `${field}.description`) ? { description: optionalString(input.description, `${field}.description`) } : {}),
+    };
+}
+export function validateDevFnPolicy(value) {
+    const input = record(value, "policy");
+    if (input.version !== 1)
+        fail("policy.version must be 1.", "version");
+    const ports = input.ports === undefined ? undefined : (() => {
+        if (!Array.isArray(input.ports))
+            fail("policy.ports must be an array.", "ports");
+        return input.ports.map((item, index) => policyEntry(item, `ports[${index}]`));
+    })();
+    const hostnameSuffix = optionalString(input.hostnameSuffix, "hostnameSuffix");
+    if (hostnameSuffix && (!hostnameSuffix.startsWith(".") || !hostnameSuffix.endsWith(".localhost")))
+        fail("hostnameSuffix must start with a dot and end in .localhost.", "hostnameSuffix");
+    return {
+        version: 1,
+        ...(range(input.fallbackRange, "fallbackRange") ? { fallbackRange: range(input.fallbackRange, "fallbackRange") } : {}),
+        ...(hostnameSuffix ? { hostnameSuffix } : {}),
+        ...(ports ? { ports } : {}),
+    };
+}

package/dist/trust.d.ts

@@ -0,0 +1,8 @@
+export declare function defaultStateDir(env?: NodeJS.ProcessEnv): string;
+export declare function configDigest(configPath: string): Promise<string>;
+export declare function readTrustedManifest(root: string, configPath: string, stateDir?: string): Promise<{
+    bytes: Buffer;
+    digest: string;
+}>;
+export declare function isProjectTrusted(root: string, configPath: string, stateDir?: string): Promise<boolean>;
+export declare function trustProject(root: string, configPath: string, stateDir?: string): Promise<void>;

package/dist/trust.js

@@ -0,0 +1,151 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { processBirthSignature, processExists } from "./process-identity.js";
+export function defaultStateDir(env = process.env) {
+    return env.XDG_STATE_HOME ? path.join(env.XDG_STATE_HOME, "devfn") : path.join(os.homedir(), ".local", "state", "devfn");
+}
+export async function configDigest(configPath) {
+    return createHash("sha256").update(await readFile(configPath)).digest("hex");
+}
+async function readTrust(filePath) {
+    try {
+        const value = JSON.parse(await readFile(filePath, "utf8"));
+        return value.version === 1 && Array.isArray(value.records) ? value : { version: 1, records: [] };
+    }
+    catch {
+        return { version: 1, records: [] };
+    }
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function readTicket(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function staleTicket(filePath, ticket, staleMs) {
+    const createdAt = ticket?.createdAt ? Date.parse(ticket.createdAt) : await stat(filePath).then((value) => value.mtimeMs).catch(() => Date.now());
+    if (!Number.isFinite(createdAt) || Date.now() - createdAt <= staleMs)
+        return false;
+    if (!ticket?.pid)
+        return true;
+    if (!processExists(ticket.pid))
+        return true;
+    if (!ticket.birthSignature)
+        return false;
+    const currentSignature = await processBirthSignature(ticket.pid);
+    return currentSignature !== undefined && currentSignature !== ticket.birthSignature;
+}
+async function ticketPaths(lockPath) {
+    return (await readdir(lockPath)).filter((name) => name.endsWith(".choosing") || name.endsWith(".ticket")).map((name) => path.join(lockPath, name));
+}
+async function cleanStaleTickets(lockPath, ownPaths, staleMs) {
+    for (const filePath of await ticketPaths(lockPath)) {
+        if (ownPaths.has(filePath))
+            continue;
+        let ticket;
+        try {
+            ticket = await readTicket(filePath);
+        }
+        catch (error) {
+            if (await staleTicket(filePath, undefined, staleMs)) {
+                await rm(filePath, { force: true });
+                continue;
+            }
+            throw error;
+        }
+        if (ticket && await staleTicket(filePath, ticket, staleMs))
+            await rm(filePath, { force: true });
+    }
+}
+async function writeTicket(filePath, ticket) {
+    const temp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, JSON.stringify(ticket), { mode: 0o600, flag: "wx" });
+        await rename(temp, filePath);
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+async function withTrustLock(stateDir, action) {
+    const lockPath = path.join(stateDir, "trust.lock");
+    await mkdir(lockPath, { recursive: true, mode: 0o700 });
+    const token = randomUUID();
+    const choosingPath = path.join(lockPath, `${token}.choosing`);
+    const ticketPath = path.join(lockPath, `${token}.ticket`);
+    const ownPaths = new Set([choosingPath, ticketPath]);
+    const staleMs = 300_000;
+    const deadline = Date.now() + 10_000;
+    const baseTicket = { token, pid: process.pid, ...(await processBirthSignature(process.pid).then((birthSignature) => birthSignature ? { birthSignature } : {})), createdAt: new Date().toISOString() };
+    await writeTicket(choosingPath, baseTicket);
+    try {
+        await cleanStaleTickets(lockPath, ownPaths, staleMs);
+        const tickets = await Promise.all((await ticketPaths(lockPath)).filter((filePath) => filePath.endsWith(".ticket")).map(readTicket));
+        const number = Math.max(0, ...tickets.map((ticket) => Number.isInteger(ticket?.number) ? ticket.number : 0)) + 1;
+        await writeTicket(ticketPath, { ...baseTicket, number });
+        await rm(choosingPath, { force: true });
+        while (true) {
+            await cleanStaleTickets(lockPath, ownPaths, staleMs);
+            const others = (await ticketPaths(lockPath)).filter((filePath) => !ownPaths.has(filePath));
+            let blocked = others.some((filePath) => filePath.endsWith(".choosing"));
+            if (!blocked) {
+                for (const filePath of others.filter((candidate) => candidate.endsWith(".ticket"))) {
+                    const ticket = await readTicket(filePath);
+                    if (!ticket || !Number.isInteger(ticket.number) || ticket.number < number || (ticket.number === number && ticket.token < token)) {
+                        blocked = true;
+                        break;
+                    }
+                }
+            }
+            if (!blocked)
+                break;
+            if (Date.now() >= deadline)
+                throw new Error(`Timed out acquiring trust-state lock ${lockPath}.`);
+            await delay(20 + Math.floor(Math.random() * 20));
+        }
+        return await action();
+    }
+    finally {
+        await rm(choosingPath, { force: true }).catch(() => undefined);
+        await rm(ticketPath, { force: true }).catch(() => undefined);
+    }
+}
+export async function readTrustedManifest(root, configPath, stateDir = defaultStateDir()) {
+    const bytes = await readFile(configPath);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    const state = await readTrust(path.join(stateDir, "trust.json"));
+    if (!state.records.some((record) => record.root === root && record.configPath === configPath && record.digest === digest)) {
+        throw new Error(`DevFn manifest is not trusted: ${configPath}`);
+    }
+    return { bytes, digest };
+}
+export async function isProjectTrusted(root, configPath, stateDir = defaultStateDir()) {
+    const digest = await configDigest(configPath);
+    const state = await readTrust(path.join(stateDir, "trust.json"));
+    return state.records.some((record) => record.root === root && record.configPath === configPath && record.digest === digest);
+}
+export async function trustProject(root, configPath, stateDir = defaultStateDir()) {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    await withTrustLock(stateDir, async () => {
+        const filePath = path.join(stateDir, "trust.json");
+        const state = await readTrust(filePath);
+        const digest = await configDigest(configPath);
+        const next = {
+            version: 1,
+            records: [
+                ...state.records.filter((record) => !(record.root === root && record.configPath === configPath)),
+                { root, configPath, digest, trustedAt: new Date().toISOString() },
+            ],
+        };
+        const temp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        await rename(temp, filePath);
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+export type RuntimeAdapter = "command" | "npm" | "pnpm" | "turbo" | "wrangler" | "xcode" | "extfn";
+export type HealthCheck = {
+    type: "http";
+    url?: string;
+    port?: string;
+    path?: string;
+    expectedStatus?: number;
+    timeoutMs?: number;
+} | {
+    type: "tcp";
+    port: string;
+    timeoutMs?: number;
+} | {
+    type: "command";
+    command: string[];
+    timeoutMs?: number;
+} | {
+    type: "log";
+    pattern: string;
+    timeoutMs?: number;
+};
+export interface PortSpec {
+    protocol?: "tcp" | "udp";
+    preferred?: number;
+    range?: [number, number];
+    exact?: boolean;
+    ephemeral?: boolean;
+    exposure?: "loopback" | "public";
+    internal?: number;
+    block?: string;
+    env?: string;
+}
+export interface ProcessSpec {
+    adapter: RuntimeAdapter;
+    exposure?: "local" | "public";
+    command?: string[];
+    script?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    envAllowlist?: string[];
+    secretEnv?: string[];
+    ports?: string[];
+    dependsOn?: string[];
+    health?: HealthCheck;
+    shutdownTimeoutMs?: number;
+}
+export interface ComposeServiceSpec {
+    adapter: "compose";
+    file?: string;
+    service: string;
+    projectName?: string;
+    ports?: Record<string, number>;
+    dependsOn?: string[];
+    health?: HealthCheck;
+    persistent?: boolean;
+    env?: Record<string, string>;
+    envAllowlist?: string[];
+    secretEnv?: string[];
+}
+export interface ProfileSpec {
+    processes?: string[];
+    services?: string[];
+    environment?: Record<string, string>;
+    proxy?: boolean;
+}
+export interface HostnameSpec {
+    target: string;
+    hostname?: string;
+    tls?: "off" | "internal";
+    profiles?: string[];
+}
+export interface RuntimePrerequisite {
+    command: string;
+    version?: string;
+    optional?: boolean;
+    profiles?: string[];
+}
+export interface EnvironmentOutput {
+    path: string;
+    format?: "dotenv" | "json";
+    mode?: number;
+}
+export interface DevFnConfig {
+    version: 1;
+    project: {
+        id: string;
+        name?: string;
+    };
+    defaultProfile?: string;
+    runtimeDir?: string;
+    ports?: Record<string, PortSpec>;
+    processes?: Record<string, ProcessSpec>;
+    services?: Record<string, ComposeServiceSpec>;
+    profiles: Record<string, ProfileSpec>;
+    hostnames?: Record<string, HostnameSpec>;
+    prerequisites?: RuntimePrerequisite[];
+    environmentOutputs?: EnvironmentOutput[];
+    policy?: string;
+}
+export interface PortPolicyEntry {
+    name: string;
+    port?: number;
+    range?: [number, number];
+    kind: "protected" | "preferred" | "excluded";
+    project?: string;
+    description?: string;
+}
+export interface DevFnPolicy {
+    version: 1;
+    fallbackRange?: [number, number];
+    hostnameSuffix?: string;
+    ports?: PortPolicyEntry[];
+}
+export interface DetectionFinding {
+    kind: "package-manager" | "process" | "compose" | "wrangler" | "xcode" | "extension";
+    confidence: "confirmed" | "proposed";
+    source: string;
+    detail: string;
+}
+export interface DiscoveryResult {
+    root: string;
+    findings: DetectionFinding[];
+    config: DevFnConfig;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@devfn/config",
+  "version": "0.1.0",
+  "description": "Validated project manifests, organization policies, discovery, and trust contracts for DevFn",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "echo 'lint not configured'",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": { "@clifn/core": "0.1.0", "@types/node": "^22.0.0", "typescript": "^5.6.0" },
+  "devDependencies": { "vitest": "^3.2.4" },
+  "engines": { "node": ">=22" },
+  "license": "MIT"
+}