@entelligentsia/forgecli 1.0.25 → 1.0.36

package/dist/extensions/forgecli/store-repair.js

@@ -0,0 +1,123 @@
+// forge:store-repair — native kickoff handler (FORGE-S23-T11).
+//
+// Replaces the auto-generated stub previously installed by
+// registerAllForgeCommands (forge-commands.ts). Kickoff Shim archetype
+// (Pack-04 + Pack-06): single LLM handoff in current context, no fork.
+//
+// --dry-run flag is forwarded in the kickoff body so the LLM calls
+// validate-store --dry-run and skips write phases accordingly.
+//
+// Workflow source: <forgeRoot>/commands/store-repair.md (command file).
+// File-existence check only — command files lack Pack-06 workflow markers.
+//
+// Iron Laws:
+//   IL1 — code only under forge-cli/src/extensions/forgecli/.
+//   IL4 — no JSON.stringify-into-subagent dispatch.
+//   IL6 — no shell-string interpolation; no spawn calls here.
+//   IL7 — every failure path emits ctx.ui.notify and returns; no silent
+//         continuation.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { sendKickoff } from "./kickoff.js";
+export function parseStoreRepairArgs(rawArgs, cwd) {
+    const trimmed = (rawArgs ?? "").trim();
+    const result = {
+        dryRun: false,
+        seed: "",
+        sourceLabel: "",
+    };
+    if (!trimmed) {
+        result.sourceLabel = "(no args — full repair run)";
+        return result;
+    }
+    const tokens = trimmed.split(/\s+/);
+    const remaining = [];
+    for (const tok of tokens) {
+        if (tok === "--dry-run") {
+            result.dryRun = true;
+        }
+        else {
+            remaining.push(tok);
+        }
+    }
+    const tail = remaining.join(" ").trim();
+    if (tail.startsWith("@")) {
+        const ref = tail.slice(1).trim();
+        const filePath = path.isAbsolute(ref) ? ref : path.resolve(cwd, ref);
+        result.seed = fs.readFileSync(filePath, "utf8");
+        result.sourceLabel = `(seed from file: ${ref})`;
+    }
+    else if (tail) {
+        result.seed = tail;
+        result.sourceLabel = "(seed from inline text)";
+    }
+    else {
+        result.sourceLabel = result.dryRun ? "(--dry-run mode)" : "(no args — full repair run)";
+    }
+    return result;
+}
+export function composeStoreRepairKickoff(opts) {
+    const { commandMd, parsed } = opts;
+    const sections = ["# /forge:repair", ""];
+    sections.push("## Dispatch", "");
+    sections.push("Diagnose and repair the Forge JSON store. Run the repair workflow below. Specifically:");
+    sections.push("");
+    if (parsed.dryRun) {
+        sections.push("**`--dry-run` mode.** Preview all repairs without writing anything. " +
+            "In Phase 2 (LLM repair) and Phase 3 (final validation), show what would change but skip all writes. " +
+            "Skip Phase 4 verification (nothing changed).");
+    }
+    else {
+        sections.push("Full repair mode: diagnose, propose fixes, apply approved repairs, verify.");
+    }
+    sections.push("", "Use `forge_store` for all store reads and writes (never raw file writes to `.forge/store/`).");
+    sections.push("", "---", "", "## Command", "", commandMd.trim(), "", "---");
+    if (parsed.seed) {
+        sections.push("", `## Additional Context — ${parsed.sourceLabel}`, "", parsed.seed.trim());
+    }
+    return sections.join("\n");
+}
+// ── Registration ──────────────────────────────────────────────────────────
+const COMMAND_NAME = "store-repair";
+export function registerStoreRepair(pi, options) {
+    pi.registerCommand("forge:repair", {
+        description: "Diagnose and repair corrupted Forge store records. " +
+            "Usage: /forge:repair [--dry-run]. " +
+            "--dry-run shows what would be repaired without making changes.",
+        async handler(args, ctx) {
+            const { forgeRoot } = options;
+            const cwd = options.cwd ?? process.cwd();
+            if (!forgeRoot) {
+                ctx.ui.notify("× forge:repair — no Forge project at cwd; run /forge:init to bootstrap", "warning");
+                return;
+            }
+            const commandPath = path.join(forgeRoot, "commands", `${COMMAND_NAME}.md`);
+            let commandMd;
+            try {
+                commandMd = fs.readFileSync(commandPath, "utf8");
+            }
+            catch (err) {
+                const e = err;
+                if (e.code === "ENOENT") {
+                    ctx.ui.notify(`× forge:repair — command file not found at commands/${COMMAND_NAME}.md; run /forge:init or /forge:rebuild first.`, "error");
+                }
+                else {
+                    ctx.ui.notify(`× forge:repair — failed to read command file: ${e.message ?? "unknown error"}`, "error");
+                }
+                return;
+            }
+            let parsed;
+            try {
+                parsed = parseStoreRepairArgs(args, cwd);
+            }
+            catch (err) {
+                const e = err;
+                ctx.ui.notify(`× forge:repair — failed to parse args: ${e.message ?? "unknown"}`, "error");
+                return;
+            }
+            const kickoff = composeStoreRepairKickoff({ commandMd, parsed });
+            sendKickoff(pi, kickoff);
+        },
+    });
+}
+//# sourceMappingURL=store-repair.js.map

