@cassiomc1/forgeloop 0.1.0

package/src/core/router.js

@@ -0,0 +1,296 @@
+import { GUIDE_IDS, PROTOCOL_VERSION } from "./protocol.js";
+
+export const ROUTING_SCHEMA_VERSION = 1;
+
+const WORK_TYPES = new Set([
+  "documentation",
+  "code",
+  "bug",
+  "refactor",
+  "backend",
+  "api",
+  "api-auth",
+  "complete-website",
+  "mobile-ui",
+  "web-game",
+  "html-video",
+  "infrastructure",
+  "security-review",
+  "performance",
+  "accessibility",
+  "test-only",
+  "dependency-update",
+  "release",
+]);
+
+const SIGNALS = Object.freeze({
+  surfaces: new Set([
+    "ui",
+    "forms",
+    "api",
+    "auth",
+    "data",
+    "database",
+    "mobile",
+    "desktop",
+    "game",
+    "video",
+    "ci",
+    "config",
+    "critical-path",
+  ]),
+  risks: new Set([
+    "untrusted-input",
+    "personal-data",
+    "secrets",
+    "external-service",
+    "publication",
+    "critical-path",
+    "performance",
+    "accessibility",
+  ]),
+  platforms: new Set(["web", "mobile", "desktop", "server", "ci", "cross-platform"]),
+});
+
+export const PLATFORM_SEMANTICS = Object.freeze({
+  web: Object.freeze({
+    mode: "informational-only",
+    description: "Web is recorded as context; surface, risk, and work signals select guides.",
+  }),
+  mobile: Object.freeze({
+    mode: "contextual",
+    reason: "PLATFORM_MOBILE",
+    description: "Mobile UI context adds performance guidance and reinforces design/accessibility.",
+  }),
+  desktop: Object.freeze({
+    mode: "contextual",
+    reason: "PLATFORM_DESKTOP",
+    description: "Desktop UI context reinforces design and accessibility guidance.",
+  }),
+  server: Object.freeze({
+    mode: "contextual",
+    reason: "PLATFORM_SERVER",
+    description: "Server authentication context adds testing and reinforces the trust boundary.",
+  }),
+  ci: Object.freeze({
+    mode: "contextual",
+    reason: "PLATFORM_CI",
+    description: "Executable CI changes add security review to the existing change checks.",
+  }),
+  "cross-platform": Object.freeze({
+    mode: "informational-only",
+    description: "Cross-platform is recorded as context; it does not select a guide by itself.",
+  }),
+});
+
+const WORK_GUIDES = Object.freeze({
+  "complete-website": ["premium", "design", "accessibility", "clean", "test", "security", "performance"],
+  "api-auth": ["clean", "test", "security", "performance"],
+  api: ["clean", "test"],
+  backend: ["clean", "test"],
+  code: ["clean", "test"],
+  bug: ["clean", "test"],
+  refactor: ["clean", "test"],
+  "dependency-update": ["clean", "test"],
+  release: ["clean", "test"],
+  "mobile-ui": ["clean", "test", "design", "accessibility", "security", "performance"],
+  "web-game": ["games", "clean", "test", "security", "performance", "accessibility"],
+  "html-video": ["design", "accessibility", "performance", "test", "security"],
+  infrastructure: ["security", "test"],
+  "security-review": ["security"],
+  performance: ["performance", "test"],
+  accessibility: ["accessibility", "test"],
+  "test-only": ["test"],
+  documentation: [],
+});
+
+const PRIMARY_GUIDES = Object.freeze({
+  "complete-website": "premium",
+  "web-game": "games",
+  documentation: null,
+});
+
+export class RouteInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RouteInputError";
+    this.code = "ROUTING_FAILURE";
+  }
+}
+
+function reasonForWorkType(workType) {
+  return `WORK_${workType.toUpperCase().replaceAll("-", "_")}`;
+}
+
+function reasonForSignal(prefix, signal) {
+  return `${prefix}_${signal.toUpperCase().replaceAll("-", "_")}`;
+}
+
+function normalizeArray(value, name, allowed) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new RouteInputError(`${name} must be an array`);
+  const seen = new Set();
+  for (const item of value) {
+    if (typeof item !== "string" || !allowed.has(item)) {
+      throw new RouteInputError(`Unknown ${name.slice(0, -1)}: ${item}`);
+    }
+    if (seen.has(item)) throw new RouteInputError(`Duplicate ${name.slice(0, -1)}: ${item}`);
+    seen.add(item);
+  }
+  return [...seen].sort();
+}
+
+export function normalizeRouteInput(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new RouteInputError("Route input must be an object");
+  }
+  if (typeof input.workType !== "string" || !WORK_TYPES.has(input.workType)) {
+    throw new RouteInputError(`Unknown work type: ${input.workType}`);
+  }
+  for (const key of ["behaviorChange", "executableChange"]) {
+    if (input[key] !== undefined && typeof input[key] !== "boolean") {
+      throw new RouteInputError(`${key} must be boolean`);
+    }
+  }
+  return {
+    schemaVersion: ROUTING_SCHEMA_VERSION,
+    workType: input.workType,
+    surfaces: normalizeArray(input.surfaces, "surfaces", SIGNALS.surfaces),
+    risks: normalizeArray(input.risks, "risks", SIGNALS.risks),
+    platforms: normalizeArray(input.platforms, "platforms", SIGNALS.platforms),
+    behaviorChange: input.behaviorChange ?? false,
+    executableChange: input.executableChange ?? false,
+  };
+}
+
+export function evaluateRoute(input = {}) {
+  const normalized = normalizeRouteInput(input);
+  const selected = new Map();
+  const excluded = {};
+
+  function add(guide, reason) {
+    if (!GUIDE_IDS.includes(guide)) throw new RouteInputError(`Unknown guide: ${guide}`);
+    const reasons = selected.get(guide) ?? [];
+    if (!reasons.includes(reason)) reasons.push(reason);
+    selected.set(guide, reasons);
+  }
+
+  const workReason = reasonForWorkType(normalized.workType);
+  for (const guide of WORK_GUIDES[normalized.workType]) add(guide, workReason);
+
+  if (normalized.surfaces.includes("ui") || normalized.surfaces.includes("forms")) {
+    add("design", "SURFACE_UI");
+    add("accessibility", normalized.surfaces.includes("forms") ? "SURFACE_FORMS" : "SURFACE_UI");
+  }
+  if (normalized.surfaces.includes("mobile") || normalized.surfaces.includes("desktop")) {
+    add("design", "SURFACE_PLATFORM_UI");
+    add("accessibility", "SURFACE_PLATFORM_UI");
+  }
+  if (normalized.surfaces.includes("game")) add("games", "SURFACE_GAME");
+  if (normalized.surfaces.includes("video")) {
+    add("design", "SURFACE_VIDEO");
+    add("accessibility", "SURFACE_VIDEO");
+  }
+  if (normalized.surfaces.includes("auth")) add("security", "SURFACE_AUTH");
+
+  for (const risk of normalized.risks) {
+    if (["untrusted-input", "personal-data", "secrets", "external-service", "publication"].includes(risk)) {
+      add("security", reasonForSignal("RISK", risk));
+    }
+    if (["critical-path", "performance"].includes(risk)) {
+      add("performance", reasonForSignal("RISK", risk));
+    }
+    if (risk === "accessibility") add("accessibility", "RISK_ACCESSIBILITY");
+  }
+
+  if (normalized.behaviorChange) {
+    add("clean", "CHANGE_BEHAVIOR");
+    add("test", "CHANGE_BEHAVIOR");
+  }
+  if (normalized.executableChange) {
+    add("clean", "CHANGE_EXECUTABLE_CONFIG");
+    add("test", "CHANGE_EXECUTABLE_CONFIG");
+  }
+
+  const hasUiContext = normalized.surfaces.some((surface) => ["ui", "forms", "mobile", "desktop"].includes(surface));
+  if (normalized.platforms.includes("mobile") && hasUiContext) {
+    add("design", "PLATFORM_MOBILE");
+    add("accessibility", "PLATFORM_MOBILE");
+    add("performance", "PLATFORM_MOBILE");
+  }
+  if (normalized.platforms.includes("desktop") && hasUiContext) {
+    add("design", "PLATFORM_DESKTOP");
+    add("accessibility", "PLATFORM_DESKTOP");
+  }
+  if (normalized.platforms.includes("server") && normalized.surfaces.includes("auth")) {
+    add("security", "PLATFORM_SERVER");
+    add("test", "PLATFORM_SERVER");
+  }
+  if (normalized.platforms.includes("ci") && normalized.executableChange) {
+    add("security", "PLATFORM_CI");
+  }
+
+  if (normalized.workType === "documentation" && selected.size === 0) {
+    excluded.documentation = ["DOCUMENTATION_DOMAIN_GUIDE_REQUIRED"];
+  }
+
+  for (const guide of GUIDE_IDS) {
+    if (selected.has(guide)) continue;
+    if (guide === "security") excluded[guide] = ["NO_TRUST_BOUNDARY"];
+    else if (guide === "performance") excluded[guide] = ["NO_MEASURABLE_PERFORMANCE_RISK"];
+    else if (guide === "design" || guide === "accessibility") excluded[guide] = ["NO_UI_SURFACE"];
+    else if (guide === "premium" || guide === "games") excluded[guide] = ["NO_PRIMARY_WORK_TYPE"];
+    else excluded[guide] = ["NO_BEHAVIOR_OR_EXECUTABLE_CHANGE"];
+  }
+
+  const guides = [...selected.keys()];
+  const result = {
+    schemaVersion: ROUTING_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    input: normalized,
+    primary: Object.prototype.hasOwnProperty.call(PRIMARY_GUIDES, normalized.workType)
+      ? PRIMARY_GUIDES[normalized.workType]
+      : guides[0] ?? null,
+    guides,
+    reasons: Object.fromEntries(guides.map((guide) => [guide, selected.get(guide)])),
+    excluded,
+  };
+  return assertRouteInvariants(result);
+}
+
+export function assertRouteInvariants(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result)) {
+    throw new RouteInputError("Route result must be an object");
+  }
+  if (!Array.isArray(result.guides) || new Set(result.guides).size !== result.guides.length) {
+    throw new RouteInputError("Route result contains duplicate guides");
+  }
+  for (const guide of result.guides) {
+    if (!GUIDE_IDS.includes(guide)) throw new RouteInputError(`Route result contains unknown guide: ${guide}`);
+    if (!Array.isArray(result.reasons?.[guide]) || result.reasons[guide].length === 0) {
+      throw new RouteInputError(`Selected guide has no reason: ${guide}`);
+    }
+  }
+  for (const [guide, reasons] of Object.entries(result.excluded ?? {})) {
+    if (guide !== "documentation" && !GUIDE_IDS.includes(guide)) {
+      throw new RouteInputError(`Route result contains unknown excluded guide: ${guide}`);
+    }
+    if (result.guides.includes(guide)) {
+      throw new RouteInputError(`Guide cannot be selected and excluded: ${guide}`);
+    }
+    if (!Array.isArray(reasons) || reasons.length === 0) {
+      throw new RouteInputError(`Excluded guide has no exclusion reason: ${guide}`);
+    }
+  }
+  if (result.primary !== null && !result.guides.includes(result.primary)) {
+    throw new RouteInputError("Primary guide must be null or selected");
+  }
+  return result;
+}
+
+export const ROUTING_SIGNALS = Object.freeze({
+  workTypes: Object.freeze([...WORK_TYPES].sort()),
+  surfaces: Object.freeze([...SIGNALS.surfaces].sort()),
+  risks: Object.freeze([...SIGNALS.risks].sort()),
+  platforms: Object.freeze([...SIGNALS.platforms].sort()),
+});

