@clossys/launcher 0.3.1 → 0.5.0

package/src/plan-contract.ts

@@ -0,0 +1,179 @@
+// The plan record and the engagement brief (issue #1475), validated against
+// the shared contracts docs/contracts/advisor-plan.json, engagement-brief.json
+// and engagement-context.json -- in the public repository, not shipped in this package.
+// This package's build packs their content into
+// src/generated/ as plain data, with a generated copy of the one contract
+// checker @clossys/advisor also uses, so Launcher and Advisor validate
+// against the same definition with no runtime dependency between them.
+// The TypeScript types below describe the same shapes for callers; they
+// validate nothing.
+
+import { formatContractViolation, validateAgainstContract } from "./generated/contract-schema.generated.js";
+import type { ContractSchema } from "./generated/contract-schema.generated.js";
+import { PLAN_CONTRACTS } from "./generated/plan-contracts.generated.js";
+import { briefRuleViolations, planRuleViolations } from "./plan-rules.js";
+import type { ContractRuleId } from "./plan-rules.js";
+
+/** An engagement-context field id (docs/contracts/engagement-context.json, in the public repository, not shipped in this package). */
+export type EngagementContextFieldId = "business" | "product" | "audience" | "stage" | "intent" | "constraints";
+
+/** An unknown context field, or a known one whose value is one of that field's fixed choice ids -- never founder text. */
+export type EngagementContextField =
+  | { readonly id: EngagementContextFieldId; readonly state: "unknown" }
+  | { readonly id: EngagementContextFieldId; readonly state: "known"; readonly value: string };
+
+/** The engagement-context snapshot a brief may carry (docs/contracts/engagement-context.json, in the public repository, not shipped in this package). */
+export interface EngagementContext {
+  readonly schemaVersion: 1;
+  readonly fields: readonly EngagementContextField[];
+}
+
+export type GoalDirection = "increase" | "decrease" | "maintain" | "target-range";
+
+export interface EngagementBriefRole {
+  readonly role: string;
+  readonly why: string;
+  readonly goal: { readonly metric: string; readonly direction: GoalDirection };
+  readonly inputsFrom: readonly string[];
+  readonly outputsTo: readonly string[];
+}
+
+/** clossys/brief.json (docs/contracts/engagement-brief.json, in the public repository, not shipped in this package). */
+export interface EngagementBrief {
+  readonly schemaVersion: 1;
+  readonly problem: string;
+  readonly roles: readonly EngagementBriefRole[];
+  readonly sequence: readonly string[];
+  readonly deliverables: readonly string[];
+  /** The roles staffed in the repository this brief is written to, in plan order; absent in the hub brief (#1178). */
+  readonly staffedHere?: readonly string[];
+  /** Optional snapshot of the hub's engagement context; absent means every field is unknown. */
+  readonly context?: EngagementContext;
+}
+
+export type BlockerKind = "missing-input" | "missing-authority" | "failing-evidence" | "unavailable-environment" | "contradiction";
+
+/** One capability at rest with exactly one next action: who does it, how, and by when. */
+export interface PlanBlocker {
+  readonly capabilityId: string;
+  readonly kind: BlockerKind;
+  readonly owner: string;
+  readonly nextAction: { readonly who: string; readonly how: string; readonly byWhen: string };
+  /** ISO 8601 date-time the blocker was recorded. */
+  readonly since: string;
+}
+
+export interface PlanDecision {
+  readonly at: string;
+  readonly recommended: string;
+  readonly chosen: string;
+  readonly by: string;
+  /** On an approving decision, the digest of the exact change the approver was shown; an approval without it binds nothing (#1178). */
+  readonly subjectDigest?: string;
+}
+
+/** A kit recommended for the plan (#1178). */
+export interface PlanKit {
+  readonly id: string;
+  readonly source: "preset" | "composed";
+  readonly verdict: "recommended";
+}
+
+/** Which roles work in one repository, named by its repository inventory id (#1178). */
+export interface PlanStaffing {
+  readonly repository: string;
+  readonly roles: readonly string[];
+}
+
+/** One exact package act: one version and one sha512 integrity value (#1178). */
+export interface PlanPackageAct {
+  readonly planItem: string;
+  readonly repository: string;
+  readonly act: "install" | "pin-starter";
+  readonly name: string;
+  readonly version: string;
+  readonly integrity: string;
+  readonly placement: "dependencies" | "devDependencies";
+}
+
+/** clossys/advisor/plan.json (docs/contracts/advisor-plan.json, in the public repository, not shipped in this package). */
+export interface AdvisorPlan {
+  readonly schemaVersion: 1;
+  readonly asOf: string;
+  readonly mandate: { readonly problem: string; readonly primaryProblemId: string; readonly roles: readonly string[] };
+  readonly whereWeAre: readonly string[];
+  readonly recommendedNext: { readonly action: string; readonly owner: string; readonly due?: string } | null;
+  readonly decisions: readonly PlanDecision[];
+  readonly blockers: readonly PlanBlocker[];
+  readonly kits?: readonly PlanKit[];
+  readonly staffing?: readonly PlanStaffing[];
+  /** Present exactly when `resolution` is. */
+  readonly packages?: readonly PlanPackageAct[];
+  readonly resolution?: { readonly snapshotDigest: string };
+  /** Declares that copy a delegate approved is accepted on production (issue #1586); read by @clossys/writer, not by this package. */
+  readonly delegatedCopyApproval?: { readonly target: "production"; readonly scopes?: readonly string[] };
+}
+
+/** `reason` lists every violation, separated by `; `, each naming the field at fault (for example `plan.blockers[0].capabilityId is required`). */
+export type ValidationResult = { readonly valid: true } | { readonly valid: false; readonly reason: string };
+
+/** Resolves a packed shared contract by its docs/contracts/ file name. Throws for a name that was not packed. */
+export function loadContract(name: string): ContractSchema {
+  const contract = Object.hasOwn(PLAN_CONTRACTS, name) ? PLAN_CONTRACTS[name] : undefined;
+  if (contract === undefined) throw new Error(`no packed contract named ${JSON.stringify(name)}`);
+  return contract;
+}
+
+/** One reason a plan or brief is refused: `rule` is "schema" for the contract's keywords, else the code rule's id. */
+export interface DocumentViolation {
+  readonly rule: "schema" | ContractRuleId;
+  /** The field at fault, like `staffing[1].repository`, or "" for the document itself. */
+  readonly path: string;
+  /** The whole message, starting with the label and path; it never quotes a value. */
+  readonly message: string;
+}
+
+function violationsOf<T>(contractName: string, label: string, value: unknown, rules: (document: T) => readonly { rule: ContractRuleId; path: string; message: string }[]): DocumentViolation[] {
+  const schema = validateAgainstContract(loadContract(contractName), value, loadContract);
+  if (schema.length > 0) return schema.map((violation) => ({ rule: "schema", path: violation.path, message: formatContractViolation(label, violation) }));
+  // The code rules relate fields to one another, so they run only on a document whose shape is known good.
+  return rules(value as T).map((violation) => ({ rule: violation.rule, path: violation.path, message: `${label}.${violation.path} ${violation.message} (rule ${violation.rule})` }));
+}
+
+function result(violations: readonly DocumentViolation[]): ValidationResult {
+  if (violations.length === 0) return { valid: true };
+  return { valid: false, reason: violations.map((violation) => violation.message).join("; ") };
+}
+
+/** Every reason a plan is refused: the plan contract's schema, then, once that passes, its code rules R1-R12. */
+export function advisorPlanViolations(value: unknown): DocumentViolation[] {
+  return violationsOf<AdvisorPlan>("advisor-plan.json", "plan", value, planRuleViolations);
+}
+
+/** Every reason a brief is refused: the brief contract's schema, then, once that passes, its code rules B1-B2. */
+export function engagementBriefViolations(value: unknown): DocumentViolation[] {
+  return violationsOf<EngagementBrief>("engagement-brief.json", "brief", value, briefRuleViolations);
+}
+
+/**
+ * Validates a brief against docs/contracts/engagement-brief.json, including
+ * its optional `context` snapshot against engagement-context.json: a known
+ * context value must be one of that field's fixed choice ids, because the
+ * brief is committed in every staffed repository. Both contracts are in the public repository, not shipped in this package.
+ * Once the schema passes, the contract's code rules run: every `staffedHere`
+ * entry is one of `roles[].role` (B1), and none repeats (B2). Never mutates,
+ * never re-derives content, and no reason echoes a value from the brief.
+ */
+export function validateEngagementBrief(value: unknown): ValidationResult {
+  return result(engagementBriefViolations(value));
+}
+
+/**
+ * Validates a plan against docs/contracts/advisor-plan.json (in the public repository, not shipped in this package):
+ * its schema, then, once that passes, its code rules R1-R12 -- staffing and
+ * package entries that repeat, the joins between staffing, the mandate
+ * and packages, and each planItem derived from its act (#1178). No reason echoes a value from the plan.
+ */
+export function validateAdvisorPlan(value: unknown): ValidationResult {
+  return result(advisorPlanViolations(value));
+}

