create-filegrc 0.3.3 → 0.3.4

package/README.md

@@ -1,6 +1,6 @@
 # create-filegrc
 
-Create a Git-native filegrc workspace for a SOC 2 program:
+Create a Git-native filegrc workspace for a SOC 2 program. Use a dedicated private repository so browser-generated compliance commits stay separate from application development history.
 
 ```sh
 npx create-filegrc@latest company-grc
@@ -40,7 +40,7 @@ npx create-filegrc@latest company-grc --config setup.json
 
 Generated workspaces also include layered `AGENTS.md` instructions and model-driven headless commands. `filegrc program-path` gives agents the same six steps, exact page guidance, current status, and next actions shown in the renderer. Agents can define program scope, approve policies, implement controls, test External Evidence, complete policy work, trigger event tasks, and prepare later audit packets through the same domain functions used by the renderer.
 
-Git is initialized when needed. The browser can create local commits before a remote is configured.
+Git is initialized on `main` when needed. New workspaces use trunk mode with `main` and `origin`. Browser editing becomes available after that branch has an upstream; each save fast-forwards, validates, commits, and pushes automatically. Existing parent repositories are supported and never receive a nested Git repository.
 
 Creation output reports the resolved filegrc version, program timezone, starter record counts, whether installation ran, and whether the target joined an existing Git worktree or received a new repository.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -30,9 +30,30 @@ export async function runCli(argv = process.argv.slice(2)) {
     `filegrc ${result.engineVersion}${result.enginePackage ? ` from ${result.enginePackage}` : ""}: ` +
     `${result.install === "installed" ? "installed" : "installation skipped"}`
   );
+  console.log("Use a dedicated private repository for your FileGRC workspace. The browser");
+  console.log("commits and pushes each saved program change, so a standalone repository keeps");
+  console.log("the compliance audit trail separate from application development history.");
   console.log(`Git: ${result.gitMode === "existing-worktree" ? "joined existing worktree" : "initialized new repository"}`);
-  if (result.gitDetached) {
-    console.log("Warning: detached HEAD detected. Check out a branch before using browser commit, pull, or push.");
+  if (result.gitMode === "existing-worktree") {
+    console.log("");
+    console.log("This FileGRC workspace joined an existing Git repository.");
+    console.log("");
+    console.log("FileGRC recommends a dedicated private repository because browser saves create");
+    console.log("frequent compliance commits. A standalone repository keeps the GRC audit trail");
+    console.log("separate from application development history.");
+    console.log("");
+    console.log("Monorepo mode remains supported. Browser Git operations will commit only files");
+    console.log("inside this FileGRC workspace.");
+  }
+  if (
+    result.gitMode === "existing-worktree"
+    && result.repository.mode === "trunk"
+    && (result.gitDetached || result.gitBranch !== result.repository.authoritativeBranch)
+  ) {
+    console.log("");
+    console.log("The browser will open in read-only mode until this workspace is available on");
+    console.log("the configured authoritative branch. File creation and CLI validation still");
+    console.log("work from this checkout.");
   }
   console.log(`Timezone: ${result.values.timezone}`);
   for (const stage of result.stages) {
@@ -103,6 +124,9 @@ function parseArgs(argv) {
     else if (name === "starter") options.starter = next();
     else if (name === "filegrc-version") options.filegrcVersion = next();
     else if (name === "filegrc-package") options.filegrcPackage = next();
+    else if (name === "repository-mode") options.repositoryMode = next();
+    else if (name === "authoritative-branch") options.authoritativeBranch = next();
+    else if (name === "repository-remote") options.repositoryRemote = next();
     else if (name === "service-name") setup.serviceName = next();
     else if (name === "boundary") setup.boundary = next();
     else if (name === "service-owner") setup.ownerId = next();
@@ -131,6 +155,9 @@ Options:
   --starter <profile>               security (default) or foundation
   --filegrc-version <version>       Override resolved engine version
   --filegrc-package <directory>     Install an unpublished local filegrc package
+  --repository-mode <mode>          trunk (default) or manual
+  --authoritative-branch <name>     Browser write branch, defaults to main
+  --repository-remote <name>        Browser sync remote, defaults to origin
   --service-name <name>             Complete service setup after creation
   --boundary <description>          Initial service boundary
   --service-owner <person-id>       Defaults to person-policy-owner

package/src/index.js

@@ -16,6 +16,7 @@ export async function createFilegrc(options = {}) {
   const parameterConfig = JSON.parse(await readFile(join(packageRoot, "template-parameters.json"), "utf8"));
   const target = resolve(options.target ?? "filegrc-program");
   const starter = normalizeStarterProfile(options.starter);
+  const repository = normalizeRepositoryOptions(options);
   if (options.setup && options.install === false) {
     throw new Error("Combined service setup requires installation. Remove --no-install or run filegrc setup after npm install.");
   }
@@ -38,6 +39,7 @@ export async function createFilegrc(options = {}) {
   await mkdir(target, { recursive: true });
   await copyTemplate(target, starter);
   await renderTemplate(target, parameterConfig, values, starter);
+  await writeRendererRepositorySettings(target, repository);
   await writeBaselineRecords(target, values.effective_date, starter);
   await applyStarterScope(target, starter, values.effective_date);
   const initialResourceCounts = await summarizeResources(target);
@@ -49,7 +51,7 @@ export async function createFilegrc(options = {}) {
     await writeMinimalLockfile(target, values.project_name, values.filegrc_version_range);
   }
   const joinedExistingWorktree = await isInsideGitWorktree(target);
-  if (!joinedExistingWorktree) await run("git", ["init"], target);
+  if (!joinedExistingWorktree) await run("git", ["init", `--initial-branch=${repository.authoritativeBranch}`], target);
   const gitHead = await inspectGitHead(target);
   const setup = options.setup ? await runCombinedSetup(target, options.setup) : null;
   const resourceCounts = setup ? await summarizeResources(target) : initialResourceCounts;
@@ -67,7 +69,8 @@ export async function createFilegrc(options = {}) {
     install: installed ? "installed" : "skipped",
     gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized",
     gitBranch: gitHead.branch,
-    gitDetached: gitHead.detached
+    gitDetached: gitHead.detached,
+    repository
   };
 }
 
@@ -80,6 +83,54 @@ export function normalizeStarterProfile(value = "security") {
   return normalized;
 }
 
+function normalizeRepositoryOptions(options) {
+  const mode = String(options.repositoryMode ?? "trunk").trim();
+  if (!["trunk", "manual"].includes(mode)) {
+    throw new Error("Repository mode must be trunk or manual.");
+  }
+  return {
+    mode,
+    authoritativeBranch: normalizeGitSetting(options.authoritativeBranch, "main", "authoritative branch"),
+    remote: normalizeGitSetting(options.repositoryRemote, "origin", "repository remote")
+  };
+}
+
+function normalizeGitSetting(value, fallback, label) {
+  const result = String(value ?? fallback).trim();
+  if (!safeGitName(result)) {
+    throw new Error(`${label} must be a safe Git name.`);
+  }
+  return result;
+}
+
+function safeGitName(value) {
+  const segments = value.split("/");
+  return Boolean(value)
+    && value !== "@"
+    && value !== "HEAD"
+    && !value.startsWith("-")
+    && !value.includes("..")
+    && !value.includes("@{")
+    && !/[\s~^:?*[\]\\\u0000-\u001f\u007f]/.test(value)
+    && segments.every((segment) => (
+      segment
+      && !segment.startsWith(".")
+      && !segment.endsWith(".")
+      && !segment.endsWith(".lock")
+    ));
+}
+
+async function writeRendererRepositorySettings(target, repository) {
+  const path = join(target, "data", "renderer.json");
+  const renderer = JSON.parse(await readFile(path, "utf8"));
+  await writeFile(path, `${JSON.stringify({
+    ...renderer,
+    repositoryMode: repository.mode,
+    authoritativeBranch: repository.authoritativeBranch,
+    repositoryRemote: repository.remote
+  }, null, 2)}\n`, "utf8");
+}
+
 export async function resolveFilegrcVersion(explicitVersion) {
   if (explicitVersion) return cleanVersion(explicitVersion);
   try {
@@ -452,13 +503,13 @@ async function runCombinedSetup(target, input) {
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.3.3",
+    version: "0.3.4",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.3.3",
+        version: "0.3.4",
         dependencies: { filegrc: versionRange }
       }
     }

package/template/AGENTS.md

@@ -58,9 +58,24 @@ Git supplies file authors, commit timestamps, messages, diffs, and revisions. Do
 
 Domain events still need explicit dates. Keep values such as `occurredOn`, `approvedOn`, `reviewedOn`, `completedOn`, and audit-period dates in their records.
 
-Make focused commits with messages that explain the reason for the change. The engine never creates commits automatically. Review the workspace diff, then use the commit action on Repository or the Git CLI. The renderer validates the workspace and requires an explicit message before it creates a commit.
+Use a dedicated private repository for your FileGRC workspace. The browser commits and pushes each saved program change, so a standalone repository keeps the compliance audit trail separate from application development history.
 
-Pull before starting work when other people or agents may have changed the repository. Without a remote, the browser's Repository page creates a local commit and hides synchronization actions. With a remote, it pulls with rebase, refuses to pull over uncommitted files, and pushes immediately after it creates a commit. Agents and terminal users own Git synchronization and should run `git pull --rebase`, `git commit`, and `git push` directly. Do not create merge commits for routine synchronization.
+- Prefer creating or cloning FileGRC as a standalone private repository.
+- Run the editable browser from the authoritative branch's main checkout.
+- Do not place a new FileGRC workspace inside an application monorepo unless the organization has explicitly chosen that structure.
+- If FileGRC already lives in a monorepo, do not relocate it automatically.
+- In a monorepo, never include application changes in FileGRC-generated commits.
+- Treat detached and feature-branch copies as read-only unless an explicit development override is active.
+
+New workspaces use trunk repository mode with `main` as the authoritative branch and `origin` as the remote. Each browser mutation checks the whole Git worktree, fetches the remote, fast-forwards only, rechecks the edited revision, writes through the normal domain function, validates the workspace, stages only this FileGRC workspace, creates a focused commit, and pushes it. Browser onboarding commits its related workspace, system, and renderer changes together.
+
+The Repository page reports `Synced`, `Syncing`, `Not synced`, `Read-only checkout`, or `Git setup required`. A failed push keeps the local FileGRC commit and offers Retry sync when every ahead commit changes only this workspace. FileGRC never pushes an ahead commit that includes files outside this workspace, and it never merges, rebases, switches branches, resolves conflicts, or changes files outside the workspace.
+
+Record lifecycle fields are the approval source. Draft, proposed, approved, and retired records may all live on the authoritative branch. Do not use Git branches to represent policy approval.
+
+Existing workspaces without `repositoryMode` remain in manual mode. In manual mode, review the workspace diff and use the Repository controls or Git CLI. Agents and terminal users always own their Git synchronization and should pull, commit, and push directly. FileGRC does not replace repository authentication, authorization, branch protection, or review controls.
+
+Use `npx filegrc serve --allow-non-authoritative-writes` only for local development in a task worktree. The override is visible in the UI and never commits or pushes.
 
 Do not rewrite or remove committed records that explain prior audit periods. Close or retire them. Delete only mistakes and uncommitted drafts.
 
@@ -93,7 +108,7 @@ Headless agents get the same protection by exporting an edit payload with `fileg
 
 ## Renderer settings and onboarding
 
