@growthub/cli 0.6.0 → 0.6.1

package/dist/kits/core/adapter-core/fork-inspector.js

@@ -0,0 +1,141 @@
+/**
+ * Fork Adapter Core — Fork Inspector
+ *
+ * Reusable inspection primitives for any kit that wraps a forked open-source repo.
+ *
+ * The inspector does not run the fork — it validates that the declared inspection
+ * surface (required planning files, source-of-truth files) is present in the
+ * local checkout before the agent begins planning.
+ *
+ * This encodes the core rule: "inspect actual fork before planning".
+ * Agents that skip fork inspection must mark their output as `assumption-based`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { makeWarning, makeInfo } from "../types/index.js";
+// ---------------------------------------------------------------------------
+// Resolve local fork root
+// ---------------------------------------------------------------------------
+export function resolveForkRoot(contract, overridePath) {
+    const candidates = [];
+    if (overridePath) {
+        candidates.push(path.resolve(overridePath));
+    }
+    // Expand ~ in defaultLocalPath
+    const defaultPath = contract.defaultLocalPath.replace(/^~/, process.env["HOME"] ?? "~");
+    candidates.push(path.resolve(defaultPath));
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Inspect fork at resolved root
+// ---------------------------------------------------------------------------
+export function inspectFork(contract, options = {}) {
+    const issues = [];
+    const passedChecks = [];
+    const forkRoot = resolveForkRoot(contract, options.forkRootOverride);
+    if (!forkRoot) {
+        issues.push(makeWarning("FORK_NOT_FOUND", `Local fork not found at ${contract.defaultLocalPath}. Run: bash setup/clone-fork.sh OR switch to browser-hosted mode.`));
+        issues.push(makeInfo("FORK_VERIFICATION_STATUS", "Proceeding as assumption-based — mark all outputs as assumption-based."));
+        return {
+            valid: true, // non-blocking — fork is optional, just changes verification status
+            issues,
+            passedChecks,
+            forkRoot: null,
+            forkFound: false,
+            verificationStatus: "assumption-based",
+            presentPlanningFiles: [],
+            missingPlanningFiles: contract.inspectionRules.requiredPlanningFiles,
+            presentSourceOfTruthFiles: [],
+            missingSourceOfTruthFiles: contract.inspectionRules.sourceOfTruthFiles,
+            fileMetadata: [],
+        };
+    }
+    passedChecks.push("fork-found");
+    const presentPlanningFiles = [];
+    const missingPlanningFiles = [];
+    const presentSourceOfTruthFiles = [];
+    const missingSourceOfTruthFiles = [];
+    const fileMetadata = [];
+    // Check required planning files
+    for (const relPath of contract.inspectionRules.requiredPlanningFiles) {
+        const fullPath = path.resolve(forkRoot, relPath);
+        const exists = fs.existsSync(fullPath);
+        const meta = buildFileMetadata(fullPath, relPath, exists, options.includeHashes);
+        fileMetadata.push(meta);
+        if (exists) {
+            presentPlanningFiles.push(relPath);
+            passedChecks.push(`planning-file:${relPath}`);
+        }
+        else {
+            missingPlanningFiles.push(relPath);
+            issues.push(makeWarning("PLANNING_FILE_MISSING", `Required planning file not found in fork: ${relPath}. Planning may be inaccurate without it.`, relPath));
+        }
+    }
+    // Check source-of-truth files
+    for (const relPath of contract.inspectionRules.sourceOfTruthFiles) {
+        if (contract.inspectionRules.requiredPlanningFiles.includes(relPath))
+            continue; // already checked
+        const fullPath = path.resolve(forkRoot, relPath);
+        const exists = fs.existsSync(fullPath);
+        const meta = buildFileMetadata(fullPath, relPath, exists, options.includeHashes);
+        fileMetadata.push(meta);
+        if (exists) {
+            presentSourceOfTruthFiles.push(relPath);
+            passedChecks.push(`sot-file:${relPath}`);
+        }
+        else {
+            missingSourceOfTruthFiles.push(relPath);
+            issues.push(makeInfo("SOT_FILE_MISSING", `Source-of-truth file not found in fork: ${relPath}. Some planning constraints may rely on upstream assumptions.`));
+        }
+    }
+    const verificationStatus = missingPlanningFiles.length === 0 ? "fork-verified" : "upstream-verified";
+    if (contract.inspectionRules.note) {
+        issues.push(makeInfo("FORK_INSPECTION_NOTE", contract.inspectionRules.note));
+    }
+    return {
+        valid: true,
+        issues,
+        passedChecks,
+        forkRoot,
+        forkFound: true,
+        verificationStatus,
+        presentPlanningFiles,
+        missingPlanningFiles,
+        presentSourceOfTruthFiles,
+        missingSourceOfTruthFiles,
+        fileMetadata,
+    };
+}
+// ---------------------------------------------------------------------------
+// File metadata builder
+// ---------------------------------------------------------------------------
+function buildFileMetadata(fullPath, relativePath, exists, includeHashes = false) {
+    if (!exists)
+        return { relativePath, exists: false };
+    const stat = fs.statSync(fullPath);
+    const meta = {
+        relativePath,
+        exists: true,
+        sizeBytes: stat.size,
+        mtimeMs: stat.mtimeMs,
+    };
+    if (includeHashes) {
+        const content = fs.readFileSync(fullPath);
+        meta.sha256 = crypto.createHash("sha256").update(content).digest("hex");
+    }
+    return meta;
+}
+// ---------------------------------------------------------------------------
+// Assert a single file is present in the fork (utility for agent planning checks)
+// ---------------------------------------------------------------------------
+export function assertForkFileExists(forkRoot, relativePath) {
+    const fullPath = path.resolve(forkRoot, relativePath);
+    return { exists: fs.existsSync(fullPath), fullPath };
+}
+//# sourceMappingURL=fork-inspector.js.map

package/dist/kits/core/adapter-core/fork-inspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork-inspector.js","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/fork-inspector.ts"],"names":[],"mappings":"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"}

package/dist/kits/core/adapter-core/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fork Adapter Core — Barrel Export
+ *
+ * Single import surface for all adapter-core modules.
+ * Import from here in factory definitions and validation runners.
+ */
+export type { ProviderOperationContract, EnvironmentGateContract, SetupPathContract, ForkInspectionContract, RuntimeSurfaceContract, OutputContract, ForkAdapterCoreConfig, } from "./contracts.js";
+export { parseEnvFile, runEnvGate, formatEnvGateResult, } from "./env-gate.js";
+export type { EnvGateResult } from "./env-gate.js";
+export { validateSetup, validateEnvExample, } from "./setup-validation.js";
+export type { SetupValidationResult } from "./setup-validation.js";
+export { resolveForkRoot, inspectFork, assertForkFileExists, } from "./fork-inspector.js";
+export type { ForkInspectionResult, ForkFileMetadata, ForkVerificationStatus, } from "./fork-inspector.js";
+export { validateProviderContract, buildMuapiProviderContract, buildProviderContract, } from "./provider-adapter.js";
+export type { ProviderAdapterValidationResult } from "./provider-adapter.js";
+export { validateRuntimeSurfaceContract, buildStudioRuntimeSurfaceContract, formatSurfaceSelectionNote, } from "./runtime-surface.js";
+export type { RuntimeSurfaceValidationResult } from "./runtime-surface.js";
+export { validateOutputContract, buildStudioOutputContract, } from "./output-contract.js";
+export type { OutputContractValidationResult } from "./output-contract.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/kits/core/adapter-core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EACL,eAAe,EACf,WAAW,EACX,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AAE7E,OAAO,EACL,8BAA8B,EAC9B,iCAAiC,EACjC,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EACL,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/kits/core/adapter-core/index.js

