filegrc 0.1.0 → 0.2.0

package/src/server.js

@@ -4,12 +4,14 @@ import { extname, resolve } from "node:path";
 import { getResourceDefinition } from "../model/index.js";
 import { prepareAuditWorkspace } from "./audit-preparation.js";
 import { generateEvidencePacket, prepareEvidencePacket } from "./evidence-packet.js";
+import { ensureEvidenceTestDrafts } from "./evidence-tests.js";
 import { FAVICON_PNG } from "./favicon.js";
 import { createResource, deleteResource, updateContent, updateResource } from "./files.js";
 import { commitAndPushWorkspace, getFileHistory, pullWorkspace, pushWorkspace } from "./git.js";
 import { completeObligationOccurrence, createObligationEvent, planObligations } from "./obligations.js";
 import { isWithin, relativeToWorkspace, resolveWorkspacePath } from "./paths.js";
 import { createAppState } from "./state.js";
+import { setupWorkspace } from "./setup.js";
 import { loadWorkspace } from "./workspace.js";
 import { APP_SCRIPT, APP_STYLES, renderIndex } from "./web.js";
 
@@ -82,6 +84,12 @@ export function createFileGRCServer(input = process.cwd(), options = {}) {
       if (request.method === "POST" && url.pathname === "/api/audit-preparation") {
         return json(response, 201, await prepareAuditWorkspace(input, await readJson(request)));
       }
+      if (request.method === "POST" && url.pathname === "/api/evidence-test-drafts") {
+        return json(response, 201, await ensureEvidenceTestDrafts(input));
+      }
+      if (request.method === "POST" && url.pathname === "/api/setup") {
+        return json(response, 200, await setupWorkspace(input, await readJson(request)));
+      }
       if (request.method === "POST" && url.pathname === "/api/resources") {
         const payload = await readJson(request);
         const record = payload.record ?? payload;

package/src/setup.js

@@ -0,0 +1,187 @@
+import { createResource, updateResource } from "./files.js";
+import { ensureEvidenceTestDrafts } from "./evidence-tests.js";
+import { createResourceId } from "./id.js";
+import { loadWorkspace } from "./workspace.js";
+
+const PROGRAM_GOALS = new Set(["none", "readiness", "type-1", "type-2"]);
+const CRITICALITIES = new Set(["low", "medium", "high", "critical"]);
+
+export async function setupWorkspace(input = process.cwd(), payload = {}) {
+  const loaded = await loadWorkspace(input);
+  const setup = normalizeSetupPayload(payload);
+  validateSetup(loaded, setup);
+
+  let current = loaded;
+  let system = findSetupSystem(current.resources, setup);
+  const systemId = system?.id || createResourceId("system", setup.serviceName, current.resources.map(({ id }) => id));
+  system = {
+    ...(system || {}),
+    schemaVersion: 1,
+    id: systemId,
+    type: "system",
+    title: setup.serviceName,
+    status: setup.draft ? system?.status || "planned" : (system?.status === "planned" ? "active" : system?.status || "active"),
+    criticality: setup.criticality,
+    ownerIds: [setup.ownerId],
+    description: setup.boundary,
+    systemKind: system?.systemKind || "service",
+    dataClassification: setup.dataClassification,
+    internetExposed: setup.internetExposed,
+    inScope: true
+  };
+  await upsertResource(current.root, current.resources.find(({ id }) => id === systemId), system);
+
+  current = await loadWorkspace(current.root);
+  const linkedControlIds = [];
+  for (const control of current.resources.filter(({ type, status }) => (
+    type === "control" && !["not-applicable", "retired"].includes(status)
+  ))) {
+    if ((control.systemIds || []).includes(systemId)) continue;
+    await updateResource(current.root, "control", control.id, {
+      ...control,
+      systemIds: [...new Set([...(control.systemIds || []), systemId])]
+    });
+    linkedControlIds.push(control.id);
+  }
+
+  current = await loadWorkspace(current.root);
+  const existingWorkspace = current.resources.find(({ type }) => type === "workspace");
+  if (!existingWorkspace) throw new Error("The workspace settings record was not found.");
+  const workspace = {
+    ...existingWorkspace,
+    assuranceGoal: assuranceGoalFromSetup(setup.programGoal),
+    frameworkIds: current.resources
+      .filter(({ type, status }) => type === "framework" && status === "active")
+      .map(({ id }) => id),
+    requirementIds: current.resources
+      .filter(({ type, applicability }) => type === "requirement" && applicability === "applicable")
+      .map(({ id }) => id),
+    controlIds: current.resources
+      .filter(({ type, status }) => type === "control" && !["not-applicable", "retired"].includes(status))
+      .map(({ id }) => id),
+    systemIds: [...new Set([...(existingWorkspace.systemIds || []), systemId])]
+  };
+  await updateResource(current.root, "workspace", workspace.id, workspace);
+
+  current = await loadWorkspace(current.root);
+  const renderer = current.resources.find(({ type }) => type === "renderer-settings");
+  if (renderer) {
+    await updateResource(current.root, renderer.type, renderer.id, {
+      ...renderer,
+      showOnboarding: setup.draft
+    });
+  }
+  const evidenceTestDrafts = setup.draft
+    ? { created: [], existing: [], total: 0 }
+    : await ensureEvidenceTestDrafts(current.root);
+
+  return {
+    draft: setup.draft,
+    system,
+    workspace,
+    linkedControlIds,
+    evidenceTestDraftIds: evidenceTestDrafts.created.map(({ id }) => id),
+    onboardingComplete: !setup.draft
+  };
+}
+
+export function normalizeSetupPayload(payload = {}) {
+  if (!payload || Array.isArray(payload) || typeof payload !== "object") {
+    throw new Error("Setup input must be a JSON object.");
+  }
+  const draft = payload.draft === true;
+  return {
+    serviceName: cleanText(payload.serviceName, "serviceName"),
+    boundary: cleanMultilineText(payload.boundary ?? payload.scope, "boundary"),
+    ownerId: cleanText(payload.ownerId ?? payload.owner, "ownerId"),
+    criticality: cleanText(payload.criticality, "criticality"),
+    dataClassification: cleanText(payload.dataClassification ?? payload.classification, "dataClassification"),
+    internetExposed: booleanValue(payload.internetExposed, "internetExposed"),
+    programGoal: cleanText(payload.programGoal ?? "none", "programGoal"),
+    draft,
+    systemId: cleanOptionalText(payload.systemId, "systemId")
+  };
+}
+
+function validateSetup(loaded, setup) {
+  for (const [name, value] of [
+    ["serviceName", setup.serviceName],
+    ["boundary", setup.boundary],
+    ["ownerId", setup.ownerId],
+    ["criticality", setup.criticality],
+    ["dataClassification", setup.dataClassification]
+  ]) {
+    if (!value) throw new Error(`Setup field "${name}" is required.`);
+  }
+  if (setup.serviceName.length > 200) throw new Error("serviceName must be 200 characters or fewer.");
+  if (setup.boundary.length > 2_000) throw new Error("boundary must be 2,000 characters or fewer.");
+  if (!CRITICALITIES.has(setup.criticality)) {
+    throw new Error(`criticality must be one of ${[...CRITICALITIES].join(", ")}.`);
+  }
+  if (!PROGRAM_GOALS.has(setup.programGoal)) {
+    throw new Error(`programGoal must be one of ${[...PROGRAM_GOALS].join(", ")}.`);
+  }
+  const owner = loaded.resources.find(({ id, type }) => id === setup.ownerId && type === "person");
+  if (!owner || owner.status !== "active") throw new Error(`Active person "${setup.ownerId}" was not found.`);
+  if (setup.systemId) {
+    const system = loaded.resources.find(({ id, type }) => id === setup.systemId && type === "system");
+    if (!system) throw new Error(`System "${setup.systemId}" was not found.`);
+    if (["deprecated", "retired"].includes(system.status)) {
+      throw new Error(`System "${setup.systemId}" cannot be used for initial scope because it is ${system.status}.`);
+    }
+  }
+  const classifications = Object.keys(loaded.workspace.classificationDefinitions || {});
+  if (classifications.length && !classifications.includes(setup.dataClassification)) {
+    throw new Error(`dataClassification must be one of ${classifications.join(", ")}.`);
+  }
+}
+
+function findSetupSystem(resources, setup) {
+  return (setup.systemId && resources.find(({ type, id }) => type === "system" && id === setup.systemId))
+    || resources.find(({ type, title, inScope, status }) => (
+      type === "system"
+      && inScope === true
+      && status !== "retired"
+      && title.trim().toLowerCase() === setup.serviceName.toLowerCase()
+    ));
+}
+
+async function upsertResource(root, existing, record) {
+  return existing
+    ? updateResource(root, record.type, record.id, record)
+    : createResource(root, record);
+}
+
+function assuranceGoalFromSetup(goal) {
+  if (goal === "type-1") return "soc-2-type-1";
+  if (goal === "type-2") return "soc-2-type-2";
+  if (goal === "readiness") return "readiness";
+  return "none";
+}
+
+function booleanValue(value, name) {
+  if (value === true || value === false) return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`Setup field "${name}" must be true or false.`);
+}
+
+function cleanText(value, name) {
+  if (value === undefined || value === null) return "";
+  const result = String(value).trim();
+  if (/[\u0000-\u001f\u007f]/.test(result)) throw new Error(`Setup field "${name}" contains control characters.`);
+  return result;
+}
+
+function cleanMultilineText(value, name) {
+  if (value === undefined || value === null) return "";
+  const result = String(value).trim();
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(result)) {
+    throw new Error(`Setup field "${name}" contains unsupported control characters.`);
+  }
+  return result;
+}
+
+function cleanOptionalText(value, name) {
+  return value === undefined || value === null || value === "" ? "" : cleanText(value, name);
+}

