@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/contracts/utils/filesystem.d.ts

@@ -1,3 +1,4 @@
+export declare function isFilesystemArtifact(filePath: string): boolean;
 export declare function countFilesRecursive(dirPath: string): number;
 export declare function listFilesRecursive(dirPath: string, predicate?: (filePath: string) => boolean): string[];
 /**

package/dist/packages/contracts/utils/filesystem.js

@@ -1,6 +1,34 @@
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { readdir, realpath } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
+/**
+ * OS-generated filesystem junk that is provably not user content: macOS
+ * `.DS_Store`, AppleDouble resource forks (`._name`), Spotlight/Trash sidecars,
+ * Windows `Thumbs.db` / `desktop.ini`. These are filesystem bookkeeping, not
+ * Source files, so they must never count as required/expected coverage units —
+ * otherwise a macOS Source folder shows "not ready" purely because Finder left
+ * a `.DS_Store` behind.
+ *
+ * This match is by filename only (deterministic, provable), never by an agent's
+ * `not-relevant` label. A real content gap an agent skipped is NOT matched here
+ * and still counts toward readiness.
+ */
+const FILESYSTEM_ARTIFACT_NAMES = new Set([
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    "Icon\r",
+    ".localized",
+]);
+export function isFilesystemArtifact(filePath) {
+    const name = basename(filePath.replace(/\\/g, "/"));
+    if (FILESYSTEM_ARTIFACT_NAMES.has(name))
+        return true;
+    // AppleDouble resource forks copied onto non-HFS volumes: `._<realname>`.
+    if (name.startsWith("._"))
+        return true;
+    return false;
+}
 export function countFilesRecursive(dirPath) {
     if (!existsSync(dirPath))
         return 0;

package/dist/packages/contracts/utils/parse.js

@@ -73,6 +73,66 @@ function parseYamlScalar(value) {
     }
     return trimmed;
 }