@@ -0,0 +1,13 @@
+/**
+ * Fork Adapter Core — Barrel Export
+ *
+ * Single import surface for all adapter-core modules.
+ * Import from here in factory definitions and validation runners.
+ */
+export { parseEnvFile, runEnvGate, formatEnvGateResult, } from "./env-gate.js";
+export { validateSetup, validateEnvExample, } from "./setup-validation.js";
+export { resolveForkRoot, inspectFork, assertForkFileExists, } from "./fork-inspector.js";
+export { validateProviderContract, buildMuapiProviderContract, buildProviderContract, } from "./provider-adapter.js";
+export { validateRuntimeSurfaceContract, buildStudioRuntimeSurfaceContract, formatSurfaceSelectionNote, } from "./runtime-surface.js";
+export { validateOutputContract, buildStudioOutputContract, } from "./output-contract.js";
+//# sourceMappingURL=index.js.map

package/dist/kits/core/adapter-core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,eAAe,EACf,WAAW,EACX,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,8BAA8B,EAC9B,iCAAiC,EACjC,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC"}

package/dist/kits/core/adapter-core/output-contract.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fork Adapter Core — Output Contract Validator
+ *
+ * Reusable output contract validator for any kit that writes structured
+ * deliverables to a working directory.
+ *
+ * Validates:
+ *   - required output directories exist (or can be created)
+ *   - declared artifact names are non-empty and unique
+ *   - output root pattern is well-formed
+ *   - output standards doc exists in the kit
+ *   - deliverable log requirement is explicitly declared
+ */
+import type { OutputContract } from "./contracts.js";
+import type { CoreValidationResult } from "../types/index.js";
+export interface OutputContractValidationResult extends CoreValidationResult {
+    outputRootPattern: string;
+    artifactCount: number;
+    duplicateArtifactNames: string[];
+    missingRequiredArtifacts: string[];
+    outputStandardsDocPresent: boolean;
+}
+export declare function validateOutputContract(kitRoot: string, contract: OutputContract): OutputContractValidationResult;
+export declare function buildStudioOutputContract(): OutputContract;
+//# sourceMappingURL=output-contract.d.ts.map