package/src/plan-digest.ts

@@ -0,0 +1,102 @@
+// The canonical plan digest (issue #1475), implemented from its one
+// definition in this package's source repository,
+// docs/contracts/advisor-plan-digest.md. An approval binds this value, so it
+// names exactly which plan was approved. @clossys/advisor implements the same
+// definition separately; both packages are tested against the same fixture
+// corpus (docs/contracts/advisor-plan-digest.fixture.json), so they compute
+// identical digests. Both files are in the public repository, not shipped in this package.
+// This implementation writes the RFC 8785 escaping out
+// character by character rather than leaning on JSON.stringify, so the
+// corpus checks two genuinely separate readings of the definition.
+
+import { createHash } from "node:crypto";
+import { validateAdvisorPlan } from "./plan-contract.js";
+import type { AdvisorPlan } from "./plan-contract.js";
+
+/** The top-level plan members the digest leaves out: when the file was written, and the decisions an approval is recorded in. */
+export const PLAN_DIGEST_EXCLUDED_FIELDS: readonly string[] = ["asOf", "decisions"];
+
+const SHORT_ESCAPES: Readonly<Record<number, string>> = { 0x08: "\\b", 0x09: "\\t", 0x0a: "\\n", 0x0c: "\\f", 0x0d: "\\r", 0x22: '\\"', 0x5c: "\\\\" };
+
+function quote(text: string): string {
+  let out = '"';
+  for (let index = 0; index < text.length; index += 1) {
+    const unit = text.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = index + 1 < text.length ? text.charCodeAt(index + 1) : -1;
+      if (next < 0xdc00 || next > 0xdfff) throw new TypeError("canonical JSON refuses a string that is not well-formed Unicode (a lone surrogate)");
+      out += text[index]! + text[index + 1]!;
+      index += 1;
+      continue;
+    }
+    if (unit >= 0xdc00 && unit <= 0xdfff) throw new TypeError("canonical JSON refuses a string that is not well-formed Unicode (a lone surrogate)");
+    const short = SHORT_ESCAPES[unit];
+    if (short !== undefined) out += short;
+    else if (unit < 0x20) out += `\\u${unit.toString(16).padStart(4, "0")}`;
+    else out += text[index]!;
+  }
+  return `${out}"`;
+}
+
+/** Orders two keys by their UTF-16 code units, as RFC 8785 requires. */
+function compareCodeUnits(left: string, right: string): number {
+  const length = Math.min(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = left.charCodeAt(index) - right.charCodeAt(index);
+    if (difference !== 0) return difference;
+  }
+  return left.length - right.length;
+}
+
+/**
+ * RFC 8785 (JSON Canonicalization Scheme) serialization: no whitespace,
+ * object members sorted by UTF-16 code units, strings escaped only where
+ * JSON requires, numbers as ECMAScript writes them. Throws on anything JSON
+ * cannot carry (undefined, a function, a non-finite number) and on a lone
+ * surrogate, rather than silently dropping or repairing it.
+ */
+export function canonicalJson(value: unknown): string {
+  switch (typeof value) {
+    case "boolean":
+      return value ? "true" : "false";
+    case "string":
+      return quote(value);
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError("canonical JSON refuses a non-finite number");
+      return value === 0 ? "0" : String(value);
+    case "object": {
+      if (value === null) return "null";
+      if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+      const record = value as Record<string, unknown>;
+      const members = Object.keys(record)
+        .sort(compareCodeUnits)
+        .map((key) => `${quote(key)}:${canonicalJson(record[key])}`);
+      return `{${members.join(",")}}`;
+    }
+    default:
+      throw new TypeError(`canonical JSON refuses a value of type ${typeof value}`);
+  }
+}
+
+/**
+ * `sha256:` and the lowercase hex SHA-256 of the UTF-8 bytes of
+ * `canonicalJson(value)` (issue #1178). The one digest step the plan digest,
+ * the change-set digest and the bundle digest share; each decides only what
+ * `value` is. Throws whatever `canonicalJson()` throws.
+ */
+export function canonicalDigest(value: unknown): string {
+  return `sha256:${createHash("sha256").update(Buffer.from(canonicalJson(value), "utf8")).digest("hex")}`;
+}
+
+/**
+ * `sha256:` and the lowercase hex SHA-256 of the canonical JSON of the plan
+ * without `asOf` and `decisions`. Throws when the plan does not validate
+ * against the plan contract: an invalid plan has no digest.
+ */
+export function planDigest(plan: AdvisorPlan): string {
+  const validation = validateAdvisorPlan(plan);
+  if (!validation.valid) throw new TypeError(`an invalid plan has no digest: ${validation.reason}`);
+  const subject: Record<string, unknown> = {};
+  for (const [key, member] of Object.entries(plan)) if (!PLAN_DIGEST_EXCLUDED_FIELDS.includes(key)) subject[key] = member;
+  return canonicalDigest(subject);
+}

