filegrc 0.3.0 → 0.3.1

package/README.md

@@ -26,7 +26,7 @@ npx filegrc list risk --json
 npx filegrc references risk-example --json
 npx filegrc describe risk
 npx filegrc search "access review"
-npx filegrc evidence-test-drafts
+npx filegrc evidence-test-drafts --preview --json
 npx filegrc program-readiness --summary --json
 npx filegrc program-readiness --require-ready
 npx filegrc audit-readiness audit-id
@@ -36,13 +36,13 @@ npx filegrc evidence-packet --start 2026-01-01 --end 2026-06-30 --audit audit-id
 
 `filegrc serve --help` prints bind, port, environment, and safety options without starting the server. The editable server defaults to `127.0.0.1:8787`; set `FILEGRC_HOST`, `FILEGRC_PORT`, or the matching flags when needed.
 
-`filegrc setup` provides the headless equivalent of browser onboarding. Run it without arguments for guided terminal setup, or pass all initial service-boundary fields and a management program goal as flags or a JSON payload. Selecting Type 1 or Type 2 updates the workspace goal and program scope. It does not create an audit record.
+`filegrc setup` provides the headless equivalent of browser onboarding. Run it without arguments for guided terminal setup, or pass all initial service-boundary fields and a management program goal as flags or a JSON payload. Add `--preview` to validate and inspect the planned service and workspace writes without saving. Add `--summary --json` for compact agent output. Selecting Type 1 or Type 2 updates the workspace goal and selected systems. Setup does not select framework records, link controls, create evidence, or create an audit record.
 
 `filegrc program-path` gives agents the renderer’s six-step order, exact page Instructions, Use, Policy Basis, commands, current state, and next actions. `filegrc guide <type>` repeats the matching page guidance and adds fields, relationship candidates, Markdown slots, and timing for that record type.
 
 `filegrc program-readiness` reports whether management can start a candidate Type 2 period. Add `--summary --json` for compact stage counts and next actions, or omit `--summary` for every readiness item. Use `--require-ready` in automation. The command does not require an audit ID or CPA firm.
 
