filegrc 0.3.2 → 0.3.4

package/README.md

@@ -34,7 +34,7 @@ npx filegrc prepare-audit audit-id
 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 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. In trunk mode, browser saves synchronize, commit, and push from the authoritative branch. Use `--allow-non-authoritative-writes` for local development in a task checkout; the override never commits or pushes.
 
 `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.
 
@@ -54,7 +54,7 @@ Use `filegrc attach <evidence-id> <source-file>` to copy a fixed evidence file u
 
 Use `filegrc detach <evidence-id> <attachment-name> --yes` for explicit removal. Evidence records with linked local attachments cannot be deleted.
 
-The package requires Node.js 20 or newer. It uses Git for authors, commit timestamps, messages, diffs, and revisions. Browser commits are explicit. Without a remote they remain local; with a remote the browser commits and pushes together. Browser pulls use rebase. Agents and terminal users use Git directly; the filegrc CLI does not wrap pull, commit, or push.
+The package requires Node.js 20 or newer. It uses Git for authors, commit timestamps, messages, diffs, and revisions. New workspaces use trunk mode, which fetches and fast-forwards before each browser mutation, validates and commits the saved change, then pushes. Existing settings without `repositoryMode` keep manual browser Git behavior. Agents and terminal users use Git directly; the filegrc CLI does not wrap pull, commit, or push.
 
 The editable server has no authentication and binds to loopback by default. Put it behind trusted authentication before exposing it on a network, or publish the read-only static build.
 

package/model/v1.json

@@ -104,17 +104,20 @@
       "pluralTitle": "Renderer settings",
       "group": "repository",
       "singleton": "renderer.json",
-      "description": "Optional local interface settings, including onboarding visibility and manually completed Step pages. Renderer settings are not required for SOC 2 and do not change compliance records.",
+      "description": "Optional local interface and browser repository settings, including onboarding visibility, manually completed Step pages, and authoritative-branch synchronization. Renderer settings are not required for SOC 2 and do not change compliance records.",
       "guidance": {
-        "policyBasis": "Renderer settings are a filegrc convenience, not a SOC 2 requirement, control, audit record, or substitute for evidence.",
-        "cadence": "Change it when the team wants to rerun or suppress an optional renderer workflow, then review and commit the resulting diff."
+        "policyBasis": "Renderer settings are a filegrc convenience, not a SOC 2 requirement, control, audit record, or substitute for evidence. Record lifecycle status represents approval; Git branches do not.",
+        "cadence": "Change it when the team wants to rerun or suppress an optional renderer workflow or change repository synchronization. Existing workspaces without repositoryMode keep manual browser Git behavior."
       },
       "required": ["showOnboarding"],
       "fields": {
         "showOnboarding": {"type":"boolean","label":"Show onboarding"},
-        "completedStagePageIds": {"type":"array","items":"string","label":"Manually completed program pages"}
+        "completedStagePageIds": {"type":"array","items":"string","label":"Manually completed program pages"},
+        "repositoryMode": {"type":"enum","values":["trunk","manual"],"label":"Repository mode"},
+        "authoritativeBranch": {"type":"string","format":"git-name","label":"Authoritative branch (defaults to main)"},
+        "repositoryRemote": {"type":"string","format":"git-name","label":"Repository remote (defaults to origin)"}
       },
-      "listFields": ["title","showOnboarding","completedStagePageIds"]
+      "listFields": ["title","showOnboarding","repositoryMode","authoritativeBranch","repositoryRemote","completedStagePageIds"]
     },
     "person": {
       "title": "Person",

package/package.json

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

package/src/build.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { FAVICON_PNG } from "./favicon.js";
+import { FAVICON_PNG, LOGO_MARK_PNG } from "./favicon.js";
 import { resolveWorkspacePath, resolveWorkspaceRoot } from "./paths.js";
 import { createAppState } from "./state.js";
 import { APP_SCRIPT, APP_STYLES, renderIndex } from "./web.js";
@@ -12,6 +12,7 @@ export async function buildWorkspace(input = process.cwd(), options = {}) {
   const paths = {
     html: resolveWorkspacePath(root, join(outputOption, "index.html")),
     favicon: resolveWorkspacePath(root, join(outputOption, "favicon.png")),
+    logoMark: resolveWorkspacePath(root, join(outputOption, "logo-mark-white.png")),
     script: resolveWorkspacePath(root, join(outputOption, "filegrc-app.js")),
     styles: resolveWorkspacePath(root, join(outputOption, "filegrc.css"))
   };
@@ -20,6 +21,7 @@ export async function buildWorkspace(input = process.cwd(), options = {}) {
   await Promise.all([
     writeFile(paths.html, renderIndex(state), "utf8"),
     writeFile(paths.favicon, FAVICON_PNG),
+    writeFile(paths.logoMark, LOGO_MARK_PNG),
     writeFile(paths.script, APP_SCRIPT, "utf8"),
     writeFile(paths.styles, APP_STYLES, "utf8")
   ]);

package/src/cli.js

@@ -29,12 +29,14 @@ import { markdownEntries } from "./resource-markdown.js";
 import { searchResources } from "./search.js";
 import { serveWorkspace } from "./server.js";
 import { planWorkspaceSetup, setupWorkspace, summarizeSetupResult } from "./setup.js";
+import { printGithubStarMessage } from "./startup.js";
 import { createAppState } from "./state.js";
 import { currentCalendarDate } from "./time.js";
 import { validateWorkspace } from "./validate.js";
 import { loadWorkspace } from "./workspace.js";
 
 const BOOLEAN_FLAGS = new Set([
+  "allow-non-authoritative-writes",
   "check-docs",
   "complete",
   "current",
@@ -62,15 +64,22 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "serve") {
     const result = await serveWorkspace(positionals[0] ?? root, {
       host: flags.host ?? process.env.FILEGRC_HOST,
-      port: flags.port ?? process.env.FILEGRC_PORT
+      port: flags.port ?? process.env.FILEGRC_PORT,
+      allowNonAuthoritativeWrites: flags["allow-non-authoritative-writes"] === true
     });
-    console.log(`filegrc workspace: ${result.url}`);
-    console.log(`Data: ${result.root}/data`);
-    return await new Promise((resolvePromise) => {
-      const stop = () => result.server.close(resolvePromise);
+    const stopped = new Promise((resolvePromise) => {
+      const stop = () => {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+        result.server.close(resolvePromise);
+      };
       process.once("SIGINT", stop);
       process.once("SIGTERM", stop);
     });
+    console.log(`filegrc workspace: ${result.url}`);
+    console.log(`Data: ${result.root}/data`);
+    printGithubStarMessage();
+    return await stopped;
   }
   if (command === "setup") {
     const payload = positionals[0] ? await readSetupPayload(positionals[0]) : {};
@@ -676,7 +685,7 @@ function printHelp() {
   console.log(`filegrc - Git-native GRC workspace
 
 Usage:
