orient-cli 0.1.0-alpha.0 → 0.2.0

package/dist/orient/clear-command.js

@@ -0,0 +1,117 @@
+/**
+ * /clear command — phase-gated context wipe
+ * ===========================================
+ *
+ * Two modes behave differently:
+ *
+ *   - **Plan/Execute mode:** /clear wipes the chat history but keeps
+ *     .orient-cli/plan.md on disk. The plan is the restart contract.
+ *     The agent re-injects the plan on the next turn from the file,
+ *     so nothing meaningful is lost.
+ *
+ *   - **ORIENT mode:** /clear checks the current phase's required
+ *     artifacts. If any artifact for the active phase is in
+ *     `pending` or `draft` status, the command refuses, prints the
+ *     blocking artifact names, and does nothing. Only when every
+ *     required artifact of the current phase is `complete` does
+ *     the clear succeed. This enforces the Brief's "spec first,
+ *     clear second" discipline — a fresh context window is only
+ *     worth having if you have a persistent artifact to anchor on.
+ *
+ * The command never touches the session file on disk. It signals to
+ * pi's agent that the conversation-message buffer should be reset
+ * via ctx.ui.clearChat() (a new method added in the fork — see
+ * MIGRATION.md for fork changes).
+ *
+ * If pi's extension API does not yet expose ctx.ui.clearChat(), the
+ * fork change that adds it is part of this packet (see Tasks.md,
+ * Wave 2: "Add clearChat hook to ExtensionAPI").
+ */
+import { PHASES } from "./phases.js";
+// ============================================================================
+// Decision logic
+// ============================================================================
+/**
+ * Pure function that decides whether a /clear can proceed, given the
+ * current project state. Callers handle the actual buffer reset.
+ *
+ * The decision tree:
+ *
+ *   if mode == plan-execute:
+ *     if plan.md exists and state is idle|planning|executing:
+ *       always allow (plan is the restart contract)
+ *     else:
+ *       always allow (nothing to protect)
+ *
+ *   if mode == orient:
+ *     if no active packet:
+ *       always allow
+ *     else:
+ *       find the current phase's required artifacts
+ *       for each required artifact:
+ *         if status not in {complete, skipped}:
+ *           deny, list blockers
+ *       else: allow
+ */
+export function decideClear(ctx) {
+    // Plan-execute mode: always safe to clear because plan.md is the anchor.
+    if (ctx.mode === "plan-execute") {
+        return {
+            allowed: true,
+            reason: ctx.planSession && ctx.planSession.state !== "idle"
+                ? "Plan persists at .orient-cli/plan.md. Clearing chat context is safe; the plan reloads on next turn."
+                : "No active plan. Clearing chat context.",
+        };
+    }
+    // ORIENT mode without a packet: nothing gated, allow.
+    if (!ctx.packet) {
+        return {
+            allowed: true,
+            reason: "No active change packet. Clearing chat context.",
+        };
+    }
+    const currentPhase = ctx.packet.currentPhase;
+    const phaseInfo = PHASES[currentPhase];
+    if (!phaseInfo) {
+        return {
+            allowed: false,
+            reason: `Current phase "${currentPhase}" is unknown. Cannot evaluate /clear safety. Fix the packet config.`,
+            blockers: [`unknown phase: ${currentPhase}`],
+        };
+    }
+    const requiredArtifacts = phaseInfo.artifacts;
+    const blockers = [];
+    for (const artifact of requiredArtifacts) {
+        const state = ctx.packet.artifacts[artifact];
+        if (!state || (state.status !== "complete" && state.status !== "skipped")) {
+            const label = state?.status ?? "pending";
+            blockers.push(`${artifact} (${label})`);
+        }
+    }
+    if (blockers.length > 0) {
+        return {
+            allowed: false,
+            reason: `Cannot /clear during the ${phaseInfo.label} phase until its artifacts are complete. Finish them first, or mark them skipped deliberately.`,
+            blockers,
+        };
+    }
+    return {
+        allowed: true,
+        reason: `All ${phaseInfo.label} artifacts are complete. Clearing chat context. Packet config persists; next turn can resume from State.md.`,
+    };
+}
+// ============================================================================
+// Formatting
+// ============================================================================
+/**
+ * Format a ClearOutcome for ctx.ui.notify() display. Blockers are
+ * rendered as a bullet list when present.
+ */
+export function formatClearMessage(outcome) {
+    if (outcome.allowed) {
+        return outcome.reason;
+    }
+    const bullets = outcome.blockers.map((b) => `  • ${b}`).join("\n");
+    return `${outcome.reason}\n\nBlocking artifacts:\n${bullets}`;
+}
+//# sourceMappingURL=clear-command.js.map

