fullstackgtm 0.10.0

package/src/config.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { builtinAuditRules } from "./rules.ts";
+import type { GtmAuditRule, GtmPolicy } from "./types.ts";
+
+/**
+ * Project-level configuration: `fullstackgtm.config.json` in the working
+ * directory (or an explicit `--config` path). Policy thresholds, rule
+ * selection, and rule packages — third-party modules exporting additional
+ * `GtmAuditRule`s — all live here so a team's audit standard is reviewable
+ * in version control.
+ */
+
+export const CONFIG_FILE_NAME = "fullstackgtm.config.json";
+
+export type FullstackgtmConfig = {
+  policy?: Partial<GtmPolicy>;
+  rules?: {
+    /** If set, only these rule ids run (after rule packages are loaded). */
+    enabled?: string[];
+    /** Removed from the effective set after `enabled` is applied. */
+    disabled?: string[];
+  };
+  /**
+   * Module specifiers resolved relative to the config file. Each module must
+   * export `rules: GtmAuditRule[]`. Use compiled .js/.mjs modules so they
+   * load under plain Node.
+   */
+  rulePackages?: string[];
+};
+
+export type LoadedConfig = {
+  config: FullstackgtmConfig;
+  path: string;
+};
+
+export function loadConfig(
+  explicitPath?: string,
+  cwd = process.cwd(),
+): LoadedConfig | null {
+  const path = explicitPath ? resolve(cwd, explicitPath) : resolve(cwd, CONFIG_FILE_NAME);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    if (explicitPath) throw new Error(`Could not read config file: ${path}`);
+    return null;
+  }
+  const config = JSON.parse(raw) as FullstackgtmConfig;
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`${path} must contain a JSON object.`);
+  }
+  return { config, path };
+}
+
+/** Overlay config policy values onto a base policy; defined values win. */
+export function mergePolicy(base: GtmPolicy, config?: FullstackgtmConfig): GtmPolicy {
+  if (!config?.policy) return base;
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(config.policy)) {
+    if (value !== undefined) {
+      (merged as Record<string, unknown>)[key] = value;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Build the effective rule set: built-ins plus rule-package exports, then
+ * `enabled` (allow-list) and `disabled` filters.
+ */
+export async function resolveConfiguredRules(
+  loaded?: LoadedConfig | null,
+  baseRules: GtmAuditRule[] = builtinAuditRules,
+): Promise<GtmAuditRule[]> {
+  let rules = [...baseRules];
+
+  for (const specifier of loaded?.config.rulePackages ?? []) {
+    const resolvedSpecifier =
+      specifier.startsWith(".") || isAbsolute(specifier)
+        ? pathToFileURL(resolve(dirname(loaded!.path), specifier)).href
+        : specifier;
+    const rulePackage = await import(resolvedSpecifier);
+    const imported = rulePackage.rules ?? rulePackage.default?.rules;
+    if (!Array.isArray(imported)) {
+      throw new Error(`Rule package ${specifier} must export \`rules: GtmAuditRule[]\`.`);
+    }
+    for (const rule of imported) {
+      if (!rule?.id || typeof rule.evaluate !== "function") {
+        throw new Error(`Rule package ${specifier} exported an invalid rule.`);
+      }
+      rules.push(rule as GtmAuditRule);
+    }
+  }
+
+  const enabled = loaded?.config.rules?.enabled;
+  if (enabled?.length) {
+    const known = new Map(rules.map((rule) => [rule.id, rule]));
+    rules = enabled.map((id) => {
+      const rule = known.get(id);
+      if (!rule) {
+        throw new Error(
+          `Config enables unknown rule: ${id}. Known rules: ${Array.from(known.keys()).join(", ")}`,
+        );
+      }
+      return rule;
+    });
+  }
+
+  const disabled = new Set(loaded?.config.rules?.disabled ?? []);
+  return rules.filter((rule) => !disabled.has(rule.id));
+}

package/src/connector.ts

@@ -0,0 +1,140 @@
+import { requiresHumanInput } from "./rules.ts";
+import type {
+  GtmConnector,
+  PatchOperation,
+  PatchOperationResult,
+  PatchPlan,
+  PatchPlanRun,
+  PatchPlanRunStatus,
+} from "./types.ts";
+
+export type ApplyPatchPlanOptions = {
+  /**
+   * Explicit allow-list of operation ids the human approved. Operations not
+   * listed are skipped without any provider call. An empty list rejects the
+   * whole run.
+   */
+  approvedOperationIds: string[];
+  /**
+   * Concrete values supplied at approval time for operations whose
+   * `afterValue` is a `requires_human_*` placeholder, keyed by operation id.
+   */
+  valueOverrides?: Record<string, unknown>;
+  /**
+   * Compare-and-set: before each field write, read the live provider value
+   * and refuse the write (`conflict` result) if it no longer matches the
+   * plan's `beforeValue`. Defaults to on when the connector supports
+   * `readField`.
+   */
+  checkConflicts?: boolean;
+};
+
+const FIELD_WRITE_OPERATIONS = new Set(["set_field", "clear_field", "link_record"]);
+
+function normalizeForComparison(value: unknown): string | null {
+  if (value === undefined || value === null || value === "") return null;
+  return String(value);
+}
+
+/**
+ * Apply an approved subset of a patch plan through a connector.
+ *
+ * The safety contract lives here, not in connectors:
+ * - nothing is written unless the operation id was explicitly approved
+ * - placeholder values are never written; they require an override
+ * - every operation produces a result, and the run is the audit record
+ */
+export async function applyPatchPlan(
+  connector: GtmConnector,
+  plan: PatchPlan,
+  options: ApplyPatchPlanOptions,
+): Promise<PatchPlanRun> {
+  if (!connector.applyOperation) {
+    throw new Error(`The ${connector.provider} connector is read-only.`);
+  }
+
+  const startedAt = new Date().toISOString();
+  const approved = new Set(options.approvedOperationIds);
+  const checkConflicts =
+    options.checkConflicts ?? typeof connector.readField === "function";
+  const results: PatchOperationResult[] = [];
+  let attempted = 0;
+  let applied = 0;
+
+  for (const operation of plan.operations) {
+    if (!approved.has(operation.id)) {
+      results.push({
+        operationId: operation.id,
+        status: "skipped",
+        detail: "Operation was not approved.",
+      });
+      continue;
+    }
+
+    const override = options.valueOverrides?.[operation.id];
+    if (requiresHumanInput(operation.afterValue) && override === undefined) {
+      results.push({
+        operationId: operation.id,
+        status: "skipped",
+        detail: "Operation needs a concrete value; supply a value override.",
+      });
+      continue;
+    }
+
+    if (
+      checkConflicts &&
+      connector.readField &&
+      operation.field &&
+      FIELD_WRITE_OPERATIONS.has(operation.operation)
+    ) {
+      const current = await connector.readField(
+        operation.objectType,
+        operation.objectId,
+        operation.field,
+      );
+      const expected = normalizeForComparison(operation.beforeValue);
+      const found = normalizeForComparison(current);
+      if (expected !== found) {
+        results.push({
+          operationId: operation.id,
+          status: "conflict",
+          detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+          providerData: { currentValue: current ?? null },
+        });
+        continue;
+      }
+    }
+
+    const resolved: PatchOperation =
+      override === undefined ? operation : { ...operation, afterValue: override };
+
+    attempted += 1;
+    try {
+      const result = await connector.applyOperation(resolved);
+      results.push(result);
+      if (result.status === "applied") applied += 1;
+    } catch (error) {
+      results.push({
+        operationId: operation.id,
+        status: "failed",
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    planId: plan.id,
+    provider: connector.provider,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    status: runStatus(attempted, applied),
+    results,
+  };
+}
+
+function runStatus(attempted: number, applied: number): PatchPlanRunStatus {
+  if (attempted === 0) return "rejected";
+  if (applied === attempted) return "applied";
+  if (applied > 0) return "partial";
+  return "failed";
+}