@wairon/cli 5.0.2-dev.13 → 5.0.2-dev.14

package/dist/index.js

@@ -1260,6 +1260,47 @@ var init_errors = __esm({
   }
 });
 
+// src/core/statehash.ts
+function computeStateId() {
+  const tree = {
+    system: loadSystemSpec(),
+    subsystems: loadSubsystemSpecs(),
+    components: loadComponentSpecs(),
+    interfaces: loadInterfaceSpecs(),
+    implementations: loadImplementationSpecs(),
+    types: loadTypeSpecs()
+  };
+  const digest = crypto.createHash("sha256").update(canonicalize(tree)).digest("hex");
+  return { algorithm: "sha256", digest };
+}
+function stateIdEquals(a, b) {
+  return !!a && !!b && a.algorithm === b.algorithm && a.digest === b.digest;
+}
+function canonicalize(value) {
+  return JSON.stringify(sortKeys(value));
+}
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === "object") {
+    const src = v;
+    const out = {};
+    for (const k of Object.keys(src).sort()) {
+      if (k === "createdAt" || k === "updatedAt") continue;
+      out[k] = sortKeys(src[k]);
+    }
+    return out;
+  }
+  return v;
+}
+var crypto;
+var init_statehash = __esm({
+  "src/core/statehash.ts"() {
+    "use strict";
+    crypto = __toESM(require("crypto"));
+    init_specs2();
+  }
+});
+
 // src/core/narrative-labels.ts
 function resolveNarrativeLabels(methodName, steps) {
   const errors = [];
@@ -6824,47 +6865,6 @@ var init_filenames = __esm({
   }
 });
 