package/src/plan-rules.ts

@@ -0,0 +1,188 @@
+// The plan and brief contracts' code rules (issue #1178): the checks the
+// contracts' JSON Schema keywords cannot express, because each one relates one
+// field to another. They are defined once, as prose in the descriptions of
+// the shared contracts docs/contracts/advisor-plan.json (R1-R12) and
+// engagement-brief.json (B1-B2) -- in the public repository, not shipped in
+// this package. @clossys/advisor implements the same rules separately; both
+// packages are tested against one corpus,
+// docs/contracts/advisor-plan-rules.fixture.json (likewise not shipped), so a
+// plan or brief Advisor accepts, Launcher accepts, and the reverse.
+//
+// These functions assume the value already passed the schema: the validators
+// in plan-contract.ts run them only then. A violation names its rule and the
+// position of the field at fault, never a value, because a plan or brief can
+// carry founder text.
+
+import { PLAN_CONTRACTS } from "./generated/plan-contracts.generated.js";
+import type { AdvisorPlan, EngagementBrief } from "./plan-contract.js";
+
+/** A code rule of the plan contract (R1-R12) or the brief contract (B1-B2). */
+export type ContractRuleId = "R1" | "R2" | "R3" | "R4" | "R5" | "R6" | "R7" | "R8" | "R9" | "R10" | "R11" | "R12" | "B1" | "B2";
+
+/**
+ * The roles whose package lives in the engagement hub only, read from the
+ * packed plan contract's `definitions.hubOnlyRoles`, the one list every
+ * package that validates a plan reads (issue #1178). Code rules R2 and R11
+ * use it. A packed contract without a well-formed list is a build defect, so
+ * loading this module throws rather than judge plans against a guess.
+ */
+export const HUB_ONLY_ROLES: readonly string[] = (() => {
+  const definitions = PLAN_CONTRACTS["advisor-plan.json"]?.definitions as Record<string, { const?: unknown }> | undefined;
+  const roles = definitions?.hubOnlyRoles?.const;
+  if (!Array.isArray(roles) || roles.some((role) => typeof role !== "string")) throw new Error("the packed plan contract has no well-formed definitions.hubOnlyRoles");
+  return Object.freeze([...(roles as string[])]);
+})();
+
+export interface ContractRuleViolation {
+  readonly rule: ContractRuleId;
+  /** The field at fault, such as `staffing[1].repository`. */
+  readonly path: string;
+  /** What is wrong, by position only. */
+  readonly message: string;
+}
+
+/** Calls `onRepeat(index, firstIndex)` for every item whose key an earlier item already had. One pass, with a Map. */
+function eachRepeat<T>(items: readonly T[], key: (item: T) => string, onRepeat: (index: number, firstIndex: number) => void): void {
+  const first = new Map<string, number>();
+  for (let index = 0; index < items.length; index += 1) {
+    const value = key(items[index]!);
+    const earlier = first.get(value);
+    if (earlier === undefined) first.set(value, index);
+    else onRepeat(index, earlier);
+  }
+}
+
+/**
+ * A document's own member, or undefined. The schema checker sees only own
+ * members, so these rules read only those too: a member inherited from a
+ * prototype is ignored, never judged -- exactly as @clossys/advisor does.
+ */
+function own<T extends object, K extends keyof T>(document: T, name: K): T[K] | undefined {
+  return Object.hasOwn(document, name) ? document[name] : undefined;
+}
+
+/** Every violation of R1-R12, for a plan that already passed the plan contract's schema. */
+export function planRuleViolations(plan: AdvisorPlan): ContractRuleViolation[] {
+  const out: ContractRuleViolation[] = [];
+  const add = (rule: ContractRuleId, path: string, message: string): void => {
+    out.push({ rule, path, message });
+  };
+  const staffing = own(plan, "staffing");
+  const packages = own(plan, "packages");
+  const kits = own(plan, "kits");
+  const mandateRoles = plan.mandate.roles;
+
+  // R1: one staffing entry per repository, ids compared case-insensitively.
+  if (staffing !== undefined) {
+    eachRepeat(staffing, (entry) => entry.repository.toLowerCase(), (index, first) => {
+      add("R1", `staffing[${index}].repository`, `names the same repository as staffing[${first}].repository (repository ids compare case-insensitively)`);
+    });
+  }
+
+  // R2: staffed roles and mandate roles agree, in both directions; a hub-only role is never required to be staffed.
+  if (staffing !== undefined) {
+    const inMandate = new Set<string>(mandateRoles);
+    const staffedRoles = new Set<string>();
+    for (let index = 0; index < staffing.length; index += 1) {
+      const roles = staffing[index]!.roles;
+      for (let position = 0; position < roles.length; position += 1) {
+        staffedRoles.add(roles[position]!);
+        if (!inMandate.has(roles[position]!)) add("R2", `staffing[${index}].roles[${position}]`, "is not one of mandate.roles");
+      }
+    }
+    for (let position = 0; position < mandateRoles.length; position += 1) {
+      if (!staffedRoles.has(mandateRoles[position]!) && !HUB_ONLY_ROLES.includes(mandateRoles[position]!)) add("R2", `mandate.roles[${position}]`, "is not staffed in any staffing entry");
+    }
+  }
+
+  if (packages !== undefined) {
+    // R3: every act names a staffed repository, spelled exactly the same.
+    const staffed = new Set<string>((staffing ?? []).map((entry) => entry.repository));
+    for (let index = 0; index < packages.length; index += 1) {
+      if (!staffed.has(packages[index]!.repository)) add("R3", `packages[${index}].repository`, "is not spelled exactly as any staffing[].repository");
+    }
+    // R4: planItem ids are unique.
+    eachRepeat(packages, (act) => act.planItem, (index, first) => {
+      add("R4", `packages[${index}].planItem`, `repeats packages[${first}].planItem`);
+    });
+    // R5: one act per (repository, name), repositories compared case-insensitively.
+    eachRepeat(packages, (act) => `${act.repository.toLowerCase()}\u0000${act.name}`, (index, first) => {
+      add("R5", `packages[${index}].name`, `repeats the repository and name of packages[${first}] (repositories compare case-insensitively)`);
+    });
+    // R12: every planItem is exactly its act's repository, a colon and its name, in the same letter case.
+    for (let index = 0; index < packages.length; index += 1) {
+      const act = packages[index]!;
+      if (act.planItem !== `${act.repository}:${act.name}`) add("R12", `packages[${index}].planItem`, "is not this act's repository, a colon and its name, in the same letter case");
+    }
+  }
+
+  // R6: resolution exactly when packages.
+  const hasPackages = Object.hasOwn(plan, "packages");
+  const hasResolution = Object.hasOwn(plan, "resolution");
+  if (hasPackages && !hasResolution) add("R6", "resolution", "is required when packages is present");
+  if (!hasPackages && hasResolution) add("R6", "resolution", "must be absent when there are no packages");
+
+  // R7: kit ids are unique.
+  if (kits !== undefined) {
+    eachRepeat(kits, (kit) => kit.id, (index, first) => {
+      add("R7", `kits[${index}].id`, `repeats kits[${first}].id`);
+    });
+  }
+
+  // R8: no role twice within one staffing entry.
+  if (staffing !== undefined) {
+    for (let index = 0; index < staffing.length; index += 1) {
+      eachRepeat(staffing[index]!.roles, (role) => role, (position, first) => {
+        add("R8", `staffing[${index}].roles[${position}]`, `repeats staffing[${index}].roles[${first}]`);
+      });
+    }
+  }
+
+  // R9: no role twice in mandate.roles.
+  eachRepeat(mandateRoles, (role) => role, (position, first) => {
+    add("R9", `mandate.roles[${position}]`, `repeats mandate.roles[${first}]`);
+  });
+
+  // R10: at most one pin-starter act per repository (compared case-insensitively), and it is a devDependency.
+  if (packages !== undefined) {
+    const pins: number[] = [];
+    for (let index = 0; index < packages.length; index += 1) if (packages[index]!.act === "pin-starter") pins.push(index);
+    eachRepeat(pins, (index) => packages[index]!.repository.toLowerCase(), (position, first) => {
+      add("R10", `packages[${pins[position]}].act`, `is a second act of this kind for the repository of packages[${pins[first]}] (repositories compare case-insensitively)`);
+    });
+    for (const index of pins) {
+      if (packages[index]!.placement !== "devDependencies") add("R10", `packages[${index}].placement`, "must be devDependencies for a pin-starter act");
+    }
+  }
+
+  // R11: a hub-only role is never staffed in a repository.
+  if (staffing !== undefined) {
+    for (let index = 0; index < staffing.length; index += 1) {
+      const roles = staffing[index]!.roles;
+      for (let position = 0; position < roles.length; position += 1) {
+        if (HUB_ONLY_ROLES.includes(roles[position]!)) add("R11", `staffing[${index}].roles[${position}]`, "is a hub-only role, which works from the hub and is never staffed in a repository");
+      }
+    }
+  }
+  return out;
+}
+
+/** Every violation of B1-B2, for a brief that already passed the brief contract's schema. */
+export function briefRuleViolations(brief: EngagementBrief): ContractRuleViolation[] {
+  const out: ContractRuleViolation[] = [];
+  const add = (rule: ContractRuleId, path: string, message: string): void => {
+    out.push({ rule, path, message });
+  };
+  const staffedHere = own(brief, "staffedHere");
+  if (staffedHere === undefined) return out;
+  // B1: every entry is one of the brief's roles.
+  const roles = new Set<string>(brief.roles.map((entry) => entry.role));
+  for (let index = 0; index < staffedHere.length; index += 1) {
+    if (!roles.has(staffedHere[index]!)) add("B1", `staffedHere[${index}]`, "is not one of roles[].role");
+  }
+  // B2: no entry repeats.
+  eachRepeat(staffedHere, (role) => role, (index, first) => {
+    add("B2", `staffedHere[${index}]`, `repeats staffedHere[${first}]`);
+  });
+  return out;
+}