package/dist/extensions/forgecli/store-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-repair.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/store-repair.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store-resolver.d.ts

@@ -0,0 +1,56 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+export declare const ENTITY_TYPES: Set<string>;
+export declare const ID_PATTERNS: {
+    task: RegExp;
+    sprint: RegExp;
+    bug: RegExp;
+    feature: RegExp;
+    bareTask: RegExp;
+    idFragment: RegExp;
+};
+export type ResolverHit = {
+    dir: string;
+} | {
+    item: any;
+};
+export interface ResolveOptions {
+    entityTypes?: Set<string>;
+    ctx?: ExtensionCommandContext;
+    statusLabel?: string;
+}
+export declare function isDebug(): boolean;
+export declare function resolveToolDir(forgeRoot: string): string;
+export declare function runStoreCli(toolDir: string, argv: string[], cwd: string): Promise<any>;
+/**
+ * Try store-cli's native --task-suffix / --sprint-suffix flags. Returns:
+ *   - results array on success
+ *   - null if the flag is unsupported (older store-cli) — caller should fall back
+ */
+export declare function suffixMatch(toolDir: string, cwd: string, kind: "task" | "sprint", suffix: string): Promise<any[] | null>;
+/**
+ * Resolution cascade:
+ *   1. @path        → use the path directly as artifact directory
+ *   2. Canonical ID → store-cli query --task/--bug/--feature/--sprint
+ *   3. ID suffix    → --task-suffix / --sprint-suffix (one call) with loop fallback
+ *   4. Keyword      → store-cli query --keyword (title substring)
+ *   5. NLP fallback → store-cli nlp "<query>"
+ */
+export declare function resolveEntityRef(arg: string, toolDir: string, cwd: string, opts?: ResolveOptions): Promise<ResolverHit | null>;
+export interface ResolveToCanonicalIdOptions {
+    /** Which entity types to search. Defaults to a single-element set matching `kind`. */
+    entityTypes?: Set<string>;
+    /** Command label used in error messages (e.g. "forge:run-task"). */
+    commandLabel?: string;
+}
+/**
+ * Resolve a raw user arg to a canonical entity ID string.
+ *
+ * 1. If the arg is already a canonical ID that resolves directly → return it.
+ * 2. If the arg is an unprefixed ID (e.g. "S22-T03") → suffix-match or
+ *    prefix-normalize to the canonical form → return it.
+ * 3. If the arg is ambiguous → prompt the user (or hard-fail in non-interactive).
+ * 4. If the arg cannot be resolved → emit an actionable error and return null.
+ */
+export declare function resolveToCanonicalId(arg: string, toolDir: string, cwd: string, kind: "task" | "sprint" | "bug" | "feature", opts: ResolveToCanonicalIdOptions & {
+    ctx?: ExtensionCommandContext;
+}): Promise<string | null>;

