pi-monofold 0.2.0 → 0.3.0

package/README.md

@@ -104,6 +104,12 @@ defaults:
     created: "{{date}}"
     source: "pi-monofold"
 
+focusPresets:
+  - id: control
+    label: Control workspace focus
+    targets:
+      - targetTags: [control]
+
 workspaces:
   - name: "Product docs"
     path: "../business"
@@ -133,6 +139,14 @@ workspaces:
     contextFiles: [README.md, AGENTS.md]
 ```
 
+## Focus presets
+
+Optional `focusPresets` define tag-based focus targets for the control workspace. Preset `id` values must be unique. Each target uses `targetTags`, matching workspace tags the same way as other Monofold target selectors. Targets that match zero configured workspaces are allowed in config and emit a runtime warning when the active preset is applied.
+
+Active focus (the selected preset id) lives in extension session memory only. It resets when Pi restarts. When `focusPresets` is non-empty, the first preset in YAML order becomes active at session start unless a later slice changes it.
+
+The example above includes a generic seed preset `control`. Add matching workspace tags in your own config when you adopt it.
+
 ## Commands
 
 Human-facing commands accept natural-language arguments and hand off interpretation to the Pi agent:

package/focus-preset.ts

@@ -0,0 +1,133 @@
+import { assertKnownKeys, asStringArray, isRecord, uniqueStrings } from "./validation.js";
+
+export type FocusPresetTarget = {
+  targetTags: string[];
+};
+
+export type FocusPreset = {
+  id: string;
+  label: string;
+  targets: FocusPresetTarget[];
+};
+
+export type FocusMatchableWorkspace = {
+  tags: string[];
+};
+
+const FOCUS_PRESET_KEYS = new Set(["id", "label", "targets"]);
+const FOCUS_PRESET_TARGET_KEYS = new Set(["targetTags"]);
+
+/** Parses and validates focus preset configuration from YAML/JSON input. */
+export function parseFocusPresets(value: unknown, label = "focusPresets"): FocusPreset[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  const presets: FocusPreset[] = [];
+  const seenIds = new Set<string>();
+  for (let index = 0; index < value.length; index += 1) {
+    const item = value[index];
+    const itemLabel = `${label}[${index}]`;
+    if (!isRecord(item)) throw new Error(`${itemLabel} must be an object`);
+    assertKnownKeys(itemLabel, item, FOCUS_PRESET_KEYS);
+    if (typeof item.id !== "string" || item.id.trim() === "") {
+      throw new Error(`${itemLabel}.id must be a non-empty string`);
+    }
+    if (typeof item.label !== "string" || item.label.trim() === "") {
+      throw new Error(`${itemLabel}.label must be a non-empty string`);
+    }
+    if (!Array.isArray(item.targets) || item.targets.length === 0) {
+      throw new Error(`${itemLabel}.targets must be a non-empty array`);
+    }
+    const targets: FocusPresetTarget[] = [];
+    for (let targetIndex = 0; targetIndex < item.targets.length; targetIndex += 1) {
+      const target = item.targets[targetIndex];
+      const targetLabel = `${itemLabel}.targets[${targetIndex}]`;
+      if (!isRecord(target)) throw new Error(`${targetLabel} must be an object`);
+      assertKnownKeys(targetLabel, target, FOCUS_PRESET_TARGET_KEYS);
+      const targetTags = uniqueStrings(asStringArray(`${targetLabel}.targetTags`, target.targetTags));
+      if (targetTags.length === 0) {
+        throw new Error(`${targetLabel}.targetTags must contain at least one non-empty string`);
+      }
+      targets.push({ targetTags });
+    }
+    if (seenIds.has(item.id)) throw new Error(`${label} has duplicate preset id: ${item.id}`);
+    seenIds.add(item.id);
+    presets.push({ id: item.id, label: item.label, targets });
+  }
+  return presets;
+}
+
+/** Returns the first preset id, or null when no focus preset is available. */
+export function pickDefaultFocusPresetId(focusPresets: FocusPreset[] | undefined): string | null {
+  if (!focusPresets || focusPresets.length === 0) return null;
+  return focusPresets[0]?.id ?? null;
+}
+
+/** Finds a focus preset by stable id. */
+export function findFocusPresetById(focusPresets: FocusPreset[] | undefined, id: string): FocusPreset | undefined {
+  return focusPresets?.find((preset) => preset.id === id);
+}
+
+/** Returns true when every requested focus tag is present on a workspace. */
+export function matchesFocusTarget(workspace: FocusMatchableWorkspace, targetTags: string[]): boolean {
+  if (targetTags.length === 0) return false;
+  return targetTags.every((tag) => workspace.tags.includes(tag));
+}
+
+/** Counts workspaces matched by a focus target's tag set. */
+export function countMatchingWorkspaces(
+  workspaces: FocusMatchableWorkspace[],
+  targetTags: string[],
+): number {
+  return workspaces.filter((workspace) => matchesFocusTarget(workspace, targetTags)).length;
+}
+
+/** Emits warnings for a preset's targets that do not match any configured workspace. */
+export function warnZeroTargetMatchesForPreset(
+  preset: FocusPreset,
+  workspaces: FocusMatchableWorkspace[],
+  warn: (message: string) => void,
+): void {
+  for (const target of preset.targets) {
+    if (countMatchingWorkspaces(workspaces, target.targetTags) === 0) {
+      warn(
+        `Focus preset "${preset.id}" target [${target.targetTags.join(", ")}] matches no configured workspace`,
+      );
+    }
+  }
+}
+
+let activeFocusPresetId: string | null = null;
+let activeFocusInitialized = false;
+
+/** Initializes the active focus preset once per process/session. */
+export function ensureActiveFocusInitialized(focusPresets: FocusPreset[] | undefined): void {
+  if (activeFocusInitialized) return;
+  activeFocusInitialized = true;
+  activeFocusPresetId = pickDefaultFocusPresetId(focusPresets);
+}
+
+/** Returns the current active focus preset id, if any. */
+export function getActiveFocusPresetId(): string | null {
+  return activeFocusPresetId;
+}
+
+/** Sets the active focus preset after validating that the id exists. */
+export function setActiveFocusPresetId(id: string, focusPresets: FocusPreset[] | undefined): void {
+  if (!findFocusPresetById(focusPresets, id)) {
+    throw new Error(`Unknown focus preset id: ${id}`);
+  }
+  activeFocusPresetId = id;
+  activeFocusInitialized = true;
+}
+
+/** Clears the active focus preset for the current process/session. */
+export function clearActiveFocusPresetId(): void {
+  activeFocusPresetId = null;
+  activeFocusInitialized = true;
+}
+
+/** Resets in-memory session state (for tests and process restart). */
+export function resetActiveFocusSessionState(): void {
+  activeFocusPresetId = null;
+  activeFocusInitialized = false;
+}

package/index.ts

@@ -4,6 +4,15 @@ import { execFile } from "node:child_process";
 import { access, copyFile, mkdir, readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
+import {
+  type FocusPreset,
+  ensureActiveFocusInitialized,
+  findFocusPresetById,
+  getActiveFocusPresetId,
+  parseFocusPresets,
+  warnZeroTargetMatchesForPreset,
+} from "./focus-preset.js";
+import { assertKnownKeys, asStringArray, isRecord, uniqueStrings } from "./validation.js";
 
 type CapabilityTag = "read" | "writeDocs" | "editCode" | "runCommands" | "git";
 type LegacyCapabilityTag = CapabilityTag | "gitCommit" | "gitPush";
@@ -42,6 +51,7 @@ type MultiWorkspaceConfig = {
     filenameTemplate?: string;
     metadata?: Record<string, unknown>;
   };
+  focusPresets?: FocusPreset[];
   workspaces: WorkspaceConfig[];
 };
 
@@ -135,26 +145,16 @@ const CODE_EXTENSIONS = new Set([
   ".scss",
   ".html",
 ]);
-const ROOT_KEYS = new Set(["version", "defaults", "workspaces"]);
+const ROOT_KEYS = new Set(["version", "defaults", "focusPresets", "workspaces"]);
 const DEFAULT_KEYS = new Set(["contextFiles", "filenameTemplate", "metadata"]);
 const WORKSPACE_KEYS = new Set(["name", "path", "tags", "capabilities", "contextFiles", "routes", "projects"]);
 const PROJECT_KEYS = new Set(["name", "path", "tags", "capabilities", "contextFiles", "routes"]);
 const ROUTE_KEYS = new Set(["path", "filenameTemplate", "metadata"]);
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function normalizeSlashes(value: string): string {
   return value.replace(/\\/g, "/");
 }
 
-function assertKnownKeys(label: string, value: Record<string, unknown>, allowed: Set<string>): void {
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) throw new Error(`${label} has unknown key: ${key}`);
-  }
-}
-
 function isInside(parent: string, child: string): boolean {
   const relative = path.relative(parent, child);
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -174,18 +174,6 @@ function assertProjectPath(label: string, value: string): void {
   }
 }
 
-function uniqueStrings(items: string[]): string[] {
-  return [...new Set(items.filter(Boolean))];
-}
-
-function asStringArray(label: string, value: unknown, required = true): string[] {
-  if (value === undefined && !required) return [];
-  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-    throw new Error(`${label} must be an array of strings`);
-  }
-  return value;
-}
-
 function asCapabilityArray(value: unknown): CapabilityTag[] {
   const items = asStringArray("capabilities", value);
   const normalized: CapabilityTag[] = [];
@@ -314,6 +302,7 @@ async function validateConfigObject(cwd: string, configPath: string, parsed: unk
   const defaultContextFiles = defaults ? asStringArray("defaults.contextFiles", defaults.contextFiles, false) : [];
   const defaultFilenameTemplate = typeof defaults?.filenameTemplate === "string" ? defaults.filenameTemplate : undefined;
   const defaultMetadata = isRecord(defaults?.metadata) ? (defaults.metadata as Record<string, unknown>) : undefined;
+  const focusPresets = parseFocusPresets(parsed.focusPresets, "focusPresets");
 
   const workspaces: ResolvedWorkspace[] = [];
   for (let index = 0; index < parsed.workspaces.length; index += 1) {
@@ -439,6 +428,7 @@ async function validateConfigObject(cwd: string, configPath: string, parsed: unk
         filenameTemplate: defaultFilenameTemplate,
         metadata: defaultMetadata,
       },
+      focusPresets: focusPresets.length > 0 ? focusPresets : undefined,
       workspaces: workspaces.filter((workspace) => workspace.kind === "workspace"),
     },
     workspaces,
@@ -476,6 +466,7 @@ function normalizeConfigForMigration(parsed: unknown): Record<string, unknown> {
   if (version !== 1) throw new Error("monofold config requires version: 1");
   const normalized: Record<string, unknown> = { version: 1 };
   if (parsed.defaults !== undefined) normalized.defaults = parsed.defaults;
+  if (parsed.focusPresets !== undefined) normalized.focusPresets = parsed.focusPresets;
   normalized.workspaces = parsed.workspaces;
   normalizeConfigCapabilities(normalized);
   return normalized;
@@ -1001,6 +992,21 @@ function inferBashCwd(ctx: ExtensionContext, command: string): string {
 }
 
 export default function piMultiWorkspace(pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      const loaded = await loadConfig(ctx.cwd);
+      ensureActiveFocusInitialized(loaded.raw.focusPresets);
+      const activeId = getActiveFocusPresetId();
+      if (!activeId) return;
+      const preset = findFocusPresetById(loaded.raw.focusPresets, activeId);
+      if (!preset) return;
+      if (!ctx.hasUI) return;
+      warnZeroTargetMatchesForPreset(preset, loaded.workspaces, (message) => ctx.ui.notify(message, "warning"));
+    } catch {
+      return;
+    }
+  });
+
   pi.on("before_agent_start", async (_event, ctx) => {
     try {
       const loaded = await loadConfig(ctx.cwd);
@@ -1612,4 +1618,4 @@ ${manifest}
     return undefined;
   });
 }
-
+

package/package.json

@@ -1,7 +1,8 @@
 {
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "check": "npm run typecheck && npm pack --dry-run"
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "check": "npm run typecheck && npm test && npm pack --dry-run"
   },
   "peerDependencies": {
     "typebox": "*",
@@ -10,7 +11,7 @@
   },
   "description": "Pi extension that folds multiple repositories and folders into a guarded virtual monorepo for AI agents.",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "pi": {
     "extensions": [
       "./index.ts"
@@ -19,13 +20,16 @@
   "files": [
     "README.md",
     "LICENSE",
-    "index.ts"
+    "index.ts",
+    "focus-preset.ts",
+    "validation.ts"
   ],
   "name": "pi-monofold",
   "devDependencies": {
     "typescript": "^6.0.3",
     "typebox": "^1.1.38",
     "@types/node": "^25.9.1",
+    "tsx": "^4.20.5",
     "@earendil-works/pi-coding-agent": "^0.75.4",
     "@earendil-works/pi-ai": "^0.75.4"
   },

package/validation.ts

@@ -0,0 +1,25 @@
+/** Returns true when a value is a plain object record, excluding arrays and null. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Throws when an object contains keys outside the supplied allow-list. */
+export function assertKnownKeys(label: string, value: Record<string, unknown>, allowed: Set<string>): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${label} has unknown key: ${key}`);
+  }
+}
+
+/** Coerces a required or optional unknown value to a string array with strict item validation. */
+export function asStringArray(label: string, value: unknown, required = true): string[] {
+  if (value === undefined && !required) return [];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return value;
+}
+
+/** Removes empty strings and duplicate entries while preserving first-seen order. */
+export function uniqueStrings(items: string[]): string[] {
+  return [...new Set(items.filter(Boolean))];
+}