filegrc 0.1.0 → 0.3.0

package/src/cli.js

@@ -1,10 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { loadModel } from "../model/index.js";
 import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldResourceMutation } from "./agent.js";
 import { assessAuditPreparation, prepareAuditWorkspace } from "./audit-preparation.js";
 import { buildWorkspace } from "./build.js";
 import { generateEvidencePacket, prepareEvidencePacket } from "./evidence-packet.js";
+import { ensureEvidenceTestDrafts } from "./evidence-tests.js";
 import {
   addEvidenceAttachment,
   createResource,
@@ -21,9 +23,12 @@ import {
   planObligations
 } from "./obligations.js";
 import { relativeToWorkspace, resolveDataPath } from "./paths.js";
+import { buildAgentProgramPath, policyEventName } from "./program-path.js";
+import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { searchResources } from "./search.js";
 import { serveWorkspace } from "./server.js";
+import { setupWorkspace } from "./setup.js";
 import { createAppState } from "./state.js";
 import { currentCalendarDate } from "./time.js";
 import { validateWorkspace } from "./validate.js";
@@ -32,10 +37,13 @@ import { loadWorkspace } from "./workspace.js";
 const BOOLEAN_FLAGS = new Set([
   "check-docs",
   "complete",
+  "draft",
+  "help",
   "json",
   "mutation",
   "preview",
   "require-ready",
+  "summary",
   "write-docs",
   "yes"
 ]);
@@ -47,10 +55,14 @@ export async function runCli(argv = process.argv.slice(2)) {
 
   if (["help", "--help", "-h"].includes(command)) return printHelp();
   if (["version", "--version", "-v"].includes(command)) return printVersion();
+  if (flags.help || args.includes("-h")) return printCommandHelp(command);
 
   if (command === "serve") {
-    const result = await serveWorkspace(positionals[0] ?? root, { host: flags.host, port: flags.port });
-    console.log(`FileGRC workspace: ${result.url}`);
+    const result = await serveWorkspace(positionals[0] ?? root, {
+      host: flags.host ?? process.env.FILEGRC_HOST,
+      port: flags.port ?? process.env.FILEGRC_PORT
+    });
+    console.log(`filegrc workspace: ${result.url}`);
     console.log(`Data: ${result.root}/data`);
     return await new Promise((resolvePromise) => {
       const stop = () => result.server.close(resolvePromise);
@@ -58,6 +70,29 @@ export async function runCli(argv = process.argv.slice(2)) {
       process.once("SIGTERM", stop);
     });
   }
+  if (command === "setup") {
+    const payload = positionals[0] ? await readSetupPayload(positionals[0]) : {};
+    const setupInput = await completeInteractiveSetup(root, {
+      ...payload,
+      ...(flags["service-name"] !== undefined ? { serviceName: flags["service-name"] } : {}),
+      ...(flags.boundary !== undefined ? { boundary: flags.boundary } : {}),
+      ...(flags.owner !== undefined ? { ownerId: flags.owner } : {}),
+      ...(flags.criticality !== undefined ? { criticality: flags.criticality } : {}),
+      ...(flags.classification !== undefined ? { dataClassification: flags.classification } : {}),
+      ...(flags["internet-exposed"] !== undefined ? { internetExposed: flags["internet-exposed"] } : {}),
+      ...(flags["program-goal"] !== undefined ? { programGoal: flags["program-goal"] } : {}),
+      ...(flags.draft ? { draft: true } : {})
+    });
+    const result = await setupWorkspace(root, setupInput);
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`${result.draft ? "Saved draft scope" : "Completed initial setup"} for ${result.system.title}.`);
+      console.log(`System: ${result.system.id} (${result.system.status})`);
+      console.log(`Target: ${result.workspace.assuranceGoal}`);
+      console.log("Next: finish Step 1 by confirming people, criteria, commitments, vendors, and in-scope systems. Run filegrc program-path for the full path.");
+    }
+    return result;
+  }
   if (command === "build") {
     const result = await buildWorkspace(positionals[0] ?? root, { output: flags.output });
     console.log(`Built read-only site at ${result.output}`);
@@ -117,6 +152,16 @@ export async function runCli(argv = process.argv.slice(2)) {
     else printAgentGuide(result);
     return result;
   }
+  if (command === "program-path") {
+    const loaded = await loadWorkspace(root);
+    const readiness = await assessProgramReadiness(loaded, { asOf: flags["as-of"] });
+    const auditId = positionals[0] || flags.audit;
+    const auditReadiness = auditId ? await assessAuditPreparation(loaded, { auditId }) : null;
+    const result = buildProgramPathResult(loaded.model, readiness, auditReadiness);
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else printProgramPath(result);
+    return result;
+  }
   if (command === "scaffold") {
     const loaded = await loadWorkspace(root);
     const type = positionals[0];
@@ -154,7 +199,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
     else {
-      console.log(`${result.counts.overdue} overdue, ${result.counts.due} due, ${result.counts.upcoming} upcoming`);
+      console.log(`${result.counts.overdue} overdue, ${result.counts.due} due, ${result.counts.upcoming} upcoming, ${result.counts.proposed} starter proposals`);
       for (const item of result.items) {
         const deadline = item.dueWindowEndAt || item.dueWindowEnd;
         if (!deadline) throw new Error(`Planned work "${item.title}" is missing a deadline.`);
@@ -167,10 +212,50 @@ export async function runCli(argv = process.argv.slice(2)) {
         ].join("\t"));
       }
       if (result.triggers.length) {
-        console.log("\nEvent reminders:");
-        for (const trigger of result.triggers) console.log(`${trigger.eventType}\t${trigger.prompt}\t${trigger.steps.length} actions`);
+        console.log("\nPolicy Events:");
+        for (const trigger of result.triggers) {
+          console.log(`${trigger.programStatus.toUpperCase()}\t${policyEventName(trigger.eventType)} (${trigger.eventType})\t${trigger.steps.length} Work Queue ${trigger.steps.length === 1 ? "task" : "tasks"}`);
+          for (const step of trigger.steps) {
+            const owners = step.ownerIds.length ? step.ownerIds.join(",") : "unassigned";
+            const proof = step.completionResourceTypes.length ? step.completionResourceTypes.join("|") : "not specified";
+            console.log(`  ${step.title}\t${eventWindowText(step.window)}\towner=${owners}\tproof=${proof}`);
+          }
+          if (trigger.programStatus !== "proposed") console.log(`  Trigger: filegrc trigger ${trigger.eventType} --occurred-on YYYY-MM-DD --subject RESOURCE_ID --json`);
+        }
+      }
+    }
+    return result;
+  }
+  if (command === "program-readiness") {
+    const loaded = await loadWorkspace(root);
+    const result = await assessProgramReadiness(loaded, { asOf: flags["as-of"] });
+    const output = flags.summary ? summarizeProgramReadiness(result) : result;
+    if (flags.json) console.log(JSON.stringify(output, null, 2));
+    else if (flags.summary) {
+      console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
+      for (const stage of output.stages) {
+        console.log(`${stage.status.toUpperCase()}\t${stage.title}\t${stage.counts.action} actions`);
+      }
+      if (output.firstAction) console.log(`Next: ${output.firstAction.title}\t${output.firstAction.message}`);
+    }
+    else {
+      console.log(`${result.status.toUpperCase()}: ${result.progress.complete} of ${result.progress.total} program items complete`);
+      console.log(`${result.target.label}${result.target.candidatePeriodStart ? `, candidate period starts ${result.target.candidatePeriodStart}` : ""}`);
+      for (const stage of result.stages) {
+        console.log(`\n${stage.title}`);
+        for (const item of stage.items) console.log(`${item.status.toUpperCase()}\t${item.title}\t${item.message}`);
+      }
+      if (result.canStartCandidatePeriod && !result.operating) {
+        console.log(`\nEvidence Ready: management can start the candidate Type 2 period on or after ${result.suggestedCandidatePeriodStart || result.asOf}.`);
       }
     }
+    if (flags["require-ready"] && !result.evidenceReady) process.exitCode = 2;
+    return output;
+  }
+  if (command === "evidence-test-drafts") {
+    const result = await ensureEvidenceTestDrafts(root);
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Created ${result.created.length} External Evidence test ${result.created.length === 1 ? "draft" : "drafts"}; ${result.total} required families are represented.`);
     return result;
   }
   if (command === "audit-readiness") {
@@ -206,7 +291,11 @@ export async function runCli(argv = process.argv.slice(2)) {
       title: flags.title
     });
     if (flags.json) console.log(JSON.stringify(result, null, 2));
-    else console.log(`Created ${result.event.id} with ${result.actions.length} action items.`);
+    else {
+      console.log(`Work added to the Work Queue: ${result.actions.length} ${result.actions.length === 1 ? "task" : "tasks"} created for ${result.event.title}.`);
+      console.log(`Event: obligation-event/${result.event.id}`);
+      for (const action of result.actions) console.log(`Task: action-item/${action.id}\t${action.title}\t${action.dueWindowEndAt || action.dueWindowEnd || action.overdueAt || action.overdueOn}`);
+    }
     return result;
   }
   if (command === "evidence-packet") {
@@ -308,7 +397,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
   if (command === "complete-event") {
     const eventId = positionals[0];
-    if (!eventId) throw new Error("An obligation event ID is required.");
+    if (!eventId) throw new Error("A Policy Event ID is required.");
     const result = await completeObligationEvent(root, {
       eventId,
       completedOn: flags["completed-on"],
@@ -466,6 +555,66 @@ async function readMutation(path) {
   };
 }
 
+async function readSetupPayload(path) {
+  if (!path) return {};
+  const source = path === "-" ? await readStdin() : await readFile(resolve(path), "utf8");
+  const parsed = JSON.parse(source);
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new Error("Setup input must be a JSON object.");
+  }
+  return parsed;
+}
+
+async function completeInteractiveSetup(root, payload) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return payload;
+  const loaded = await loadWorkspace(root);
+  const activePeople = loaded.resources.filter(({ type, status }) => type === "person" && status === "active");
+  if (!activePeople.length) throw new Error("Setup requires at least one active person who can own the service.");
+  const classifications = Object.keys(loaded.workspace.classificationDefinitions || {});
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  const result = { ...payload };
+  const askRequired = async (label, defaultValue = "") => {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    let value = "";
+    while (!value) value = (await prompt.question(`${label}${suffix}: `)).trim() || defaultValue;
+    return value;
+  };
+  const askChoice = async (label, choices, defaultValue = "") => {
+    let value = "";
+    while (!choices.includes(value)) {
+      value = await askRequired(`${label} (${choices.join("/")})`, defaultValue);
+    }
+    return value;
+  };
+  try {
+    result.serviceName ||= await askRequired(
+      "Service name",
+      loaded.workspace.organizationName ? `${loaded.workspace.organizationName} service` : ""
+    );
+    result.boundary ||= await askRequired("Service boundary");
+    result.ownerId ||= await askChoice(
+      "Service owner ID",
+      activePeople.map(({ id }) => id),
+      activePeople[0].id
+    );
+    result.criticality ||= await askChoice("Criticality", ["low", "medium", "high", "critical"], "high");
+    result.dataClassification ||= classifications.length
+      ? await askChoice(
+        "Data classification",
+        classifications,
+        classifications.includes("Confidential") ? "Confidential" : classifications[0]
+      )
+      : await askRequired("Data classification");
+    if (result.internetExposed === undefined) {
+      result.internetExposed = (await askChoice("Internet exposed", ["yes", "no"])) === "yes";
+    }
+    result.programGoal ||= await askChoice("Program goal", ["none", "readiness", "type-1", "type-2"]);
+  } finally {
+    prompt.close();
+  }
+  return result;
+}
+
 async function readTextInput(path) {
   if (path === true || !path) throw new Error("Pass --write <markdown-file|->.");
   return path === "-" ? readStdin() : readFile(resolve(String(path)), "utf8");
@@ -488,20 +637,24 @@ async function printVersion() {
 }
 
 function printHelp() {
-  console.log(`FileGRC - Git-native GRC workspace
+  console.log(`filegrc - Git-native GRC workspace
 
 Usage:
   filegrc serve [root] [--host 127.0.0.1] [--port 8787]
+  filegrc setup [setup.json|-] [setup options] [--draft] [--json]
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
   filegrc model [--json|--write-docs|--check-docs]
   filegrc describe <resource-type>
   filegrc types [--json]
   filegrc guide [resource-type] [--id resource-id] [--json]
+  filegrc program-path [audit-id] [--as-of YYYY-MM-DD] [--json]
   filegrc scaffold <resource-type> --title text [--id resource-id]
   filegrc list [resource-type] [--json]
   filegrc search <query> [--type resource-type] [--json]
   filegrc obligations [--as-of YYYY-MM-DD] [--from YYYY-MM-DD] [--through YYYY-MM-DD] [--now RFC3339] [--complete] [--json]
+  filegrc program-readiness [--as-of YYYY-MM-DD] [--require-ready] [--summary] [--json]
+  filegrc evidence-test-drafts [--json]
   filegrc audit-readiness [audit-id] [--require-ready] [--json]
   filegrc prepare-audit <audit-id> [--json]
   filegrc trigger <event-type> (--occurred-on YYYY-MM-DD | --occurred-at RFC3339) [--subject resource-id[,resource-id]] [--title text] [--json]
@@ -521,23 +674,116 @@ Usage:
 All commands accept --root <workspace>. Writes never create Git commits.`);
 }
 
+function printCommandHelp(command) {
+  if (command === "serve") {
+    console.log(`Usage:
+  filegrc serve [root] [--host address] [--port number]
+
+Options:
+  --host <address>  Bind address. Defaults to FILEGRC_HOST or 127.0.0.1.
+  --port <number>   Port. Defaults to FILEGRC_PORT or 8787. Use 0 for an available port.
+  --root <path>     Workspace path when no positional root is given.
+  --help            Show this help without starting the server.
+
+Safety:
+  The editable server has no authentication and binds to loopback by default.
+  Do not bind it to an untrusted network without trusted authentication.`);
+    return;
+  }
+  if (command === "setup") {
+    console.log(`Usage:
+  filegrc setup [setup.json|-] [options]
+
+Create or update the initial service boundary through the same validated operation
+used by browser onboarding. Run without input in an interactive terminal for guided
+setup. JSON keys use the camelCase forms shown below.
+
+Options:
+  --service-name <name>       serviceName
+  --boundary <description>    boundary
+  --owner <person-id>         ownerId
+  --criticality <level>       low, medium, high, or critical
+  --classification <name>     dataClassification
+  --internet-exposed <bool>   true or false
+  --program-goal <goal>       none, readiness, type-1, or type-2
+  --draft                     Save the service boundary as planned
+  --json                      Print the result as JSON
+  --root <path>               Workspace path
+  --help                      Show this help`);
+    return;
+  }
+  if (command === "program-readiness") {
+    console.log(`Usage:
+  filegrc program-readiness [options]
+
+Report whether management has defined scope, activated policies, implemented
+controls, configured authoritative evidence sources, and verified test collection
+for external evidence without a dedicated Step 5 record. No audit ID or CPA firm
+is required.
+
+Options:
+  --as-of <date>     Evaluate effective dates and obligations on YYYY-MM-DD
+  --require-ready    Exit with code 2 unless the Evidence Ready gate passes
+  --summary          Omit item details and print stage counts and next actions
+  --json             Print the result as JSON
+  --root <path>      Workspace path
+  --help             Show this help`);
+    return;
+  }
+  if (command === "program-path") {
+    console.log(`Usage:
+  filegrc program-path [audit-id] [options]
+
+Show the same six-step SOC 2 lifecycle used by the renderer. Each step includes
+its exact page instructions, Use and Policy Basis context, resource commands,
+and current readiness state. Pass an audit ID to include Step 6 status.
+
+Options:
+  --audit <id>       Audit record to use for Step 6
+  --as-of <date>     Evaluate readiness on YYYY-MM-DD
+  --json             Print the full agent-oriented path as JSON
+  --root <path>      Workspace path
+  --help             Show this help`);
+    return;
+  }
+  if (command === "evidence-test-drafts") {
+    console.log(`Usage:
+  filegrc evidence-test-drafts [options]
+
+Create missing draft External Evidence records for collection that does not
+already have a dedicated Step 5 operating record. Existing tests are preserved.
+
+Options:
+  --json         Print created and existing records as JSON
+  --root <path>  Workspace path
+  --help         Show this help`);
+    return;
+  }
+  printHelp();
+}
+
 function agentOverview(model) {
   return {
     rule: "Treat data/ as the source of truth. Run guide before creating an unfamiliar type, validate after every write, review the Git diff, then commit a focused change.",
+    programPath: buildAgentProgramPath(model),
     actions: {
       help: "filegrc help",
       version: "filegrc version",
       serve: "filegrc serve [root]",
+      setup: "filegrc setup [setup.json|-] [--draft] [--json]",
       build: "filegrc build [root]",
       validate: "filegrc validate [root] --json",
       model: "filegrc model --json",
       describe: "filegrc describe <resource-type>",
       types: "filegrc types --json",
       guide: "filegrc guide [resource-type] --json",
+      programPath: "filegrc program-path [audit-id] --json",
       scaffold: "filegrc scaffold <resource-type> --title <name>",
       list: "filegrc list [resource-type] --json",
       search: "filegrc search <query> --json",
       obligations: "filegrc obligations --json",
+      programReadiness: "filegrc program-readiness --json",
+      evidenceTestDrafts: "filegrc evidence-test-drafts --json",
       auditReadiness: "filegrc audit-readiness <audit-id> --json",
       prepareAudit: "filegrc prepare-audit <audit-id>",
       trigger: "filegrc trigger <event-type> <date-or-time-and-subject-flags>",
@@ -561,6 +807,8 @@ function agentOverview(model) {
 
 function printAgentOverview(result) {
   console.log(result.rule);
+  console.log("\nProgram path:");
+  for (const stage of result.programPath) console.log(`${stage.number}. ${stage.title}\t${stage.summary}`);
   console.log("\nActions:");
   for (const [name, command] of Object.entries(result.actions)) console.log(`${name}\t${command}`);
   console.log("\nResource types:");
@@ -569,7 +817,11 @@ function printAgentOverview(result) {
 
 function printAgentGuide(result) {
   console.log(`${result.title} (${result.type})`);
-  console.log(`Purpose: ${result.purpose}`);
+  if (result.programStep) {
+    console.log(`Program step: ${result.programStep.order ? `Step ${result.programStep.order}` : `Step ${result.programStep.number}`} · ${result.programStep.title}`);
+  }
+  console.log(`Instructions: ${result.instructions}`);
+  console.log(`Use: ${result.use}`);
   console.log(`Policy basis: ${result.policyBasis}`);
   console.log(`Timing: ${result.cadence}`);
   console.log(`JSON: ${result.location}`);
@@ -613,6 +865,109 @@ function printAgentGuide(result) {
   result.workflow.forEach((step, index) => console.log(`${index + 1}. ${step}`));
 }
 
+function buildProgramPathResult(model, readiness, auditReadiness) {
+  const readinessById = new Map(readiness.stages.map((stage) => [stage.id, stage]));
+  const stages = buildAgentProgramPath(model).map((stage) => {
+    if (stage.id === "audit") {
+      return {
+        ...stage,
+        status: auditReadiness?.status || "not-started",
+        counts: auditReadiness?.counts || null,
+        nextActions: auditReadiness?.firstAction ? [auditReadiness.firstAction] : []
+      };
+    }
+    const readinessId = stage.id === "run" ? "operation" : stage.id;
+    const current = readinessById.get(readinessId);
+    const status = stage.id === "run" && readiness.operating
+      ? "operating"
+      : current?.status || "not-started";
+    return {
+      ...stage,
+      status,
+      counts: current?.counts || null,
+      nextActions: (current?.items || []).filter((item) => item.status === "action")
+    };
+  });
+  const currentStep = stages.find((stage) => !["complete", "operating", "management-ready"].includes(stage.status)) || stages.at(-1);
+  return {
+    schemaVersion: 1,
+    asOf: readiness.asOf,
+    currentStep: { id: currentStep.id, number: currentStep.number, title: currentStep.title },
+    evidenceReady: readiness.evidenceReady,
+    operating: readiness.operating,
+    stages
+  };
+}
+
+function printProgramPath(result) {
+  console.log(`Current: Step ${result.currentStep.number}, ${result.currentStep.title}`);
+  console.log(`Evidence Ready: ${result.evidenceReady ? "yes" : "no"}; operating: ${result.operating ? "yes" : "no"}`);
+  for (const stage of result.stages) {
+    console.log(`\nStep ${stage.number}. ${stage.title} [${String(stage.status).toUpperCase()}]`);
+    console.log(stage.summary);
+    for (const page of stage.pages) {
+      console.log(`${page.order ? `Step ${page.order}` : "Operating area"} · ${page.title} (${page.type || `utility:${page.utility}`})`);
+      console.log(`  Instructions: ${page.instructions}`);
+      console.log(`  Use: ${page.use}`);
+      console.log(`  Policy basis: ${page.policyBasis}`);
+    }
+    if (stage.operatingRecords?.length) {
+      console.log("Operating record guides:");
+      for (const record of stage.operatingRecords) {
+        console.log(`  ${record.type}\t${record.instructions}\t${record.guide}`);
+      }
+    }
+    console.log("Commands:");
+    for (const command of stage.commands) console.log(`  ${command}`);
+    for (const action of stage.nextActions) console.log(`Next: ${action.title} · ${action.message}`);
+  }
+}
+
+function summarizeProgramReadiness(result) {
+  const summarizeItem = (item) => item ? {
+    id: item.id,
+    status: item.status,
+    title: item.title,
+    message: item.message,
+    ...(item.resourceType ? { resourceType: item.resourceType } : {}),
+    ...(item.resourceId ? { resourceId: item.resourceId } : {})
+  } : null;
+  return {
+    schemaVersion: result.schemaVersion,
+    generatedAt: result.generatedAt,
+    asOf: result.asOf,
+    status: result.status,
+    evidenceReady: result.evidenceReady,
+    operating: result.operating,
+    canStartCandidatePeriod: result.canStartCandidatePeriod,
+    suggestedCandidatePeriodStart: result.suggestedCandidatePeriodStart,
+    target: result.target,
+    progress: result.progress,
+    counts: result.counts,
+    scopeCounts: Object.fromEntries(
+      Object.entries(result.scope).map(([name, ids]) => [name.replace(/Ids$/, ""), ids.length])
+    ),
+    firstAction: summarizeItem(result.firstAction),
+    stages: result.stages.map((stage) => ({
+      id: stage.id,
+      title: stage.title,
+      status: stage.status,
+      counts: stage.counts,
+      firstAction: summarizeItem(stage.items.find(({ status }) => status === "action"))
+    }))
+  };
+}
+
+function eventWindowText(window) {
+  if (Number.isInteger(window?.endOffsetHours)) {
+    return window.endOffsetHours === 0 ? "due at event time" : `due within ${window.endOffsetHours} hours`;
+  }
+  if (Number.isInteger(window?.endOffsetDays)) {
+    return window.endOffsetDays === 0 ? "due on event date" : `due within ${window.endOffsetDays} days`;
+  }
+  return "due within 30 days";
+}
+
 function formatGuideField(field) {
   const details = [
     field.values?.length ? `one of ${field.values.join("|")}` : field.type,