package/src/state.js

@@ -5,6 +5,7 @@ import { getGitSummary, getWorkspaceHistories } from "./git.js";
 import { renderMarkdown } from "./markdown.js";
 import { planObligations } from "./obligations.js";
 import { resolveDataPath } from "./paths.js";
+import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { currentCalendarDate } from "./time.js";
 import { validateWorkspace } from "./validate.js";
@@ -52,12 +53,17 @@ export async function createAppState(input = process.cwd(), options = {}) {
   };
   const asOf = options.asOf ?? currentCalendarDate(workspace.timezone);
   const generatedAt = new Date().toISOString();
+  const programReadiness = await assessProgramReadiness(loaded, {
+    asOf,
+    generatedAt
+  });
   const audits = loaded.resources.filter((record) => record.type === "audit");
   const auditPreparations = Object.fromEntries(await Promise.all(
     (audits.length ? audits : [null]).map(async (audit) => {
       const preparation = await assessAuditPreparation(loaded, {
         auditId: audit?.id,
-        generatedAt
+        generatedAt,
+        programReadiness
       });
       return [audit?.id || "none", preparation];
     })
@@ -74,6 +80,7 @@ export async function createAppState(input = process.cwd(), options = {}) {
       diagnostics: validation.diagnostics
     },
     obligations: planObligations(entries, { asOf, now: options.now ?? generatedAt }),
+    programReadiness,
     auditPreparations,
     git
   };

package/src/validate.js

@@ -2,8 +2,9 @@ import { stat } from "node:fs/promises";
 import { getResourceDefinition } from "../model/index.js";
 import { isCanonicalDataPath, resolveDataPath } from "./paths.js";
 import { parseCalendarDate, validCalendarRecurrence } from "./recurrence.js";
+import { obligationIsRunning } from "./program-lifecycle.js";
 import { isMarkdownChoice, markdownEntries } from "./resource-markdown.js";
-import { isRfc3339Timestamp } from "./time.js";
+import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
 import { indexResources, loadWorkspace } from "./workspace.js";
 
 const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -17,6 +18,14 @@ export async function validateWorkspace(input = process.cwd()) {
   const diagnostics = [...loaded.diagnostics];
   const { byId } = indexResources(loaded.resources);
   const seen = new Map();
+  const asOf = currentCalendarDate(loaded.workspace?.timezone || "UTC");
+  const obligationsByControl = new Map();
+  for (const obligation of loaded.resources.filter((record) => record.type === "obligation" && record.status !== "retired")) {
+    for (const controlId of obligation.controlIds || []) {
+      if (!obligationsByControl.has(controlId)) obligationsByControl.set(controlId, []);
+      obligationsByControl.get(controlId).push(obligation);
+    }
+  }
 
   for (const entry of loaded.entries) {
     const { record } = entry;
@@ -88,6 +97,7 @@ export async function validateWorkspace(input = process.cwd()) {
     }
     validateIndependentApproval(record, byId, displayPath, diagnostics);
     validateCompletedObligationEvent(record, byId, displayPath, diagnostics);
+    validateImplementedControlSchedules(record, obligationsByControl, byId, asOf, displayPath, diagnostics);
     await validateMarkdown(record, definition, loaded.model, loaded.root, displayPath, diagnostics);
   }
 
@@ -104,10 +114,41 @@ export async function validateWorkspace(input = process.cwd()) {
   };
 }
 
+function validateImplementedControlSchedules(record, obligationsByControl, byId, asOf, path, diagnostics) {
+  if (record.type !== "control" || record.status !== "implemented") return;
+  const schedules = obligationsByControl.get(record.id) || [];
+  if (!schedules.length || schedules.every((obligation) => obligationIsRunning(obligation, byId, asOf))) return;
+  const stopped = schedules.filter((obligation) => !obligationIsRunning(obligation, byId, asOf));
+  const paused = stopped.filter((obligation) => obligation.status === "paused");
+  const waiting = stopped.filter((obligation) => obligation.status === "active");
+  const policyBlockers = [...new Set(waiting.flatMap((obligation) => (obligation.policyIds || []).map((id) => {
+    const policy = byId.get(id);
+    if (!policy || policy.type !== "policy") return `${id} (missing)`;
+    if (policy.status !== "active") return `${policy.title} (${policy.status})`;
+    if (!policy.effectiveOn) return `${policy.title} (effective date missing)`;
+    if (policy.effectiveOn > asOf) return `${policy.title} (effective ${policy.effectiveOn})`;
+    return null;
+  })).filter(Boolean))];
+  const reasons = [
+    waiting.length
+      ? `${waiting.length} enabled ${waiting.length === 1 ? "schedule is" : "schedules are"} waiting for governing ${policyBlockers.length === 1 ? "policy" : "policies"} to become active and effective${policyBlockers.length ? `: ${policyBlockers.join(", ")}` : ""}. Complete Step 2 first.`
+      : "",
+    paused.length
+      ? `${paused.length} linked ${paused.length === 1 ? "schedule is" : "schedules are"} paused. Enable ${paused.length === 1 ? "it" : "them"} before implementing the control.`
+      : ""
+  ].filter(Boolean).join(" ");
+  diagnostics.push(error(
+    "control-work-queue-not-running",
+    path,
+    `This control cannot be marked implemented yet. ${reasons}`
+  ));
+}
+
 function validateDateRanges(record, path, diagnostics) {
   for (const [startField, endField] of [
     ["startDate", "endDate"],
     ["periodStart", "periodEnd"],
+    ["candidatePeriodStart", "candidatePeriodEnd"],
     ["dueWindowStart", "dueWindowEnd"]
   ]) {
     const start = record[startField];
@@ -131,9 +172,11 @@ function validateCompletedObligationEvent(record, byId, path, diagnostics) {
       "completedOn cannot be before occurredOn."
     ));
   }
-  const actionIds = record.actionItemIds || [];
+  const actionIds = [...byId.values()]
+    .filter((candidate) => candidate.type === "action-item" && candidate.sourceResourceId === record.id)
+    .map((candidate) => candidate.id);
   if (actionIds.length === 0) {
-    diagnostics.push(error("incomplete-obligation-event", path, "A complete obligation event must have action items."));
+    diagnostics.push(error("incomplete-obligation-event", path, "A complete Policy Event must have action items."));
     return;
   }
   for (const actionId of actionIds) {
@@ -191,6 +234,21 @@ function validateIndependentApproval(record, byId, path, diagnostics) {
       `Approvers must be separate from owners, including through team membership: ${overlap.join(", ")}.`
     ));
   }