package/dist/extensions/forgecli/store-resolver.js

@@ -0,0 +1,263 @@
+// store-resolver.ts — Shared store-cli resolver for `@path` / canonical ID /
+// ID-suffix / keyword / NLP cascade. Used by /forge:read, /forge:run-task,
+// /forge:run-sprint, /forge:fix-bug, and (eventually) /forge:plan,
+// /forge:implement ports. Co-locates the spawn helper, regex constants, and
+// the multi-result picker so future ports do not drift from the canonical
+// cascade.
+import * as path from "node:path";
+import { execFileAsync } from "./lib/exec-helpers.js";
+import { isDirectory } from "./lib/shared-fs-utils.js";
+export const ENTITY_TYPES = new Set(["task", "sprint", "bug", "feature"]);
+export const ID_PATTERNS = {
+    task: /^([A-Z0-9]+-)?S\d+-T\d+$/i,
+    sprint: /^([A-Z0-9]+-)?S\d+$/i,
+    bug: /^([A-Z0-9]+-)?B\d+$/i,
+    feature: /^([A-Z0-9]+-)?F\d+$/i,
+    bareTask: /^T\d+$/i,
+    idFragment: /^(S|B|F|T)\d+(-T\d+)?$/i,
+};
+export function isDebug() {
+    return process.env.FORGE_DEBUG === "1";
+}
+export function resolveToolDir(forgeRoot) {
+    const nested = path.join(forgeRoot, "tools");
+    return isDirectory(nested) ? nested : forgeRoot;
+}
+export async function runStoreCli(toolDir, argv, cwd) {
+    const toolPath = path.join(toolDir, "store-cli.cjs");
+    const timeout = argv[0] === "nlp" ? 30_000 : 10_000;
+    const result = await execFileAsync("node", [toolPath, ...argv], {
+        cwd,
+        encoding: "utf8",
+        timeout,
+    });
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new Error(`store-cli returned non-JSON for argv=${JSON.stringify(argv)}: ${result.stdout.slice(0, 200)}`);
+    }
+}
+function filterEntities(rs, entityTypes) {
+    return rs.filter((r) => entityTypes.has(r.type));
+}
+async function pickFromResults(items, arg, ctx, statusLabel) {
+    if (items.length === 1)
+        return { item: items[0] };
+    ctx.ui.setStatus(statusLabel, undefined);
+    const nonInteractive = process.env.FORGE_YES === "1" || process.env.FORGE_NON_INTERACTIVE === "1";
+    if (nonInteractive) {
+        ctx.ui.notify(`Multiple records match "${arg}" — refusing to pick in non-interactive mode`, "error");
+        return null;
+    }
+    const options = items.map((t, i) => `[${i}] ${t.id} (${t.type}): ${t.title}`);
+    const selection = await ctx.ui.select(`Multiple records found for "${arg}". Select one:`, options);
+    if (!selection)
+        return null;
+    const idx = parseInt(selection.match(/^\[(\d+)\]/)?.[1] ?? "-1", 10);
+    if (idx < 0 || idx >= items.length)
+        return null;
+    return { item: items[idx] };
+}
+/**
+ * Try store-cli's native --task-suffix / --sprint-suffix flags. Returns:
+ *   - results array on success
+ *   - null if the flag is unsupported (older store-cli) — caller should fall back
+ */
+export async function suffixMatch(toolDir, cwd, kind, suffix) {
+    const flag = kind === "task" ? "--task-suffix" : "--sprint-suffix";
+    try {
+        const r = await runStoreCli(toolDir, ["query", flag, suffix], cwd);
+        if (r && Array.isArray(r.results) && r.path === "suffix")
+            return r.results;
+        // store-cli ran but didn't take the suffix path → treat as unsupported.
+        return null;
+    }
+    catch (err) {
+        if (isDebug())
+            console.error(`[forge:resolver] suffix flag failed: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Resolution cascade:
+ *   1. @path        → use the path directly as artifact directory
+ *   2. Canonical ID → store-cli query --task/--bug/--feature/--sprint
+ *   3. ID suffix    → --task-suffix / --sprint-suffix (one call) with loop fallback
+ *   4. Keyword      → store-cli query --keyword (title substring)
+ *   5. NLP fallback → store-cli nlp "<query>"
+ */
+export async function resolveEntityRef(arg, toolDir, cwd, opts = {}) {
+    const ctx = opts.ctx;
+    const statusLabel = opts.statusLabel ?? "forge:resolve";
+    const entityTypes = opts.entityTypes ?? ENTITY_TYPES;
+    const setStatus = (msg) => ctx?.ui.setStatus(statusLabel, msg);
+    const pick = (items) => ctx ? pickFromResults(items, arg, ctx, statusLabel) : Promise.resolve({ item: items[0] });
+    // ── 1. @path ──────────────────────────────────────────────────────────────
+    if (arg.startsWith("@")) {
+        const rawPath = arg.slice(1).trim();
+        const resolved = path.isAbsolute(rawPath) ? rawPath : path.join(cwd, rawPath);
+        return { dir: resolved };
+    }
+    // ── 2. Canonical structured ID ────────────────────────────────────────────
+    const isCanonical = /^[A-Z0-9]+-/i.test(arg) &&
+        (ID_PATTERNS.task.test(arg) ||
+            ID_PATTERNS.bug.test(arg) ||
+            ID_PATTERNS.feature.test(arg) ||
+            ID_PATTERNS.sprint.test(arg));
+    let structuredResult = null;
+    try {
+        if (ID_PATTERNS.task.test(arg)) {
+            setStatus(`Looking up task ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--task", arg], cwd);
+        }
+        else if (ID_PATTERNS.bug.test(arg)) {
+            setStatus(`Looking up bug ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--bug", arg], cwd);
+        }
+        else if (ID_PATTERNS.feature.test(arg)) {
+            setStatus(`Looking up feature ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--feature", arg], cwd);
+        }
+        else if (ID_PATTERNS.sprint.test(arg)) {
+            setStatus(`Looking up sprint ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--sprint", arg], cwd);
+        }
+    }
+    catch (err) {
+        if (isDebug())
+            console.error(`[forge:resolver] structured query failed: ${err.message}`);
+    }
+    if (structuredResult?.results?.length > 0) {
+        return pick(structuredResult.results);
+    }
+    if (isCanonical) {
+        setStatus(undefined);
+        ctx?.ui.notify(`No record found for canonical ID "${arg}"`, "warning");
+        return null;
+    }
+    // ── 3. ID suffix matching ─────────────────────────────────────────────────
+    const looksLikeIdFragment = ID_PATTERNS.idFragment.test(arg);
+    if (looksLikeIdFragment) {
+        setStatus(`Searching for ID suffix "${arg}"…`);
+        try {
+            const suffix = arg.toUpperCase();
+            // Sprint-shaped fragment (e.g. "S01"): native sprint-suffix first,
+            // fall back to list-and-filter.
+            if (ID_PATTERNS.sprint.test(arg) && !ID_PATTERNS.task.test(arg)) {
+                const fast = await suffixMatch(toolDir, cwd, "sprint", suffix);
+                if (fast && fast.length > 0)
+                    return pick(fast);
+                if (fast === null) {
+                    const r = await runStoreCli(toolDir, ["query", "--list-sprints"], cwd);
+                    const matched = (r?.results ?? []).filter((s) => s.id?.toUpperCase().endsWith(`-${suffix}`) || s.id?.toUpperCase() === suffix);
+                    if (matched.length > 0) {
+                        const canonical = [];
+                        for (const s of matched) {
+                            try {
+                                const rr = await runStoreCli(toolDir, ["query", "--sprint", s.id], cwd);
+                                canonical.push(...(rr?.results ?? []));
+                            }
+                            catch (err) {
+                                if (isDebug())
+                                    console.error(`[forge:resolver] sprint lookup failed for ${s.id}: ${err.message}`);
+                            }
+                        }
+                        if (canonical.length > 0)
+                            return pick(canonical);
+                    }
+                }
+            }
+            // Task-shaped fragment (e.g. "T01" or "S01-T01"): native task-suffix
+            // first; fall back to N sprint × Tnn loop.
+            if (ID_PATTERNS.task.test(arg) || ID_PATTERNS.bareTask.test(arg)) {
+                const tPart = ID_PATTERNS.bareTask.test(arg) ? suffix : suffix.split("-")[1];
+                const fast = await suffixMatch(toolDir, cwd, "task", tPart);
+                if (fast && fast.length > 0)
+                    return pick(fast);
+                if (fast === null) {
+                    const r = await runStoreCli(toolDir, ["query", "--list-sprints"], cwd);
+                    for (const s of r?.results ?? []) {
+                        try {
+                            const taskId = `${s.id}-${tPart}`;
+                            const rr = await runStoreCli(toolDir, ["query", "--task", taskId], cwd);
+                            if (rr?.results?.length > 0)
+                                return pick(rr.results);
+                        }
+                        catch (err) {
+                            if (isDebug())
+                                console.error(`[forge:resolver] task lookup failed for ${s.id}-${tPart}: ${err.message}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (isDebug())
+                console.error(`[forge:resolver] suffix search failed: ${err.message}`);
+        }
+    }
+    // ── 4. Keyword search ─────────────────────────────────────────────────────
+    setStatus(`Keyword search: "${arg}"…`);
+    let keywordResult = null;
+    try {
+        keywordResult = await runStoreCli(toolDir, ["query", "--keyword", arg], cwd);
+    }
+    catch (err) {
+        if (isDebug())
+            console.error(`[forge:resolver] keyword search failed: ${err.message}`);
+    }
+    if (keywordResult?.results?.length > 0) {
+        return pick(filterEntities(keywordResult.results, entityTypes));
+    }
+    // ── 5. NLP fallback ───────────────────────────────────────────────────────
+    setStatus(`Searching Forge store: "${arg}"…`);
+    const nlpResult = await runStoreCli(toolDir, ["nlp", arg], cwd);
+    const items = filterEntities(nlpResult.results || [], entityTypes);
+    if (items.length === 0) {
+        setStatus(undefined);
+        ctx?.ui.notify(`No records found matching "${arg}"`, "warning");
+        return null;
+    }
+    return pick(items);
+}
+/**
+ * Resolve a raw user arg to a canonical entity ID string.
+ *
+ * 1. If the arg is already a canonical ID that resolves directly → return it.
+ * 2. If the arg is an unprefixed ID (e.g. "S22-T03") → suffix-match or
+ *    prefix-normalize to the canonical form → return it.
+ * 3. If the arg is ambiguous → prompt the user (or hard-fail in non-interactive).
+ * 4. If the arg cannot be resolved → emit an actionable error and return null.
+ */
+export async function resolveToCanonicalId(arg, toolDir, cwd, kind, opts) {
+    const { ctx, entityTypes = new Set([kind]), commandLabel = `forge:${kind}` } = opts;
+    const resolved = await resolveEntityRef(arg, toolDir, cwd, {
+        entityTypes,
+        ctx,
+        statusLabel: `${commandLabel}: resolving`,
+    });
+    if (!resolved) {
+        ctx?.ui.notify(`× ${commandLabel} — could not resolve "${arg}". ` +
+            `No matching ${kind} found. ` +
+            `Try a canonical ID like <PREFIX>-S<N>-T<N> or use /forge:read for search.`, "error");
+        return null;
+    }
+    if ("dir" in resolved) {
+        // @path resolution — not a task/sprint/bug ID pattern.
+        ctx?.ui.notify(`× ${commandLabel} — "${arg}" resolved to a directory path, not a ${kind} ID. ` +
+            `Provide a canonical ${kind} ID instead.`, "error");
+        return null;
+    }
+    const canonicalId = resolved.item?.id;
+    if (!canonicalId || typeof canonicalId !== "string") {
+        ctx?.ui.notify(`× ${commandLabel} — resolved "${arg}" but record has no canonical ID.`, "error");
+        return null;
+    }
+    // If the canonical ID differs from the raw arg, notify the user.
+    if (canonicalId !== arg) {
+        ctx?.ui.notify(`ℹ ${commandLabel} — resolved "${arg}" → ${canonicalId}`, "info");
+    }
+    return canonicalId;
+}
+//# sourceMappingURL=store-resolver.js.map

package/dist/extensions/forgecli/store-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-resolver.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/store-resolver.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store-validator.d.ts

@@ -0,0 +1,16 @@
+export interface StoreValidatorResult {
+    ok: boolean;
+    /** Raw error output from store-cli. Present when ok=false. */
+    reason: string;
+    /** Enhanced message with remediation hints. Present when ok=false. */
+    remediation: string;
+}
+/**
+ * Validate a store entity payload by spawning `store-cli.cjs validate`.
+ *
+ * @param entity    Entity type: "task" | "sprint" | "bug" | "event" | …
+ * @param payload   The raw payload (will be JSON.stringify'd if object; passed as-is if string).
+ * @param forgeRoot Absolute path to the Forge plugin root — locates store-cli.cjs.
+ * @returns         `{ ok: true, reason: "" }` on success, `{ ok: false, reason: <stderr> }` on failure.
+ */
+export declare function validateStoreCLIPayload(entity: string, payload: unknown, forgeRoot: string): StoreValidatorResult;

package/dist/extensions/forgecli/store-validator.js

@@ -0,0 +1,32 @@
+// Store-CLI payload validator — FORGE-S18-T03
+//
+// Spawns `store-cli.cjs validate <entity> '<json>'` synchronously and surfaces
+// any schema error as a structured result. This module is the sole point of
+// contact between hook-dispatcher.ts and store-cli's validation logic.
+//
+// Why spawnSync?
+//   pi's tool_call handler is synchronous — the event system does not support
+//   async handlers. spawnSync completes before the block result is returned to pi.
+//
+// FORGE-S25-T17: spawnSync replaced with spawnStoreCliValidate from lib/spawn-store-cli.ts.
+import * as path from "node:path";
+import { spawnStoreCliValidate } from "./lib/spawn-store-cli.js";
+import { enhanceBlockMessage } from "./store-error-remediation.js";
+/**
+ * Validate a store entity payload by spawning `store-cli.cjs validate`.
+ *
+ * @param entity    Entity type: "task" | "sprint" | "bug" | "event" | …
+ * @param payload   The raw payload (will be JSON.stringify'd if object; passed as-is if string).
+ * @param forgeRoot Absolute path to the Forge plugin root — locates store-cli.cjs.
+ * @returns         `{ ok: true, reason: "" }` on success, `{ ok: false, reason: <stderr> }` on failure.
+ */
+export function validateStoreCLIPayload(entity, payload, forgeRoot) {
+    const storeCliPath = path.join(forgeRoot, "tools", "store-cli.cjs");
+    const { ok, reason } = spawnStoreCliValidate(storeCliPath, entity, payload, forgeRoot);
+    if (!ok) {
+        const remediation = enhanceBlockMessage(reason, entity, "unknown");
+        return { ok: false, reason, remediation };
+    }
+    return { ok: true, reason: "", remediation: "" };
+}
+//# sourceMappingURL=store-validator.js.map

package/dist/extensions/forgecli/store-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-validator.js","sourceRoot":"","sources":["../../../src/extensions/forgecli/store-validator.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,uEAAuE;AACvE,EAAE;AACF,iBAAiB;AACjB,8EAA8E;AAC9E,mFAAmF;AACnF,EAAE;AACF,4FAA4F;AAE5F,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAUnE;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAE,OAAgB,EAAE,SAAiB;IAC1F,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC;IAEpE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACvF,IAAI,CAAC,EAAE,EAAE,CAAC;QACT,MAAM,WAAW,GAAG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;QACnE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC3C,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;AAClD,CAAC"}

package/dist/extensions/forgecli/test-orchestrate.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerTestOrchestrate(pi: ExtensionAPI): void;