@aipper/aiws 0.0.24 → 0.0.25

package/src/governance.js

@@ -0,0 +1,157 @@
+import { UserError } from "./errors.js";
+import { loadWorkflowGovernanceRules } from "./spec.js";
+
+/**
+ * @param {any} status
+ */
+export function effectiveReviewCount(status) {
+  return Number(status?.reviewSignals?.effectiveCount ?? status?.collaboration?.counts?.review ?? 0);
+}
+
+/**
+ * @param {any} status
+ * @param {any} [governance]
+ */
+function collectGovernanceSignals(status, governance) {
+  const git = status?.git && typeof status.git === "object" ? status.git : {};
+  const lifecycle = status?.lifecycle && typeof status.lifecycle === "object" ? status.lifecycle : {};
+  const repo = status?.repo && typeof status.repo === "object" ? status.repo : {};
+  const gov = governance && typeof governance === "object" ? governance : status?.governance && typeof status.governance === "object" ? status.governance : {};
+  const reviewGates = status?.reviewGates && typeof status.reviewGates === "object" ? status.reviewGates : {};
+  const reviewGateSummary = reviewGates?.summary && typeof reviewGates.summary === "object" ? reviewGates.summary : {};
+  const reviewEffectiveCount = effectiveReviewCount(status);
+  const specReviewReady = reviewGates?.specReview?.ready === true || (!reviewGates.specReview && reviewEffectiveCount > 0);
+  const qualityReviewReady = reviewGates?.qualityReview?.ready === true || (!reviewGates.qualityReview && reviewEffectiveCount > 0);
+  const verifyBeforeCompleteReady = reviewGates?.verifyBeforeComplete?.ready === true;
+  const validateStampReady = reviewGates?.validateStamp?.ready === true;
+
+  return {
+    blockers_strict_count: Array.isArray(status?.blockersStrict) ? status.blockersStrict.length : 0,
+    tasks_unchecked: Number(status?.tasks?.unchecked || 0),
+    review_effective_count: reviewEffectiveCount,
+    evidence_persistent_count: Number(status?.evidence?.counts?.persistent || 0),
+    git_total: Number(git.total || 0),
+    git_staged: Number(git.staged || 0),
+    git_conflicted: Number(git.conflicted || 0),
+    lifecycle_evidence_runs: Number(lifecycle.evidenceRuns || 0),
+    finish_cleanup_pending_reason: String(lifecycle.finishCleanupPendingReason || ""),
+    finish_state: String(lifecycle.finishState || ""),
+    finish_state_reason: String(lifecycle.finishStateReason || ""),
+    repo_submodules: Number(repo.submodules || 0),
+    spec_review_ready: specReviewReady,
+    quality_review_ready: qualityReviewReady,
+    verify_before_complete_ready: verifyBeforeCompleteReady,
+    validate_stamp_ready: validateStampReady,
+    spec_review_status: String(reviewGates?.specReview?.status || (specReviewReady ? "ready" : "missing")),
+    quality_review_status: String(reviewGates?.qualityReview?.status || (qualityReviewReady ? "ready" : "missing")),
+    verify_before_complete_status: String(
+      reviewGates?.verifyBeforeComplete?.status || (verifyBeforeCompleteReady ? "ready" : "missing"),
+    ),
+    validate_stamp_status: String(reviewGates?.validateStamp?.status || (validateStampReady ? "ready" : "missing")),
+    dual_review_missing_count: Number(reviewGateSummary?.dualReviewMissingCount || 0),
+    finish_gate_missing_count: Number(reviewGateSummary?.finishGateMissingCount || 0),
+    governance_current_stage: String(gov.currentStage || ""),
+    governance_recommended_stage: String(gov.recommendedStage || ""),
+    governance_rule_id: String(gov.ruleId || ""),
+  };
+}
+
+/**
+ * @param {string} template
+ * @param {Record<string, string | number | boolean>} signals
+ */
+function renderTemplate(template, signals) {
+  return String(template || "").replace(/\{([a-z0-9_]+)\}/gi, (_, key) => String(signals[key] ?? ""));
+}
+
+/**
+ * @param {unknown} actual
+ * @param {any} condition
+ */
+function matchesLeafCondition(actual, condition) {
+  if (Object.prototype.hasOwnProperty.call(condition, "eq") && actual !== condition.eq) return false;
+  if (Object.prototype.hasOwnProperty.call(condition, "ne") && actual === condition.ne) return false;
+  if (Object.prototype.hasOwnProperty.call(condition, "gt") && !(Number(actual) > Number(condition.gt))) return false;
+  if (Object.prototype.hasOwnProperty.call(condition, "gte") && !(Number(actual) >= Number(condition.gte))) return false;
+  if (Object.prototype.hasOwnProperty.call(condition, "lt") && !(Number(actual) < Number(condition.lt))) return false;
+  if (Object.prototype.hasOwnProperty.call(condition, "lte") && !(Number(actual) <= Number(condition.lte))) return false;
+  if (Array.isArray(condition?.in) && !condition.in.includes(actual)) return false;
+  if (Array.isArray(condition?.notIn) && condition.notIn.includes(actual)) return false;
+  if (condition?.truthy === true && !actual) return false;
+  if (condition?.falsy === true && !!actual) return false;
+  return true;
+}
+
+/**
+ * @param {any} when
+ * @param {Record<string, string | number | boolean>} signals
+ */
+function matchesCondition(when, signals) {
+  if (!when || (typeof when === "object" && Object.keys(when).length === 0)) return true;
+  if (Array.isArray(when?.all)) return when.all.every((item) => matchesCondition(item, signals));
+  if (Array.isArray(when?.any)) return when.any.some((item) => matchesCondition(item, signals));
+  if (when?.not) return !matchesCondition(when.not, signals);
+  if (typeof when?.signal === "string") {
+    return matchesLeafCondition(signals[when.signal], when);
+  }
+  return false;
+}
+
+/**
+ * @param {string[]} lines
+ */
+function uniqueLines(lines) {
+  const seen = new Set();
+  /** @type {string[]} */
+  const out = [];
+  for (const raw of lines || []) {
+    const line = String(raw || "").trim();
+    if (!line || seen.has(line)) continue;
+    seen.add(line);
+    out.push(line);
+  }
+  return out;
+}
+
+/**
+ * @param {any} status
+ */
+export async function inferChangeGovernance(status) {
+  const spec = await loadWorkflowGovernanceRules();
+  const signals = collectGovernanceSignals(status);
+  const matched = spec.governanceRules.find((rule) => matchesCondition(rule?.when, signals));
+  if (!matched) {
+    throw new UserError("Failed to infer workflow governance from spec rules.", {
+      details: JSON.stringify({ source: spec.source, signals }, null, 2),
+    });
+  }
+  return {
+    phase: String(status?.phase || ""),
+    currentStage: String(matched.currentStage || ""),
+    recommendedStage: String(matched.recommendedStage || matched.currentStage || ""),
+    rationale: renderTemplate(String(matched.rationale || ""), signals),
+    ruleId: String(matched.id || ""),
+    source: spec.source,
+  };
+}
+
+/**
+ * @param {any} status
+ */
+export async function governanceGuidanceLines(status) {
+  const spec = await loadWorkflowGovernanceRules();
+  const governance = status?.governance && typeof status.governance === "object" ? status.governance : await inferChangeGovernance(status);
+  const signals = collectGovernanceSignals(status, governance);
+  /** @type {string[]} */
+  const lines = [];
+
+  for (const rule of spec.guidanceRules) {
+    if (!matchesCondition(rule?.when, signals)) continue;
+    const entries = Array.isArray(rule?.lines) ? rule.lines : [];
+    for (const entry of entries) lines.push(renderTemplate(String(entry || ""), signals));
+  }
+
+  const deduped = uniqueLines(lines);
+  if (deduped.length > 0) return deduped;
+  return ["按阶段契约继续推进当前 change"];
+}