-`filegrc evidence-test-drafts` creates missing draft tests for external evidence that does not already have a dedicated Step 5 record. When a Step 5 operating record exists, put the fixed artifact in an External Evidence record and link it from that operating record. Completing browser or CLI onboarding runs the same operation automatically.
+`filegrc evidence-test-drafts --preview --json` reports the missing draft tests for external evidence without writing them. Run `filegrc evidence-test-drafts` after confirming applicable controls and authoritative source Systems. When a Step 5 operating record exists, put the fixed artifact in an External Evidence record and link it from that operating record.
 
 `filegrc obligations` shows recurring work and a task-level preview for each Policy Event, including owners, deadlines, and requested proof. `filegrc trigger` adds the event and all of its Action Items to the Work Queue atomically, then prints the created task IDs and deadlines.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filegrc",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Zero-dependency Git-native GRC engine",
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -6,7 +6,7 @@ import { buildAgentGuide, findResourceReferences, listResourceTypes, scaffoldRes
 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 { ensureEvidenceTestDrafts, planEvidenceTestDrafts } from "./evidence-tests.js";
 import {
   addEvidenceAttachment,
   createResource,
@@ -28,7 +28,7 @@ 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 { planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
 import { createAppState } from "./state.js";
 import { currentCalendarDate } from "./time.js";
 import { validateWorkspace } from "./validate.js";
@@ -83,15 +83,22 @@ export async function runCli(argv = process.argv.slice(2)) {
       ...(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));
+    const result = flags.preview
+      ? await planWorkspaceSetup(root, setupInput)
+      : await setupWorkspace(root, setupInput);
+    const output = flags.summary && !flags.preview ? summarizeSetupResult(result) : result;
+    if (flags.json) console.log(JSON.stringify(output, null, 2));
+    else if (flags.preview) {
+      console.log(`Setup preview: ${result.changes.system} system ${result.system.id}; update workspace target to ${result.target.assuranceGoal}.`);
+      console.log("No controls will be linked and no evidence drafts will be created.");
+    }
     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;
+    return output;
   }
   if (command === "build") {
     const result = await buildWorkspace(positionals[0] ?? root, { output: flags.output });
@@ -253,6 +260,29 @@ export async function runCli(argv = process.argv.slice(2)) {
     return output;
   }
   if (command === "evidence-test-drafts") {
+    if (flags.preview) {
+      const loaded = await loadWorkspace(root);
+      const plan = planEvidenceTestDrafts(loaded);
+      const result = {
+        schemaVersion: 1,
+        preview: true,
+        total: plan.length,
+        create: plan.filter(({ existing }) => !existing).map((item) => ({
+          familyId: item.familyId,
+          title: item.title,
+          testEvidenceKind: item.testEvidenceKind,
+          controlIds: item.controlIds
+        })),
+        existing: plan.filter(({ existing }) => existing).map(({ existing }) => ({
+          id: existing.id,
+          title: existing.title,
+          status: existing.status
+        }))
+      };
+      if (flags.json) console.log(JSON.stringify(result, null, 2));
+      else console.log(`Evidence draft preview: create ${result.create.length}; preserve ${result.existing.length}.`);
+      return result;
+    }
     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.`);
@@ -641,7 +671,7 @@ function printHelp() {
 
 Usage:
   filegrc serve [root] [--host 127.0.0.1] [--port 8787]
-  filegrc setup [setup.json|-] [setup options] [--draft] [--json]
+  filegrc setup [setup.json|-] [setup options] [--draft] [--preview] [--summary] [--json]
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
   filegrc model [--json|--write-docs|--check-docs]
@@ -654,7 +684,7 @@ Usage:
   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 evidence-test-drafts [--preview] [--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]
@@ -707,6 +737,8 @@ Options:
   --internet-exposed <bool>   true or false
   --program-goal <goal>       none, readiness, type-1, or type-2
   --draft                     Save the service boundary as planned
+  --preview                   Validate and report planned writes without saving
+  --summary                   Omit full workspace relationship arrays
   --json                      Print the result as JSON
   --root <path>               Workspace path
   --help                      Show this help`);
@@ -750,10 +782,12 @@ Options:
     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.
+Preview or create missing draft External Evidence records for collection that
+does not already have a dedicated Step 5 operating record. Existing tests are
+preserved. Run after confirming applicable controls and source systems.
 
 Options:
+  --preview      Report proposed drafts without creating them
   --json         Print created and existing records as JSON
   --root <path>  Workspace path
   --help         Show this help`);
@@ -770,7 +804,7 @@ function agentOverview(model) {
       help: "filegrc help",
       version: "filegrc version",
       serve: "filegrc serve [root]",
-      setup: "filegrc setup [setup.json|-] [--draft] [--json]",
+      setup: "filegrc setup [setup.json|-] [--draft] [--preview] [--summary] [--json]",
       build: "filegrc build [root]",
       validate: "filegrc validate [root] --json",
       model: "filegrc model --json",
@@ -783,7 +817,7 @@ function agentOverview(model) {
       search: "filegrc search <query> --json",
       obligations: "filegrc obligations --json",
       programReadiness: "filegrc program-readiness --json",
-      evidenceTestDrafts: "filegrc evidence-test-drafts --json",
+      evidenceTestDrafts: "filegrc evidence-test-drafts --preview --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>",
@@ -924,13 +958,17 @@ function printProgramPath(result) {
 }
 
 function summarizeProgramReadiness(result) {
+  const ownership = result.stages
+    .flatMap((stage) => stage.items)
+    .find((item) => item.id === "program-ownership");
   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 } : {})
+    ...(item.resourceId ? { resourceId: item.resourceId } : {}),
+    ...(item.unresolvedAssignments?.length ? { unresolvedAssignments: item.unresolvedAssignments } : {})
   } : null;
   return {
     schemaVersion: result.schemaVersion,
@@ -947,6 +985,7 @@ function summarizeProgramReadiness(result) {
     scopeCounts: Object.fromEntries(
       Object.entries(result.scope).map(([name, ids]) => [name.replace(/Ids$/, ""), ids.length])
     ),
+    unresolvedOwnership: ownership?.unresolvedAssignments || [],
     firstAction: summarizeItem(result.firstAction),
     stages: result.stages.map((stage) => ({
       id: stage.id,

package/src/index.js

@@ -51,7 +51,7 @@ export {
 } from "./recurrence.js";
 export { searchResources, searchableValues } from "./search.js";
 export { createFilegrcServer, serveWorkspace } from "./server.js";
-export { normalizeSetupPayload, setupWorkspace } from "./setup.js";
+export { normalizeSetupPayload, planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
 export { createAppState } from "./state.js";
 export { currentCalendarDate, formatCalendarDate, formatLocalDateTime } from "./time.js";
 export { validateWorkspace } from "./validate.js";

package/src/program-path.js

@@ -119,7 +119,7 @@ export const PROGRAM_PATH = [
     ],
     resourceTypes: ["evidence"],
     commands: [
-      "filegrc evidence-test-drafts --json",
+      "filegrc evidence-test-drafts --preview --json",
       "filegrc guide evidence --json",
       "filegrc list evidence --json",
       "filegrc program-readiness --json"

package/src/program-readiness.js

@@ -203,9 +203,21 @@ function programOwnershipItem(records, byId) {
     && ![...oversightChairs].some((id) => policyOwnerIds.has(id))
   );
   const complete = currentOwners.size > 0 && unresolved.length === 0 && oversightComplete;
+  const unresolvedAssignments = unresolved.map((record) => ({
+    resourceType: record.type,
+    resourceId: record.id,
+    title: record.title,
+    ownerIds: record.ownerIds || [],
+    reasons: ownershipResolutionReasons(record.ownerIds || [], byId)
+  }));
   const detail = [];
   if (!currentOwners.size) detail.push("No current person owns the program records.");
-  if (unresolved.length) detail.push(`${unresolved.length} ownership ${unresolved.length === 1 ? "assignment does" : "assignments do"} not resolve to a current person.`);
+  if (unresolved.length) {
+    detail.push(
+      `${unresolved.length} ${unresolved.length === 1 ? "record has" : "records have"} no current person owner: ` +
+      `${unresolvedAssignments.map(({ title, resourceId }) => `${title} (${resourceId})`).join(", ")}.`
+    );
+  }
   if (!oversightComplete) detail.push("Finish and activate Security and Risk Oversight with a current chair who is separate from policy ownership.");
   return item(
     "program-ownership",
@@ -214,10 +226,29 @@ function programOwnershipItem(records, byId) {
     complete
       ? `${currentOwners.size} current ${currentOwners.size === 1 ? "person owns" : "people own"} the program records.${oversight ? " Security and Risk Oversight has a separate current chair." : ""}`
       : detail.join(" "),
-    !oversightComplete ? oversight : unresolved[0] || { type: "person" }
+    !oversightComplete ? oversight : unresolved[0] || { type: "person" },
+    { unresolvedAssignments }
   );
 }
 
+function ownershipResolutionReasons(ownerIds, byId) {
+  if (!ownerIds.length) return [{ ownerId: null, reason: "missing-owner" }];
+  return ownerIds.flatMap((ownerId) => {
+    const owner = byId.get(ownerId);
+    if (!owner) return [{ ownerId, reason: "missing-record" }];
+    if (owner.type === "person" && owner.status !== "active") {
+      return [{ ownerId, reason: "inactive-person" }];
+    }
+    if (owner.type === "team" && owner.status !== "active") {
+      return [{ ownerId, reason: "inactive-team" }];
+    }
+    if (currentPartyPeople([ownerId], byId).size === 0) {
+      return [{ ownerId, reason: owner.type === "team" ? "team-has-no-current-members" : "no-current-person" }];
+    }
+    return [];
+  });
+}
+
 async function policiesStage(scope, byId, readMarkdown, asOf) {
   const linkedPolicyIds = new Set(scope.controls.flatMap((control) => control.policyIds || []));
   const policies = [...linkedPolicyIds].map((id) => byId.get(id)).filter((record) => (

package/src/setup.js

@@ -1,5 +1,4 @@
 import { createResource, updateResource } from "./files.js";
-import { ensureEvidenceTestDrafts } from "./evidence-tests.js";
 import { createResourceId } from "./id.js";
 import { loadWorkspace } from "./workspace.js";
 
@@ -10,81 +9,61 @@ export async function setupWorkspace(input = process.cwd(), payload = {}) {
   const loaded = await loadWorkspace(input);
   const setup = normalizeSetupPayload(payload);
   validateSetup(loaded, setup);
+  const plan = buildSetupRecords(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);
-  }
+  await upsertResource(loaded.root, plan.existingSystem, plan.system);
+  await updateResource(loaded.root, "workspace", plan.workspace.id, plan.workspace);
+  if (plan.renderer) await updateResource(loaded.root, plan.renderer.type, plan.renderer.id, plan.renderer);
 
-  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])]
+  return {
+    draft: setup.draft,
+    system: plan.system,
+    workspace: plan.workspace,
+    linkedControlIds: [],
+    evidenceTestDraftIds: [],
+    onboardingComplete: !setup.draft
   };
-  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);
+}
 
+export async function planWorkspaceSetup(input = process.cwd(), payload = {}) {
+  const loaded = await loadWorkspace(input);
+  const setup = normalizeSetupPayload(payload);
+  validateSetup(loaded, setup);
+  const plan = buildSetupRecords(loaded, setup);
   return {
+    schemaVersion: 1,
+    preview: true,
     draft: setup.draft,
-    system,
-    workspace,
-    linkedControlIds,
-    evidenceTestDraftIds: evidenceTestDrafts.created.map(({ id }) => id),
+    changes: {
+      system: plan.existingSystem ? "update" : "create",
+      workspace: "update",
+      renderer: plan.renderer ? "update" : "unchanged",
+      controls: 0,
+      evidenceDrafts: 0
+    },
+    system: setupSystemSummary(plan.system),
+    target: setupTargetSummary(plan.workspace),
     onboardingComplete: !setup.draft
   };
 }
 
+export function summarizeSetupResult(result) {
+  return {
+    schemaVersion: 1,
+    preview: false,
+    draft: result.draft,
+    changes: {
+      system: "saved",
+      workspace: "updated",
+      controls: result.linkedControlIds?.length || 0,
+      evidenceDrafts: result.evidenceTestDraftIds?.length || 0
+    },
+    system: setupSystemSummary(result.system),
+    target: setupTargetSummary(result.workspace),
+    onboardingComplete: result.onboardingComplete
+  };
+}
+
 export function normalizeSetupPayload(payload = {}) {
   if (!payload || Array.isArray(payload) || typeof payload !== "object") {
     throw new Error("Setup input must be a JSON object.");
@@ -146,6 +125,44 @@ function findSetupSystem(resources, setup) {
     ));
 }
 
+function buildSetupRecords(loaded, setup) {
+  const existingSystem = findSetupSystem(loaded.resources, setup);
+  const systemId = existingSystem?.id || createResourceId(
+    "system",
+    setup.serviceName,
+    loaded.resources.map(({ id }) => id)
+  );
+  const system = {
+    ...(existingSystem || {}),
+    schemaVersion: 1,
+    id: systemId,
+    type: "system",
+    title: setup.serviceName,
+    status: setup.draft
+      ? existingSystem?.status || "planned"
+      : existingSystem?.status === "planned"
+        ? "active"
+        : existingSystem?.status || "active",
+    criticality: setup.criticality,
+    ownerIds: [setup.ownerId],
+    description: setup.boundary,
+    systemKind: existingSystem?.systemKind || "service",
+    dataClassification: setup.dataClassification,
+    internetExposed: setup.internetExposed,
+    inScope: true
+  };
+  const existingWorkspace = loaded.resources.find(({ type }) => type === "workspace");
+  if (!existingWorkspace) throw new Error("The workspace settings record was not found.");
+  const workspace = {
+    ...existingWorkspace,
+    assuranceGoal: assuranceGoalFromSetup(setup.programGoal),
+    systemIds: [...new Set([...(existingWorkspace.systemIds || []), systemId])]
+  };
+  const existingRenderer = loaded.resources.find(({ type }) => type === "renderer-settings");
+  const renderer = existingRenderer ? { ...existingRenderer, showOnboarding: setup.draft } : null;
+  return { existingSystem, system, workspace, renderer };
+}
+
 async function upsertResource(root, existing, record) {
   return existing
     ? updateResource(root, record.type, record.id, record)
@@ -159,6 +176,27 @@ function assuranceGoalFromSetup(goal) {
   return "none";
 }
 
+function setupSystemSummary(system) {
+  return {
+    id: system.id,
+    title: system.title,
+    status: system.status,
+    inScope: system.inScope
+  };
+}
+
+function setupTargetSummary(workspace) {
+  return {
+    assuranceGoal: workspace.assuranceGoal,
+    scopeCounts: {
+      systems: workspace.systemIds?.length || 0,
+      frameworks: workspace.frameworkIds?.length || 0,
+      requirements: workspace.requirementIds?.length || 0,
+      controls: workspace.controlIds?.length || 0
+    }
+  };
+}
+
 function booleanValue(value, name) {
   if (value === true || value === false) return value;
   if (value === "true") return true;