package/dist/kits/core/adapter-core/output-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-contract.d.ts","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/output-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAmB,MAAM,mBAAmB,CAAC;AAO/E,MAAM,WAAW,8BAA+B,SAAQ,oBAAoB;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,yBAAyB,EAAE,OAAO,CAAC;CACpC;AAMD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,GACvB,8BAA8B,CA2GhC;AAMD,wBAAgB,yBAAyB,IAAI,cAAc,CAiB1D"}

package/dist/kits/core/adapter-core/output-contract.js

@@ -0,0 +1,114 @@
+/**
+ * Fork Adapter Core — Output Contract Validator
+ *
+ * Reusable output contract validator for any kit that writes structured
+ * deliverables to a working directory.
+ *
+ * Validates:
+ *   - required output directories exist (or can be created)
+ *   - declared artifact names are non-empty and unique
+ *   - output root pattern is well-formed
+ *   - output standards doc exists in the kit
+ *   - deliverable log requirement is explicitly declared
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { makeError, makeWarning, makeInfo } from "../types/index.js";
+// ---------------------------------------------------------------------------
+// Validate an output contract declaration
+// ---------------------------------------------------------------------------
+export function validateOutputContract(kitRoot, contract) {
+    const issues = [];
+    const passedChecks = [];
+    const duplicateArtifactNames = [];
+    const missingRequiredArtifacts = [];
+    // Validate output root pattern is declared
+    if (!contract.outputRootPattern.trim()) {
+        issues.push(makeError("OUTPUT_ROOT_PATTERN_EMPTY", "outputRootPattern must be a non-empty string.", "outputRootPattern"));
+    }
+    else if (!contract.outputRootPattern.includes("<client-slug>")) {
+        issues.push(makeWarning("OUTPUT_ROOT_NO_CLIENT_SLUG", 'outputRootPattern does not include <client-slug>. Multi-client output namespacing is recommended.', "outputRootPattern"));
+    }
+    else {
+        passedChecks.push("output-root-pattern-valid");
+    }
+    // Validate artifact names are unique
+    const seenNames = new Set();
+    for (const artifact of contract.artifacts) {
+        if (!artifact.name.trim()) {
+            issues.push(makeError("ARTIFACT_NAME_EMPTY", "Artifact name must be non-empty.", "artifacts"));
+            continue;
+        }
+        if (seenNames.has(artifact.name)) {
+            duplicateArtifactNames.push(artifact.name);
+            issues.push(makeError("ARTIFACT_NAME_DUPLICATE", `Duplicate artifact name: "${artifact.name}". Artifact names must be unique.`, "artifacts"));
+        }
+        seenNames.add(artifact.name);
+    }
+    if (duplicateArtifactNames.length === 0 && contract.artifacts.length > 0) {
+        passedChecks.push("artifact-names-unique");
+    }
+    // Validate at least one artifact is declared
+    if (contract.artifacts.length === 0) {
+        issues.push(makeWarning("NO_ARTIFACTS_DECLARED", "No output artifacts declared. Consider declaring expected deliverables."));
+    }
+    else {
+        passedChecks.push("artifacts-declared");
+    }
+    // Validate required artifacts have non-empty relative paths
+    for (const artifact of contract.artifacts.filter((a) => a.required)) {
+        if (!artifact.relativePath.trim()) {
+            missingRequiredArtifacts.push(artifact.name);
+            issues.push(makeError("REQUIRED_ARTIFACT_NO_PATH", `Required artifact "${artifact.name}" has no relativePath declared.`, "artifacts"));
+        }
+    }
+    if (missingRequiredArtifacts.length === 0) {
+        passedChecks.push("required-artifact-paths-declared");
+    }
+    // Validate output standards doc exists
+    const outputStandardsDocPath = path.resolve(kitRoot, contract.outputStandardsDocPath);
+    const outputStandardsDocPresent = fs.existsSync(outputStandardsDocPath);
+    if (!outputStandardsDocPresent) {
+        issues.push(makeWarning("OUTPUT_STANDARDS_DOC_MISSING", `Output standards doc not found at ${contract.outputStandardsDocPath}.`, "outputStandardsDocPath"));
+    }
+    else {
+        passedChecks.push("output-standards-doc-present");
+    }
+    // Validate deliverable log requirement is explicit
+    if (contract.requiresDeliverableLog) {
+        passedChecks.push("deliverable-log-required");
+        issues.push(makeInfo("DELIVERABLE_LOG_REQUIRED", "This kit requires all completed deliverables to be logged in the active brand kit."));
+    }
+    return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues,
+        passedChecks,
+        outputRootPattern: contract.outputRootPattern,
+        artifactCount: contract.artifacts.length,
+        duplicateArtifactNames,
+        missingRequiredArtifacts,
+        outputStandardsDocPresent,
+    };
+}
+// ---------------------------------------------------------------------------
+// Standard Open Higgsfield Studio output contract factory
+// ---------------------------------------------------------------------------
+export function buildStudioOutputContract() {
+    return {
+        outputRootPattern: "output/<client-slug>/<project-slug>/",
+        requiresDeliverableLog: true,
+        outputStandardsDocPath: "output-standards.md",
+        artifacts: [
+            { name: "VisualCampaignBrief", relativePath: "visual-campaign-brief.md", required: true, description: "Campaign goals, brand context, and visual intent" },
+            { name: "StudioSelectionBrief", relativePath: "studio-selection-brief.md", required: true, description: "Studio mode selection with rationale and fallback" },
+            { name: "ModelSelectionRecommendation", relativePath: "model-selection-recommendation.md", required: true, description: "Model class, endpoint, constraints, and fallback model" },
+            { name: "ShotPlan", relativePath: "shot-plan.md", required: true, description: "Scene-by-scene shot descriptions and asset requirements" },
+            { name: "PromptMatrix", relativePath: "prompt-matrix.md", required: true, description: "Prompt variants keyed to shot plan entries" },
+            { name: "GenerationBatchPlan", relativePath: "generation-batch-plan.md", required: true, description: "Ordered generation sequence with timing and dependencies" },
+            { name: "AssetTracking", relativePath: "asset-tracking.md", required: true, description: "Upload history, generation history, and reuse decisions" },
+            { name: "ReviewQAChecklist", relativePath: "review-qa-checklist.md", required: true, description: "QA gates before considering the package complete" },
+            { name: "PlatformReadyExecutionHandoff", relativePath: "platform-ready-execution-handoff.md", required: true, description: "Complete operator handoff document — executable against the provider" },
+        ],
+    };
+}
+//# sourceMappingURL=output-contract.js.map

package/dist/kits/core/adapter-core/output-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-contract.js","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/output-contract.ts"],"names":[],"mappings":"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"}

package/dist/kits/core/adapter-core/provider-adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fork Adapter Core — Provider Adapter Contract & Validator
+ *
+ * Defines the typed planning/validation contract for provider adapters.
+ * This is NOT a provider client implementation — it validates that a kit's
+ * declared provider contract is complete, consistent, and documented.
+ *
+ * Any kit that wraps a provider-backed generation workflow declares a
+ * ProviderOperationContract in its ForkAdapterCoreConfig. This module
+ * validates that declaration at authoring time (CLI) and planning time (agent).
+ *
+ * Current reference provider: Muapi (muapi.io)
+ * Extension path: implement same contract for Replicate, fal.ai, RunPod, etc.
+ */
+import type { ProviderOperationContract } from "./contracts.js";
+import { type ProviderOperation, type CoreValidationResult } from "../types/index.js";
+export interface ProviderAdapterValidationResult extends CoreValidationResult {
+    providerId: string;
+    declaredOperations: ProviderOperation[];
+    missingRequiredOperations: ProviderOperation[];
+    referenceDocPresent: boolean;
+}
+export declare function validateProviderContract(kitRoot: string, contract: ProviderOperationContract): ProviderAdapterValidationResult;
+export declare function buildMuapiProviderContract(overrides?: Partial<ProviderOperationContract>): ProviderOperationContract;
+export declare function buildProviderContract(providerId: string, providerName: string, baseUrl: string, authField: string, referenceDocPath: string, additionalOperations?: ProviderOperation[]): ProviderOperationContract;
+//# sourceMappingURL=provider-adapter.d.ts.map