+function yamlBlockHeader(value) {
+    const trimmed = value.trim();
+    if (!/^[>|](?:[+-]?\d*|\d*[+-]?)$/.test(trimmed))
+        return null;
+    return trimmed.startsWith(">") ? "folded" : "literal";
+}
+function leadingWhitespaceLength(value) {
+    const match = value.match(/^\s*/);
+    return match?.[0].length ?? 0;
+}
+function foldYamlBlock(lines) {
+    const paragraphs = [];
+    let current = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            if (current.length > 0) {
+                paragraphs.push(current.join(" "));
+                current = [];
+            }
+            if (paragraphs[paragraphs.length - 1] !== "") {
+                paragraphs.push("");
+            }
+            continue;
+        }
+        current.push(trimmed);
+    }
+    if (current.length > 0) {
+        paragraphs.push(current.join(" "));
+    }
+    return paragraphs.join("\n").trimEnd();
+}
+function parseYamlBlockScalar(lines, startIndex, style) {
+    const blockLines = [];
+    let blockIndent = null;
+    let cursor = startIndex + 1;
+    while (cursor < lines.length) {
+        const nextLine = lines[cursor] ?? "";
+        const nextTrimmed = nextLine.trim();
+        if (nextTrimmed.length === 0) {
+            if (blockIndent !== null)
+                blockLines.push("");
+            cursor += 1;
+            continue;
+        }
+        const indent = leadingWhitespaceLength(nextLine);
+        if (indent === 0)
+            break;
+        if (blockIndent === null)
+            blockIndent = indent;
+        if (indent < blockIndent)
+            break;
+        blockLines.push(nextLine.slice(blockIndent));
+        cursor += 1;
+    }
+    return {
+        value: style === "folded" ? foldYamlBlock(blockLines) : blockLines.join("\n").trimEnd(),
+        nextIndex: cursor,
+    };
+}
 function parseYamlFrontmatter(frontmatterText) {
     const lines = frontmatterText.split("\n");
     const frontmatter = {};
@@ -88,6 +148,13 @@ function parseYamlFrontmatter(frontmatterText) {
         if (!key)
             return null;
         if (inlineValue && inlineValue.trim().length > 0) {
+            const blockStyle = yamlBlockHeader(inlineValue);
+            if (blockStyle) {
+                const parsedBlock = parseYamlBlockScalar(lines, index, blockStyle);
+                frontmatter[key] = parsedBlock.value;
+                index = parsedBlock.nextIndex - 1;
+                continue;
+            }
             frontmatter[key] = parseYamlScalar(inlineValue);
             continue;
         }

package/dist/packages/projects/index.d.ts

@@ -0,0 +1,6 @@
+export * as schema from "./lib/schema.js";
+export * as sourceConfig from "./source-config.js";
+export * as sourceFolders from "./source-folders.js";
+export * as interf from "./interf.js";
+export * as detect from "./interf-detect.js";
+export type { InterfConfig, BuildPlanId, ProjectId, SourceFolderBinding, ProjectConfig, BenchmarkCheck, SourceContext, SourceFolderConfig, } from "./lib/schema.js";

package/dist/packages/{project → projects}/index.js

@@ -3,6 +3,3 @@ export * as sourceConfig from "./source-config.js";
 export * as sourceFolders from "./source-folders.js";
 export * as interf from "./interf.js";
 export * as detect from "./interf-detect.js";
-export * as bootstrap from "./interf-bootstrap.js";
-export * as scaffold from "./interf-scaffold.js";
-export * as preparationEntries from "./preparation-entries.js";

package/dist/packages/{project → projects}/interf-detect.d.ts

@@ -1,8 +1,8 @@
 import { type InterfConfig } from "./lib/schema.js";
 export type { InterfConfig } from "./lib/schema.js";
-export interface ResolvedVerifiableContext {
-    prepDataDir: string;
-    verifiableContextPath: string;
+export interface ResolvedContextGraph {
+    projectDataDir: string;
+    contextGraphPath: string;
     config: InterfConfig;
 }
 export declare const INTERF_CONTAINER_NAME = "interf";
@@ -16,23 +16,23 @@ export declare function hasSourceFolderInput(config: InterfConfig | null | undef
         path: string;
     };
 };
-export declare function hasSourcePreparationInput(config: InterfConfig | null | undefined): config is InterfConfig & {
+export declare function hasSourceProjectInput(config: InterfConfig | null | undefined): config is InterfConfig & {
     source: {
-        preparation_path: string;
+        project_path: string;
     };
 };
 export declare function detectInterf(cwd: string): {
     path: string;
     config: InterfConfig;
 } | null;
-export declare function resolveVerifiableContext(cwd: string): ResolvedVerifiableContext | null;
-export declare function resolveSourceFolderPath(verifiableContextPath: string, config?: InterfConfig | null): string;
-export declare function resolveSourceControlPath(verifiableContextPath: string): string;
-export declare function resolveSourceInputPath(verifiableContextPath: string): string;
-export declare function listVerifiableContextsForSourceFolder(prepDataDir: string): Array<{
+export declare function resolveContextGraph(cwd: string): ResolvedContextGraph | null;
+export declare function resolveSourceFolderPath(contextGraphPath: string, config?: InterfConfig | null): string;
+export declare function resolveSourceControlPath(contextGraphPath: string): string;
+export declare function resolveSourceInputPath(contextGraphPath: string): string;
+export declare function listContextGraphsForSourceFolder(projectDataDir: string): Array<{
     path: string;
     config: InterfConfig;
 }>;
-export declare function assertVerifiableContextContainer(prepDataDir: string): string;
+export declare function assertContextGraphContainer(projectDataDir: string): string;
 export declare function assertWritableTargetDir(dirPath: string, label: string): void;
-export declare function assertVerifiableContextName(name: string, label: string): void;
+export declare function assertContextGraphName(name: string, label: string): void;

package/dist/packages/{project → projects}/interf-detect.js

@@ -2,8 +2,8 @@ import { existsSync, readdirSync, statSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { warnInterf } from "../contracts/utils/logger.js";
 import { readJsonFileUnchecked } from "../contracts/utils/parse.js";
-import { asPreparationDataDir, preparationVerifiableContextPath, } from "../contracts/lib/preparation-paths.js";
-import { resolveSourceControlPathForVerifiableContext, verifiableContextInterfConfigPath, } from "../engine/build/verifiable-context-paths.js";
+import { asProjectDataDir, projectContextGraphPath, } from "../contracts/lib/project-paths.js";
+import { resolveSourceControlPathForContextGraph, contextGraphInterfConfigPath, } from "../runtime/build/context-graph-paths.js";
 import { InterfConfigSchema, } from "./lib/schema.js";
 import { assertPathWithinRoot } from "../contracts/utils/path-guards.js";
 export const INTERF_CONTAINER_NAME = "interf";
@@ -12,7 +12,7 @@ export const TEST_CONTAINER_NAME = "tests";
 export const INTERF_CONFIG_FILE = "interf.json";
 export const BUILD_PLAN_PACKAGE_DIR = "build-plan";
 export function readInterfConfig(dirPath) {
-    const configPath = verifiableContextInterfConfigPath(dirPath);
+    const configPath = contextGraphInterfConfigPath(dirPath);
     if (!existsSync(configPath))
         return null;
     const raw = readJsonFileUnchecked(configPath, "Interf config");
@@ -20,7 +20,7 @@ export function readInterfConfig(dirPath) {
         return null;
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return null;
-    if (raw.type !== "verifiable-context") {
+    if (raw.type !== "context-graph") {
         return null;
     }
     const parsed = InterfConfigSchema.safeParse(raw);
@@ -33,8 +33,8 @@ export function readInterfConfig(dirPath) {
 export function hasSourceFolderInput(config) {
     return typeof config?.source?.path === "string" && config.source.path.length > 0;
 }
-export function hasSourcePreparationInput(config) {
-    return typeof config?.source?.preparation_path === "string" && config.source.preparation_path.length > 0;
+export function hasSourceProjectInput(config) {
+    return typeof config?.source?.project_path === "string" && config.source.project_path.length > 0;
 }
 export function detectInterf(cwd) {
     const config = readInterfConfig(cwd);
@@ -42,70 +42,76 @@ export function detectInterf(cwd) {
         return { path: cwd, config };
     return null;
 }
-export function resolveVerifiableContext(cwd) {
+export function resolveContextGraph(cwd) {
     const detected = detectInterf(cwd);
     if (!detected)
         return null;
     return {
-        prepDataDir: resolveSourceControlPath(detected.path),
-        verifiableContextPath: detected.path,
+        projectDataDir: resolveSourceControlPath(detected.path),
+        contextGraphPath: detected.path,
         config: detected.config,
     };
 }
-export function resolveSourceFolderPath(verifiableContextPath, config = null) {
-    const resolvedConfig = config ?? readInterfConfig(verifiableContextPath);
-    if (hasSourcePreparationInput(resolvedConfig)) {
-        return resolve(verifiableContextPath, resolvedConfig.source.preparation_path);
+export function resolveSourceFolderPath(contextGraphPath, config = null) {
+    const resolvedConfig = config ?? readInterfConfig(contextGraphPath);
+    if (hasSourceProjectInput(resolvedConfig)) {
+        return resolve(contextGraphPath, resolvedConfig.source.project_path);
     }
     if (hasSourceFolderInput(resolvedConfig)) {
-        return assertPathWithinRoot(verifiableContextPath, resolve(verifiableContextPath, resolvedConfig.source.path), "Verifiable context source path");
+        return assertPathWithinRoot(contextGraphPath, resolve(contextGraphPath, resolvedConfig.source.path), "Context Graph source path");
     }
-    throw new Error(`Verifiable context at ${verifiableContextPath} is missing source.preparation_path or source.path in ${verifiableContextInterfConfigPath(verifiableContextPath)}.`);
+    throw new Error(`Context Graph at ${contextGraphPath} is missing source.project_path or source.path in ${contextGraphInterfConfigPath(contextGraphPath)}.`);
 }
-export function resolveSourceControlPath(verifiableContextPath) {
-    return resolveSourceControlPathForVerifiableContext(verifiableContextPath);
+export function resolveSourceControlPath(contextGraphPath) {
+    return resolveSourceControlPathForContextGraph(contextGraphPath);
 }
-export function resolveSourceInputPath(verifiableContextPath) {
-    const config = readInterfConfig(verifiableContextPath);
-    if (hasSourcePreparationInput(config)) {
-        return resolve(verifiableContextPath, config.source.preparation_path);
+export function resolveSourceInputPath(contextGraphPath) {
+    const config = readInterfConfig(contextGraphPath);
+    if (hasSourceProjectInput(config)) {
+        return resolve(contextGraphPath, config.source.project_path);
     }
-    throw new Error(`Verifiable context is missing source.preparation_path in ${verifiableContextInterfConfigPath(verifiableContextPath)}.`);
+    throw new Error(`Context Graph is missing source.project_path in ${contextGraphInterfConfigPath(contextGraphPath)}.`);
 }
-export function listVerifiableContextsForSourceFolder(prepDataDir) {
-    if (!existsSync(prepDataDir))
+export function listContextGraphsForSourceFolder(projectDataDir) {
+    if (!existsSync(projectDataDir))
         return [];
     try {
-        if (!statSync(prepDataDir).isDirectory())
+        if (!statSync(projectDataDir).isDirectory())
             return [];
     }
     catch (error) {
-        warnInterf(`Warning: failed to inspect Interf preparation data folder at ${prepDataDir}: ${error instanceof Error ? error.message : String(error)}`);
+        warnInterf(`Warning: failed to inspect Interf Project data folder at ${projectDataDir}: ${error instanceof Error ? error.message : String(error)}`);
         return [];
     }
-    return readdirSync(prepDataDir)
+    return readdirSync(projectDataDir)
         .filter((entry) => !entry.startsWith(".") &&
         entry !== BUILD_PLAN_CONTAINER_NAME &&
         entry !== TEST_CONTAINER_NAME &&
         entry !== INTERF_CONFIG_FILE)
-        .map((entry) => preparationVerifiableContextPath(asPreparationDataDir(prepDataDir), entry))
-        .filter((verifiableContextPath) => existsSync(verifiableContextPath))
-        .map((verifiableContextPath) => {
-        const config = readInterfConfig(verifiableContextPath);
-        return config ? { path: verifiableContextPath, config } : null;
+        .map((entry) => projectContextGraphPath(asProjectDataDir(projectDataDir), entry))
+        .filter((contextGraphPath) => existsSync(contextGraphPath))
+        .map((contextGraphPath) => {
+        const config = readInterfConfig(contextGraphPath);
+        return config ? { path: contextGraphPath, config } : null;
     })
         .filter((value) => value !== null);
 }
-export function assertVerifiableContextContainer(prepDataDir) {
-    if (existsSync(prepDataDir)) {
-        const stat = statSync(prepDataDir);
+export function assertContextGraphContainer(projectDataDir) {
+    if (existsSync(projectDataDir)) {
+        const stat = statSync(projectDataDir);
         if (!stat.isDirectory()) {
-            throw new Error(`Interf preparation data folder exists and is not a directory: ${prepDataDir}`);
+            throw new Error(`Interf Project data folder exists and is not a directory: ${projectDataDir}`);
         }
-        const unexpectedRootEntries = readdirSync(prepDataDir).filter((entry) => {
+        const unexpectedRootEntries = readdirSync(projectDataDir).filter((entry) => {
             if (entry.startsWith("."))
                 return false;
-            const entryPath = join(prepDataDir, entry);
+            // Tolerate interf.json migration backups (e.g.
+            // interf.json.pre-ownership-refactor-<ts>.bak) that older migrations
+            // left in the Project root — they are benign and must not block Builds.
+            if (entry !== INTERF_CONFIG_FILE && entry.startsWith(`${INTERF_CONFIG_FILE}.`)) {
+                return false;
+            }
+            const entryPath = join(projectDataDir, entry);
             if (entry === INTERF_CONFIG_FILE) {
                 try {
                     return !statSync(entryPath).isFile();
@@ -121,7 +127,7 @@ export function assertVerifiableContextContainer(prepDataDir) {
                     return !statSync(entryPath).isDirectory();
                 }
                 catch (error) {
-                    warnInterf(`Warning: failed to inspect Interf preparation data path at ${entryPath}: ${error instanceof Error ? error.message : String(error)}`);
+                    warnInterf(`Warning: failed to inspect Interf Project data path at ${entryPath}: ${error instanceof Error ? error.message : String(error)}`);
                     return true;
                 }
             }
@@ -134,21 +140,21 @@ export function assertVerifiableContextContainer(prepDataDir) {
             }
         });
         if (unexpectedRootEntries.length > 0) {
-            throw new Error(`Interf preparation data folder contains unexpected entries: ${prepDataDir}`);
+            throw new Error(`Interf Project data folder contains unexpected entries: ${projectDataDir}`);
         }
     }
-    if (!existsSync(prepDataDir)) {
-        return prepDataDir;
+    if (!existsSync(projectDataDir)) {
+        return projectDataDir;
     }
-    const stat = statSync(prepDataDir);
+    const stat = statSync(projectDataDir);
     if (!stat.isDirectory()) {
-        throw new Error(`Interf preparation data folder exists and is not a directory: ${prepDataDir}`);
+        throw new Error(`Interf Project data folder exists and is not a directory: ${projectDataDir}`);
     }
-    const unexpectedEntries = readdirSync(prepDataDir).filter((entry) => {
+    const unexpectedEntries = readdirSync(projectDataDir).filter((entry) => {
         if (entry.startsWith("."))
             return false;
         if (entry === INTERF_CONFIG_FILE) {
-            const entryPath = join(prepDataDir, entry);
+            const entryPath = join(projectDataDir, entry);
             try {
                 return !statSync(entryPath).isFile();
             }
@@ -160,7 +166,7 @@ export function assertVerifiableContextContainer(prepDataDir) {
         if (entry === BUILD_PLAN_CONTAINER_NAME ||
             entry === TEST_CONTAINER_NAME)
             return false;
-        const entryPath = join(prepDataDir, entry);
+        const entryPath = join(projectDataDir, entry);
         try {
             if (!statSync(entryPath).isDirectory())
                 return true;
@@ -172,9 +178,9 @@ export function assertVerifiableContextContainer(prepDataDir) {
         return false;
     });
     if (unexpectedEntries.length > 0) {
-        throw new Error(`Interf preparation data folder contains invalid Preparation entries: ${prepDataDir}`);
+        throw new Error(`Interf Project data folder contains invalid Project entries: ${projectDataDir}`);
     }
-    return prepDataDir;
+    return projectDataDir;
 }
 export function assertWritableTargetDir(dirPath, label) {
     if (!existsSync(dirPath))
@@ -187,7 +193,7 @@ export function assertWritableTargetDir(dirPath, label) {
         throw new Error(`${label} target already exists and is not empty: ${dirPath}`);
     }
 }
-export function assertVerifiableContextName(name, label) {
+export function assertContextGraphName(name, label) {
     if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
         throw new Error(`${label} name must be a safe slug with lowercase letters, numbers, and dashes only: ${name}`);
     }

package/dist/packages/projects/interf.d.ts

@@ -0,0 +1,2 @@
+export { INTERF_CONTAINER_NAME, BUILD_PLAN_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, BUILD_PLAN_PACKAGE_DIR, readInterfConfig, detectInterf, resolveContextGraph, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listContextGraphsForSourceFolder, hasSourceFolderInput, assertContextGraphContainer, assertWritableTargetDir, assertContextGraphName, } from "./interf-detect.js";
+export type { InterfConfig, ResolvedContextGraph } from "./interf-detect.js";

package/dist/packages/projects/interf.js

@@ -0,0 +1 @@
+export { INTERF_CONTAINER_NAME, BUILD_PLAN_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, BUILD_PLAN_PACKAGE_DIR, readInterfConfig, detectInterf, resolveContextGraph, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listContextGraphsForSourceFolder, hasSourceFolderInput, assertContextGraphContainer, assertWritableTargetDir, assertContextGraphName, } from "./interf-detect.js";

package/dist/packages/projects/lib/schema.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+export { BuildPlanIdSchema, ProjectIdSchema, } from "../../contracts/lib/schema.js";
+export declare const BenchmarkCheckSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    question: z.ZodString;
+    answer: z.ZodOptional<z.ZodString>;
+    expect: z.ZodOptional<z.ZodObject<{
+        must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min_words: z.ZodOptional<z.ZodNumber>;
+        max_words: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    strictness: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export { RequestedArtifactCheckSchema, RequestedArtifactOutputSchema, RequestedArtifactSchema, SourceContextItemSchema, SourceContextSchema, } from "../../build-plans/authoring/brief.js";
+export declare const ProjectConfigSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
+    path: z.ZodString;
+    build_plan: z.ZodOptional<z.ZodString>;
+    latest_context_graph_run_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const SourceFolderBindingSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$loose>;
+export declare const ContextGraphInterfConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"context-graph">;
+    name: z.ZodString;
+    intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
+    build_plan: z.ZodString;
+    build_plan_origin: z.ZodOptional<z.ZodObject<{
+        selected: z.ZodString;
+        local_draft: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    source: z.ZodObject<{
+        path: z.ZodString;
+        control_path: z.ZodOptional<z.ZodString>;
+        project_path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const InterfConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"context-graph">;
+    name: z.ZodString;
+    intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
+    build_plan: z.ZodString;
+    build_plan_origin: z.ZodOptional<z.ZodObject<{
+        selected: z.ZodString;
+        local_draft: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    source: z.ZodObject<{
+        path: z.ZodString;
+        control_path: z.ZodOptional<z.ZodString>;
+        project_path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const SourceFolderConfigSchema: z.ZodObject<{
+    source_folder: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$loose>>;
+    projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        intent: z.ZodDefault<z.ZodUnion<[z.ZodString, z.ZodLiteral<"">]>>;
+        path: z.ZodString;
+        build_plan: z.ZodOptional<z.ZodString>;
+        latest_context_graph_run_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SourceFolderBinding = z.infer<typeof SourceFolderBindingSchema>;
+export type BenchmarkCheck = z.infer<typeof BenchmarkCheckSchema>;
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+export type { RequestedArtifactCheck, RequestedArtifact, RequestedArtifactOutput, SourceContext, } from "../../build-plans/authoring/brief.js";
+export type { ProjectId, BuildPlanId, ProjectIntent, } from "../../contracts/lib/schema.js";
+export type InterfConfig = z.infer<typeof InterfConfigSchema>;
+export type SourceFolderConfig = z.infer<typeof SourceFolderConfigSchema>;

package/dist/packages/projects/lib/schema.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { InterfIdPattern, BuildPlanIdSchema, ProjectIdSchema, ProjectIntentSchema, TestCaseExpectSchema, } from "../../contracts/lib/schema.js";
+export { BuildPlanIdSchema, ProjectIdSchema, } from "../../contracts/lib/schema.js";
+/**
+ * Absolute paths that an attacker-controlled config must never reach. The
+ * build runtime treats `project.path` as a filesystem instruction — letting
+ * a browser-tab forge `/etc` or `/sys` could mutate or read system state.
+ * The list mirrors the CSO review allowlist.
+ */
+const FORBIDDEN_ABSOLUTE_PATH_PREFIXES = [
+    "/etc",
+    "/sys",
+    "/proc",
+    "/dev",
+    "/var/run",
+    "/var/lib",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/boot",
+];
+function normalizePathForValidation(value) {
+    const normalized = value.replace(/\\/g, "/").replace(/\/+/g, "/");
+    if (normalized.length > 1)
+        return normalized.replace(/\/$/, "");
+    return normalized;
+}
+function isForbiddenAbsolutePath(value) {
+    const normalized = normalizePathForValidation(value);
+    for (const prefix of FORBIDDEN_ABSOLUTE_PATH_PREFIXES) {
+        if (normalized === prefix || normalized.startsWith(`${prefix}/`))
+            return true;
+    }
+    return false;
+}
+export const BenchmarkCheckSchema = z.object({
+    id: z.string().regex(InterfIdPattern).optional(),
+    question: z.string().min(1),
+    answer: z.string().min(1).optional(),
+    expect: TestCaseExpectSchema.optional(),
+    strictness: z.string().min(1).optional(),
+}).strict().superRefine((value, ctx) => {
+    if (!value.answer && !value.expect) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["answer"],
+            message: "Benchmark checks need `answer` or `expect`.",
+        });
+    }
+});
+export { RequestedArtifactCheckSchema, RequestedArtifactOutputSchema, RequestedArtifactSchema, SourceContextItemSchema, SourceContextSchema, } from "../../build-plans/authoring/brief.js";
+export const ProjectConfigSchema = z.object({
+    id: z.string().regex(InterfIdPattern).optional(),
+    name: ProjectIdSchema,
+    intent: ProjectIntentSchema.or(z.literal("")).default(""),
+    path: z
+        .string()
+        .min(1)
+        .refine((value) => !isForbiddenAbsolutePath(value), {
+        message: "Project Source path may not target system directories (/etc, /sys, /proc, /dev, /usr, /bin, /sbin, /boot, /var/run, /var/lib).",
+    })
+        .refine((value) => !value.split(/[/\\]/).some((segment) => segment === ".."), {
+        message: "Project Source path may not contain `..` segments.",
+    }),
+    build_plan: BuildPlanIdSchema.optional(),
+    latest_context_graph_run_id: z.string().min(1).optional(),
+}).strict();
+export const SourceFolderBindingSchema = z.object({
+    path: z.string().min(1),
+}).passthrough();
+export const ContextGraphInterfConfigSchema = z.object({
+    type: z.literal("context-graph"),
+    name: ProjectIdSchema,
+    intent: ProjectIntentSchema.or(z.literal("")).default(""),
+    build_plan: BuildPlanIdSchema,
+    build_plan_origin: z.object({
+        selected: BuildPlanIdSchema,
+        local_draft: z.boolean().optional(),
+    }).optional(),
+    source: z.object({
+        path: z.string(),
+        control_path: z.string().optional(),
+        project_path: z.string().optional(),
+    }),
+});
+export const InterfConfigSchema = ContextGraphInterfConfigSchema;
+export const SourceFolderConfigSchema = z.object({
+    source_folder: SourceFolderBindingSchema.optional(),
+    /** Project entries inside `interf.json`. */
+    projects: z.array(ProjectConfigSchema).default([]),
+}).strict();

package/dist/packages/projects/source-config.d.ts

@@ -0,0 +1,53 @@
+import { type InterfConfig, type SourceFolderBinding, type BenchmarkCheck, type ProjectConfig, type SourceFolderConfig } from "./lib/schema.js";
+import type { TestSpec, TestTargetType } from "../runtime/verify/lib/schema.js";
+interface LoadedSourceTestSpec extends TestSpec {
+    id: string;
+    filePath: string;
+}
+export declare function sourceFolderConfigPath(projectDataDir: string): string;
+export declare function fingerprintBenchmarkChecks(checks: BenchmarkCheck[]): string;
+export declare function loadSourceFolderConfig(projectDataDir: string): SourceFolderConfig | null;
+export interface WritableSourceFolderConfig {
+    source_folder?: SourceFolderBinding;
+    projects?: ProjectConfig[];
+}
+export { DEFAULT_BUILD_PLAN_ID, buildPlanIdForProjectConfig } from "../build-plans/build-plan-resolution.js";
+export declare function listProjectConfigs(config: SourceFolderConfig | null): ProjectConfig[];
+export declare function resolveBuildMaxAttempts(override?: number | null): number | null;
+export declare function resolveBuildMaxLoops(override?: number | null): number | null;
+export declare function findProjectConfig(config: SourceFolderConfig | null, projectId: string): ProjectConfig | null;
+export declare function resolveConfiguredSourceFolderPath(projectDataDir: string, config?: SourceFolderConfig | WritableSourceFolderConfig | null | undefined): string | null;
+export declare function saveSourceFolderConfig(projectDataDir: string, config: WritableSourceFolderConfig): void;
+export declare function upsertProjectConfig(projectDataDir: string, projectConfig: ProjectConfig, options?: {
+    matchName?: string;
+}): void;
+export declare function markProjectLatestContextGraphRun(projectDataDir: string, projectName: string, runId: string): ProjectConfig;
+export declare function projectConfigFromInterfConfig(config: InterfConfig, projectPath?: string): ProjectConfig;
+export declare function loadContextGraphProjectConfig(contextGraphPath: string): ProjectConfig | null;
+export declare function saveContextGraphInterfConfig(contextGraphPath: string, config: InterfConfig): InterfConfig;
+export declare function syncContextGraphInterfConfigFromProjectConfig(contextGraphPath: string, projectConfig: ProjectConfig): InterfConfig;
+export declare function buildTestSpecFromSourceFolderConfig(options: {
+    projectDataDir: string;
+    targetName?: string | null;
+    targetType?: TestTargetType;
+}): LoadedSourceTestSpec | null;
+export declare function buildTestSpecFromProjectConfig(options: {
+    contextGraphPath: string;
+    targetType?: TestTargetType;
+}): LoadedSourceTestSpec | null;
+export declare function writeBenchmarkSpecsForProject(options: {
+    projectDataDir: string;
+    projectName: string;
+    checks: BenchmarkCheck[];
+    description?: string;
+}): {
+    source_files?: string;
+    context_graph?: string;
+};
+export declare function fingerprintSavedBenchmarkSpec(options: {
+    projectDataDir: string;
+    projectName: string;
+    targetType?: TestTargetType;
+}): string | null;
+export declare function resolveProjectSourcePath(projectDataDir: string, projectConfig: Pick<ProjectConfig, "path">): string;
+export declare function resolveProjectSourceBindingPath(projectDataDir: string, projectConfig: Pick<ProjectConfig, "path">, config?: SourceFolderConfig | WritableSourceFolderConfig | null | undefined): string;