orient-cli 0.1.0 → 0.2.0

package/dist/orient/wizard.d.ts

@@ -0,0 +1,108 @@
+/**
+ * First-run wizard
+ * =================
+ *
+ * When `orient` is invoked in a project, the wizard fires from
+ * session_start. Its job is to pick the shortest path from "user
+ * opened the CLI" to "user is typing their first prompt." In the
+ * default case that path is ONE STEP: show the banner, set the
+ * status bar, and hand control to the editor. No picker, no choice,
+ * no ceremony — just like Gemini CLI or OpenCode feels.
+ *
+ * Decision flow:
+ *
+ *   1. If `.orient-cli/mode` does not exist → default to plan-execute
+ *      silently. Never ask on first run; users who want ORIENT mode
+ *      discover it via the `/orient.framework` command which the
+ *      banner subtitle hints at.
+ *
+ *   2. If mode is "plan-execute" → read any existing plan.md and
+ *      plan-state.json. If a plan exists and state is "planning",
+ *      inject the plan-guard reminder on the next turn. If state is
+ *      "executing", inject the execute reminder. If no plan exists,
+ *      the user is just in a normal execute-mode REPL with shift+tab
+ *      available to draft one.
+ *
+ *   3. If mode is "orient" → look for an active packet. If one
+ *      exists, resume at its current phase (set the status bar,
+ *      inject phase-context system message). If no packet exists,
+ *      prompt the user to start one (this is the only place
+ *      ORIENT-mode shows the tier picker / packet-name prompt).
+ *
+ *   4. The `/orient.framework` slash command is the explicit opt-in
+ *      to ORIENT mode from inside plan-execute mode. It sets mode,
+ *      runs the packet-creation wizard, and transitions the current
+ *      session into ORIENT mode without losing chat context.
+ *
+ * This file exports pure functions. The wiring into pi's extension
+ * API happens in orient-extension.ts so wizard.ts can be unit-tested
+ * without a running TUI.
+ */
+import { type OrientMode } from "./mode.js";
+import type { Phase } from "./types.js";
+export type WizardAction = {
+    type: "plan-execute-fresh";
+    statusText: string;
+    welcomeText: string;
+} | {
+    type: "plan-execute-resume-planning";
+    planFilePath: string;
+    statusText: string;
+    welcomeText: string;
+} | {
+    type: "plan-execute-resume-executing";
+    planFilePath: string;
+    statusText: string;
+    welcomeText: string;
+} | {
+    type: "orient-resume-packet";
+    packetName: string;
+    phase: Phase;
+    statusText: string;
+    welcomeText: string;
+} | {
+    type: "orient-no-packet";
+    welcomeText: string;
+} | {
+    type: "orient-first-run";
+    welcomeText: string;
+};
+export interface WizardContext {
+    projectDir: string;
+}
+/**
+ * Pure function — takes the project directory state, returns the next
+ * WizardAction the extension should execute. Does NOT touch the UI.
+ *
+ * Default-on-first-run: plan-execute. The mode file is written the
+ * moment this function is called on an unconfigured project, so the
+ * next run doesn't trigger the "fresh" branch again. This is the
+ * "zero friction" promise from Brief.md.
+ */
+export declare function decideWizardAction(ctx: WizardContext): WizardAction;
+export interface FrameworkOptInResult {
+    mode: OrientMode;
+    message: string;
+}
+/**
+ * Called when the user types /orient.framework. Flips the project's
+ * mode to "orient" and returns a confirmation message. Does not
+ * automatically create a packet — that happens via a follow-up
+ * /orient.new call, giving the user room to name it.
+ */
+export declare function optIntoOrientFramework(ctx: WizardContext): FrameworkOptInResult;
+/** Inverse: opt back into plan-execute without creating any state. */
+export declare function optOutOfOrientFramework(ctx: WizardContext): FrameworkOptInResult;
+/**
+ * The one-line subtitle shown beneath the banner on fresh runs. Acts
+ * as an always-visible breadcrumb: the user can see at a glance how
+ * to switch modes. Kept intentionally short — if this line doesn't
+ * fit on one row at 60 columns, the banner already broke.
+ */
+export declare function buildBannerSubtitle(mode: OrientMode | null): string;
+/**
+ * Helper: does this project have any ORIENT activity worth resuming?
+ * Used by the wizard to short-circuit between the "fresh" and "resume"
+ * branches without duplicating checks across callers.
+ */
+export declare function hasAnyActivity(ctx: WizardContext): boolean;

