pi-soly 0.2.1

package/workflows/parser.ts

@@ -0,0 +1,268 @@
+// =============================================================================
+// workflows/parser.ts — Shared `soly <verb> <args>` parser
+// =============================================================================
+//
+// Parses user input like "soly execute 11" or "soly pause" into a structured
+// command that each workflow handler can dispatch on.
+//
+// Convention:
+//   - User types exactly "soly <verb> <args...>" (lowercase required for match)
+//   - The extension intercepts via the `input` event (no slash-command needed)
+//   - The handler transforms the input into a detailed LLM instruction that
+//     delegates to the `subagent(...)` tool (provided by pi-subagents)
+//
+// This module is pure parsing — no I/O, no extension state. Trivial to unit
+// test in isolation.
+// =============================================================================
+
+/** Verbs currently supported by the workflow handlers. */
+export type WorkflowVerb =
+	| "execute" | "pause" | "compact" | "resume" | "status" | "log" | "diff"
+	| "plan" | "discuss" | "help" | "doctor" | "iterations" | "phase" | "todos";
+
+export interface SolyCommand {
+	verb: WorkflowVerb;
+	args: string[];
+	/** Original input, for logging/debugging. */
+	raw: string;
+}
+
+/**
+ * Try to parse `text` as a `soly <verb> <args>` command.
+ * Returns null if the text doesn't match the convention.
+ *
+ * Whitespace is normalized; case is preserved for args but verb is matched
+ * case-insensitively to be friendly.
+ */
+export function parseSolyCommand(text: string): SolyCommand | null {
+	const trimmed = text.trim();
+	if (!trimmed) return null;
+	// Reject the slash-command form ("/soly ...") — that's pi's territory;
+	// we want plain "soly ..." text input only.
+	if (trimmed.startsWith("/")) return null;
+	const lower = trimmed.toLowerCase();
+	// Plain "soly" (no verb) → "help" picker
+	if (lower === "soly" || lower === "soly ") {
+		return { verb: "help", args: [], raw: trimmed };
+	}
+	// Case-insensitive `soly` prefix (so "SOLY Execute 11" matches).
+	if (!lower.startsWith("soly ")) return null;
+
+	const tokens = trimmed.split(/\s+/);
+	// tokens[0] === "soly"
+	const verbRaw = (tokens[1] ?? "").toLowerCase();
+	const verb = verbRaw as WorkflowVerb;
+	if (
+		verb !== "execute" &&
+		verb !== "pause" &&
+		verb !== "compact" &&
+		verb !== "resume" &&
+		verb !== "status" &&
+		verb !== "log" &&
+		verb !== "diff" &&
+		verb !== "plan" &&
+		verb !== "discuss" &&
+		verb !== "help" &&
+		verb !== "doctor" &&
+		verb !== "iterations" &&
+		verb !== "phase" &&
+		verb !== "todos"
+	) {
+		return null;
+	}
+
+	return {
+		verb,
+		args: tokens.slice(2),
+		raw: trimmed,
+	};
+}
+
+// =============================================================================
+// Shared target-parsing helpers
+// =============================================================================
+//
+// These are used by both `describeExecuteTarget` and `describePlanTarget` to
+// avoid duplicating the regex / flag-extraction logic. Pure functions, no
+// I/O, no extension state.
+// =============================================================================
+
+/** Shape of an already-tokenized `soly <verb> ...` args list. */
+interface ArgsShape {
+	raw: string;
+	flags: string[];
+	positional: string;
+}
+
+function parseArgsShape(args: string[]): ArgsShape {
+	const raw = args.join(" ").trim();
+	if (!raw) return { raw: "", flags: [], positional: "" };
+	return {
+		raw,
+		flags: args.filter((a) => a.startsWith("--")),
+		positional: args.find((a) => !a.startsWith("--")) ?? "",
+	};
+}
+
+/** Match `<N>` or `<N.MM>` (phase / plan). Returns null if not a phase shape. */
+function parsePhaseShape(s: string): { phase: number; plan: number | null } | null {
+	const m = s.match(/^(\d+)(?:\.(\d+))?$/);
+	if (!m) return null;
+	return {
+		phase: parseInt(m[1], 10),
+		plan: m[2] != null ? parseInt(m[2], 10) : null,
+	};
+}
+
+/** Match `<N>` only — for `soly plan`, which never has a plan sub-index. */
+function parsePhaseOnlyShape(s: string): { phase: number } | null {
+	const m = s.match(/^(\d+)$/);
+	if (!m) return null;
+	return { phase: parseInt(m[1], 10) };
+}
+
+/** Match task-id `<slug>-<4hex>`, case-insensitive. */
+function parseTaskIdShape(s: string): string | null {
+	return s.match(/^[a-z0-9][a-z0-9-]*-[a-f0-9]{4}$/i) ? s : null;
+}
+
+/** Extract `--feature <name>` from args. Returns null if not present or invalid. */
+function parseFeatureFlag(args: string[]): string | null {
+	const idx = args.indexOf("--feature");
+	if (idx === -1) return null;
+	const feature = args[idx + 1];
+	return feature && !feature.startsWith("--") ? feature : null;
+}
+
+/** Extract `--new-task <slug>` together with `--feature <name>`. */
+function parseNewTaskFlag(
+	args: string[],
+): { slug: string; feature: string } | null {
+	const idx = args.indexOf("--new-task");
+	const feature = parseFeatureFlag(args);
+	if (idx === -1 || !feature) return null;
+	const slug = args[idx + 1];
+	if (!slug || slug.startsWith("--")) return null;
+	return { slug, feature };
+}
+
+// =============================================================================
+// execute target
+// =============================================================================
+
+/**
+ * What `soly execute ...` should target. Dual-mode: phases and tasks
+ * live side by side.
+ */
+export type ExecuteTarget =
+	| { kind: "phase"; phase: number; plan: number | null; raw: string }
+	| { kind: "task"; taskId: string; raw: string }
+	| { kind: "all"; raw: string }
+	| { kind: "feature"; feature: string; raw: string };
+
+/**
+ * Parse `soly execute <args>` into a structured target.
+ *
+ * Recognized forms:
+ *   <N>           — execute all plans in phase N
+ *   <N.MM>        — execute a specific plan
+ *   <task-id>     — execute a specific task (slug-hash, e.g. auth-be-login-a3f9)
+ *   --all         — execute all ready tasks (sequential in v0.1)
+ *   --feature <n> — execute all tasks in a feature (sequential in v0.1)
+ *
+ * Returns null when args are missing or malformed.
+ */
+export function describeExecuteTarget(args: string[]): ExecuteTarget | null {
+	const { raw, flags, positional } = parseArgsShape(args);
+	if (!raw) return null;
+
+	// --all / --all-ready
+	if (flags.includes("--all") || flags.includes("--all-ready")) {
+		return { kind: "all", raw };
+	}
+
+	// --feature <name>
+	const feature = parseFeatureFlag(args);
+	if (feature) {
+		return { kind: "feature", feature, raw };
+	}
+
+	const target = positional.trim();
+	if (!target) return null;
+
+	const phase = parsePhaseShape(target);
+	if (phase) {
+		return { kind: "phase", phase: phase.phase, plan: phase.plan, raw };
+	}
+
+	const taskId = parseTaskIdShape(target);
+	if (taskId) {
+		return { kind: "task", taskId, raw };
+	}
+
+	return null;
+}
+
+// =============================================================================
+// plan target
+// =============================================================================
+
+/**
+ * What `soly plan ...` should target. Dual-mode with execute.
+ *
+ *   phase    — plan a phase
+ *   task     — plan (write/flesh out PLAN.md for) an existing task
+ *   new-task — create a brand-new task dir + PLAN.md (with frontmatter)
+ *   feature  — plan all ready tasks in a feature
+ */
+export type PlanTarget =
+	| { kind: "phase"; phase: number; raw: string }
+	| { kind: "task"; taskId: string; raw: string }
+	| { kind: "new-task"; slug: string; feature: string; raw: string }
+	| { kind: "feature"; feature: string; raw: string };
+
+/**
+ * Parse `soly plan <args>` into a structured target.
+ *
+ * Recognized forms:
+ *   <N>                          — plan phase N
+ *   <task-id>                    — plan existing task (PLAN.md already exists, flesh it out)
+ *   --new-task <slug> --feature <n>  — create new task dir + PLAN.md skeleton
+ *   --feature <n>                — plan all ready tasks in a feature
+ *
+ * Returns null when args are missing or malformed.
+ */
+export function describePlanTarget(args: string[]): PlanTarget | null {
+	const { raw, positional } = parseArgsShape(args);
+	if (!raw) return null;
+
+	// --new-task <slug> --feature <name>  (order-independent)
+	const newTask = parseNewTaskFlag(args);
+	if (newTask) {
+		return { kind: "new-task", slug: newTask.slug, feature: newTask.feature, raw };
+	}
+
+	// --feature <name>  (only when it's the only flag — disambiguate from
+	// the new-task case above where --feature is also present)
+	const feature = parseFeatureFlag(args);
+	if (feature) {
+		return { kind: "feature", feature, raw };
+	}
+
+	const target = positional.trim();
+	if (!target) return null;
+
+	// Plan target only matches plain N (no .MM — plan is per-phase, executed
+	// at the phase level by `soly execute <N.MM>`).
+	const phase = parsePhaseOnlyShape(target);
+	if (phase) {
+		return { kind: "phase", phase: phase.phase, raw };
+	}
+
+	const taskId = parseTaskIdShape(target);
+	if (taskId) {
+		return { kind: "task", taskId, raw };
+	}
+
+	return null;
+}

