skill-family-engineering-kit 0.1.3 → 0.2.1

package/src/host.mjs

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { canonicalJson, digestDocument, validateDocument } from "skill-family-contracts";
+import {
+  buildAdapterClosure,
+  materializeAdapterBuild,
+  verifyAdapterBuildManifest,
+} from "skill-family-harness-node";
+import { invalidParamsError, kitError, KIT_ERROR_KINDS } from "./errors.mjs";
+import { HOST_CAPABILITIES, probeTrustedVersionDriver } from "./host-drivers.mjs";
+import { describeHost } from "./host-profiles.mjs";
+
+const FACT_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-capability-fact.json";
+const PROBE_RESULT_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-probe-result.json";
+const PLAN_SCHEMA_ID = "https://contracts.skill-family.example/v1/host-operation-plan.json";
+
+function validateContract(document, schemaId, message) {
+  const result = validateDocument(document, { schemaId, dialect: "2020-12", policy: "strict" });
+  if (!result.valid) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, message, { errors: result.errors });
+  return result.data;
+}
+
+function selectCategory(descriptor, pathCategoryId) {
+  const category = descriptor.pathCategories.find((candidate) => candidate.id === pathCategoryId);
+  if (!category) throw invalidParamsError(`host ${descriptor.hostId} does not declare path category ${String(pathCategoryId)}`);
+  return { id: category.id, scope: category.scope, anchor: category.anchor, relPath: category.relPath };
+}
+
+export async function probeHost({ hostId, hostsRoot, registry, executable, allowSpawn = false, timeoutMs = 5000, runner } = {}) {
+  const descriptor = await describeHost({ hostId, hostsRoot, registry });
+  if (descriptor.support === "unsupported") {
+    return validateContract({ schemaVersion: 1, kind: "skill-family.host-probe-result", hostId, support: "unsupported", reason: descriptor.unsupportedReason, facts: [] }, PROBE_RESULT_SCHEMA_ID, "unsupported probe result fails its contract");
+  }
+  const facts = await probeTrustedVersionDriver({
+    hostId,
+    driverId: descriptor.driverId,
+    capabilities: descriptor.probeCapabilities,
+    executable,
+    allowSpawn,
+    timeoutMs,
+    runner,
+  });
+  for (const fact of facts) validateContract(fact, FACT_SCHEMA_ID, "host driver emitted an invalid capability fact");
+  const names = facts.map((fact) => fact.capability);
+  if (new Set(names).size !== HOST_CAPABILITIES.length || !HOST_CAPABILITIES.every((name) => names.includes(name))) {
+    throw kitError(KIT_ERROR_KINDS.HOST_PROBE_FAILED, "host driver did not emit the exact capability fact set");
+  }
+  return validateContract({ schemaVersion: 1, kind: "skill-family.host-probe-result", hostId, support: "supported", facts }, PROBE_RESULT_SCHEMA_ID, "host probe result fails its contract");
+}
+
+export async function buildHostAdapter({ hostId, pathCategoryId, input, hostsRoot, registry } = {}) {
+  const descriptor = await describeHost({ hostId, hostsRoot, registry });
+  if (descriptor.support !== "supported") return { status: "unsupported", reason: descriptor.unsupportedReason };
+  return buildAdapterClosure({ hostId, pathCategory: selectCategory(descriptor, pathCategoryId), input });
+}
+
+export async function materializeHostBuild(options) {
+  return materializeAdapterBuild(options);
+}
+
+function validateFactSet(hostId, facts) {
+  if (!Array.isArray(facts) || facts.length !== HOST_CAPABILITIES.length) throw invalidParamsError(`planHost requires exactly ${HOST_CAPABILITIES.length} explicit probe facts`);
+  for (const fact of facts) {
+    validateContract(fact, FACT_SCHEMA_ID, "planHost received an invalid probe fact");
+    if (fact.hostId !== hostId) throw invalidParamsError("probe fact hostId does not match the planned host");
+  }
+  const names = facts.map((fact) => fact.capability);
+  if (new Set(names).size !== names.length || !HOST_CAPABILITIES.every((name) => names.includes(name))) throw invalidParamsError("probe facts must cover each capability exactly once");
+  return [...facts].sort((left, right) => HOST_CAPABILITIES.indexOf(left.capability) - HOST_CAPABILITIES.indexOf(right.capability));
+}
+
+export async function planHost({ hostId, pathCategoryId, buildManifest, probeFacts, hostsRoot, registry } = {}) {
+  const descriptor = await describeHost({ hostId, hostsRoot, registry });
+  if (descriptor.support !== "supported") {
+    const base = { schemaVersion: 1, kind: "skill-family.host-operation-plan", hostId, status: "unsupported", unsupportedReason: descriptor.unsupportedReason, probeFacts: [], actions: [], writeSet: [] };
+    return validateContract({ ...base, digest: digestDocument(base) }, PLAN_SCHEMA_ID, "unsupported host plan fails its contract");
+  }
+  const category = selectCategory(descriptor, pathCategoryId);
+  const facts = validateFactSet(hostId, probeFacts);
+  const manifest = verifyAdapterBuildManifest(buildManifest, { hostId, pathCategory: category });
+  const actions = manifest.members.map((member, index) => ({ sequence: index + 1, kind: "install-file", categoryId: category.id, scope: category.scope, anchor: category.anchor, target: member.target, expect: "absent", sourceSha256: member.sha256 }));
+  const writeSet = actions.map(({ categoryId, scope, anchor, target, sourceSha256 }) => ({ categoryId, scope, anchor, target, sourceSha256 }));
+  const base = { schemaVersion: 1, kind: "skill-family.host-operation-plan", hostId, status: "planned", pathCategory: category, probeFacts: facts, actions, writeSet };
+  const plan = validateContract({ ...base, digest: digestDocument(base) }, PLAN_SCHEMA_ID, "host operation plan fails its contract");
+  assertPlanConsistency(plan);
+  return plan;
+}
+
+export function assertPlanConsistency(planInput) {
+  const plan = validateContract(planInput, PLAN_SCHEMA_ID, "host operation plan fails its registered contract");
+  const { digest, ...base } = plan;
+  if (digestDocument(base) !== digest) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "plan digest does not match its content");
+  if (plan.status === "unsupported") return true;
+  if (plan.actions.length !== plan.writeSet.length) throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "plan actions/writeSet lengths differ");
+  for (let index = 0; index < plan.actions.length; index += 1) {
+    const action = plan.actions[index];
+    const write = plan.writeSet[index];
+    const normalized = path.posix.normalize(action.target);
+    if (normalized !== action.target || normalized.startsWith("../") || path.isAbsolute(action.target)) throw invalidParamsError("plan target must be a normalized contained path");
+    if (action.sequence !== index + 1 || action.categoryId !== plan.pathCategory.id || action.scope !== plan.pathCategory.scope || action.anchor !== plan.pathCategory.anchor || !action.target.startsWith(`${plan.pathCategory.relPath}/`) || canonicalJson(write) !== canonicalJson({ categoryId: action.categoryId, scope: action.scope, anchor: action.anchor, target: action.target, sourceSha256: action.sourceSha256 })) {
+      throw kitError(KIT_ERROR_KINDS.HOST_CONTRACT_INVALID, "plan action, target, writeSet, category and anchor are inconsistent");
+    }
+  }
+  return true;
+}
+
+export function refuseHostApply() {
+  throw invalidParamsError("host apply is not implemented in the read-only Phase D slice", { action: "apply", stableRefusal: true });
+}