package/dist/orient/clear-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-command.js","sourceRoot":"","sources":["../../src/orient/clear-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAsBrC,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,WAAW,CAAC,GAAiB;IAC5C,yEAAyE;IACzE,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACjC,OAAO;YACN,OAAO,EAAE,IAAI;YACb,MAAM,EACL,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,KAAK,KAAK,MAAM;gBAClD,CAAC,CAAC,qGAAqG;gBACvG,CAAC,CAAC,wCAAwC;SAC5C,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QACjB,OAAO;YACN,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,iDAAiD;SACzD,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,YAAqB,CAAC;IACtD,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO;YACN,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,kBAAkB,YAAY,qEAAqE;YAC3G,QAAQ,EAAE,CAAC,kBAAkB,YAAY,EAAE,CAAC;SAC5C,CAAC;IACH,CAAC;IAED,MAAM,iBAAiB,GAAG,SAAS,CAAC,SAAS,CAAC;IAC9C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,UAAU,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;YAC3E,MAAM,KAAK,GAAG,KAAK,EAAE,MAAM,IAAI,SAAS,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,KAAK,KAAK,GAAG,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO;YACN,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,4BAA4B,SAAS,CAAC,KAAK,gGAAgG;YACnJ,QAAQ;SACR,CAAC;IACH,CAAC;IAED,OAAO;QACN,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,OAAO,SAAS,CAAC,KAAK,6GAA6G;KAC3I,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAqB;IACvD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnE,OAAO,GAAG,OAAO,CAAC,MAAM,4BAA4B,OAAO,EAAE,CAAC;AAC/D,CAAC"}

package/dist/orient/mode.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ORIENT CLI product modes
+ * =========================
+ *
+ * ORIENT CLI ships two product modes:
+ *
+ *   - `plan-execute`: vanilla agent CLI — like Gemini CLI, Codex CLI,
+ *     Claude Code, OpenCode. Two-state cycle: /plan drafts an
+ *     implementation plan, /execute runs it. No phase walkthrough.
+ *     This is the default for new users and the fastest path from
+ *     "I want to build X" to "X is built."
+ *
+ *   - `orient`: full spec-driven framework — phase walkthrough, tier
+ *     picker, 17-artifact change packet, [NEEDS CLARIFICATION]
+ *     markers, /orient.clarify loop, /orient.transition, etc. The
+ *     beast mode. For feature work, high-risk changes, and situations
+ *     where a traceability matrix actually matters.
+ *
+ * Mode is chosen once per project on first run and persists at
+ * `.orient-cli/mode` (a single-line text file with "plan-execute" or
+ * "orient"). Users can switch modes later via `/orient.mode <name>`.
+ *
+ * The mode is NOT stored on the PacketConfig because plan-execute mode
+ * has no packets — it has a single `.orient-cli/plan.md` per project
+ * instead. Storing mode at the project-root .orient-cli/ level keeps
+ * the two subsystems cleanly separated.
+ */
+export type OrientMode = "plan-execute" | "orient";
+export interface ModeSpec {
+    mode: OrientMode;
+    digit: "1" | "2";
+    label: string;
+    summary: string;
+    persuasion: string;
+}
+export declare const MODES: Record<OrientMode, ModeSpec>;
+/**
+ * Path to the mode file for a given project root.
+ * Note: this uses the `.orient-cli/` project-level dir (the piConfig
+ * configDir rebrand), NOT `.orient/` (which holds change packets).
+ * Keeping them separate makes the two subsystems cleanly decoupled.
+ */
+export declare function getModeFilePath(projectDir: string): string;
+/**
+ * Read the current mode for a project, or null if not yet chosen.
+ */
+export declare function readMode(projectDir: string): OrientMode | null;
+/**
+ * Write the mode for a project. Creates the `.orient-cli/` dir if missing.
+ */
+export declare function writeMode(projectDir: string, mode: OrientMode): void;
+/**
+ * Check whether the project has a mode configured yet.
+ */
+export declare function isModeConfigured(projectDir: string): boolean;
+/**
+ * Build the option array for the mode picker's ctx.ui.select() call.
+ * Digits come first so users can literally type 1 or 2 in terminals
+ * that support digit-shortcut selection.
+ */
+export declare function buildModeSelectOptions(): string[];
+/**
+ * Parse a mode-selector option back to an OrientMode.
+ * Matches both the digit prefix and substring fallbacks.
+ */
+export declare function parseModeFromSelection(selection: string): OrientMode | null;
+/**
+ * Human-readable mode description for status bar and welcome lines.
+ */
+export declare function describeMode(mode: OrientMode): string;

package/dist/orient/mode.js