package/dist/orient/wizard.js

@@ -0,0 +1,183 @@
+/**
+ * First-run wizard
+ * =================
+ *
+ * When `orient` is invoked in a project, the wizard fires from
+ * session_start. Its job is to pick the shortest path from "user
+ * opened the CLI" to "user is typing their first prompt." In the
+ * default case that path is ONE STEP: show the banner, set the
+ * status bar, and hand control to the editor. No picker, no choice,
+ * no ceremony — just like Gemini CLI or OpenCode feels.
+ *
+ * Decision flow:
+ *
+ *   1. If `.orient-cli/mode` does not exist → default to plan-execute
+ *      silently. Never ask on first run; users who want ORIENT mode
+ *      discover it via the `/orient.framework` command which the
+ *      banner subtitle hints at.
+ *
+ *   2. If mode is "plan-execute" → read any existing plan.md and
+ *      plan-state.json. If a plan exists and state is "planning",
+ *      inject the plan-guard reminder on the next turn. If state is
+ *      "executing", inject the execute reminder. If no plan exists,
+ *      the user is just in a normal execute-mode REPL with shift+tab
+ *      available to draft one.
+ *
+ *   3. If mode is "orient" → look for an active packet. If one
+ *      exists, resume at its current phase (set the status bar,
+ *      inject phase-context system message). If no packet exists,
+ *      prompt the user to start one (this is the only place
+ *      ORIENT-mode shows the tier picker / packet-name prompt).
+ *
+ *   4. The `/orient.framework` slash command is the explicit opt-in
+ *      to ORIENT mode from inside plan-execute mode. It sets mode,
+ *      runs the packet-creation wizard, and transitions the current
+ *      session into ORIENT mode without losing chat context.
+ *
+ * This file exports pure functions. The wiring into pi's extension
+ * API happens in orient-extension.ts so wizard.ts can be unit-tested
+ * without a running TUI.
+ */
+import { readPacketConfig, resolveActivePacketDir } from "./change-packet.js";
+import { isModeConfigured, readMode, writeMode } from "./mode.js";
+import { formatPhaseProgress, PHASES } from "./phases.js";
+import { readPlan, readState } from "./plan-execute.js";
+// ============================================================================
+// Decision logic
+// ============================================================================
+/**
+ * Pure function — takes the project directory state, returns the next
+ * WizardAction the extension should execute. Does NOT touch the UI.
+ *
+ * Default-on-first-run: plan-execute. The mode file is written the
+ * moment this function is called on an unconfigured project, so the
+ * next run doesn't trigger the "fresh" branch again. This is the
+ * "zero friction" promise from Brief.md.
+ */
+export function decideWizardAction(ctx) {
+    // Step 1: resolve / set mode.
+    if (!isModeConfigured(ctx.projectDir)) {
+        writeMode(ctx.projectDir, "plan-execute");
+        return {
+            type: "plan-execute-fresh",
+            statusText: "execute",
+            welcomeText: "Ready. Describe what you want to build — or press shift+tab for plan mode, or type /orient.framework to enter ORIENT beast mode.",
+        };
+    }
+    const mode = readMode(ctx.projectDir);
+    // Step 2: plan-execute resume branches.
+    if (mode === "plan-execute") {
+        const plan = readPlan(ctx.projectDir);
+        const state = readState(ctx.projectDir);
+        if (!plan || !state) {
+            return {
+                type: "plan-execute-fresh",
+                statusText: "execute",
+                welcomeText: "Ready. Describe what you want to build — or press shift+tab for plan mode, or type /orient.framework for ORIENT beast mode.",
+            };
+        }
+        if (state.state === "planning") {
+            return {
+                type: "plan-execute-resume-planning",
+                planFilePath: ".orient-cli/plans/current.md",
+                statusText: "plan",
+                welcomeText: `Resuming plan mode. Plan draft at .orient-cli/plans/current.md. Edit it, approve with /execute, or press shift+tab to switch back to execute.`,
+            };
+        }
+        if (state.state === "executing") {
+            const total = state.steps.length;
+            const done = state.steps.filter((s) => s.status === "completed").length;
+            const next = state.currentStepIndex >= 0 && state.currentStepIndex < total
+                ? state.steps[state.currentStepIndex].description
+                : "all steps complete";
+            return {
+                type: "plan-execute-resume-executing",
+                planFilePath: ".orient-cli/plans/current.md",
+                statusText: `execute ${done}/${total}`,
+                welcomeText: `Resuming execution. Plan progress: ${done}/${total} steps. Next: ${next}`,
+            };
+        }
+        // state === "idle"
+        return {
+            type: "plan-execute-fresh",
+            statusText: "execute",
+            welcomeText: "Ready. Describe what you want to build.",
+        };
+    }
+    // Step 3: orient-mode branches.
+    const active = resolveActivePacketDir(ctx.projectDir);
+    if (!active) {
+        return {
+            type: "orient-no-packet",
+            welcomeText: "ORIENT beast mode. No active change packet — type /orient.new <name> to start one, or /orient.mode plan-execute to fall back to plan/execute mode.",
+        };
+    }
+    const config = readPacketConfig(active.dir);
+    if (!config) {
+        return {
+            type: "orient-no-packet",
+            welcomeText: `Packet "${active.name}" has no readable config. Inspect ${active.dir}/.orient.yaml or run /orient.new <name> to create a fresh one.`,
+        };
+    }
+    const phaseInfo = PHASES[config.currentPhase];
+    const progress = formatPhaseProgress(config.currentPhase, config.phases, config.workflow);
+    return {
+        type: "orient-resume-packet",
+        packetName: active.name,
+        phase: config.currentPhase,
+        statusText: `${active.name} [${phaseInfo?.label ?? config.currentPhase}] ${progress}`,
+        welcomeText: `Resuming "${active.name}" at ${phaseInfo?.label ?? config.currentPhase}. ${phaseInfo?.description ?? ""} Type /orient.status for artifact progress.`,
+    };
+}
+/**
+ * Called when the user types /orient.framework. Flips the project's
+ * mode to "orient" and returns a confirmation message. Does not
+ * automatically create a packet — that happens via a follow-up
+ * /orient.new call, giving the user room to name it.
+ */
+export function optIntoOrientFramework(ctx) {
+    writeMode(ctx.projectDir, "orient");
+    return {
+        mode: "orient",
+        message: "ORIENT beast mode enabled. Run /orient.new <name> to start a change packet. Tier picker (fast / balanced / thorough) will follow. Run /orient.mode plan-execute to revert.",
+    };
+}
+/** Inverse: opt back into plan-execute without creating any state. */
+export function optOutOfOrientFramework(ctx) {
+    writeMode(ctx.projectDir, "plan-execute");
+    return {
+        mode: "plan-execute",
+        message: "Plan/Execute mode restored. Existing packets are untouched but not resumed. Press shift+tab to draft a plan.",
+    };
+}
+// ============================================================================
+// Subtitle hint line
+// ============================================================================
+/**
+ * The one-line subtitle shown beneath the banner on fresh runs. Acts
+ * as an always-visible breadcrumb: the user can see at a glance how
+ * to switch modes. Kept intentionally short — if this line doesn't
+ * fit on one row at 60 columns, the banner already broke.
+ */
+export function buildBannerSubtitle(mode) {
+    const effective = mode ?? "plan-execute";
+    if (effective === "plan-execute") {
+        return "plan · execute · shift+tab to toggle · /orient.framework for beast mode";
+    }
+    return "Constitution · Orient · Research · Integrate · Execute · Normalize · Test";
+}
+/**
+ * Helper: does this project have any ORIENT activity worth resuming?
+ * Used by the wizard to short-circuit between the "fresh" and "resume"
+ * branches without duplicating checks across callers.
+ */
+export function hasAnyActivity(ctx) {
+    const mode = readMode(ctx.projectDir);
+    if (mode === null)
+        return false;
+    if (mode === "plan-execute") {
+        return readPlan(ctx.projectDir) !== null || readState(ctx.projectDir) !== null;
+    }
+    return resolveActivePacketDir(ctx.projectDir) !== null;
+}
+//# sourceMappingURL=wizard.js.map

package/dist/orient/wizard.js.map

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

package/docs/open-source-resources.md

@@ -8,7 +8,7 @@ describes each one: what it is, why it was chosen, how it is used, and its licen
 ## pi coding agent
 
 - **Repository:** https://github.com/badlogic/pi-mono
-- **Package:** `@mariozechner/pi-coding-agent` (+ `pi-agent-core`, `pi-ai`, `pi-tui`)
+- **Package:** `@orient-cli/coding-agent` (+ `pi-agent-core`, `pi-ai`, `pi-tui`)
 - **License:** See repository
 - **Language:** TypeScript / Node.js