package/src/json-schema-lite.js

@@ -0,0 +1,164 @@
+import { UserError } from "./errors.js";
+
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function joinPath(base, segment) {
+  if (!base || base === "$") return `$${segment}`;
+  return `${base}${segment}`;
+}
+
+function resolvePointer(rootSchema, ref) {
+  if (typeof ref !== "string" || !ref.startsWith("#/")) {
+    throw new UserError("Unsupported schema $ref.", { details: String(ref || "") });
+  }
+  const parts = ref
+    .slice(2)
+    .split("/")
+    .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+  let cur = rootSchema;
+  for (const part of parts) {
+    if (!isPlainObject(cur) && !Array.isArray(cur)) return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function typeMatches(value, type) {
+  switch (type) {
+    case "object":
+      return isPlainObject(value);
+    case "array":
+      return Array.isArray(value);
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    default:
+      return true;
+  }
+}
+
+/**
+ * @param {any} value
+ * @param {any} schema
+ * @param {any} rootSchema
+ * @param {string} curPath
+ * @param {string[]} errors
+ */
+function validateNode(value, schema, rootSchema, curPath, errors) {
+  if (!isPlainObject(schema)) return;
+
+  if (schema.$ref) {
+    const target = resolvePointer(rootSchema, schema.$ref);
+    if (!target) {
+      errors.push(`${curPath}: unresolved $ref ${schema.$ref}`);
+      return;
+    }
+    validateNode(value, target, rootSchema, curPath, errors);
+    return;
+  }
+
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    const matched = schema.anyOf.some((candidate) => {
+      const branchErrors = [];
+      validateNode(value, candidate, rootSchema, curPath, branchErrors);
+      return branchErrors.length === 0;
+    });
+    if (!matched) errors.push(`${curPath}: does not match anyOf`);
+  }
+
+  if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+    for (const candidate of schema.allOf) validateNode(value, candidate, rootSchema, curPath, errors);
+  }
+
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+    let matches = 0;
+    for (const candidate of schema.oneOf) {
+      const branchErrors = [];
+      validateNode(value, candidate, rootSchema, curPath, branchErrors);
+      if (branchErrors.length === 0) matches += 1;
+    }
+    if (matches !== 1) errors.push(`${curPath}: does not match exactly one schema`);
+  }
+
+  if (schema.type && !typeMatches(value, schema.type)) {
+    errors.push(`${curPath}: expected ${schema.type}`);
+    return;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(schema, "const") && value !== schema.const) {
+    errors.push(`${curPath}: expected const ${JSON.stringify(schema.const)}`);
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${curPath}: expected one of ${schema.enum.map((item) => JSON.stringify(item)).join(", ")}`);
+  }
+
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+      errors.push(`${curPath}: expected minLength ${schema.minLength}`);
+    }
+    if (typeof schema.pattern === "string") {
+      const re = new RegExp(schema.pattern);
+      if (!re.test(value)) errors.push(`${curPath}: does not match pattern ${schema.pattern}`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+      errors.push(`${curPath}: expected minItems ${schema.minItems}`);
+    }
+    if (schema.items) {
+      value.forEach((item, index) => validateNode(item, schema.items, rootSchema, joinPath(curPath, `[${index}]`), errors));
+    }
+  }
+
+  if (isPlainObject(value)) {
+    const entries = Object.keys(value);
+    if (typeof schema.minProperties === "number" && entries.length < schema.minProperties) {
+      errors.push(`${curPath}: expected minProperties ${schema.minProperties}`);
+    }
+    if (typeof schema.maxProperties === "number" && entries.length > schema.maxProperties) {
+      errors.push(`${curPath}: expected maxProperties ${schema.maxProperties}`);
+    }
+    const properties = isPlainObject(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const key of required) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) errors.push(`${curPath}: missing required property ${key}`);
+    }
+    for (const [key, childSchema] of Object.entries(properties)) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) continue;
+      validateNode(value[key], childSchema, rootSchema, joinPath(curPath, `.${key}`), errors);
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of entries) {
+        if (!Object.prototype.hasOwnProperty.call(properties, key)) {
+          errors.push(`${curPath}: unexpected property ${key}`);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * @param {any} value
+ * @param {any} schema
+ * @param {{ source: string }} options
+ */
+export function validateJsonSchemaLite(value, schema, options) {
+  const errors = [];
+  validateNode(value, schema, schema, "$", errors);
+  if (errors.length > 0) {
+    throw new UserError("Spec doc schema validation failed.", {
+      details: [options?.source || "", ...errors].filter(Boolean).join("\n"),
+    });
+  }
+}

package/src/opencode-env.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { pathExists, readText } from "./fs.js";
+
+const OPENCODE_AGENT_NAMES = ["planner-sisyphus", "librarian", "explore", "oracle"];
+
+/**
+ * @param {string} value
+ */
+function relativeOrDot(value) {
+  return value ? value.replaceAll(path.sep, "/") : ".";
+}
+
+/**
+ * @param {any} raw
+ * @param {string} agentName
+ */
+function readAgentState(raw, agentName) {
+  const agents = raw && typeof raw === "object" && raw.agents && typeof raw.agents === "object" ? raw.agents : {};
+  const entry = agents[agentName];
+  return {
+    present: !!entry && typeof entry === "object",
+    enabled: !!(entry && typeof entry === "object" && entry.enabled === true),
+    replacePlan: entry && typeof entry === "object" && typeof entry.replace_plan === "boolean" ? entry.replace_plan : null,
+  };
+}
+
+/**
+ * @param {string} workspaceRoot
+ */
+export async function detectOpenCodeEnvironment(workspaceRoot) {
+  const opencodeDir = path.join(workspaceRoot, ".opencode");
+  const configPath = path.join(opencodeDir, "oh-my-opencode.json");
+  const examplePath = path.join(opencodeDir, "oh-my-opencode.json.example");
+  const opencodeDirExists = await pathExists(opencodeDir);
+  const configExists = await pathExists(configPath);
+  const exampleExists = await pathExists(examplePath);
+
+  /** @type {any} */
+  let config = null;
+  let configStatus = "missing";
+  let configError = "";
+  if (configExists) {
+    try {
+      config = JSON.parse(await readText(configPath));
+      configStatus = "loaded";
+    } catch (error) {
+      configStatus = "invalid";
+      configError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  const agents = Object.fromEntries(OPENCODE_AGENT_NAMES.map((name) => [name, readAgentState(config, name)]));
+  const enabledAgents = OPENCODE_AGENT_NAMES.filter((name) => agents[name]?.enabled === true);
+  const recommendedAgentsReady = ["planner-sisyphus", "librarian", "explore", "oracle"].every((name) => agents[name]?.enabled === true);
+
+  return {
+    workspaceRoot,
+    opencodeDir,
+    opencodeDirExists,
+    configPath,
+    configExists,
+    configStatus,
+    configError,
+    examplePath,
+    exampleExists,
+    mode: configStatus === "loaded" ? "oMo-enabled" : "standard-opencode",
+    recommendedAgentsReady,
+    enabledAgents,
+    agents,
+    rel: {
+      opencodeDir: relativeOrDot(path.relative(workspaceRoot, opencodeDir)),
+      configPath: relativeOrDot(path.relative(workspaceRoot, configPath)),
+      examplePath: relativeOrDot(path.relative(workspaceRoot, examplePath)),
+    },
+  };
+}

package/src/spec.js

@@ -4,6 +4,9 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { pathExists, readText } from "./fs.js";
 import { UserError } from "./errors.js";
+import { validateJsonSchemaLite } from "./json-schema-lite.js";
+
+const specJsonDocCache = new Map();
 
 /**
  * @returns {Promise<{ rootDir: string, version: string }>}
@@ -62,3 +65,131 @@ export async function loadTemplate(templateId) {
   const manifest = JSON.parse(await readText(manifestPath));
   return { templateId, templateDir, manifest, specVersion: spec.version };
 }
+
+/**
+ * @param {string} relPath
+ */
+async function loadSpecJsonDoc(relPath) {
+  const spec = await loadSpecPackage();
+  const absPath = path.join(spec.rootDir, relPath);
+  const cacheKey = `${spec.rootDir}:${relPath}`;
+  if (specJsonDocCache.has(cacheKey)) {
+    return { spec, data: specJsonDocCache.get(cacheKey), absPath };
+  }
+  const raw = await readText(absPath);
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new UserError(`Invalid JSON in spec doc: ${relPath}`, {
+      details: error instanceof Error ? error.message : String(error),
+    });
+  }
+  specJsonDocCache.set(cacheKey, data);
+  return { spec, data, absPath };
+}
+
+async function loadValidatedSpecJsonDoc(relPath, schemaRelPath) {
+  const loaded = await loadSpecJsonDoc(relPath);
+  const { data: schema } = await loadSpecJsonDoc(schemaRelPath);
+  validateJsonSchemaLite(loaded.data, schema, { source: loaded.absPath });
+  return loaded;
+}
+
+export async function loadWorkflowGovernanceRules() {
+  const relPath = path.join("docs", "workflow-governance-rules.json");
+  const schemaRelPath = path.join("docs", "workflow-governance-rules.schema.json");
+  const { spec, data } = await loadValidatedSpecJsonDoc(relPath, schemaRelPath);
+  const governanceRules = data.governanceRules;
+  const guidanceRules = data.guidanceRules;
+  return {
+    ok: true,
+    source: "@aipper/aiws-spec/docs/workflow-governance-rules.json",
+    specVersion: spec.version,
+    version: Number(data?.version || 1),
+    description: String(data?.description || ""),
+    governanceRules,
+    guidanceRules,
+  };
+}
+
+export async function loadWorkflowStageContracts() {
+  const relPath = path.join("docs", "workflow-stage-contracts.json");
+  const schemaRelPath = path.join("docs", "workflow-stage-contracts.schema.json");
+  const { spec, data } = await loadValidatedSpecJsonDoc(relPath, schemaRelPath);
+  const stages = data.stages;
+  return {
+    ok: true,
+    source: "@aipper/aiws-spec/docs/workflow-stage-contracts.json",
+    specVersion: spec.version,
+    version: Number(data?.version || 1),
+    description: String(data?.description || ""),
+    standardChain: Array.isArray(data?.standardChain) ? data.standardChain : [],
+    notes: Array.isArray(data?.notes) ? data.notes : [],
+    stages,
+  };
+}
+
+export async function loadWorkflowRouterRules() {
+  const relPath = path.join("docs", "workflow-router-rules.json");
+  const schemaRelPath = path.join("docs", "workflow-router-rules.schema.json");
+  const { spec, data } = await loadValidatedSpecJsonDoc(relPath, schemaRelPath);
+  return {
+    ok: true,
+    source: "@aipper/aiws-spec/docs/workflow-router-rules.json",
+    specVersion: spec.version,
+    version: Number(data?.version || 1),
+    title: String(data?.title || ""),
+    description: String(data?.description || ""),
+    truthFiles: Array.isArray(data?.truthFiles) ? data.truthFiles : [],
+    bootstrapEntry: data.bootstrapEntry,
+    universalSequence: Array.isArray(data?.universalSequence) ? data.universalSequence : [],
+    routingRules: Array.isArray(data?.routingRules) ? data.routingRules : [],
+    routeCases: Array.isArray(data?.routeCases) ? data.routeCases : [],
+    clarificationTriggers: Array.isArray(data?.clarificationTriggers) ? data.clarificationTriggers : [],
+    universalRules: Array.isArray(data?.universalRules) ? data.universalRules : [],
+    notes: Array.isArray(data?.notes) ? data.notes : [],
+  };
+}
+
+export async function loadWorkflowReviewGates() {
+  const relPath = path.join("docs", "workflow-review-gates.json");
+  const schemaRelPath = path.join("docs", "workflow-review-gates.schema.json");
+  const { spec, data } = await loadValidatedSpecJsonDoc(relPath, schemaRelPath);
+  return {
+    ok: true,
+    source: "@aipper/aiws-spec/docs/workflow-review-gates.json",
+    specVersion: spec.version,
+    version: Number(data?.version || 1),
+    title: String(data?.title || ""),
+    description: String(data?.description || ""),
+    gates: Array.isArray(data?.gates) ? data.gates : [],
+    unifiedRules: Array.isArray(data?.unifiedRules) ? data.unifiedRules : [],
+    evidence: Array.isArray(data?.evidence) ? data.evidence : [],
+    notes: Array.isArray(data?.notes) ? data.notes : [],
+  };
+}
+
+export async function loadWorkflowDelegationContracts() {
+  const relPath = path.join("docs", "workflow-delegation-contracts.json");
+  const schemaRelPath = path.join("docs", "workflow-delegation-contracts.schema.json");
+  const { spec, data } = await loadValidatedSpecJsonDoc(relPath, schemaRelPath);
+  return {
+    ok: true,
+    source: "@aipper/aiws-spec/docs/workflow-delegation-contracts.json",
+    specVersion: spec.version,
+    version: Number(data?.version || 1),
+    title: String(data?.title || ""),
+    description: String(data?.description || ""),
+    purpose: Array.isArray(data?.purpose) ? data.purpose : [],
+    truthFiles: Array.isArray(data?.truthFiles) ? data.truthFiles : [],
+    delegationFlow: Array.isArray(data?.delegationFlow) ? data.delegationFlow : [],
+    roleTypes: Array.isArray(data?.roleTypes) ? data.roleTypes : [],
+    artifactTargets: Array.isArray(data?.artifactTargets) ? data.artifactTargets : [],
+    reviewConvergence: data?.reviewConvergence || {},
+    fallbackMode: data?.fallbackMode || {},
+    toolCapabilityMatrix: Array.isArray(data?.toolCapabilityMatrix) ? data.toolCapabilityMatrix : [],
+    universalRules: Array.isArray(data?.universalRules) ? data.universalRules : [],
+    notes: Array.isArray(data?.notes) ? data.notes : [],
+  };
+}