-`data/renderer.json` stores committed renderer preferences. New workspaces set `showOnboarding` to `true`. Completing or skipping onboarding sets it to `false`; the app does not commit that change.
+`data/renderer.json` stores committed renderer and repository preferences. New workspaces set `showOnboarding` to `true`, `repositoryMode` to `trunk`, `authoritativeBranch` to `main`, and `repositoryRemote` to `origin`. In trunk mode, completing or skipping onboarding commits and pushes the related change. Existing settings without `repositoryMode` keep manual behavior.
 
 Onboarding explains the file and Git workflow, the program path, policy obligations, and Policy Events before covering report types and the final audit stage. It then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional program goal. It creates or updates one `system` record and stores that selected system and the management goal on `workspace`. It does not select framework records, link controls to the service, or create evidence. Selecting Type 1 or Type 2 does not create an audit engagement. Completing onboarding opens the Step 1 overview so the user can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before approving policies.
 

package/template/README.md

@@ -8,6 +8,8 @@ filegrc gives founder-led engineering teams one place to adopt policies, impleme
 
 It is open source, MIT licensed, and runs locally.
 
+Use a dedicated private repository for your FileGRC workspace. The browser commits and pushes each saved program change, so a standalone repository keeps the compliance audit trail separate from application development history.
+
 ```sh
 npx create-filegrc@latest company-grc
 cd company-grc
@@ -27,6 +29,10 @@ The repository is the program. There is no separate application database.
 
 Use the same source through the local web app, a text editor, the CLI, or CI. Browser and CLI actions call the same rules, so engineers and agents see the same validation and readiness results.
 
+New workspaces use `main` as the authoritative browser branch. Browser saves fetch and fast-forward from `origin`, validate the change, create a focused commit, and push it. Draft, proposed, approved, and retired records all live on that branch because record status, not a Git branch, represents approval.
+
+Detached and feature-branch checkouts are read-only in the browser by default. Developers can run `npx filegrc serve --allow-non-authoritative-writes` for local task-worktree edits; that override never commits or pushes. Existing workspaces without `repositoryMode` keep manual browser Git behavior. CLI and agent workflows continue to manage Git explicitly.
+
 ## One path from setup to audit
 
 ![filegrc SOC 2 program overview](docs/filegrc-home.png)

package/template/data/AGENTS.md

@@ -185,3 +185,5 @@ git diff
 ```
 
 Review every changed JSON, Markdown, and attachment. Confirm the diff contains no secrets, temporary files, source exports with prohibited data, or derived `.filegrc/` output. Make one focused commit whose message says why the compliance record changed.
+
+These commands are for CLI and agent work, which continues to manage Git explicitly. Browser saves in trunk mode commit and push automatically from the configured authoritative branch. Do not use a feature branch as a record approval state, and never include application changes when this workspace lives in a monorepo.

package/template/data/renderer.json

@@ -4,5 +4,8 @@
   "type": "renderer-settings",
   "title": "Renderer settings",
   "showOnboarding": true,
+  "repositoryMode": "trunk",
+  "authoritativeBranch": "main",
+  "repositoryRemote": "origin",
   "completedStagePageIds": []
 }

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "{{project_name}}",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "private": true,
   "description": "filegrc workspace for a SOC 2 program",
   "type": "module",