+  if (["approved", "active"].includes(record.status)) {
+    const incompleteStarterApprover = [...approvers]
+      .map((id) => byId.get(id))
+      .find((person) => (
+        person?.id === "person-independent-approver"
+        && ["Independent Approver", "Independent Reviewer"].includes(person.title)
+      ));
+    if (incompleteStarterApprover) {
+      diagnostics.push(error(
+        "independent-approver-not-appointed",
+        path,
+        `The selected approver "${incompleteStarterApprover.title}" is still the starter placeholder. Open People and replace it with the reviewer's actual name before approving this record. The reviewer may be internal or external but must be separate from the owner.`
+      ));
+    }
+  }
 }
 
 function expandPeople(ids, byId, seen = new Set()) {
@@ -364,7 +422,9 @@ async function validateMarkdown(record, definition, model, root, path, diagnosti
     }
   }
 
-  for (const choices of definition.oneOf ?? []) {
+  for (const group of definition.oneOf ?? []) {
+    const choices = Array.isArray(group) ? group : group.fields;
+    if (!Array.isArray(choices) || (!Array.isArray(group) && !conditionMatches(record, group.when))) continue;
     const satisfied = choices.some((name) => (
       isMarkdownChoice(name)
         ? present.has(name.slice("$markdown:".length))
@@ -480,7 +540,9 @@ function isTimezone(value) {
 }
 
 function conditionMatches(record, condition) {
-  return Object.entries(condition).every(([name, value]) => record[name] === value);
+  return Boolean(condition) && Object.entries(condition).every(([name, expected]) => (
+    Array.isArray(expected) ? expected.includes(record[name]) : record[name] === expected
+  ));
 }
 
 function findDefinitionType(model, definition) {