package/src/core/schema-validation.js

@@ -0,0 +1,179 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { getPackageRoot } from "./templates.js";
+import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+import { createEvidence } from "./evidence.js";
+
+export const SHIPPED_SCHEMA_NAMES = Object.freeze([
+  "routing-input",
+  "routing-result",
+  "work-state",
+  "execution-receipt",
+  "task-brief",
+  "delegated-result",
+  "evidence",
+]);
+
+export class SchemaValidationError extends Error {
+  constructor(errors, label = "value") {
+    const normalized = errors.length > 0 ? errors : [`${label}: schema validation failed`];
+    super(normalized.join("; "));
+    this.name = "SchemaValidationError";
+    this.errors = normalized;
+  }
+}
+
+function typeMatches(value, type) {
+  if (type === "object") return value !== null && typeof value === "object" && !Array.isArray(value);
+  if (type === "array") return Array.isArray(value);
+  if (type === "integer") return Number.isInteger(value);
+  if (type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (type === "null") return value === null;
+  return typeof value === type;
+}
+
+function display(value) {
+  return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+
+function validate(value, schema, location, errors) {
+  if (schema.const !== undefined && value !== schema.const) {
+    errors.push(`${location}: expected ${display(schema.const)}`);
+    return;
+  }
+
+  if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
+    errors.push(`${location}: expected one of ${schema.enum.map(display).join(", ")}`);
+    return;
+  }
+
+  if (schema.oneOf) {
+    const matches = schema.oneOf.filter((candidate) => {
+      const candidateErrors = [];
+      validate(value, candidate, location, candidateErrors);
+      return candidateErrors.length === 0;
+    });
+    if (matches.length !== 1) errors.push(`${location}: expected exactly one matching schema`);
+    return;
+  }
+
+  if (schema.type && !typeMatches(value, schema.type)) {
+    errors.push(`${location}: expected type ${schema.type}`);
+    return;
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      errors.push(`${location}: must contain at least ${schema.minLength} characters`);
+    }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${location}: does not match the required pattern`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push(`${location}: must contain at least ${schema.minItems} items`);
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      errors.push(`${location}: must contain at most ${schema.maxItems} items`);
+    }
+    if (schema.items) {
+      value.forEach((item, index) => validate(item, schema.items, `${location}[${index}]`, errors));
+    }
+  }
+
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    for (const key of schema.required ?? []) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) {
+        errors.push(`${location}.${key}: is required`);
+      }
+    }
+
+    const properties = schema.properties ?? {};
+    for (const [key, child] of Object.entries(properties)) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) {
+        validate(value[key], child, `${location}.${key}`, errors);
+      }
+    }
+
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(properties, key)) {
+          errors.push(`${location}.${key}: additional property is not allowed`);
+        }
+      }
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      for (const key of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(properties, key)) {
+          validate(value[key], schema.additionalProperties, `${location}.${key}`, errors);
+        }
+      }
+    }
+  }
+}
+
+export function validateSchema(value, schema, { label = "$" } = {}) {
+  assertJsonLimits(value, label);
+  const errors = [];
+  validate(value, schema, label, errors);
+  return errors;
+}
+
+export function assertSchema(value, schema, label = "value") {
+  const errors = validateSchema(value, schema, { label });
+  if (errors.length > 0) throw new SchemaValidationError(errors, label);
+  return value;
+}
+
+export async function readSchema(name, packageRoot = getPackageRoot()) {
+  const filename = name.endsWith(".schema.json") ? name : `${name}.schema.json`;
+  const schemaPath = path.join(packageRoot, "schemas", filename);
+  return JSON.parse(await readFile(schemaPath, "utf8"));
+}
+
+export async function inspectSchemaHealth(packageRoot = getPackageRoot()) {
+  const schemas = [];
+  for (const name of SHIPPED_SCHEMA_NAMES) {
+    const filename = `${name}.schema.json`;
+    const schemaPath = path.join(packageRoot, "schemas", filename);
+    try {
+      const bytes = await readFile(schemaPath);
+      assertJsonBytes(bytes, filename);
+      const schema = JSON.parse(bytes.toString("utf8"));
+      assertJsonLimits(schema, filename);
+      const version = schema?.properties?.schemaVersion?.const ?? null;
+      let status = "valid";
+      let error = null;
+      if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        status = "invalid";
+        error = "schema root must be an object";
+      } else if (version !== 1) {
+        status = "unsupported-version";
+        error = `schemaVersion ${version ?? "missing"} is not supported`;
+      }
+      schemas.push({ name, version, status, error });
+    } catch (caught) {
+      const status = caught.code === "ENOENT" ? "missing" : "invalid";
+      schemas.push({ name, version: null, status, error: caught.message });
+    }
+  }
+  const status = schemas.some((schema) => schema.status === "invalid")
+    ? "invalid"
+    : schemas.some((schema) => schema.status === "missing")
+      ? "missing"
+      : schemas.some((schema) => schema.status === "unsupported-version")
+        ? "unsupported-version"
+        : "valid";
+  return {
+    version: 1,
+    status,
+    schemas,
+    evidence: [createEvidence({
+      kind: status === "valid" ? "OBSERVED" : status === "missing" ? "NOT_VERIFIED" : "BLOCKED",
+      source: "shipped target schemas",
+      result: status,
+    })],
+  };
+}

package/src/core/templates.js

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+export const TEMPLATE_PATHS = [
+  ".forgeloop/.gitignore",
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".cursor/rules/project-loop.mdc",
+  ".github/copilot-instructions.md",
+  "LOOP_ENGINEERING.md",
+  "GUIDE_ROUTER.md",
+  "PROJECT_PROFILE.md",
+  "LOOP_SYSTEM_DESIGN.md",
+  "QUALITY_SCORECARD.md",
+  "TERMINOLOGY.md",
+  "EXECUTION_STATE.md",
+  "DELEGATION_PROTOCOL.md",
+  "ORCHESTRATOR_INTEGRATION.md",
+  "THREAT_MODEL.md",
+  "CONTRACT_COVERAGE.md",
+  "AGENT_COMPATIBILITY.md",
+  "THIRD_PARTY_NOTICES.md",
+  "LICENSE",
+  "LICENSE-DOCS.md",
+  "ENG/accessibility-eng.md",
+  "ENG/clean-code-eng.md",
+  "ENG/design-code-eng.md",
+  "ENG/games-code-design-web-eng.md",
+  "ENG/perf-code-eng.md",
+  "ENG/premium-sites-studio-eng.md",
+  "ENG/sec-code-eng.md",
+  "ENG/test-code-eng.md",
+  "schemas/routing-input.schema.json",
+  "schemas/routing-result.schema.json",
+  "schemas/work-state.schema.json",
+  "schemas/execution-receipt.schema.json",
+  "schemas/task-brief.schema.json",
+  "schemas/delegated-result.schema.json",
+  "schemas/evidence.schema.json",
+];
+
+export function getPackageRoot() {
+  return PACKAGE_ROOT;
+}
+
+export async function readTemplateEntries(packageRoot = PACKAGE_ROOT) {
+  return Promise.all(
+    TEMPLATE_PATHS.map(async (relativePath) => ({
+      relativePath,
+      bytes: await readFile(path.join(packageRoot, relativePath)),
+    })),
+  );
+}