pi-monofold 0.2.0 → 0.3.1

package/README.md

@@ -1,18 +1,31 @@
-# Pi Monofold
+# pi-monofold
 
+[![CI](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pi-monofold?color=cb3837&logo=npm)](https://www.npmjs.com/package/pi-monofold)
-[![Publish to npm](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
-[![Auto Release](https://github.com/eiei114/pi-monofold/actions/workflows/auto-release.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/auto-release.yml)
+[![npm downloads](https://img.shields.io/npm/dw/pi-monofold)](https://www.npmjs.com/package/pi-monofold)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Pi Package](https://img.shields.io/badge/Pi-package-6f42c1)](https://github.com/eiei114/pi-monofold)
+[![Trusted Publishing](https://img.shields.io/badge/npm-provenance-yellow)](https://docs.npmjs.com/generating-provenance-statements)
 
-Pi Monofold (`pi-monofold`) is a Pi Coding Agent extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
+Pi extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
 
-It keeps repositories physically separate, while giving Pi a lightweight manifest, routed writes, workspace-aware reads, guarded commands, and explicit git flows.
+## What this is
 
-## Why
+Pi Monofold (`pi-monofold`) keeps repositories physically separate while giving Pi a lightweight manifest, routed writes, workspace-aware reads, guarded commands, and explicit git flows. Documentation, rules, product context, and implementation code can appear as one connected system without migrating everything into a single git repository.
 
-AI coding agents work best when documentation, rules, product context, and implementation code are visible as one connected system. Physical monorepos are not always practical. Pi Monofold gives Pi a logical monorepo boundary without forcing repository migration.
+See [docs/usage.md](./docs/usage.md) for configuration, commands, agent tools, and guard behavior.
+
+## Features
+
+- **Virtual monorepo manifest** — declare workspaces and project workspaces in `.pi/monofold.yaml`
+- **Routed Markdown writes** — route PRDs, progress notes, and other doc types to configured folders
+- **Workspace-aware reads** — list, read, search, and tree views scoped to readable workspaces
+- **Capability guard** — block or confirm `read` / `write` / `edit` / `grep` / `find` / `bash` based on workspace tags
+- **Focus presets** — tag-based focus targets for the control workspace
+- **Natural-language commands** — `/monofold:explore`, `/monofold:write`, `/monofold:config`, `/monofold:git`, and more
+- **Strict agent tools** — `monofold_*` tools for programmatic access behind the command surface
+- **Config migration** — upgrade legacy `.pi/monofold.yml` with backups and validation
 
 ## Install
 
@@ -26,16 +39,16 @@ Pi Monofold is a Pi package. Install it with Pi's package installer from git or
 pi install git:github.com/eiei114/pi-monofold
 ```
 
-Install into the current project settings instead of user settings:
+Project-local install:
 
 ```powershell
 pi install -l git:github.com/eiei114/pi-monofold
 ```
 
-Pin a version/ref:
+Pin a version:
 
 ```powershell
-pi install git:github.com/eiei114/pi-monofold@v0.1.0
+pi install git:github.com/eiei114/pi-monofold@v0.3.1
 ```
 
 Try without installing:
@@ -46,13 +59,11 @@ pi -e git:github.com/eiei114/pi-monofold
 
 ### From npm
 
-After the package is published to npm:
-
 ```powershell
 pi install npm:pi-monofold
 ```
 
-Install into the current project settings instead of user settings:
+Project-local install:
 
 ```powershell
 pi install -l npm:pi-monofold
@@ -61,7 +72,7 @@ pi install -l npm:pi-monofold
 Pin a version:
 
 ```powershell
-pi install npm:pi-monofold@0.1.0
+pi install npm:pi-monofold@0.3.1
 ```
 
 Try without installing:
@@ -70,123 +81,92 @@ Try without installing:
 pi -e npm:pi-monofold
 ```
 
-### Local development
+## Quick start
 
-```powershell
-git clone https://github.com/eiei114/pi-monofold.git
-cd pi-monofold
-npm install
-npm run typecheck
-```
+1. Install the extension (see [Install](#install)).
+2. In your control repository, create `.pi/monofold.yaml` with at least one workspace entry (or run `/monofold:init`).
+3. Start Pi in the control repository and run `/monofold:explore show the project workspaces`.
+4. Use `/monofold:write` for routed Markdown outputs and `/monofold:git` for guarded git workflows.
 
-Try the local checkout without installing:
+Example command flows: [docs/examples.md](./docs/examples.md).
 
-```powershell
-pi -e .
-```
+## Usage summary
 
-## Config
+| Surface | Purpose |
+|---------|---------|
+| `/monofold:explore` | List, read, search, or inspect workspace trees |
+| `/monofold:write` | Create routed Markdown outputs |
+| `/monofold:config` | Add or change workspaces and project workspaces |
+| `/monofold:git` | Run guarded git status, commit, push, or commit+push |
+| `/monofold:guide` | Interactive guide for common flows |
+| `/monofold:init` | Create or update `.pi/monofold.yaml` |
+| `/monofold:update` | Migrate legacy config and optionally request config edits |
 
-Place config in the control repository:
+Agent tools (`monofold_list`, `monofold_read`, `monofold_write`, `monofold_git`, `monofold_init`) sit behind these commands. Full reference: [docs/usage.md](./docs/usage.md).
 
-```text
-<control-repo>/.pi/monofold.yaml
-```
+## Package contents
 
-Example:
-
-```yaml
-version: 1
-
-defaults:
-  filenameTemplate: "{{date}}-{{slug}}.md"
-  metadata:
-    created: "{{date}}"
-    source: "pi-monofold"
-
-workspaces:
-  - name: "Product docs"
-    path: "../business"
-    tags: [business, markdown, planning]
-    capabilities: [read, writeDocs, git]
-    contextFiles: [README.md, CONTEXT.md]
-    routes:
-      default: "Notes"
-      prd:
-        path: "Docs/PRD"
-        filenameTemplate: "prd-{{slug}}.md"
-        metadata:
-          type: prd
-    projects:
-      - name: "Launch plan"
-        path: "Projects/Launch"
-        tags: [project, launch]
-        contextFiles: [CONTEXT.md]
-        routes:
-          default: "."
-          progress: "Progress"
-
-  - name: "Application"
-    path: "../app"
-    tags: [development, app]
-    capabilities: [read, editCode, runCommands, git]
-    contextFiles: [README.md, AGENTS.md]
+```text
+pi-monofold/
+├── .github/workflows/
+│   ├── auto-release.yml            # Auto-tag + release on merge to main
+│   ├── ci.yml                      # Validate on PR / push
+│   └── publish.yml                 # Publish to npm (Trusted Publishing)
+├── docs/
+│   ├── usage.md                    # Config, commands, agent API, guard
+│   ├── examples.md                 # Command examples
+│   └── release.md                  # Release and publish flow
+├── tests/
+│   └── focus-preset.test.ts
+├── CHANGELOG.md
+├── SECURITY.md
+├── focus-preset.ts
+├── index.ts
+├── LICENSE
+├── package.json
+├── README.md
+├── validation.ts
+└── tsconfig.json
 ```
 
-## Commands
-
-Human-facing commands accept natural-language arguments and hand off interpretation to the Pi agent:
+## Development
 
-- `/monofold:explore [request]`: list, read, search, or inspect workspace trees.
-- `/monofold:write [request]`: create routed Markdown outputs.
-- `/monofold:config [request]`: add or change Workspaces and Project Workspaces.
-- `/monofold:git [request]`: run git status, commit, push, or commit+push workflows.
-- `/monofold:guide`: start an interactive guide for Explore, Write, Config, Git, init, and update flows.
-- `/monofold:init`: create or update `.pi/monofold.yaml` with an interactive wizard.
-- `/monofold:update [request]`: migrate/clean up legacy config and optionally hand a config-change request to the agent.
+Clone and validate:
 
-Examples:
-
-```text
-/monofold:explore show the project workspaces
-/monofold:write write today's progress note for Pi Monofold
-/monofold:config add 4_Project/NewApp as a Project Workspace under Obsidian Vault with tag project,newapp
-/monofold:git commit and push the pi-monofold dev workspace
-/monofold:guide
+```powershell
+git clone https://github.com/eiei114/pi-monofold.git
+cd pi-monofold
+npm install
+npm run check
 ```
 
-Fine-grained legacy commands such as `/monofold:list`, `/monofold:read`, `/monofold:search`, `/monofold:tree`, `/monofold:add`, `/monofold:project-add`, and underscore aliases are not part of the human command surface.
-
-## Agent API
+Try the local checkout without installing:
 
-Pi agents use strict `monofold_*` tools behind the natural-language command surface:
+```powershell
+pi -e .
+```
 
-- `monofold_list`: show manifest and git status summary.
-- `monofold_read`: read files, search text, or show a tree inside readable workspaces.
-- `monofold_write`: create routed Markdown outputs by `routeType`, `title`, and `body`.
-- `monofold_git`: run guarded workspace git `status`, `commit`, `push`, or `commitPush`.
-- `monofold_init`: queue `/monofold:init`.
+## Release
 
-Project Workspaces are listed under `workspaces[].projects`. Their `path` is relative to the parent workspace, `tags` are combined with parent tags, `capabilities` inherit unless explicitly replaced, and missing routes default to `default: "."` when the effective target has `writeDocs`.
+Releases are automated. See [docs/release.md](./docs/release.md) for details.
 
-## Updating configuration
+1. Bump `version` in `package.json` and update `CHANGELOG.md`.
+2. Merge to `main`.
+3. **Auto Release** tags `v<version>` and creates a GitHub release when the tag is new.
+4. The tag triggers **Publish**, which publishes to npm with OIDC provenance.
 
-`.pi/monofold.yaml` is the canonical config file. Legacy `.pi/monofold.yml` is still readable. Intent commands try to migrate a legacy-only config automatically, show a notice, and continue with the legacy config if migration fails. `/monofold:update` migrates or cleans up legacy config, writes timestamped backups such as `.pi/monofold.yml.bak-20260524-153012`, and removes the legacy file after a successful write. If both `.yaml` and `.yml` exist, normal intent commands prefer canonical `.yaml`; `/monofold:update` handles legacy cleanup.
+## Security
 
-`/monofold:update` is a configuration migration command, not a Pi package updater. Use `pi update`, `pi update --extensions`, or `pi install ...@new-ref` for package updates.
+Pi Monofold intercepts standard Pi tool calls when monofold config is present. Writes and shell commands are allowed only when the resolved workspace grants the matching capability. Git commit/push via raw `bash` is blocked; use `/monofold:git` or `monofold_git` instead.
 
-After migration, you can provide a natural-language configuration change request. The command hands that request to the Pi agent, which edits `.pi/monofold.yaml` directly and validates the result through the manifest path:
+Report vulnerabilities per [SECURITY.md](./SECURITY.md).
 
-```text
-/monofold:update add 4_Project/NewApp as a Project Workspace under Obsidian Vault with tags project,newapp and progress route Progress
-```
+## Links
 
-## Guard
+- **Repository**: <https://github.com/eiei114/pi-monofold>
+- **npm**: <https://www.npmjs.com/package/pi-monofold>
+- **Issues**: <https://github.com/eiei114/pi-monofold/issues>
 
-When `.pi/monofold.yaml` or legacy `.pi/monofold.yml` exists, Pi Monofold guards standard `read/write/edit/grep/find/bash` calls against workspace capabilities.
+## License
 
-- Unknown path: confirm in UI, block without UI.
-- Docs write: requires `writeDocs`.
-- Code edit: requires `editCode`.
-- Bash: requires workspace cwd and `runCommands`.
-- Git commit/push via bash: blocked; use `/monofold:git` or the `monofold_git` agent tool.
+[MIT](LICENSE)

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.1",
   "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))];
+}