@@ -0,0 +1,124 @@
+/**
+ * ORIENT CLI product modes
+ * =========================
+ *
+ * ORIENT CLI ships two product modes:
+ *
+ *   - `plan-execute`: vanilla agent CLI — like Gemini CLI, Codex CLI,
+ *     Claude Code, OpenCode. Two-state cycle: /plan drafts an
+ *     implementation plan, /execute runs it. No phase walkthrough.
+ *     This is the default for new users and the fastest path from
+ *     "I want to build X" to "X is built."
+ *
+ *   - `orient`: full spec-driven framework — phase walkthrough, tier
+ *     picker, 17-artifact change packet, [NEEDS CLARIFICATION]
+ *     markers, /orient.clarify loop, /orient.transition, etc. The
+ *     beast mode. For feature work, high-risk changes, and situations
+ *     where a traceability matrix actually matters.
+ *
+ * Mode is chosen once per project on first run and persists at
+ * `.orient-cli/mode` (a single-line text file with "plan-execute" or
+ * "orient"). Users can switch modes later via `/orient.mode <name>`.
+ *
+ * The mode is NOT stored on the PacketConfig because plan-execute mode
+ * has no packets — it has a single `.orient-cli/plan.md` per project
+ * instead. Storing mode at the project-root .orient-cli/ level keeps
+ * the two subsystems cleanly separated.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const MODES = {
+    "plan-execute": {
+        mode: "plan-execute",
+        digit: "1",
+        label: "Plan & Execute",
+        summary: "Fast. Two commands: /plan drafts a plan, /execute runs it. Like Gemini CLI or OpenCode.",
+        persuasion: "You type a goal. ORIENT drafts a plan. You approve. ORIENT executes. Ship a real change in under five turns.",
+    },
+    orient: {
+        mode: "orient",
+        digit: "2",
+        label: "ORIENT Framework",
+        summary: "Beast mode. Six-phase spec-driven walkthrough with ambiguity markers and a traceability matrix.",
+        persuasion: "Every change gets a Brief, a Spec, a Plan, Tasks, Verification, and an Archive. Restartable from any phase. For work that must not regress.",
+    },
+};
+// ============================================================================
+// Persistence
+// ============================================================================
+const MODE_FILE = "mode";
+/**
+ * Path to the mode file for a given project root.
+ * Note: this uses the `.orient-cli/` project-level dir (the piConfig
+ * configDir rebrand), NOT `.orient/` (which holds change packets).
+ * Keeping them separate makes the two subsystems cleanly decoupled.
+ */
+export function getModeFilePath(projectDir) {
+    return join(projectDir, ".orient-cli", MODE_FILE);
+}
+/**
+ * Read the current mode for a project, or null if not yet chosen.
+ */
+export function readMode(projectDir) {
+    const path = getModeFilePath(projectDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = readFileSync(path, "utf-8").trim();
+        if (value === "plan-execute" || value === "orient")
+            return value;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the mode for a project. Creates the `.orient-cli/` dir if missing.
+ */
+export function writeMode(projectDir, mode) {
+    const path = getModeFilePath(projectDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, mode, "utf-8");
+}
+/**
+ * Check whether the project has a mode configured yet.
+ */
+export function isModeConfigured(projectDir) {
+    return readMode(projectDir) !== null;
+}
+// ============================================================================
+// Wizard helpers
+// ============================================================================
+/**
+ * Build the option array for the mode picker's ctx.ui.select() call.
+ * Digits come first so users can literally type 1 or 2 in terminals
+ * that support digit-shortcut selection.
+ */
+export function buildModeSelectOptions() {
+    return [
+        `${MODES["plan-execute"].digit} — ${MODES["plan-execute"].label} · ${MODES["plan-execute"].summary}`,
+        `${MODES.orient.digit} — ${MODES.orient.label} · ${MODES.orient.summary}`,
+    ];
+}
+/**
+ * Parse a mode-selector option back to an OrientMode.
+ * Matches both the digit prefix and substring fallbacks.
+ */
+export function parseModeFromSelection(selection) {
+    if (!selection)
+        return null;
+    const trimmed = selection.trim();
+    if (trimmed.startsWith("1") || trimmed.toLowerCase().includes("plan"))
+        return "plan-execute";
+    if (trimmed.startsWith("2") || trimmed.toLowerCase().includes("orient framework"))
+        return "orient";
+    return null;
+}
+/**
+ * Human-readable mode description for status bar and welcome lines.
+ */
+export function describeMode(mode) {
+    return MODES[mode].label;
+}
+//# sourceMappingURL=mode.js.map

package/dist/orient/mode.js.map

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

package/dist/orient/orient-extension.d.ts

@@ -7,5 +7,5 @@
  * - Augmenting the system prompt with ORIENT phase context
  * - Tracking state via turn_end events
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@orient-cli/coding-agent";
 export default function orientExtension(pi: ExtensionAPI): void;