@aliou/pi-guardrails 0.9.4 → 0.10.0

package/src/index.ts

@@ -1,7 +1,15 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { isOnboardingPending } from "./commands/onboarding";
+import { registerGuardrailsOnboardingCommand } from "./commands/onboarding-command";
 import { registerGuardrailsSettings } from "./commands/settings-command";
 import { configLoader } from "./config";
 import { setupGuardrailsHooks } from "./hooks";
+import {
+  migrateApplyBuiltinDefaults,
+  migrateMarkOnboardingDone,
+  needsApplyBuiltinDefaultsMigration,
+  needsOnboardingDoneMigration,
+} from "./utils/migration";
 import { pendingWarnings } from "./utils/warnings";
 
 /**
@@ -22,16 +30,67 @@ import { pendingWarnings } from "./utils/warnings";
  */
 export default async function (pi: ExtensionAPI) {
   await configLoader.load();
-  const config = configLoader.getConfig();
 
-  if (!config.enabled) return;
+  const hasGlobalConfig = configLoader.hasConfig("global");
+
+  if (hasGlobalConfig) {
+    const globalConfig = configLoader.getRawConfig("global");
+    if (globalConfig) {
+      let migrated = globalConfig;
+      let changed = false;
+
+      if (needsApplyBuiltinDefaultsMigration(migrated)) {
+        migrated = migrateApplyBuiltinDefaults(migrated);
+        changed = true;
+      }
+
+      if (needsOnboardingDoneMigration(migrated)) {
+        migrated = migrateMarkOnboardingDone(migrated);
+        changed = true;
+      }
+
+      if (changed) {
+        await configLoader.save("global", migrated);
+        await configLoader.load();
+      }
+    }
+  }
+
+  let hooksRegistered = false;
 
-  setupGuardrailsHooks(pi, config);
   registerGuardrailsSettings(pi);
 
+  const maybeRegisterHooks = () => {
+    if (hooksRegistered) return;
+    const config = configLoader.getConfig();
+    if (!config.enabled) return;
+    setupGuardrailsHooks(pi, config);
+    hooksRegistered = true;
+  };
+
+  if (isOnboardingPending(configLoader.getRawConfig("global"))) {
+    registerGuardrailsOnboardingCommand(pi, maybeRegisterHooks);
+  } else {
+    maybeRegisterHooks();
+  }
+
   pi.on("session_start", (_event, ctx) => {
     for (const warning of pendingWarnings.splice(0)) {
       ctx.ui.notify(warning, "warning");
     }
+
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    if (isOnboardingPending(configLoader.getRawConfig("global"))) {
+      ctx.ui.notify(
+        "[Guardrails] setup pending. Run `/guardrails:onboarding` to choose recommended or minimal protection defaults.",
+        "info",
+      );
+      return;
+    }
+
+    maybeRegisterHooks();
   });
 }

package/src/utils/migration.ts

@@ -21,7 +21,7 @@ import { pendingWarnings } from "./warnings";
  * Keep this independent from package.json version.
  * Bump only when config schema/default migration markers change.
  */
-export const CURRENT_VERSION = "0.8.0-20260228";
+export const CURRENT_VERSION = "0.9.0-20260327";
 
 /**
  * Check if a config needs migration (no version field = v0).
@@ -97,6 +97,60 @@ export function needsEnvFilesToPoliciesMigration(
   return features?.protectEnvFiles !== undefined;
 }
 
+/**
+ * Check if config needs applyBuiltinDefaults bridge migration.
+ * This runs only for existing config files loaded by ConfigLoader.
+ */
+export function needsApplyBuiltinDefaultsMigration(
+  config: GuardrailsConfig,
+): boolean {
+  return config.applyBuiltinDefaults === undefined;
+}
+
+/**
+ * Bridge migration for defaults deprecation.
+ * Existing config files get applyBuiltinDefaults=true to preserve behavior.
+ */
+export function migrateApplyBuiltinDefaults(
+  config: GuardrailsConfig,
+): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  migrated.applyBuiltinDefaults = true;
+  migrated.version = CURRENT_VERSION;
+
+  pendingWarnings.push(
+    "Guardrails config was migrated. `applyBuiltinDefaults` was set to `true` to preserve current behavior.",
+  );
+
+  return migrated;
+}
+
+export function needsOnboardingDoneMigration(
+  config: GuardrailsConfig,
+): boolean {
+  return (
+    config.onboarding?.completed === undefined &&
+    config.applyBuiltinDefaults !== undefined
+  );
+}
+
+export function migrateMarkOnboardingDone(
+  config: GuardrailsConfig,
+): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  pendingWarnings.push(
+    "Guardrails config was migrated. Existing setup marked as onboarding-complete.",
+  );
+  migrated.onboarding = {
+    ...(migrated.onboarding ?? {}),
+    completed: true,
+    completedAt: migrated.onboarding?.completedAt ?? new Date().toISOString(),
+    version: migrated.onboarding?.version ?? CURRENT_VERSION,
+  };
+  migrated.version = CURRENT_VERSION;
+  return migrated;
+}
+
 /**
  * Migrate deprecated envFiles/protectEnvFiles fields to policies.
  */

package/src/utils/path.ts

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Expand a leading tilde to the current user's home directory.
+ * Preserves all other paths unchanged.
+ */
+export function expandHomePath(input: string): string {
+  if (input === "~") {
+    return homedir();
+  }
+
+  if (input.startsWith("~/")) {
+    return join(homedir(), input.slice(2));
+  }
+
+  return input;
+}