-// src/core/statehash.ts
-function computeStateId() {
-  const tree = {
-    system: loadSystemSpec(),
-    subsystems: loadSubsystemSpecs(),
-    components: loadComponentSpecs(),
-    interfaces: loadInterfaceSpecs(),
-    implementations: loadImplementationSpecs(),
-    types: loadTypeSpecs()
-  };
-  const digest = crypto.createHash("sha256").update(canonicalize(tree)).digest("hex");
-  return { algorithm: "sha256", digest };
-}
-function stateIdEquals(a, b) {
-  return !!a && !!b && a.algorithm === b.algorithm && a.digest === b.digest;
-}
-function canonicalize(value) {
-  return JSON.stringify(sortKeys(value));
-}
-function sortKeys(v) {
-  if (Array.isArray(v)) return v.map(sortKeys);
-  if (v && typeof v === "object") {
-    const src = v;
-    const out = {};
-    for (const k of Object.keys(src).sort()) {
-      if (k === "createdAt" || k === "updatedAt") continue;
-      out[k] = sortKeys(src[k]);
-    }
-    return out;
-  }
-  return v;
-}
-var crypto;
-var init_statehash = __esm({
-  "src/core/statehash.ts"() {
-    "use strict";
-    crypto = __toESM(require("crypto"));
-    init_specs2();
-  }
-});
-
 // src/core/openapi.ts
 function schemaFor(typeRef, closureIds) {
   const trimmed = typeRef.trim().replace(/^promise\s*<(.+)>$/i, "$1").trim();
@@ -7322,6 +7322,57 @@ function projectOwnSurface(maxAudience) {
 function projectChildSurface() {
   return projectOwnSurface("project");
 }
+function localName(id) {
+  return id.split("::").pop();
+}
+function projectSubsystemSurface(subsystemId) {
+  const system = loadSystemSpec();
+  if (!system) {
+    throw new Error("Cannot project a subsystem surface: the L0 system spec is missing.");
+  }
+  const subsystems = loadSubsystemSpecs();
+  const target = subsystems.find((s) => s.id === subsystemId);
+  if (!target) {
+    throw new Error(`Cannot project a subsystem surface: subsystem "${subsystemId}" does not exist.`);
+  }
+  const components = loadComponentSpecs();
+  const interfaces = loadInterfaceSpecs();
+  const types = loadTypeSpecs();
+  const entries = [];
+  for (const pub of target.publicInterfaces ?? []) {
+    if (!pub.component) continue;
+    const comp = components.find((c) => c.id === pub.component || c.id === `${subsystemId}::${pub.component}`);
+    if (!comp) continue;
+    if (comp.componentType !== "Portal") continue;
+    const compInterfaces = interfaces.filter((i) => i.component === comp.id && (!pub.interface || i.id === pub.interface || i.id === `${subsystemId}::${pub.interface}`));
+    const methods = compInterfaces.flatMap((i) => i.methods);
+    entries.push({
+      id: localName(pub.interface ?? comp.id),
+      name: comp.name,
+      // Family ceiling: a sibling surface is consumable by the system family only.
+      audience: "project",
+      type: pub.type ?? "Custom",
+      // The snapshot carries the LOCAL portal name — consumers resolve cross-tree
+      // refs by their final segment.
+      component: localName(comp.id),
+      methods,
+      ...comp.dispatch && comp.dispatch.length ? { dispatch: comp.dispatch } : {},
+      // Project the backing Portal's auth + basePath so the codec can emit
+      // OpenAPI security + per-portal servers self-contained from the snapshot.
+      ...comp.auth && comp.auth.scheme !== "none" ? { auth: comp.auth } : {},
+      ...comp.basePath ? { basePath: comp.basePath } : {},
+      details: pub.details ?? ""
+    });
+  }
+  return SurfaceSnapshotSchema.parse({
+    projectName: `${system.name}::${subsystemId}`,
+    origin: "generated",
+    stateId: stateIdString(),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    interfaces: entries,
+    types: computeTypeClosure(entries, types)
+  });
+}
 function listSnapshots(rootDir = getProjectRoot()) {
   const dir = surfacesDir(rootDir);
   if (!fs4.existsSync(dir)) return [];
@@ -7338,18 +7389,37 @@ function listSnapshots(rootDir = getProjectRoot()) {
 function getSnapshot(projectName, rootDir = getProjectRoot()) {
   return listSnapshots(rootDir).find((s) => s.projectName === projectName) ?? null;
 }
+function snapshotFilename(projectName) {
+  return `${safeFilenamePart(projectName)}.yaml`;
+}
 function saveSnapshot(snapshot, rootDir = getProjectRoot()) {
   const dir = surfacesDir(rootDir);
   fs4.mkdirSync(dir, { recursive: true });
-  const p = path5.join(dir, `${snapshot.projectName}.yaml`);
+  const p = path5.join(dir, snapshotFilename(snapshot.projectName));
   writeYamlFile(p, SurfaceSnapshotSchema.parse(snapshot));
   return p;
 }
 function removeSnapshot(projectName, rootDir = getProjectRoot()) {
-  const p = path5.join(surfacesDir(rootDir), `${projectName}.yaml`);
-  if (!fs4.existsSync(p)) return false;
-  fs4.unlinkSync(p);
-  return true;
+  const dir = surfacesDir(rootDir);
+  const direct = path5.join(dir, snapshotFilename(projectName));
+  if (fs4.existsSync(direct)) {
+    fs4.unlinkSync(direct);
+    return true;
+  }
+  if (!fs4.existsSync(dir)) return false;
+  for (const file of fs4.readdirSync(dir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+    const p = path5.join(dir, file);
+    try {
+      const snap = SurfaceSnapshotSchema.parse(readYamlFile(p));
+      if (snap.projectName === projectName) {
+        fs4.unlinkSync(p);
+        return true;
+      }
+    } catch {
+    }
+  }
+  return false;
 }
 function loadSurfaceSnapshots() {
   return listSnapshots();
@@ -7420,17 +7490,54 @@ function importSurface(sourcePath, origin) {
   return snapshot;
 }
 function generateChildSnapshots(rootDir = getProjectRoot()) {
-  const children = loadSubsystemSpecs().filter((s) => s.projectPath && !s.id.includes("::"));
+  const topLevel = loadSubsystemSpecs().filter((s) => !s.id.includes("::"));
+  const children = topLevel.filter((s) => s.projectPath);
   if (!children.length) return [];
-  const snapshot = projectChildSurface();
+  const familySnapshot = projectChildSurface();
+  const siblingSnapshots = /* @__PURE__ */ new Map();
+  const siblingSurface = (subsystemId) => {
+    let snap = siblingSnapshots.get(subsystemId);
+    if (!snap) {
+      snap = projectSubsystemSurface(subsystemId);
+      siblingSnapshots.set(subsystemId, snap);
+    }
+    return snap;
+  };
   const written = [];
   for (const child of children) {
     const childDir = path5.resolve(rootDir, child.projectPath);
     if (!fs4.existsSync(childDir)) continue;
-    written.push(saveSnapshot(snapshot, childDir));
+    written.push(saveSnapshot(familySnapshot, childDir));
+    for (const sibling of topLevel) {
+      if (sibling.id === child.id) continue;
+      written.push(saveSnapshot(siblingSurface(sibling.id), childDir));
+    }
   }
   return written;
 }
+function computeParentStateId(parentRoot) {
+  return computeStateIdAt(parentRoot);
+}
+function listExternalInterfaces() {
+  const snapshots = listSnapshots();
+  const chainingParent = resolveChainingParent();
+  const parentStateId = chainingParent ? computeParentStateId(chainingParent.parentRoot) : null;
+  return snapshots.map((snapshot) => {
+    const generated = snapshot.origin === "generated";
+    const sourceKind = !generated ? "foreign" : snapshot.projectName.includes("::") ? "sibling" : "parent";
+    const freshness = generated && parentStateId ? snapshot.stateId === parentStateId ? "fresh" : "stale" : "unverifiable";
+    return {
+      projectName: snapshot.projectName,
+      origin: snapshot.origin,
+      sourceKind,
+      generatedAt: snapshot.generatedAt,
+      ...snapshot.stateId ? { stateId: snapshot.stateId } : {},
+      ...snapshot.version ? { version: snapshot.version } : {},
+      freshness,
+      interfaceIds: snapshot.interfaces.map((e) => e.id)
+    };
+  });
+}
 function surfaceContentKey(snapshot) {
   const { stateId, generatedAt, origin, ...content } = snapshot;
   return JSON.stringify(content);
@@ -7639,7 +7746,8 @@ var init_contracts = __esm({
                           "SURFACE_REF_NOT_EXPOSED",
                           `Method "${implMethod.name}" in implementation "${impl.id}" dispatches capability "${step.capability}" through cross-tree portal "${step.targetComponent}" (step ${step.stepNumber}), but the surface snapshot of "${resolved.snapshot.projectName}" does not serve that capability on "${resolved.entry.id}".`,
                           impl.id,
-                          isDraftCtx
+                          isDraftCtx,
+                          true
                         );
                       }
                       continue;
@@ -7696,7 +7804,8 @@ var init_contracts = __esm({
                         "SURFACE_REF_NOT_EXPOSED",
                         `Method "${implMethod.name}" in implementation "${impl.id}" calls "${step.targetMethod}" on cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), but the surface snapshot of "${resolved.snapshot.projectName}" does not expose that method on "${resolved.entry.id}".`,
                         impl.id,
-                        isDraftCtx
+                        isDraftCtx,
+                        true
                       );
                     } else if (step.assertsGuarantees) {
                       const declared = new Set(surfaceMethod.guarantees ?? []);
@@ -7707,7 +7816,8 @@ var init_contracts = __esm({
                             "NARRATIVE_SEMANTIC_UNBACKED",
                             `Step ${step.stepNumber} of "${implMethod.name}" in implementation "${impl.id}" asserts guarantee "${g}", but the surface snapshot of "${resolved.snapshot.projectName}" does not declare it on "${resolved.entry.id}.${step.targetMethod}".`,
                             impl.id,
-                            isDraftCtx
+                            isDraftCtx,
+                            true
                           );
                         }
                       }
@@ -9195,7 +9305,8 @@ var init_stereotype_deps = __esm({
                       "CROSS_SUBSYSTEM_NON_ADAPTER",
                       `Boundary violation: ${comp.componentType} "${comp.id}" depends directly on "${depId}", a surface of project "${resolved.snapshot.projectName}". Only a local client Adapter may cross a project boundary \u2014 route this hop through an Adapter.`,
                       comp.id,
-                      isDraftCtx
+                      isDraftCtx,
+                      true
                     );
                   }
                   continue;
@@ -12453,9 +12564,15 @@ function buildRuleContext(opts) {
     ...[...SDD_RULES, ...extensions.rules].flatMap((r) => r.codes.map((c) => c.code)),
     // Declarative assertions bring their own namespaced codes — lint.allow
     // and severity overrides treat them exactly like builtins.
-    ...extensions.assertions.map((a) => a.fullCode)
+    ...extensions.assertions.map((a) => a.fullCode),
+    // Entry-point emitted codes: validateSddTree's chained-subproject pass
+    // raises these AFTER the rule run (it post-processes the aggregated issue
+    // list), so no registered rule declares them — but lint.allow validation
+    // must still recognize them as real codes.
+    "CHAINED_SUBPROJECT_CONTEXT",
+    "UNVERIFIED_EXTERNAL_REF"
   ]);
-  const addIssue = (defaultSeverity, code, message, specId, isDraftContext) => {
+  const addIssue = (defaultSeverity, code, message, specId, isDraftContext, surfaceResolved) => {
     if (scopeSubsystem && specId && !isSpecInScope(specId)) {
       return;
     }
@@ -12473,7 +12590,14 @@ function buildRuleContext(opts) {
         if (severity === "warning") return;
       }
     }
-    issues.push({ severity, code, message, specId, ...isDraftContext ? { draftContext: true } : {} });
+    issues.push({
+      severity,
+      code,
+      message,
+      specId,
+      ...isDraftContext ? { draftContext: true } : {},
+      ...surfaceResolved ? { surfaceResolved: true } : {}
+    });
   };
   return {
     system,
@@ -12951,24 +13075,54 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
     for (const rule of ruleSequence()) {
       rule.check(ctx);
     }
-    const hasCrossTreeSuspects = issues.some((i) => SUBPROJECT_LENIENT_CODES.has(i.code));
+    const hasCrossTreeSuspects = issues.some(
+      (i) => SUBPROJECT_REFERENCE_CODES.has(i.code) || SUBPROJECT_CONFORMANCE_CODES.has(i.code)
+    );
     const chainingParent = hasCrossTreeSuspects ? findChainingParent(getProjectRoot()) : null;
     if (chainingParent) {
+      let unverified = 0;
       let downgraded = 0;
-      for (const iss of issues) {
-        if (!SUBPROJECT_LENIENT_CODES.has(iss.code)) continue;
-        if (iss.severity === "error") {
-          iss.severity = "warning";
-          downgraded++;
+      for (let at = 0; at < issues.length; at++) {
+        const iss = issues[at];
+        if (SUBPROJECT_REFERENCE_CODES.has(iss.code) && !iss.surfaceResolved) {
+          issues[at] = {
+            severity: "warning",
+            code: "UNVERIFIED_EXTERNAL_REF",
+            crossTreeContext: true,
+            // --ci waives it (parent root is authoritative)
+            specId: iss.specId,
+            ...iss.agentId ? { agentId: iss.agentId } : {},
+            ...iss.draftContext ? { draftContext: true } : {},
+            message: `Unverified external reference (${iss.code}): ${iss.message} No vendored surface snapshot covers this reference, so it cannot be verified from this chained subproject standalone \u2014 re-lock the parent so fresh family/sibling snapshots ship, or inspect what this project can consume via \`wairon surface externals\` / sdd_list_external_interfaces.`
+          };
+          unverified++;
+          continue;
+        }
+        if (SUBPROJECT_CONFORMANCE_CODES.has(iss.code)) {
+          if (iss.severity === "error") {
+            iss.severity = "warning";
+            downgraded++;
+          }
+          iss.crossTreeContext = true;
         }
-        iss.crossTreeContext = true;
       }
-      if (downgraded > 0) {
+      if (unverified > 0 || downgraded > 0) {
+        const notes = [];
+        if (unverified > 0) {
+          notes.push(
+            `${unverified} cross-tree reference(s) have no vendored surface snapshot covering them and were reported as UNVERIFIED_EXTERNAL_REF warnings \u2014 re-lock the parent so fresh family/sibling snapshots ship, or inspect via \`wairon surface externals\` / sdd_list_external_interfaces.`
+          );
+        }
+        if (downgraded > 0) {
+          notes.push(
+            `${downgraded} code\u2194spec conformance finding(s) (parent-root-relative source paths) were downgraded to warnings.`
+          );
+        }
         issues.unshift({
           severity: "warning",
           code: "CHAINED_SUBPROJECT_CONTEXT",
           crossTreeContext: true,
-          message: `This project is a chained subproject ("${chainingParent.subsystemId}") of the parent project at "${chainingParent.parentRoot}". ${downgraded} reference(s) resolve only in the parent tree (shared types, sibling subsystems, or cross-tree components that live above this root) and were downgraded to warnings \u2014 validating a subproject standalone cannot verify them. Run validation from the parent root for full cross-tree verification.`
+          message: `This project is a chained subproject ("${chainingParent.subsystemId}") of the parent project at "${chainingParent.parentRoot}". ${notes.join(" ")} Full cross-tree verification runs from the parent root.`
         });
       }
     }
@@ -12985,7 +13139,7 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
 function validateAsComplete(options) {
   return validateSddTree({ ...options ?? {}, treatAllAsComplete: true });
 }
-var SUBPROJECT_LENIENT_CODES;
+var SUBPROJECT_REFERENCE_CODES, SUBPROJECT_CONFORMANCE_CODES;
 var init_validation = __esm({
   "src/core/validation.ts"() {
     "use strict";
@@ -12998,8 +13152,7 @@ var init_validation = __esm({
     init_source_analysis();
     init_specs2();
     init_fs();
-    SUBPROJECT_LENIENT_CODES = /* @__PURE__ */ new Set([
-      // reference resolution
+    SUBPROJECT_REFERENCE_CODES = /* @__PURE__ */ new Set([
       "UNDEFINED_TYPE_REFERENCE",
       "INVALID_DEPENDENCY_REFERENCE",
       "INVALID_TARGET_COMPONENT_REFERENCE",
@@ -13007,8 +13160,9 @@ var init_validation = __esm({
       "UNDECLARED_DEPENDENCY_CALL",
       "INVALID_TRUSTED_LINK",
       "CROSS_SUBSYSTEM_NON_ADAPTER",
-      "CROSS_TREE_REF_UNRESOLVED",
-      // code↔spec conformance (root-relative sourcePaths / import graph)
+      "CROSS_TREE_REF_UNRESOLVED"
+    ]);
+    SUBPROJECT_CONFORMANCE_CODES = /* @__PURE__ */ new Set([
       "MISSING_SOURCE_FILE",
       "SOURCE_PATH_ESCAPES_ROOT",
       "MISSING_SOURCE_PATH",
@@ -13931,6 +14085,19 @@ function dryRunSerializeSpecs(include) {
 function buildProjectGraph(level) {
   return buildGraphModel(level);
 }
+function resolveChainingParent() {
+  return findChainingParent(getProjectRoot());
+}
+function computeStateIdAt(root) {
+  const resolved = path10.resolve(root);
+  return runWithProjectRoot(resolved, () => {
+    workspaceFor(resolved).invalidate();
+    const system = loadSystemSpec();
+    if (!system) return null;
+    const s = computeStateId();
+    return `${s.algorithm}:${s.digest}`;
+  });
+}
 function deleteTypeSpec(id) {
   return current().deleteTypeSpec(id);
 }
@@ -13974,6 +14141,7 @@ var init_specs2 = __esm({
     path10 = __toESM(require("path"));
     init_loader();
     init_fs();
+    init_statehash();
     init_yaml();
     init_models();
     init_narrative_labels();
@@ -16138,7 +16306,9 @@ __export(src_exports, {
   clearLoaderIssues: () => clearLoaderIssues,
   collectPromotableSpecs: () => collectPromotableSpecs,
   composeRuleSequence: () => composeRuleSequence,
+  computeParentStateId: () => computeParentStateId,
   computeStateId: () => computeStateId,
+  computeStateIdAt: () => computeStateIdAt,
   contextDir: () => contextDir,
   createAgentRecord: () => createAgentRecord,
   createChainedSubsystem: () => createChainedSubsystem,
@@ -16204,6 +16374,7 @@ __export(src_exports, {
   isOpenApiDocument: () => isOpenApiDocument,
   isProjectInitialized: () => isProjectInitialized,
   listDirectChainedSubprojects: () => listDirectChainedSubprojects,
+  listExternalInterfaces: () => listExternalInterfaces,
   listFiles: () => listFiles,
   listFilesRecursive: () => listFilesRecursive,
   listFreeStandingDomains: () => listFreeStandingDomains,
@@ -16249,6 +16420,7 @@ __export(src_exports, {
   pathExists: () => pathExists,
   projectChildSurface: () => projectChildSurface,
   projectOwnSurface: () => projectOwnSurface,
+  projectSubsystemSurface: () => projectSubsystemSurface,
   promoteAllComplete: () => promoteAllComplete,
   provisionProject: () => provisionProject,
   readArchitectureContext: () => readArchitectureContext,
@@ -16268,6 +16440,7 @@ __export(src_exports, {
   renderTemplateInstructions: () => renderTemplateInstructions,
   renderWaironGuide: () => renderWaironGuide,
   resolveAgentTopology: () => resolveAgentTopology,
+  resolveChainingParent: () => resolveChainingParent,
   resolveDomains: () => resolveDomains,
   resolvePackRef: () => resolvePackRef,
   resolveSubprojectForNamespace: () => resolveSubprojectForNamespace,
@@ -16331,7 +16504,7 @@ function defaultTargetConfig(type) {
     enabled: true
   };
 }
-var WAIRON_VERSION = "5.0.2-dev.13";
+var WAIRON_VERSION = "5.0.2-dev.14";
 var GITHUB_REPO = "SYW-Apps/Waffle-AIron";
 var ARCHITECT_AGENT_ID = "agent-architect";
 var ARCHITECT_TEMPLATE_ID = "architect";
@@ -17725,7 +17898,9 @@ init_yaml();
   clearLoaderIssues,
   collectPromotableSpecs,
   composeRuleSequence,
+  computeParentStateId,
   computeStateId,
+  computeStateIdAt,
   contextDir,
   createAgentRecord,
   createChainedSubsystem,
@@ -17791,6 +17966,7 @@ init_yaml();
   isOpenApiDocument,
   isProjectInitialized,
   listDirectChainedSubprojects,
+  listExternalInterfaces,
   listFiles,
   listFilesRecursive,
   listFreeStandingDomains,
@@ -17836,6 +18012,7 @@ init_yaml();
   pathExists,
   projectChildSurface,
   projectOwnSurface,
+  projectSubsystemSurface,
   promoteAllComplete,
   provisionProject,
   readArchitectureContext,
@@ -17855,6 +18032,7 @@ init_yaml();
   renderTemplateInstructions,
   renderWaironGuide,
   resolveAgentTopology,
+  resolveChainingParent,
   resolveDomains,
   resolvePackRef,
   resolveSubprojectForNamespace,