package/workflows/pause.ts

@@ -0,0 +1,150 @@
+// =============================================================================
+// workflows/pause.ts — `soly pause` / `soly compact` handler
+// =============================================================================
+//
+// Intercepts "soly pause" (just write handoff) and "soly compact" (write
+// handoff AND trigger session compaction).
+//
+// Like execute, we transform the input into a detailed LLM instruction that
+// walks the LLM through the soly pause-work workflow. The LLM produces both:
+//   - .soly/HANDOFF.json  (machine-readable state for resume)
+//   - .soly/.continue-here.md  (human-readable context)
+//
+// For `compact`, we additionally call ctx.compact() AFTER the handoff files
+// are written — but we still let the LLM drive the handoff generation, since
+// the work-done/work-remaining/decisions/blockers content requires reading
+// the current session context.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { SolyCommand } from "./parser.js";
+import type { SolyState } from "../core.js";
+
+/** Resolve <extension>/workflows-data/<name>.md regardless of cwd. */
+function loadWorkflowMarkdown(name: string): string | null {
+	try {
+		const here = path.dirname(fileURLToPath(import.meta.url));
+		const candidate = path.resolve(here, "..", "workflows-data", name);
+		if (fs.existsSync(candidate)) return fs.readFileSync(candidate, "utf-8");
+	} catch {
+		// fall through
+	}
+	return null;
+}
+
+export interface PauseHandlerResult {
+	handled: boolean;
+	transformedText?: string;
+	/** Whether the extension should also call ctx.compact() after the handoff. */
+	triggerCompact: boolean;
+}
+
+/** Build HANDOFF.json scaffold from current state — the LLM fills in details. */
+function handoffScaffold(state: SolyState): string {
+	const projectRoot = path.dirname(state.solyDir);
+	const position = state.position;
+	const phase = state.currentPhase;
+
+	return JSON.stringify(
+		{
+			schema_version: "1.0",
+			generated_by: "soly extension",
+			generated_at: new Date().toISOString(),
+			project_root: projectRoot,
+			soly_dir: state.solyDir,
+			milestone: state.milestone,
+			milestone_name: state.milestoneName,
+			status: state.status,
+			position: position
+				? {
+						phase: position.phase,
+						plan: position.plan,
+						status: position.status,
+					}
+				: null,
+			current_phase: phase
+				? {
+						number: phase.number,
+						name: phase.name,
+						slug: phase.slug,
+						dir: phase.dir,
+						plan_count: phase.planCount,
+					}
+				: null,
+			progress: state.progress,
+			work_completed: [], // LLM fills in
+			work_remaining: [], // LLM fills in
+			decisions: [], // LLM fills in (or read from STATE.md Decisions table)
+			blockers: [], // LLM fills in
+			human_actions_pending: [], // LLM fills in
+			resume_command: "soly resume", // not yet implemented; documented
+		},
+		null,
+		2,
+	);
+}
+
+export function buildPauseTransform(
+	cmd: SolyCommand,
+	state: SolyState,
+): PauseHandlerResult {
+	if (!state.exists) {
+		return {
+			handled: true,
+			transformedText:
+				`soly: no .soly/ directory found in cwd (${state.solyDir || "<cwd>"}) — nothing to pause.\n` +
+				`If you wanted to start a soly project, see the soly quickstart.`,
+			triggerCompact: false,
+		};
+	}
+
+	const isCompact = cmd.verb === "compact";
+	const workflow = loadWorkflowMarkdown("pause-work.md");
+	if (!workflow) {
+		return {
+			handled: true,
+			transformedText:
+				`soly: pause-work workflow markdown not found: workflows-data/pause-work.md\n` +
+				`This is an extension installation issue — reinstall soly.`,
+			triggerCompact: false,
+		};
+	}
+
+	const scaffold = handoffScaffold(state);
+
+	const actionLine = isCompact
+		? `Action: PAUSE + COMPACT the session after handoff files are written.`
+		: `Action: PAUSE only. Do not call ctx.compact() — the user wants to keep the session as-is.`;
+
+	const instruction = `soly ${cmd.verb} — preparing handoff for resume.
+
+${actionLine}
+
+Current position (from .soly/STATE.md):
+${state.position
+	? `  phase: ${state.position.phase}\n  plan:  ${state.position.plan}\n  status: ${state.position.status}`
+	: "  (no position set — likely pre-planning or paused at a milestone boundary)"}
+
+Use this HANDOFF.json scaffold as your starting point (you'll fill in the work_*, decisions, blockers, human_actions_pending arrays from the current session context):
+
+\`\`\`json
+${scaffold}
+\`\`\`
+
+Follow the workflow below VERBATIM — these are the user-approved soly instructions, not suggestions.
+
+=== WORKFLOW: pause-work.md ===
+${workflow}
+=== END WORKFLOW ===
+
+After you write both .soly/HANDOFF.json and .soly/.continue-here.md, tell the user:
+  - where the files were written (absolute paths)
+  - the resume command: soly resume
+  - ${isCompact ? "session will be compacted at end of this turn" : "session state preserved as-is"}
+
+${isCompact ? `IMPORTANT: the extension will call ctx.compact() for you at the end of this turn. Do NOT call it yourself — your job is just to produce the handoff files. The compaction will happen automatically once this turn completes.` : ""}`;
+
+	return { handled: true, transformedText: instruction, triggerCompact: isCompact };
+}