package/src/index.mjs

@@ -51,7 +51,17 @@ import {
   loadLicensingProfile,
 } from "./licensing.mjs";
 import { runProjection, loadProjectionManifest } from "./projection.mjs";
+import { checkReportAction, renderReportAction } from "./report.mjs";
 import { scaffoldTarget } from "./scaffold.mjs";
+import {
+  assertPlanConsistency,
+  buildHostAdapter,
+  materializeHostBuild,
+  planHost,
+  probeHost,
+  refuseHostApply,
+} from "./host.mjs";
+import { describeHost, loadHostRegistry } from "./host-profiles.mjs";
 import {
   describeSkeletonFiles,
   IDENTITY_RECORD_PATH,
@@ -109,13 +119,13 @@ export const COMMAND_SIDE_EFFECTS = Object.freeze({
   projection: Object.freeze({
     summary: "投影受管生成物。",
     sideEffect:
-      "writes only manifest-authorized managed artifacts; unauthorized, handwritten, escaping, or conflicting paths are refused with zero writes",
+      "writes only manifest-authorized managed artifacts; the report sub-action (projection report) writes only the explicitly named --out/--binding paths contained in --root (Markdown goes to stdout when no --out is given); unauthorized, handwritten, escaping, or conflicting paths are refused with zero writes",
     exitCodes: "0 成功；2 拒绝/用法/机制错误",
   }),
   check: Object.freeze({
     summary: "契约/漂移/闭包/版本/文档事实/Git 前置状态诊断。",
     sideEffect:
-      "none — diagnosis only: never writes, never auto-fixes; git is probed read-only (one frozen status query at most)",
+      "none — diagnosis only: never writes, never auto-fixes; git is probed read-only (one frozen status query at most); the report sub-action (check report) grades one rendered report against its bound machine result and writes nothing",
     exitCodes: "0 无发现；1 有发现；2 拒绝/用法/机制错误",
   }),
 });
@@ -183,6 +193,8 @@ export {
   HANDOFF_FIELDS,
   runProjection,
   loadProjectionManifest,
+  renderReportAction,
+  checkReportAction,
   runChecks,
   CHECK_CLASSES,
   DOCUMENT_STATES,
@@ -204,6 +216,14 @@ export {
   PROJECTION_MANIFEST_PATH,
   IDENTITY_RECORD_PATH,
   matchAnyGlob,
+  describeHost,
+  loadHostRegistry,
+  probeHost,
+  buildHostAdapter,
+  materializeHostBuild,
+  planHost,
+  assertPlanConsistency,
+  refuseHostApply,
 };
 export { ContractsError };
 

package/src/report.mjs

@@ -0,0 +1,335 @@
+import process from "node:process";
+import { lstat, readFile, realpath, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import {
+  buildBinding,
+  checkReport,
+  computeModelDigest,
+  computeResultDigest,
+  digestReport,
+  readFileContained,
+  renderReportMarkdown,
+  resolveContained,
+  validateReportModel,
+  writeFileAtomic,
+} from "skill-family-harness-node";
+import { ContractsError } from "skill-family-contracts";
+import { invalidParamsError, kitError, KIT_ERROR_KINDS } from "./errors.mjs";
+import { resolveTargetRoot } from "./workspace.mjs";
+
+/**
+ * Report sub-actions of the existing kit commands (FND-ADR-005 / FND-DES-004).
+ *
+ * These are positional sub-actions, not new top-level commands: the kit keeps
+ * exactly four commands.
+ *
+ *   projection report  — render one validated report model to neutral Markdown
+ *   check report       — grade one rendered report against its model and source result
+ *
+ * Write discipline: rendering writes nothing by default (Markdown goes to
+ * stdout); a file is written only when explicit --out/--binding paths are
+ * given, and every such path is contained inside --root and written
+ * atomically. `check report` never writes. Hard failures and advisory style
+ * warnings are separate outputs: style warnings never block a
+ * machine-correct report, and hard failures never exit 0.
+ *
+ * Actions return { status: "ok" | "findings" | "rejected", output }; the CLI
+ * maps status onto KIT_EXIT_CODES (0/1/2). Throws carry registered SFC codes.
+ */
+
+async function readReportJson(rootAbs, relPath, role) {
+  if (typeof relPath !== "string" || relPath.length === 0) {
+    throw invalidParamsError(`${role} path must be a non-empty relative path`, { flag: `--${role}` });
+  }
+  let text;
+  try {
+    text = await readFileContained(rootAbs, relPath, { encoding: "utf8" });
+  } catch (cause) {
+    throw kitError(
+      KIT_ERROR_KINDS.REPORT_INPUT_MISSING,
+      `report ${role} is missing or unreadable: ${relPath}`,
+      { path: relPath, causeKind: cause && cause.details ? cause.details.kind : undefined },
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw kitError(
+      KIT_ERROR_KINDS.CONTRACT_PARSE_FAILED,
+      `report ${role} is not valid JSON: ${relPath}`,
+      { path: relPath },
+    );
+  }
+}
+
+async function readReportText(rootAbs, relPath, role) {
+  if (typeof relPath !== "string" || relPath.length === 0) {
+    throw invalidParamsError(`${role} path must be a non-empty relative path`, { flag: `--${role}` });
+  }
+  try {
+    return await readFileContained(rootAbs, relPath, { encoding: "utf8" });
+  } catch (cause) {
+    throw kitError(
+      KIT_ERROR_KINDS.REPORT_INPUT_MISSING,
+      `report ${role} is missing or unreadable: ${relPath}`,
+      { path: relPath, causeKind: cause && cause.details ? cause.details.kind : undefined },
+    );
+  }
+}
+
+async function canonicalCandidate(absPath) {
+  try {
+    return await realpath(absPath);
+  } catch {
+    const missing = [path.basename(absPath)];
+    let ancestor = path.dirname(absPath);
+    while (true) {
+      try {
+        return path.join(await realpath(ancestor), ...missing);
+      } catch {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor) return absPath;
+        missing.unshift(path.basename(ancestor));
+        ancestor = parent;
+      }
+    }
+  }
+}
+
+async function describeReportPath(rootAbs, relPath, role, { output = false } = {}) {
+  const absPath = await resolveContained(rootAbs, relPath);
+  let entry = null;
+  try {
+    entry = await lstat(absPath);
+  } catch {
+    entry = null;
+  }
+  if (output && entry?.isSymbolicLink()) {
+    throw kitError(
+      KIT_ERROR_KINDS.REPORT_PATH_CONFLICT,
+      `report ${role} must not be a symbolic link`,
+      { role, path: relPath },
+    );
+  }
+  if (output && entry && !entry.isFile()) {
+    throw kitError(
+      KIT_ERROR_KINDS.REPORT_PATH_CONFLICT,
+      `report ${role} must be absent or a regular file`,
+      { role, path: relPath },
+    );
+  }
+  let identity = null;
+  if (entry) {
+    try {
+      const inspected = await stat(absPath);
+      identity = `${inspected.dev}:${inspected.ino}`;
+    } catch {
+      identity = null;
+    }
+  }
+  return {
+    role,
+    relPath,
+    absPath,
+    canonicalPath: await canonicalCandidate(absPath),
+    identity,
+    existed: entry !== null,
+  };
+}
+
+function samePath(left, right) {
+  return left.canonicalPath === right.canonicalPath ||
+    (left.identity !== null && left.identity === right.identity);
+}
+
+async function stageReportOutputs(rootAbs, options, markdown, bindingDocument) {
+  const inputs = [
+    await describeReportPath(rootAbs, options.model, "model"),
+    await describeReportPath(rootAbs, options.result, "result"),
+  ];
+  const outputs = [
+    await describeReportPath(rootAbs, options.out, "out", { output: true }),
+    await describeReportPath(rootAbs, options.binding, "binding", { output: true }),
+  ];
+  for (const [index, output] of outputs.entries()) {
+    for (const other of [...inputs, ...outputs.slice(0, index)]) {
+      if (samePath(output, other)) {
+        throw kitError(
+          KIT_ERROR_KINDS.REPORT_PATH_CONFLICT,
+          `report ${output.role} aliases ${other.role}; inputs and outputs must be distinct`,
+          { role: output.role, path: output.relPath, conflictsWith: other.role },
+        );
+      }
+    }
+  }
+  const contents = [markdown, `${JSON.stringify(bindingDocument, null, 2)}\n`];
+  return Promise.all(outputs.map(async (output, index) => ({
+    ...output,
+    content: contents[index],
+    priorBytes: output.existed ? await readFile(output.absPath) : null,
+  })));
+}
+
+async function rollbackReportOutputs(rootAbs, written, rollbackWrite = writeFileAtomic) {
+  const failures = [];
+  for (const output of [...written].reverse()) {
+    try {
+      if (output.priorBytes === null) {
+        await rm(output.absPath, { force: true });
+      } else {
+        await rollbackWrite(rootAbs, output.relPath, output.priorBytes);
+      }
+    } catch (cause) {
+      failures.push({ role: output.role, message: cause?.message ?? String(cause) });
+    }
+  }
+  return failures;
+}
+
+async function commitReportOutputs(rootAbs, staged, fileOps = {}) {
+  const commitWrite = fileOps.commitWrite ?? writeFileAtomic;
+  const rollbackWrite = fileOps.rollbackWrite ?? writeFileAtomic;
+  const written = [];
+  try {
+    for (const output of staged) {
+      await commitWrite(rootAbs, output.relPath, output.content);
+      written.push(output);
+    }
+  } catch (cause) {
+    const rollbackFailures = await rollbackReportOutputs(rootAbs, written, rollbackWrite);
+    if (rollbackFailures.length === 0 && cause instanceof ContractsError) throw cause;
+    throw kitError(
+      KIT_ERROR_KINDS.REPORT_WRITE_FAILED,
+      "report output group commit failed; committed outputs were rolled back",
+      {
+        causeCode: cause?.code,
+        causeKind: cause?.details?.kind,
+        causeMessage: cause?.message ?? String(cause),
+        rollbackFailures,
+      },
+    );
+  }
+}
+
+/**
+ * `projection report`: deterministic render of one caller-authored report model.
+ *
+ * Options: root, model (required), result (required), out, binding.
+ * Without --out the Markdown goes to stdout and nothing is written; with
+ * --out, --binding is mandatory and only those explicit contained paths are
+ * written, atomically. A missing report element rejects with an SFC3002 list
+ * and writes nothing (no half report).
+ */
+export async function renderReportAction(options = {}) {
+  const rootAbs = await resolveTargetRoot(options.root ?? ".");
+  if (!options.model) {
+    throw invalidParamsError("projection report: --model <path> is required", { flag: "--model" });
+  }
+  if (!options.result) {
+    throw invalidParamsError("projection report: --result <path> is required", { flag: "--result" });
+  }
+  if (options.out && !options.binding) {
+    return {
+      status: "rejected",
+      output: {
+        kind: "skill-family.kit.report-render",
+        ok: false,
+        errors: [{
+          code: "SFC3002",
+          message: "missing report element: binding",
+          details: { element: "binding" },
+        }],
+      },
+    };
+  }
+  if (!options.out && options.binding) {
+    throw invalidParamsError("projection report: --binding requires --out", { flag: "--binding" });
+  }
+  const reportModel = await readReportJson(rootAbs, options.model, "model");
+  const resultDocument = await readReportJson(rootAbs, options.result, "result");
+  const validated = validateReportModel(reportModel, { resultDocument });
+  if (!validated.ok) {
+    return {
+      status: "rejected",
+      output: {
+        kind: "skill-family.kit.report-render",
+        ok: false,
+        errors: validated.hardFailures,
+      },
+    };
+  }
+
+  const markdown = renderReportMarkdown(reportModel);
+  const summary = {
+    kind: "skill-family.kit.report-render",
+    ok: true,
+    runId: reportModel.identity.runId,
+    locale: reportModel.identity.locale,
+    modelDigest: computeModelDigest(reportModel),
+    resultDigest: computeResultDigest(resultDocument),
+    reportDigest: digestReport(markdown),
+    bytes: Buffer.byteLength(markdown, "utf8"),
+    writes: [],
+  };
+
+  if (options.out) {
+    const bindingDocument = buildBinding(reportModel, resultDocument, markdown);
+    const staged = await stageReportOutputs(rootAbs, options, markdown, bindingDocument);
+    await commitReportOutputs(rootAbs, staged, options.fileOps);
+    summary.writes.push({ path: options.out, role: "report" });
+    summary.writes.push({ path: options.binding, role: "binding" });
+  } else {
+    // stdout mode: the Markdown itself is the only stdout payload.
+    process.stdout.write(markdown);
+  }
+  return { status: "ok", output: options.out ? summary : undefined };
+}
+
+/**
+ * `check report`: graded diagnosis of one rendered report.
+ *
+ * Options: root, report (required), model (required), result (required), binding.
+ * Read-only, never writes. Hard failures (SFC3001/SFC3002/SFC3003)
+ * are findings (exit 1); advisory style warnings are reported alongside but
+ * never change the verdict; usage/mechanism problems throw (exit 2).
+ */
+export async function checkReportAction(options = {}) {
+  const rootAbs = await resolveTargetRoot(options.root ?? ".");
+  if (!options.report) {
+    throw invalidParamsError("check report: --report <path> is required", { flag: "--report" });
+  }
+  if (!options.model) {
+    throw invalidParamsError("check report: --model <path> is required", { flag: "--model" });
+  }
+  if (!options.result) {
+    throw invalidParamsError("check report: --result <path> is required", { flag: "--result" });
+  }
+  const reportMarkdown = await readReportText(rootAbs, options.report, "report");
+  const reportModel = await readReportJson(rootAbs, options.model, "model");
+  const resultDocument = await readReportJson(rootAbs, options.result, "result");
+  const binding = options.binding
+    ? await readReportJson(rootAbs, options.binding, "binding")
+    : undefined;
+
+  const graded = checkReport({
+    reportMarkdown,
+    reportModel,
+    resultDocument,
+    binding,
+  });
+
+  return {
+    status: graded.ok ? "ok" : "findings",
+    output: {
+      kind: "skill-family.kit.report-check",
+      ok: graded.ok,
+      hardFailures: graded.hardFailures,
+      styleWarnings: graded.styleWarnings,
+      digests: {
+        model: computeModelDigest(reportModel),
+        report: digestReport(reportMarkdown),
+        result: computeResultDigest(resultDocument),
+      },
+    },
+  };
+}