march-cli 0.1.0

package/src/extensions/discovery.mjs

@@ -0,0 +1,40 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const EXTENSION_FILE_NAMES = new Set(["index.js", "index.ts", "index.mjs", "index.cjs"]);
+const EXTENSION_FILE_EXTENSIONS = new Set([".js", ".ts", ".mjs", ".cjs"]);
+
+export function discoverProjectExtensionPaths(cwd) {
+  const extensionsDir = resolve(cwd, ".march", "extensions");
+  if (!existsSync(extensionsDir)) return [];
+
+  const entries = readdirSync(extensionsDir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const paths = [];
+
+  for (const entry of entries) {
+    const entryPath = join(extensionsDir, entry.name);
+    if (entry.isFile() && hasExtensionFileExtension(entry.name)) {
+      paths.push(entryPath);
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+
+    const indexPath = findExtensionIndex(entryPath);
+    if (indexPath) paths.push(indexPath);
+  }
+
+  return paths;
+}
+
+function findExtensionIndex(dir) {
+  for (const fileName of EXTENSION_FILE_NAMES) {
+    const filePath = join(dir, fileName);
+    if (existsSync(filePath)) return filePath;
+  }
+  return null;
+}
+
+function hasExtensionFileExtension(fileName) {
+  return EXTENSION_FILE_EXTENSIONS.has(fileName.slice(fileName.lastIndexOf(".")));
+}

package/src/extensions/lifecycle-adapter.mjs

@@ -0,0 +1,210 @@
+export const MARCH_LIFECYCLE_LAYERS = Object.freeze([
+  {
+    name: "pi-agent-turn",
+    owner: "pi runtime host",
+    effects: Object.freeze(["read-runtime-diagnostics"]),
+  },
+  {
+    name: "march-agent-runtime",
+    owner: "March runner",
+    effects: Object.freeze(["read-session-ref", "read-sidecar-metadata", "read-runtime-state"]),
+  },
+  {
+    name: "march-collaboration",
+    owner: "March orchestrator",
+    effects: Object.freeze(["read-group-ref", "read-workspace-ref", "read-diff-metadata"]),
+  },
+]);
+
+export const DEFAULT_MARCH_HOOK_POLICY = Object.freeze({
+  mode: "read-only",
+  defaultBlocking: false,
+  allowedEffects: Object.freeze([
+    "read-group-ref",
+    "read-agent-ref",
+    "read-workspace-ref",
+    "read-session-ref",
+    "read-sidecar-metadata",
+    "read-diff-metadata",
+    "read-runtime-diagnostics",
+    "write-diagnostics",
+  ]),
+  deniedEffects: Object.freeze([
+    "write-files",
+    "run-shell",
+    "switch-session",
+    "commit-worktree",
+    "read-private-agent-context",
+  ]),
+});
+
+export function createMarchLifecycleAdapter({
+  cwd,
+  projectMarchDir,
+  extensionPaths = [],
+  sessionBinding,
+  engine,
+  getSessionStats,
+  getRuntimeDiagnostics = () => [],
+  manifestHooks = [],
+  manifestDiagnostics = [],
+}) {
+  const hooks = new Map();
+  const adapterDiagnostics = [...manifestDiagnostics];
+
+  for (const manifestHook of manifestHooks) {
+    try {
+      registerManifestHook(hooks, manifestHook);
+    } catch (err) {
+      adapterDiagnostics.push({
+        type: "warning",
+        message: `Failed to register March lifecycle hook ${manifestHook?.id ?? "(unknown)"}: ${err.message}`,
+        path: manifestHook?.sourcePath,
+      });
+    }
+  }
+
+  return {
+    registerHook(hook) {
+      const normalized = normalizeHook(hook);
+      const deniedEffect = normalized.effects
+        .map((effect) => evaluateMarchHookEffect(effect))
+        .find((result) => !result.allowed);
+      if (deniedEffect) {
+        throw new Error(deniedEffect.reason);
+      }
+      hooks.set(normalized.id, normalized);
+      return normalized;
+    },
+
+    unregisterHook(id) {
+      return hooks.delete(id);
+    },
+
+    async runHook(kind, payload = {}) {
+      const matchingHooks = [...hooks.values()].filter((hook) => hook.kind === kind);
+      const results = [];
+      for (const hook of matchingHooks) {
+        const result = await runRegisteredHook(hook, {
+          facts: buildFacts({ cwd, projectMarchDir, engine, getSessionStats }),
+          payload,
+          canExecute: evaluateMarchHookEffect,
+        }, adapterDiagnostics);
+        results.push(result);
+      }
+      return results;
+    },
+
+    getState() {
+      return {
+        status: "read-only",
+        registeredHookCount: hooks.size,
+        extensionPathCount: extensionPaths.length,
+        hookKinds: [...new Set([...hooks.values()].map((hook) => hook.kind))].sort(),
+        facts: buildFacts({ cwd, projectMarchDir, engine, getSessionStats }),
+        layers: MARCH_LIFECYCLE_LAYERS,
+        policy: DEFAULT_MARCH_HOOK_POLICY,
+        diagnostics: [
+          {
+            type: "info",
+            message: hooks.size === 0
+              ? "March lifecycle hook adapter is read-only; no March hooks are registered."
+              : "March lifecycle hook adapter is read-only; registered hooks are permission-gated.",
+          },
+          ...adapterDiagnostics,
+          ...getRuntimeDiagnostics(),
+        ],
+      };
+    },
+
+    canExecute(effect) {
+      return evaluateMarchHookEffect(effect);
+    },
+
+    getActiveSession() {
+      return sessionBinding?.get?.() ?? null;
+    },
+  };
+}
+
+function registerManifestHook(hooks, manifestHook) {
+  const normalized = normalizeHook({
+    ...manifestHook,
+    handler: () => ({
+      sourcePath: manifestHook.sourcePath,
+      description: manifestHook.description,
+    }),
+  });
+  const deniedEffect = normalized.effects
+    .map((effect) => evaluateMarchHookEffect(effect))
+    .find((result) => !result.allowed);
+  if (deniedEffect) throw new Error(deniedEffect.reason);
+  hooks.set(normalized.id, normalized);
+  return normalized;
+}
+
+export function evaluateMarchHookEffect(effect) {
+  if (DEFAULT_MARCH_HOOK_POLICY.allowedEffects.includes(effect)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    reason: DEFAULT_MARCH_HOOK_POLICY.deniedEffects.includes(effect)
+      ? `March lifecycle hooks cannot ${effect} in read-only mode`
+      : `Unknown March lifecycle hook effect: ${effect}`,
+  };
+}
+
+function buildFacts({ cwd, projectMarchDir, engine, getSessionStats }) {
+  const stats = getSessionStats?.();
+  return {
+    cwd,
+    projectMarchDir,
+    sessionId: stats?.sessionId ?? null,
+    sessionFile: stats?.sessionFile ?? null,
+    persisted: Boolean(stats?.persisted),
+    runtimeHost: Boolean(stats?.runtimeHost),
+    modelId: engine?.modelId ?? null,
+    provider: engine?.provider ?? null,
+    thinkingLevel: engine?.thinkingLevel ?? null,
+    namespace: engine?.namespace ?? null,
+    turnCount: engine?.turns?.length ?? 0,
+  };
+}
+
+function normalizeHook(hook) {
+  if (!hook || typeof hook !== "object") throw new Error("March lifecycle hook must be an object");
+  if (!hook.id || typeof hook.id !== "string") throw new Error("March lifecycle hook requires a string id");
+  if (!hook.kind || typeof hook.kind !== "string") throw new Error("March lifecycle hook requires a string kind");
+  if (typeof hook.handler !== "function") throw new Error("March lifecycle hook requires a handler function");
+  return {
+    id: hook.id,
+    kind: hook.kind,
+    effects: [...new Set(hook.effects ?? [])].sort(),
+    blocking: Boolean(hook.blocking ?? DEFAULT_MARCH_HOOK_POLICY.defaultBlocking),
+    handler: hook.handler,
+  };
+}
+
+async function runRegisteredHook(hook, context, diagnostics) {
+  try {
+    for (const effect of hook.effects) {
+      const gate = evaluateMarchHookEffect(effect);
+      if (!gate.allowed) throw new Error(gate.reason);
+    }
+    const value = await hook.handler(Object.freeze({
+      facts: Object.freeze({ ...context.facts }),
+      payload: Object.freeze({ ...context.payload }),
+      canExecute: context.canExecute,
+    }));
+    return { id: hook.id, kind: hook.kind, ok: true, value };
+  } catch (err) {
+    const diagnostic = {
+      type: hook.blocking ? "error" : "warning",
+      message: `March lifecycle hook ${hook.id} failed: ${err.message}`,
+    };
+    diagnostics.push(diagnostic);
+    if (hook.blocking) throw err;
+    return { id: hook.id, kind: hook.kind, ok: false, error: err.message };
+  }
+}

package/src/extensions/lifecycle-manifest.mjs

@@ -0,0 +1,69 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export function discoverProjectLifecycleHookManifestPaths(cwd) {
+  const extensionsDir = resolve(cwd, ".march", "extensions");
+  if (!existsSync(extensionsDir)) return [];
+
+  const entries = readdirSync(extensionsDir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const paths = [];
+  for (const entry of entries) {
+    const entryPath = join(extensionsDir, entry.name);
+    if (entry.isFile() && entry.name.endsWith(".march-hooks.json")) {
+      paths.push(entryPath);
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const manifestPath = join(entryPath, "march-hooks.json");
+      if (existsSync(manifestPath)) paths.push(manifestPath);
+    }
+  }
+  return paths;
+}
+
+export function loadProjectLifecycleHookManifests(cwd) {
+  return loadLifecycleHookManifests(discoverProjectLifecycleHookManifestPaths(cwd));
+}
+
+export function loadLifecycleHookManifests(paths) {
+  const hooks = [];
+  const diagnostics = [];
+  for (const path of paths) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      for (const hook of normalizeManifestHooks(parsed, path)) hooks.push(hook);
+    } catch (err) {
+      diagnostics.push({
+        type: "warning",
+        message: `Failed to load March lifecycle hook manifest: ${err.message}`,
+        path,
+      });
+    }
+  }
+  return { hooks, diagnostics };
+}
+
+function normalizeManifestHooks(parsed, path) {
+  const rawHooks = Array.isArray(parsed) ? parsed : parsed?.hooks;
+  if (!Array.isArray(rawHooks)) throw new Error("manifest must be an array or an object with hooks[]");
+  return rawHooks.map((hook, index) => normalizeManifestHook(hook, path, index));
+}
+
+function normalizeManifestHook(hook, path, index) {
+  if (!hook || typeof hook !== "object") throw new Error(`hook ${index + 1} must be an object`);
+  if (!hook.id || typeof hook.id !== "string") throw new Error(`hook ${index + 1} requires string id`);
+  if (!hook.kind || typeof hook.kind !== "string") throw new Error(`hook ${index + 1} requires string kind`);
+  const effects = Array.isArray(hook.effects) ? hook.effects : [];
+  if (!effects.every((effect) => typeof effect === "string")) {
+    throw new Error(`hook ${hook.id} effects must be strings`);
+  }
+  return {
+    id: hook.id,
+    kind: hook.kind,
+    effects,
+    blocking: Boolean(hook.blocking),
+    description: typeof hook.description === "string" ? hook.description : "",
+    sourcePath: path,
+  };
+}

package/src/image-gen/index.mjs

@@ -0,0 +1,7 @@
+import { createImageGenTool } from "./tool.mjs";
+
+export function initImageGen({ authStorage, projectMarchDir }) {
+  const credentials = authStorage?.get?.("openai-codex");
+  if (!credentials) return [];
+  return [createImageGenTool({ authStorage, projectMarchDir })];
+}

package/src/image-gen/provider.mjs

@@ -0,0 +1,231 @@
+import { getOAuthProvider } from "@earendil-works/pi-ai/oauth";
+import { saveGeneratedImageAttachment } from "../session/attachments.mjs";
+
+const CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex/responses";
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+
+const ASPECT_RATIO_MAP = {
+  "1:1": "1024x1024",
+  "16:9": "1792x1024",
+  "4:3": "1024x768",
+  "3:2": "1536x1024",
+};
+
+function extractAccountId(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) throw new Error("Invalid token");
+    const payload = JSON.parse(atob(parts[1]));
+    const accountId = payload?.[JWT_CLAIM_PATH]?.chatgpt_account_id;
+    if (!accountId) throw new Error("No account ID in token");
+    return accountId;
+  } catch {
+    throw new Error("Failed to extract account ID from token");
+  }
+}
+
+function buildHeaders(token, accountId) {
+  return {
+    Authorization: `Bearer ${token}`,
+    "chatgpt-account-id": accountId,
+    originator: "march",
+    "User-Agent": "march-cli",
+    "OpenAI-Beta": "responses=experimental",
+    accept: "text/event-stream",
+    "content-type": "application/json",
+  };
+}
+
+function buildRequestBody(prompt, quality, size) {
+  return {
+    model: "gpt-5.4",
+    instructions: "You are an assistant that must fulfill image generation requests by using the image_generation tool when provided.",
+    input: [{ type: "message", role: "user", content: [{ type: "input_text", text: prompt }] }],
+    stream: true,
+    store: false,
+    tools: [
+      {
+        type: "image_generation",
+        model: "gpt-image-2",
+        size,
+        quality: quality || "medium",
+        output_format: "png",
+        background: "opaque",
+        partial_images: 1,
+      },
+    ],
+    tool_choice: {
+      type: "allowed_tools",
+      mode: "required",
+      tools: [{ type: "image_generation" }],
+    },
+  };
+}
+
+async function* parseSSE(response) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n\n")) !== -1) {
+        const chunk = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        const dataLines = chunk
+          .split("\n")
+          .filter((l) => l.startsWith("data:"))
+          .map((l) => l.slice(5).trim());
+        if (dataLines.length > 0) {
+          const data = dataLines.join("\n").trim();
+          if (data && data !== "[DONE]") {
+            yield JSON.parse(data);
+          }
+        }
+      }
+    }
+  } finally {
+    try {
+      reader.cancel();
+    } catch {}
+  }
+}
+
+export async function generateImage({
+  prompt,
+  quality = "medium",
+  aspectRatio = "1:1",
+  authStorage,
+  projectMarchDir,
+  fetchImpl = fetch,
+  oauthProvider = getOAuthProvider("openai-codex"),
+  now = new Date(),
+  id,
+} = {}) {
+  if (!projectMarchDir) throw new Error("projectMarchDir is required for image generation");
+  const credentials = authStorage?.get?.("openai-codex");
+  if (!credentials) throw new Error("OpenAI Codex not authenticated. Run: march login openai-codex");
+
+  const provider = oauthProvider;
+  if (!provider) throw new Error("OpenAI Codex OAuth provider is not available");
+  let apiKey = provider.getApiKey(credentials);
+
+  if (Date.now() >= credentials.expires) {
+    const refreshed = await provider.refreshToken(credentials);
+    apiKey = provider.getApiKey(refreshed);
+    authStorage.set("openai-codex", refreshed);
+  }
+
+  const accountId = extractAccountId(apiKey);
+  const size = ASPECT_RATIO_MAP[aspectRatio] || "1024x1024";
+
+  const response = await fetchImpl(CODEX_BASE_URL, {
+    method: "POST",
+    headers: buildHeaders(apiKey, accountId),
+    body: JSON.stringify(buildRequestBody(prompt, quality, size)),
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Codex image generation failed (${response.status}): ${text || response.statusText}`);
+  }
+
+  let imageBase64 = null;
+  let mimeType = "image/png";
+
+  for await (const event of parseSSE(response)) {
+    const type = event.type;
+
+    if (type === "response.image_generation_call.partial_image" && event.partial_image_b64) {
+      imageBase64 = event.partial_image_b64;
+      mimeType = "image/png";
+      continue;
+    }
+
+    if (type === "response.output_item.added") {
+      continue;
+    }
+
+    if (type === "response.output_item.done") {
+      const item = event.item;
+      if (!item) continue;
+
+      if (item.type === "image_generation_call" && item.result) {
+        imageBase64 = item.result;
+        mimeType = "image/png";
+        continue;
+      }
+
+      if (item.type === "file" && item.filename?.endsWith?.(".png")) {
+        const content = item.content?.[0];
+        if (content?.type === "image_file" && content.image_base64) {
+          imageBase64 = content.image_base64;
+          mimeType = "image/png";
+        }
+      }
+
+      for (const part of item.content || []) {
+        if (part.type === "image_file" && part.image_base64) {
+          imageBase64 = part.image_base64;
+          mimeType = "image/png";
+        }
+        if (part.type === "output_text" && isBase64(part.text)) {
+          imageBase64 = part.text;
+        }
+      }
+
+      if (item.base64) imageBase64 = item.base64;
+      continue;
+    }
+
+    if (type === "response.completed" || type === "response.incomplete") {
+      const resp = event.response;
+      if (resp?.output) {
+        for (const item of resp.output) {
+          if (item.type === "image_generation_call" && item.result) {
+            imageBase64 = item.result;
+            mimeType = "image/png";
+          }
+          for (const part of item.content || []) {
+            if (part.type === "image_file" && part.image_base64) {
+              imageBase64 = part.image_base64;
+              mimeType = "image/png";
+            }
+          }
+        }
+      }
+      break;
+    }
+
+    if (type === "error") {
+      throw new Error(`Codex error: ${event.message || JSON.stringify(event)}`);
+    }
+
+    if (type === "response.failed") {
+      const msg = event.response?.error?.message || "Image generation failed";
+      throw new Error(msg);
+    }
+  }
+
+  if (!imageBase64) {
+    throw new Error("No image data received from Codex");
+  }
+
+  const saved = saveGeneratedImageAttachment({
+    projectMarchDir,
+    data: imageBase64,
+    mimeType,
+    now,
+    id,
+  });
+
+  return { filePath: saved.path, marker: saved.marker, mimeType, metadataPath: saved.metadataPath };
+}
+
+function isBase64(str) {
+  if (typeof str !== "string" || str.length < 100) return false;
+  return /^[A-Za-z0-9+/]*={0,2}$/.test(str);
+}

package/src/image-gen/tool.mjs

@@ -0,0 +1,84 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../agent/tool-result.mjs";
+import { openFileWithDefaultApp } from "../platform/open-file.mjs";
+import { generateImage } from "./provider.mjs";
+
+export function createImageGenTool({
+  authStorage,
+  projectMarchDir,
+  generateImageImpl = generateImage,
+  openFileImpl = openFileWithDefaultApp,
+}) {
+  return defineTool({
+    name: "image_generate",
+    label: "Image Generation",
+    description:
+      "Generate an image using ChatGPT's image generation engine (gpt-image-2). " +
+      "Three quality levels: low (~15s, drafts), medium (~40s, default), high (~2min, highest detail). " +
+      "Supported aspect ratios: 1:1, 16:9, 4:3, 3:2. Default: 1:1.",
+    promptSnippet: "image_generate(prompt, quality?, aspectRatio?, auto_open?) - Generate an image using ChatGPT",
+    promptGuidelines: [
+      "When the user asks you to generate or draw an image, use the image_generate tool.",
+      "Describe what you want to generate in detail for best results.",
+    ],
+    parameters: Type.Object({
+      prompt: Type.String({
+        description: "Detailed description of the image to generate",
+      }),
+      quality: Type.Optional(
+        Type.String({
+          enum: ["low", "medium", "high"],
+          description: "Generation quality. medium is default.",
+        })
+      ),
+      aspectRatio: Type.Optional(
+        Type.String({
+          enum: ["1:1", "16:9", "4:3", "3:2"],
+          description: "Aspect ratio. 1:1 is default.",
+        })
+      ),
+      auto_open: Type.Optional(
+        Type.Boolean({
+          description: "Open the generated image with the system default app. true is default.",
+        })
+      ),
+    }),
+    execute: async (_toolCallId, params) => {
+      try {
+        const { prompt, quality = "medium", aspectRatio = "1:1", auto_open: autoOpen = true } = params;
+        const image = await generateImageImpl({ prompt, quality, aspectRatio, authStorage, projectMarchDir });
+        const openResult = autoOpen ? await openGeneratedImage(image.filePath, openFileImpl) : { opened: false };
+        return toolJson({
+          success: true,
+          image: image.marker,
+          path: image.filePath,
+          mimeType: image.mimeType,
+          prompt,
+          aspectRatio,
+          quality,
+          ...openResult,
+        }, { ...image, ...openResult });
+      } catch (err) {
+        return toolJson({
+          success: false,
+          image: null,
+          error: err.message,
+        }, { error: true });
+      }
+    },
+  });
+}
+
+async function openGeneratedImage(filePath, openFileImpl) {
+  try {
+    await openFileImpl(filePath);
+    return { opened: true };
+  } catch (err) {
+    return { opened: false, openError: err.message };
+  }
+}
+
+function toolJson(payload, details = {}) {
+  return toolText(JSON.stringify(payload, null, 2), details);
+}