-  filegrc serve [root] [--host 127.0.0.1] [--port 8787]
+  filegrc serve [root] [--host 127.0.0.1] [--port 8787] [--allow-non-authoritative-writes]
   filegrc setup [setup.json|-] [setup options] [--draft] [--preview] [--summary] [--json]
   filegrc build [root] [--output .filegrc/site]
   filegrc validate [root] [--json]
@@ -713,12 +722,15 @@ 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]
+  filegrc serve [root] [--host address] [--port number] [--allow-non-authoritative-writes]
 
 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.
+  --allow-non-authoritative-writes
+                     Allow local browser writes from a task checkout. This explicit
+                     development override never commits or pushes.
   --help            Show this help without starting the server.
 
 Safety:

package/src/favicon.js

@@ -1,109 +1,4 @@
-import { deflateSync } from "node:zlib";
+import { readFileSync } from "node:fs";
 
-const SIZE = 64;
-const WHITE = [248, 249, 255, 255];
-
-export const FAVICON_PNG = createFavicon();
-
-function createFavicon() {
-  const pixels = Buffer.alloc(SIZE * SIZE * 4);
-
-  for (let y = 0; y < SIZE; y += 1) {
-    for (let x = 0; x < SIZE; x += 1) {
-      if (!insideRoundedSquare(x, y, 11)) continue;
-      setPixel(pixels, x, y, backgroundColor(x, y));
-    }
-  }
-
-  drawStroke(pixels, [
-    [18, 8],
-    [39, 8],
-    [51, 20],
-    [51, 50],
-    [50, 53],
-    [47, 55],
-    [17, 55],
-    [14, 54],
-    [12, 51],
-    [12, 13],
-    [14, 10],
-    [18, 8]
-  ], 2.3, WHITE);
-  drawStroke(pixels, [[39, 8], [39, 20], [51, 20]], 2.3, WHITE);
-
-  const rows = Buffer.alloc((SIZE * 4 + 1) * SIZE);
-  for (let y = 0; y < SIZE; y += 1) {
-    const rowOffset = y * (SIZE * 4 + 1);
-    rows[rowOffset] = 0;
-    pixels.copy(rows, rowOffset + 1, y * SIZE * 4, (y + 1) * SIZE * 4);
-  }
-
-  const header = Buffer.alloc(13);
-  header.writeUInt32BE(SIZE, 0);
-  header.writeUInt32BE(SIZE, 4);
-  header.set([8, 6, 0, 0, 0], 8);
-
-  return Buffer.concat([
-    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
-    pngChunk("IHDR", header),
-    pngChunk("IDAT", deflateSync(rows)),
-    pngChunk("IEND", Buffer.alloc(0))
-  ]);
-}
-
-function insideRoundedSquare(x, y, radius) {
-  const cornerX = x < radius ? radius - 1 : x >= SIZE - radius ? SIZE - radius : x;
-  const cornerY = y < radius ? radius - 1 : y >= SIZE - radius ? SIZE - radius : y;
-  return Math.hypot(x - cornerX, y - cornerY) <= radius;
-}
-
-function backgroundColor(x, y) {
-  const progress = Math.min(1, (x + y) / ((SIZE - 1) * 1.2));
-  return [0, 0, Math.round(112 + (53 - 112) * progress), 255];
-}
-
-function drawStroke(pixels, points, radius, color) {
-  for (let y = 0; y < SIZE; y += 1) {
-    for (let x = 0; x < SIZE; x += 1) {
-      const onStroke = points.slice(1).some((point, index) => (
-        distanceToSegment(x, y, points[index], point) <= radius
-      ));
-      if (onStroke) setPixel(pixels, x, y, color);
-    }
-  }
-}
-
-function distanceToSegment(x, y, start, end) {
-  const dx = end[0] - start[0];
-  const dy = end[1] - start[1];
-  const lengthSquared = dx * dx + dy * dy;
-  const progress = lengthSquared
-    ? Math.max(0, Math.min(1, ((x - start[0]) * dx + (y - start[1]) * dy) / lengthSquared))
-    : 0;
-  return Math.hypot(x - (start[0] + progress * dx), y - (start[1] + progress * dy));
-}
-
-function setPixel(pixels, x, y, color) {
-  pixels.set(color, (y * SIZE + x) * 4);
-}
-
-function pngChunk(type, data) {
-  const typeBuffer = Buffer.from(type, "ascii");
-  const chunk = Buffer.alloc(data.length + 12);
-  chunk.writeUInt32BE(data.length, 0);
-  typeBuffer.copy(chunk, 4);
-  data.copy(chunk, 8);
-  chunk.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), data.length + 8);
-  return chunk;
-}
-
-function crc32(buffer) {
-  let value = 0xffffffff;
-  for (const byte of buffer) {
-    value ^= byte;
-    for (let bit = 0; bit < 8; bit += 1) {
-      value = (value >>> 1) ^ (value & 1 ? 0xedb88320 : 0);
-    }
-  }
-  return (value ^ 0xffffffff) >>> 0;
-}
+export const FAVICON_PNG = readFileSync(new URL("./favicon.png", import.meta.url));
+export const LOGO_MARK_PNG = readFileSync(new URL("./logo-mark-white.png", import.meta.url));

package/src/git-name.js

@@ -0,0 +1,16 @@
+export function isSafeGitName(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")
+    ));
+}