package/dist/kits/core/adapter-core/provider-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-adapter.d.ts","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/provider-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAK1B,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,+BAAgC,SAAQ,oBAAoB;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,yBAAyB,EAAE,iBAAiB,EAAE,CAAC;IAC/C,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAMD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,yBAAyB,GAClC,+BAA+B,CA0EjC;AAOD,wBAAgB,0BAA0B,CACxC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,yBAAyB,CAoB3B;AAMD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EACxB,oBAAoB,GAAE,iBAAiB,EAAO,GAC7C,yBAAyB,CAU3B"}

package/dist/kits/core/adapter-core/provider-adapter.js

@@ -0,0 +1,119 @@
+/**
+ * Fork Adapter Core — Provider Adapter Contract & Validator
+ *
+ * Defines the typed planning/validation contract for provider adapters.
+ * This is NOT a provider client implementation — it validates that a kit's
+ * declared provider contract is complete, consistent, and documented.
+ *
+ * Any kit that wraps a provider-backed generation workflow declares a
+ * ProviderOperationContract in its ForkAdapterCoreConfig. This module
+ * validates that declaration at authoring time (CLI) and planning time (agent).
+ *
+ * Current reference provider: Muapi (muapi.io)
+ * Extension path: implement same contract for Replicate, fal.ai, RunPod, etc.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { REQUIRED_PROVIDER_OPERATIONS, makeError, makeWarning, } from "../types/index.js";
+// ---------------------------------------------------------------------------
+// Validate a provider operation contract declaration
+// ---------------------------------------------------------------------------
+export function validateProviderContract(kitRoot, contract) {
+    const issues = [];
+    const passedChecks = [];
+    const missingRequiredOperations = [];
+    // Check provider ID is non-empty
+    if (!contract.providerId.trim()) {
+        issues.push(makeError("PROVIDER_ID_EMPTY", "providerId must be a non-empty string.", "providerId"));
+    }
+    else {
+        passedChecks.push("provider-id-present");
+    }
+    // Check all required operations are declared
+    for (const op of REQUIRED_PROVIDER_OPERATIONS) {
+        if (!contract.operations.includes(op)) {
+            missingRequiredOperations.push(op);
+            issues.push(makeError("PROVIDER_OPERATION_MISSING", `Required provider operation "${op}" is not declared for provider "${contract.providerId}".`, "operations"));
+        }
+    }
+    if (missingRequiredOperations.length === 0) {
+        passedChecks.push("required-operations-complete");
+    }
+    // Check auth fields are set
+    if (!contract.authMechanism) {
+        issues.push(makeError("PROVIDER_AUTH_MISSING", "authMechanism must be declared.", "authMechanism"));
+    }
+    else {
+        passedChecks.push("auth-mechanism-declared");
+    }
+    if (!contract.authField.trim()) {
+        issues.push(makeError("PROVIDER_AUTH_FIELD_EMPTY", "authField must be a non-empty string.", "authField"));
+    }
+    else {
+        passedChecks.push("auth-field-declared");
+    }
+    if (!contract.baseUrl.trim()) {
+        issues.push(makeError("PROVIDER_BASE_URL_EMPTY", "baseUrl must be a non-empty string.", "baseUrl"));
+    }
+    else {
+        passedChecks.push("base-url-declared");
+    }
+    // Check reference doc exists in kit
+    const refDocPath = path.resolve(kitRoot, contract.referenceDocPath);
+    const referenceDocPresent = fs.existsSync(refDocPath);
+    if (!referenceDocPresent) {
+        issues.push(makeWarning("PROVIDER_REF_DOC_MISSING", `Provider reference doc not found at ${contract.referenceDocPath}. Agents will plan without adapter documentation.`, "referenceDocPath"));
+    }
+    else {
+        passedChecks.push("reference-doc-present");
+    }
+    return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues,
+        passedChecks,
+        providerId: contract.providerId,
+        declaredOperations: contract.operations,
+        missingRequiredOperations,
+        referenceDocPresent,
+    };
+}
+// ---------------------------------------------------------------------------
+// Muapi reference provider contract factory
+// Used by Studio kits that wrap the Open Higgsfield AI → Muapi workflow
+// ---------------------------------------------------------------------------
+export function buildMuapiProviderContract(overrides = {}) {
+    return {
+        providerId: "muapi",
+        providerName: "Muapi",
+        operations: [
+            "UPLOAD_ASSET",
+            "SUBMIT_GENERATION",
+            "POLL_RESULT",
+            "NORMALIZE_RESULT",
+            "LIST_MODEL_CAPABILITIES",
+            "CANCEL_JOB",
+            "LIST_HISTORY",
+            "HEALTHCHECK",
+        ],
+        referenceDocPath: "docs/provider-adapter-layer.md",
+        authMechanism: "api-key-header",
+        authField: "x-api-key",
+        baseUrl: "https://api.muapi.io",
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Generic provider contract builder for future extension
+// ---------------------------------------------------------------------------
+export function buildProviderContract(providerId, providerName, baseUrl, authField, referenceDocPath, additionalOperations = []) {
+    return {
+        providerId,
+        providerName,
+        operations: [...REQUIRED_PROVIDER_OPERATIONS, ...additionalOperations],
+        referenceDocPath,
+        authMechanism: "api-key-header",
+        authField,
+        baseUrl,
+    };
+}
+//# sourceMappingURL=provider-adapter.js.map

package/dist/kits/core/adapter-core/provider-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-adapter.js","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/provider-adapter.ts"],"names":[],"mappings":"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"}

package/dist/kits/core/adapter-core/runtime-surface.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Fork Adapter Core — Runtime Surface
+ *
+ * Reusable declaration and validation for the execution surfaces a kit supports.
+ *
+ * A runtime surface is the environment where generation actually executes:
+ *   local-fork     — cloned repo running locally (e.g. localhost:3001)
+ *   browser-hosted — hosted web app (e.g. muapi.ai/open-higgsfield-ai)
+ *   desktop-app    — Electron or native app installed locally
+ *   custom         — any other surface declared by the kit
+ *
+ * Surfaces are declared in ForkAdapterCoreConfig.runtimeSurface.
+ * The agent picks one surface per session in Step 8 of the CLAUDE.md workflow.
+ */
+import type { RuntimeSurfaceContract } from "./contracts.js";
+import { type RuntimeSurfaceType, type CoreValidationResult } from "../types/index.js";
+export interface RuntimeSurfaceValidationResult extends CoreValidationResult {
+    supportedSurfaces: RuntimeSurfaceType[];
+    defaultSurface: RuntimeSurfaceType;
+    invalidSurfaces: string[];
+}
+export declare function validateRuntimeSurfaceContract(contract: RuntimeSurfaceContract): RuntimeSurfaceValidationResult;
+export declare function buildStudioRuntimeSurfaceContract(): RuntimeSurfaceContract;
+export declare function formatSurfaceSelectionNote(surface: RuntimeSurfaceType): string;
+//# sourceMappingURL=runtime-surface.d.ts.map

