gsd-pi 2.78.0 → 2.78.1-dev.84a383f51

package/dist/resources/skills/create-gsd-extension/workflows/create-extension.md

@@ -34,22 +34,19 @@ Identify what the extension needs from the user's description:
 
 ## Step 3: Choose Extension Structure
 
-**Single file** — for small extensions (1-2 tools/commands, simple hooks):
-```
-~/.pi/agent/extensions/my-extension.ts
-```
-
-**Directory with index.ts** — for multi-file extensions:
+**Directory with index.ts** — the standard pattern for all extensions:
 ```
 ~/.pi/agent/extensions/my-extension/
-├── index.ts
-├── tools.ts
-└── utils.ts
+├── extension-manifest.json   # Required — declares capabilities
+├── index.ts                  # Entry point (must export default function)
+├── tools.ts                  # Optional — tool implementations
+└── utils.ts                  # Optional — shared utilities
 ```
 
 **Package with dependencies** — when npm packages are needed:
 ```
 ~/.pi/agent/extensions/my-extension/
+├── extension-manifest.json
 ├── package.json
 ├── src/index.ts
 └── node_modules/
@@ -64,12 +61,34 @@ For packages, `package.json` needs:
 }
 ```
 
+## Step 3b: Create the Extension Manifest
+
+Every extension must include an `extension-manifest.json`:
+
+```json
+{
+  "id": "my-extension",
+  "name": "My Extension",
+  "version": "1.0.0",
+  "description": "What this extension does in one line",
+  "tier": "community",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": ["my_tool"],
+    "commands": ["mycommand"],
+    "hooks": ["session_start"]
+  }
+}
+```
+
+Only include non-empty arrays in `provides`. See `docs/extension-sdk/manifest-spec.md` for the full spec.
+
 ## Step 4: Write the Extension
 
 Start with the skeleton:
 
 ```typescript
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
 export default function (pi: ExtensionAPI) {
   // Register events, tools, commands here
@@ -81,7 +100,7 @@ Then add capabilities based on Step 2. Reference the appropriate reference files
 **Tool registration pattern:**
 ```typescript
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@mariozechner/pi-ai";
+import { StringEnum } from "@gsd/pi-ai";
 
 pi.registerTool({
   name: "my_tool",
@@ -144,7 +163,8 @@ Fix issues, add features, refine. Use `/reload` for hot-reload during developmen
 
 <success_criteria>
 Extension creation is complete when:
-- [ ] Extension file(s) written to correct location
+- [ ] Extension directory created with index.ts and extension-manifest.json
+- [ ] Manifest `provides` accurately lists all registered tools, commands, hooks, shortcuts
 - [ ] All imports resolve (TypeBox, pi-ai, pi-coding-agent, pi-tui as needed)
 - [ ] Tools use `StringEnum` for string enums (not `Type.Union`/`Type.Literal`)
 - [ ] Tool output is truncated if variable-length

package/dist/rtk-shared.d.ts

@@ -8,3 +8,6 @@ export declare function getRtkBinaryName(platform?: NodeJS.Platform): string;
 export declare function getPathValue(env: NodeJS.ProcessEnv): string | undefined;
 export declare function resolvePathCandidates(pathValue: string | undefined): string[];
 export declare function resolveSystemRtkPath(pathValue: string | undefined, platform?: NodeJS.Platform): string | null;
+export declare function prependPathEntry(env: NodeJS.ProcessEnv, entry: string): NodeJS.ProcessEnv;
+export declare function applyRtkProcessEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function buildRtkEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/rtk-shared.js

@@ -45,3 +45,20 @@ export function resolveSystemRtkPath(pathValue, platform = process.platform) {
     }
     return null;
 }
+export function prependPathEntry(env, entry) {
+    const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? (process.platform === "win32" ? "Path" : "PATH");
+    const currentPath = env[pathKey] ?? "";
+    const parts = currentPath.split(delimiter).filter(Boolean);
+    if (!parts.includes(entry)) {
+        env[pathKey] = [entry, currentPath].filter(Boolean).join(delimiter);
+    }
+    return env;
+}
+export function applyRtkProcessEnv(env = process.env) {
+    prependPathEntry(env, getManagedRtkDir(env));
+    env[RTK_TELEMETRY_DISABLED_ENV] = "1";
+    return env;
+}
+export function buildRtkEnv(env = process.env) {
+    return applyRtkProcessEnv({ ...env });
+}

package/dist/rtk.d.ts

@@ -1,8 +1,8 @@
 import { spawnSync } from "node:child_process";
-import { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, getManagedRtkDir, getRtkBinaryName, isRtkEnabled } from "./rtk-shared.js";
+import { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, applyRtkProcessEnv, buildRtkEnv, getManagedRtkDir, getRtkBinaryName, isRtkEnabled, prependPathEntry } from "./rtk-shared.js";
 export declare const RTK_VERSION = "0.33.1";
 export declare const GSD_SKIP_RTK_INSTALL_ENV = "GSD_SKIP_RTK_INSTALL";
-export { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, getManagedRtkDir, getRtkBinaryName, isRtkEnabled, };
+export { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, applyRtkProcessEnv, buildRtkEnv, getManagedRtkDir, getRtkBinaryName, isRtkEnabled, prependPathEntry, };
 export interface EnsureRtkOptions {
     targetDir?: string;
     allowDownload?: boolean;
@@ -20,9 +20,6 @@ export interface EnsureRtkResult {
     reason?: string;
 }
 export declare function getManagedRtkPath(platform?: NodeJS.Platform, targetDir?: string): string;
-export declare function prependPathEntry(env: NodeJS.ProcessEnv, entry: string): NodeJS.ProcessEnv;
-export declare function applyRtkProcessEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
-export declare function buildRtkEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function resolveRtkAssetName(platform: NodeJS.Platform, arch: string, version?: string): string | null;
 export interface ResolveRtkBinaryPathOptions {
     binaryPath?: string;

package/dist/rtk.js

@@ -3,36 +3,19 @@ import { spawnSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, chmodSync, readdirSync } from "node:fs";
 import { createWriteStream } from "node:fs";
 import { arch as osArch } from "node:os";
-import { delimiter, join } from "node:path";
+import { join } from "node:path";
 import { Readable } from "node:stream";
 import { finished } from "node:stream/promises";
 import extractZip from "extract-zip";
-import { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, getManagedRtkDir, getPathValue, getRtkBinaryName, isTruthy, isRtkEnabled, resolveSystemRtkPath, } from "./rtk-shared.js";
+import { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, applyRtkProcessEnv, buildRtkEnv, getManagedRtkDir, getPathValue, getRtkBinaryName, isTruthy, isRtkEnabled, prependPathEntry, resolveSystemRtkPath, } from "./rtk-shared.js";
 export const RTK_VERSION = "0.33.1";
 export const GSD_SKIP_RTK_INSTALL_ENV = "GSD_SKIP_RTK_INSTALL";
-export { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, getManagedRtkDir, getRtkBinaryName, isRtkEnabled, };
+export { GSD_RTK_DISABLED_ENV, GSD_RTK_PATH_ENV, RTK_TELEMETRY_DISABLED_ENV, applyRtkProcessEnv, buildRtkEnv, getManagedRtkDir, getRtkBinaryName, isRtkEnabled, prependPathEntry, };
 const RTK_REPO = "rtk-ai/rtk";
 const RTK_REWRITE_TIMEOUT_MS = 5_000;
 export function getManagedRtkPath(platform = process.platform, targetDir = getManagedRtkDir()) {
     return join(targetDir, getRtkBinaryName(platform));
 }
-export function prependPathEntry(env, entry) {
-    const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? (process.platform === "win32" ? "Path" : "PATH");
-    const currentPath = env[pathKey] ?? "";
-    const parts = currentPath.split(delimiter).filter(Boolean);
-    if (!parts.includes(entry)) {
-        env[pathKey] = [entry, currentPath].filter(Boolean).join(delimiter);
-    }
-    return env;
-}
-export function applyRtkProcessEnv(env = process.env) {
-    prependPathEntry(env, getManagedRtkDir(env));
-    env[RTK_TELEMETRY_DISABLED_ENV] = "1";
-    return env;
-}
-export function buildRtkEnv(env = process.env) {
-    return applyRtkProcessEnv({ ...env });
-}
 export function resolveRtkAssetName(platform, arch, version = RTK_VERSION) {
     void version;
     if (platform === "darwin" && arch === "arm64")

package/dist/runtime-checks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimum supported Node.js major version. Kept in sync with
+ * `engines.node` in package.json — see test
+ * `loader MIN_NODE_MAJOR matches package.json engines field`.
+ */
+export declare const MIN_NODE_MAJOR = 22;
+/**
+ * Parse a Node version string (e.g. "22.5.1") and return whether the major
+ * version meets the required minimum.
+ *
+ * Returns `{ ok: true }` when supported, or `{ ok: false, actualMajor }`
+ * when below the minimum. Throws if the version string is malformed —
+ * callers should treat that as a fatal precondition violation.
+ */
+export declare function checkNodeVersion(versionString: string, min?: number): {
+    ok: true;
+} | {
+    ok: false;
+    actualMajor: number;
+};
+/**
+ * Probe whether `git` is available by invoking the supplied exec function.
+ * Returns true on success, false if the exec throws (any reason). The
+ * function is injected so tests can substitute a stub without spawning a
+ * real subprocess.
+ */
+export declare function requireGit(execFn: (cmd: string, args: ReadonlyArray<string>) => unknown): boolean;

package/dist/runtime-checks.js

@@ -0,0 +1,38 @@
+// Runtime dependency checks — pure helpers used by loader.ts.
+// Extracted so they can be unit-tested without spawning the full loader.
+/**
+ * Minimum supported Node.js major version. Kept in sync with
+ * `engines.node` in package.json — see test
+ * `loader MIN_NODE_MAJOR matches package.json engines field`.
+ */
+export const MIN_NODE_MAJOR = 22;
+/**
+ * Parse a Node version string (e.g. "22.5.1") and return whether the major
+ * version meets the required minimum.
+ *
+ * Returns `{ ok: true }` when supported, or `{ ok: false, actualMajor }`
+ * when below the minimum. Throws if the version string is malformed —
+ * callers should treat that as a fatal precondition violation.
+ */
+export function checkNodeVersion(versionString, min = MIN_NODE_MAJOR) {
+    const major = parseInt(versionString.split('.')[0], 10);
+    if (!Number.isFinite(major)) {
+        throw new Error(`checkNodeVersion: cannot parse major from "${versionString}"`);
+    }
+    return major < min ? { ok: false, actualMajor: major } : { ok: true };
+}
+/**
+ * Probe whether `git` is available by invoking the supplied exec function.
+ * Returns true on success, false if the exec throws (any reason). The
+ * function is injected so tests can substitute a stub without spawning a
+ * real subprocess.
+ */
+export function requireGit(execFn) {
+    try {
+        execFn('git', ['--version']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}