package/dist/kits/core/adapter-core/runtime-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-surface.d.ts","sourceRoot":"","sources":["../../../../src/kits/core/adapter-core/runtime-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,oBAAoB,EAK1B,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,8BAA+B,SAAQ,oBAAoB;IAC1E,iBAAiB,EAAE,kBAAkB,EAAE,CAAC;IACxC,cAAc,EAAE,kBAAkB,CAAC;IACnC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,sBAAsB,GAC/B,8BAA8B,CA8DhC;AAMD,wBAAgB,iCAAiC,IAAI,sBAAsB,CAuB1E;AAMD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAQ9E"}

package/dist/kits/core/adapter-core/runtime-surface.js

@@ -0,0 +1,100 @@
+/**
+ * Fork Adapter Core — Runtime Surface
+ *
+ * Reusable declaration and validation for the execution surfaces a kit supports.
+ *
+ * A runtime surface is the environment where generation actually executes:
+ *   local-fork     — cloned repo running locally (e.g. localhost:3001)
+ *   browser-hosted — hosted web app (e.g. muapi.ai/open-higgsfield-ai)
+ *   desktop-app    — Electron or native app installed locally
+ *   custom         — any other surface declared by the kit
+ *
+ * Surfaces are declared in ForkAdapterCoreConfig.runtimeSurface.
+ * The agent picks one surface per session in Step 8 of the CLAUDE.md workflow.
+ */
+import { RUNTIME_SURFACE_TYPES, makeError, makeWarning, } from "../types/index.js";
+// ---------------------------------------------------------------------------
+// Validate a runtime surface contract declaration
+// ---------------------------------------------------------------------------
+export function validateRuntimeSurfaceContract(contract) {
+    const issues = [];
+    const passedChecks = [];
+    const invalidSurfaces = [];
+    // At least one surface must be declared
+    if (contract.supportedSurfaces.length === 0) {
+        issues.push(makeError("NO_SURFACES_DECLARED", "At least one runtime surface must be declared in supportedSurfaces."));
+    }
+    else {
+        passedChecks.push("surfaces-declared");
+    }
+    // All declared surfaces must be valid types
+    for (const surface of contract.supportedSurfaces) {
+        if (!RUNTIME_SURFACE_TYPES.includes(surface)) {
+            invalidSurfaces.push(surface);
+            issues.push(makeError("INVALID_SURFACE_TYPE", `"${surface}" is not a valid runtime surface type. Valid: ${RUNTIME_SURFACE_TYPES.join(", ")}`, "supportedSurfaces"));
+        }
+    }
+    // Default surface must be in supported surfaces
+    if (!contract.supportedSurfaces.includes(contract.defaultSurface)) {
+        issues.push(makeError("DEFAULT_SURFACE_NOT_SUPPORTED", `defaultSurface "${contract.defaultSurface}" is not in supportedSurfaces.`, "defaultSurface"));
+    }
+    else {
+        passedChecks.push("default-surface-valid");
+    }
+    // Warn if local-fork is declared but no probe is configured
+    if (contract.supportedSurfaces.includes("local-fork") &&
+        !contract.surfaceProbes["local-fork"]) {
+        issues.push(makeWarning("LOCAL_FORK_NO_PROBE", "local-fork surface is declared but no reachability probe is configured. Consider adding an HTTP probe for localhost."));
+    }
+    else if (contract.supportedSurfaces.includes("local-fork")) {
+        passedChecks.push("local-fork-probe-configured");
+    }
+    return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues,
+        passedChecks,
+        supportedSurfaces: contract.supportedSurfaces,
+        defaultSurface: contract.defaultSurface,
+        invalidSurfaces,
+    };
+}
+// ---------------------------------------------------------------------------
+// Standard surface contract factory for Open Higgsfield / Studio kits
+// ---------------------------------------------------------------------------
+export function buildStudioRuntimeSurfaceContract() {
+    return {
+        supportedSurfaces: ["local-fork", "browser-hosted", "desktop-app"],
+        defaultSurface: "local-fork",
+        surfaceProbes: {
+            "local-fork": {
+                id: "local-fork-http",
+                type: "http",
+                target: "http://localhost:3001",
+                required: false,
+                description: "Open Higgsfield AI local fork dev server",
+            },
+            "browser-hosted": {
+                id: "browser-hosted-http",
+                type: "http",
+                target: "https://muapi.ai/open-higgsfield-ai",
+                required: false,
+                description: "Open Higgsfield AI hosted browser app",
+            },
+            "desktop-app": null,
+            "custom": null,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Format surface selection for agent handoff doc
+// ---------------------------------------------------------------------------
+export function formatSurfaceSelectionNote(surface) {
+    const notes = {
+        "local-fork": "Execute against the local fork running at http://localhost:3001. Inspect fork source files before planning.",
+        "browser-hosted": "Execute against the hosted browser app. UI behavior follows the public hosted workflow.",
+        "desktop-app": "Execute against the locally installed Electron app. UI behavior matches browser but with local asset history.",
+        "custom": "Execute against a custom-declared surface. Verify the surface contract before planning.",
+    };
+    return notes[surface];
+}
+//# sourceMappingURL=runtime-surface.js.map