jeo-code 0.1.0

package/src/auth/oauth.ts

@@ -0,0 +1,80 @@
+import type { AuthProvider } from "./storage";
+import { setOauthToken, clearOauthToken, setOauthCredential } from "./storage";
+import { OAUTH_FLOW_REGISTRY } from "./flows";
+import type { OAuthController } from "./types";
+
+export interface OauthFlowDef {
+  label: string;
+  authorizeUrl: string;
+  instructions: string[];
+}
+
+/** Metadata kept for help text / manual-paste fallback. */
+export const OAUTH_FLOWS: Record<AuthProvider, OauthFlowDef> = {
+  anthropic: {
+    label: "Anthropic Console (Claude)",
+    authorizeUrl: "https://claude.ai/oauth/authorize",
+    instructions: [
+      "Real PKCE OAuth: a browser tab opens at claude.ai and a local callback",
+      "server on http://localhost:54545/callback receives the code automatically.",
+      "If the browser cannot reach this machine, paste the redirect URL / code when prompted.",
+    ],
+  },
+  openai: {
+    label: "OpenAI (ChatGPT/Codex)",
+    authorizeUrl: "https://auth.openai.com/oauth/authorize",
+    instructions: [
+      "Real PKCE OAuth via auth.openai.com with a fixed callback on localhost:1455.",
+      "Note: the minted token targets the ChatGPT/Codex backend, not the Chat Completions API.",
+    ],
+  },
+  gemini: {
+    label: "Google (Gemini CLI)",
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    instructions: [
+      "Real Google OAuth (authorization-code) with a callback on localhost:8085.",
+      "Note: the minted token targets Cloud Code Assist; the public Gemini API prefers an API key.",
+    ],
+  },
+};
+
+export async function openInBrowser(url: string): Promise<void> {
+  try {
+    const cmd =
+      process.platform === "darwin" ? ["open", url] :
+      process.platform === "win32" ? ["cmd", "/c", "start", "", url] :
+      ["xdg-open", url];
+    const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
+    await proc.exited;
+  } catch {
+    // ignore — the URL is printed for manual opening
+  }
+}
+
+/**
+ * Run the real interactive OAuth flow for a provider: open the browser, spin up
+ * the local callback server, wait for the code (or manual paste), exchange it,
+ * and persist the full credential set (access + refresh + expiry).
+ */
+export async function interactiveLogin(provider: AuthProvider, ctrl: OAuthController): Promise<{ email?: string }> {
+  const flow = OAUTH_FLOW_REGISTRY[provider];
+  const creds = await flow.login(ctrl);
+  await setOauthCredential(provider, {
+    access: creds.access,
+    refresh: creds.refresh,
+    expires: creds.expires,
+    accountId: creds.accountId,
+    email: creds.email,
+    projectId: creds.projectId,
+  });
+  return { email: creds.email };
+}
+
+/** Non-interactive entry: stash a pre-acquired bearer (no refresh metadata). */
+export async function loginOAuth(provider: AuthProvider, token: string): Promise<void> {
+  await setOauthToken(provider, token);
+}
+
+export async function logoutOAuth(provider: AuthProvider): Promise<boolean> {
+  return clearOauthToken(provider);
+}

package/src/auth/pkce.ts

@@ -0,0 +1,24 @@
+/**
+ * Generate a PKCE code verifier + S256 challenge using the Web Crypto API.
+ * Mirrors gjc's `packages/ai/src/utils/oauth/pkce.ts`.
+ */
+export async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+  const verifierBytes = new Uint8Array(96);
+  crypto.getRandomValues(verifierBytes);
+  const verifier = Buffer.from(verifierBytes).toString("base64url");
+
+  const data = new TextEncoder().encode(verifier);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const challenge = Buffer.from(hashBuffer).toString("base64url");
+
+  return { verifier, challenge };
+}
+
+/** Random hex CSRF state token. */
+export function generateState(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/auth/refresh.ts

@@ -0,0 +1,60 @@
+import {
+  getStoredOAuth,
+  setOauthCredential,
+  resolveCredential,
+  snapshotProvider,
+  type AuthProvider,
+  type Credential,
+} from "./storage";
+import { OAUTH_FLOW_REGISTRY } from "./flows";
+import type { StoredOAuth } from "../agent/state";
+
+export interface RefreshResult {
+  refreshed: boolean;
+  reason: string;
+  credential: Credential;
+}
+
+/**
+ * Exchange the stored refresh token for a fresh access token via the provider's
+ * real OAuth token endpoint, persist it, and return the updated credential.
+ * Mirrors gjc's auth-broker refresher semantics (single source of truth).
+ */
+export async function refreshOAuthToken(provider: AuthProvider): Promise<RefreshResult> {
+  const stored = await getStoredOAuth(provider);
+  if (!stored) {
+    const snap = await snapshotProvider(provider);
+    const reason = snap.oauth ? "manual_token_no_refresh" : "no_oauth_token";
+    return { refreshed: false, reason, credential: await resolveCredential(provider) };
+  }
+  if (!stored.refresh) {
+    return {
+      refreshed: false,
+      reason: "no_refresh_token",
+      credential: { kind: "oauth", provider, token: stored.access },
+    };
+  }
+
+  const flow = OAUTH_FLOW_REGISTRY[provider];
+  const fresh = await flow.refresh(stored.refresh);
+  const next: StoredOAuth = {
+    access: fresh.access,
+    refresh: fresh.refresh || stored.refresh,
+    expires: fresh.expires,
+    accountId: fresh.accountId ?? stored.accountId,
+    email: fresh.email ?? stored.email,
+    projectId: fresh.projectId ?? stored.projectId,
+  };
+  await setOauthCredential(provider, next);
+  return {
+    refreshed: true,
+    reason: "refreshed",
+    credential: { kind: "oauth", provider, token: next.access },
+  };
+}
+
+/** Force-replace the stored OAuth token (used after a manual re-login). */
+export async function rotateOAuthToken(provider: AuthProvider, newToken: string): Promise<void> {
+  const { setOauthToken } = await import("./storage");
+  await setOauthToken(provider, newToken);
+}

package/src/auth/storage.ts

@@ -0,0 +1,113 @@
+import { readGlobalConfig, saveGlobalConfig, type Config, type StoredOAuth } from "../agent/state";
+
+export type AuthProvider = "anthropic" | "openai" | "gemini";
+
+export type Credential =
+  | { kind: "oauth"; provider: AuthProvider; token: string }
+  | { kind: "api_key"; provider: AuthProvider; token: string }
+  | { kind: "none"; provider: AuthProvider };
+
+export interface AuthSnapshot {
+  apiKey: string | undefined;
+  oauth: string | undefined;
+  /** Present only when the stored OAuth is a refreshable {@link StoredOAuth}. */
+  oauthExpires?: number;
+  oauthHasRefresh?: boolean;
+  oauthEmail?: string;
+}
+
+const inFlightRefresh = new Map<AuthProvider, Promise<any>>();
+
+function accessOf(stored: string | StoredOAuth | undefined): string | undefined {
+  if (!stored) return undefined;
+  return typeof stored === "string" ? stored : stored.access;
+}
+
+/** Single point of resolution: OAuth bearer beats API key when both exist. */
+export async function resolveCredential(provider: AuthProvider): Promise<Credential> {
+  const cfg = await readGlobalConfig();
+  const stored = cfg.oauth?.[provider];
+
+  if (stored) {
+    // Auto-refresh refreshable credentials that are past their expiry.
+    if (typeof stored !== "string" && stored.refresh && stored.expires && stored.expires <= Date.now()) {
+      try {
+        let refreshPromise = inFlightRefresh.get(provider);
+        if (!refreshPromise) {
+          refreshPromise = (async () => {
+            const { refreshOAuthToken } = await import("./refresh");
+            return refreshOAuthToken(provider);
+          })();
+          inFlightRefresh.set(provider, refreshPromise);
+          refreshPromise.finally(() => {
+            inFlightRefresh.delete(provider);
+          });
+        }
+        const result = await refreshPromise;
+        if (result.refreshed && result.credential.kind === "oauth") {
+          return result.credential;
+        }
+      } catch {
+        // Fall through and use the (stale) access token; the provider call will surface a 401.
+      }
+    }
+    const token = accessOf(stored);
+    if (token) return { kind: "oauth", provider, token };
+  }
+
+  const apiKey = cfg.providers[provider];
+  if (apiKey) return { kind: "api_key", provider, token: apiKey };
+  return { kind: "none", provider };
+}
+
+export async function snapshotProvider(provider: AuthProvider): Promise<AuthSnapshot> {
+  const cfg = await readGlobalConfig();
+  const stored = cfg.oauth?.[provider];
+  return {
+    apiKey: cfg.providers[provider],
+    oauth: accessOf(stored),
+    oauthExpires: typeof stored === "object" ? stored.expires : undefined,
+    oauthHasRefresh: typeof stored === "object" ? !!stored.refresh : false,
+    oauthEmail: typeof stored === "object" ? stored.email : undefined,
+  };
+}
+
+/** Read the full stored OAuth record (object form only). */
+export async function getStoredOAuth(provider: AuthProvider): Promise<StoredOAuth | undefined> {
+  const cfg = await readGlobalConfig();
+  const stored = cfg.oauth?.[provider];
+  return typeof stored === "object" ? stored : undefined;
+}
+
+/** Persist a plain bearer token (legacy / manual paste — no refresh metadata). */
+export async function setOauthToken(provider: AuthProvider, token: string): Promise<void> {
+  const cfg = await readGlobalConfig();
+  const next: Config = JSON.parse(JSON.stringify(cfg));
+  next.oauth = next.oauth ?? {};
+  next.oauth[provider] = token;
+  await saveGlobalConfig(next);
+}
+
+/** Persist a full OAuth credential set (access + refresh + expiry). */
+export async function setOauthCredential(provider: AuthProvider, cred: StoredOAuth): Promise<void> {
+  const cfg = await readGlobalConfig();
+  const next: Config = JSON.parse(JSON.stringify(cfg));
+  next.oauth = next.oauth ?? {};
+  next.oauth[provider] = cred;
+  await saveGlobalConfig(next);
+}
+
+export async function clearOauthToken(provider: AuthProvider): Promise<boolean> {
+  const cfg = await readGlobalConfig();
+  if (!cfg.oauth?.[provider]) return false;
+  delete cfg.oauth[provider];
+  await saveGlobalConfig(cfg);
+  return true;
+}
+
+export async function setApiKey(provider: AuthProvider, key: string): Promise<void> {
+  const cfg = await readGlobalConfig();
+  const next: Config = JSON.parse(JSON.stringify(cfg));
+  next.providers[provider] = key;
+  await saveGlobalConfig(next);
+}

package/src/auth/types.ts

@@ -0,0 +1,26 @@
+/** OAuth flow types, mirroring gjc's oauth/types.ts (trimmed to joc's surface). */
+
+export interface OAuthCredentials {
+  access: string;
+  refresh: string;
+  /** Epoch ms when the access token should be treated as expired (already skew-adjusted). */
+  expires: number;
+  accountId?: string;
+  email?: string;
+  projectId?: string;
+}
+
+export interface OAuthAuthInfo {
+  url: string;
+  instructions?: string;
+}
+
+export interface OAuthController {
+  /** Invoked once the authorization URL is ready (open it / print it). */
+  onAuth?(info: OAuthAuthInfo): void;
+  /** Progress messages during the flow. */
+  onProgress?(message: string): void;
+  /** Optional manual paste fallback when the browser cannot reach the callback. */
+  onManualCodeInput?(): Promise<string>;
+  signal?: AbortSignal;
+}

package/src/cli/index.ts

@@ -0,0 +1 @@
+export * from "./runner";

package/src/cli/runner.ts

@@ -0,0 +1,245 @@
+export interface CommandSpec {
+  readonly name: string;
+  readonly summary: string;
+  readonly usage?: string;
+  readonly loader: () => Promise<(args: string[]) => Promise<void>>;
+}
+
+export const COMMANDS: readonly CommandSpec[] = [
+  {
+    name: "launch",
+    summary: "Interactive coding agent (chat + tools). Default when no subcommand is given.",
+    usage: "launch [\"one-shot request\"] [--resume [id]] [--list] [--tmux] [--worktree <path>]",
+    loader: async () => {
+      const m = await import("../commands/launch");
+      return args => m.runLaunchCommand(args);
+    },
+  },
+  {
+    name: "setup",
+    summary: "Configure LLM providers (API key / OAuth / local) + default model.",
+    loader: async () => {
+      const m = await import("../commands/setup");
+      return async () => m.runSetupCommand();
+    },
+  },
+  {
+    name: "auth",
+    summary: "Real OAuth (PKCE) login + token storage with auto-refresh.",
+    usage: "auth [login|logout|refresh|status] [provider] [--token <bearer>]",
+    loader: async () => {
+      const m = await import("../commands/auth");
+      return args => m.runAuthCommand(args);
+    },
+  },
+  {
+    name: "deep-interview",
+    summary: "Execute Socratic requirements interview (locks tools while ambiguity > 20%).",
+    usage: 'deep-interview "<initial idea>"',
+    loader: async () => {
+      const m = await import("../commands/deep-interview");
+      return args => m.runDeepInterviewCommand(args);
+    },
+  },
+  {
+    name: "ralplan",
+    summary: "Create planning blueprint (Planner/Architect/Critic).",
+    loader: async () => {
+      const m = await import("../commands/ralplan");
+      return async () => m.runRalplanCommand();
+    },
+  },
+  {
+    name: "approve",
+    summary: "Approve a planning blueprint.",
+    usage: "approve <plan-path>",
+    loader: async () => {
+      const m = await import("../commands/approve");
+      return args => m.runApproveCommand(args);
+    },
+  },
+  {
+    name: "team",
+    summary: "Execute the planning blueprint (Executor subagent tools).",
+    loader: async () => {
+      const m = await import("../commands/team");
+      return async () => m.runTeamCommand();
+    },
+  },
+  {
+    name: "ultragoal",
+    summary: "Verify goals and run acceptance checks.",
+    loader: async () => {
+      const m = await import("../commands/ultragoal");
+      return async () => m.runUltragoalCommand();
+    },
+  },
+  {
+    name: "doctor",
+    summary: "Probe provider connectivity + credentials. Reports if default model is reachable.",
+    loader: async () => {
+      const m = await import("../commands/doctor");
+      return args => m.runDoctorCommand(args);
+    },
+  },
+  {
+    name: "mcp",
+    summary: "Run joc as an MCP stdio server (subcommand: serve|tools).",
+    usage: "mcp [serve|tools]",
+    loader: async () => {
+      const m = await import("../commands/mcp");
+      return args => m.runMcpCommand(args);
+    },
+  },
+  {
+    name: "models",
+    summary: "List model aliases + probe local/compatible models.",
+    loader: async () => {
+      const m = await import("../commands/models");
+      return args => m.runModelsCommand(args);
+    },
+  },
+  {
+    name: "skills",
+    summary: "List bundled workflow skills (joc skills <name> for details).",
+    usage: "skills [name]",
+    loader: async () => {
+      const m = await import("../commands/skills");
+      return args => m.runSkillsCommand(args);
+    },
+  },
+  {
+    name: "resume",
+    summary: "Resume the latest interactive session (or 'joc resume <id>').",
+    usage: "resume [id]",
+    loader: async () => {
+      const m = await import("../commands/resume");
+      return args => m.runResumeCommand(args);
+    },
+  },
+  {
+    name: "chat",
+    summary: "Single-shot streaming chat (no tools) — renders the reply token-by-token.",
+    usage: "chat \"<message>\"",
+    loader: async () => {
+      const m = await import("../commands/chat");
+      return args => m.runChatCommand(args);
+    },
+  },
+  {
+    name: "evolve",
+    summary: "Preview the evolution TUI identity (ASCII art + track + meter per stage).",
+    usage: "evolve [--step N] [--max M] [--animate] [--no-color]",
+    loader: async () => {
+      const m = await import("../commands/evolve");
+      return args => m.runEvolveCommand(args);
+    },
+  },
+];
+
+export function findCommand(name: string): CommandSpec | undefined {
+  return COMMANDS.find(c => c.name === name);
+}
+
+/** Levenshtein edit distance (small inputs; iterative two-row DP). */
+function editDistance(a: string, b: string): number {
+  const m = a.length, n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let cur = new Array<number>(n + 1);
+  for (let i = 1; i <= m; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, cur] = [cur, prev];
+  }
+  return prev[n];
+}
+
+/** Suggest near-miss command names for an unknown input (prefix match or ≤2 edits). */
+export function suggestCommands(name: string): string[] {
+  const q = name.toLowerCase();
+  if (!q) return [];
+  return COMMANDS.map(c => c.name).filter(n => n.startsWith(q) || editDistance(n, q) <= 2);
+}
+
+export interface DispatchContext {
+  appName: string;
+  version: string;
+}
+
+export function renderHelp(ctx: DispatchContext): string {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(`=== @jeo-code CLI (${ctx.appName}) ===`);
+  lines.push("Clean, highly optimized AI coding agent using a Socratic spec-first loop.");
+  lines.push("");
+  lines.push("Usage:");
+  lines.push(`  ${ctx.appName} <command> [arguments]`);
+  lines.push("");
+  lines.push("Commands:");
+  const width = Math.max(...COMMANDS.map(c => (c.usage ?? c.name).length));
+  for (const c of COMMANDS) {
+    const label = (c.usage ?? c.name).padEnd(width);
+    lines.push(`  ${label}   ${c.summary}`);
+  }
+  lines.push("");
+  lines.push("Options:");
+  lines.push("  -v, --version    Show version.");
+  lines.push("  -h, --help       Show help.");
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function renderCommandHelp(spec: CommandSpec, ctx: DispatchContext): string {
+  return [
+    "",
+    `Usage: ${ctx.appName} ${spec.usage ?? spec.name}`,
+    "",
+    spec.summary,
+    "",
+  ].join("\n");
+}
+
+export async function dispatch(argv: string[], ctx: DispatchContext): Promise<number> {
+  const first = argv[0];
+
+  if (first === "--version" || first === "-v") {
+    console.log(`${ctx.appName} v${ctx.version}`);
+    return 0;
+  }
+  if (first === "--help" || first === "-h") {
+    console.log(renderHelp(ctx));
+    return 0;
+  }
+  // Bare invocation or a leading global flag (e.g. `joc`, `joc --tmux`,
+  // `joc --tmux --worktree <path>`) routes to the interactive agent — gjc parity.
+  if (!first || first.startsWith("-")) {
+    const run = await findCommand("launch")!.loader();
+    await run(argv);
+    return 0;
+  }
+
+  const spec = findCommand(first);
+  if (!spec) {
+    console.log(`Unknown command: ${first}`);
+    const near = suggestCommands(first);
+    if (near.length) console.log(`Did you mean: ${near.join(", ")}?`);
+    console.log(renderHelp(ctx));
+    return 1;
+  }
+
+  // Per-command help: `joc <cmd> --help`.
+  const rest = argv.slice(1);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(renderCommandHelp(spec, ctx));
+    return 0;
+  }
+
+  const run = await spec.loader();
+  await run(rest);
+  return 0;
+}

package/src/cli.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+import { dispatch } from "./cli/runner";
+
+const APP_NAME = "joc";
+const VERSION = "0.1.0";
+const MIN_BUN_VERSION = "1.3.14";
+
+if (typeof Bun !== "undefined" && Bun.semver?.order(Bun.version, MIN_BUN_VERSION) < 0) {
+  process.stderr.write(
+    `error: Bun >= ${MIN_BUN_VERSION} required (found v${Bun.version}). Upgrade: bun upgrade\n`,
+  );
+  process.exit(1);
+}
+process.title = APP_NAME;
+
+const code = await dispatch(process.argv.slice(2), { appName: APP_NAME, version: VERSION });
+if (code !== 0) process.exit(code);

package/src/commands/approve.ts

@@ -0,0 +1,63 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  readWorkflowState,
+  writeWorkflowState,
+} from "../agent/state";
+
+export async function runApproveCommand(args: string[] = []): Promise<void> {
+  const cwd = process.cwd();
+  const planPathInput = args[0];
+
+  if (!planPathInput) {
+    console.log("[ERROR] Plan path argument is required.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolvedInputPath = path.resolve(cwd, planPathInput);
+
+  // Rejection if the plan file doesn't exist on disk
+  try {
+    await fs.access(resolvedInputPath);
+  } catch {
+    console.log(`[ERROR] Plan file not found: ${resolvedInputPath}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Read ralplan state
+  const ralplanState = await readWorkflowState("ralplan", cwd);
+  if (!ralplanState) {
+    console.log(`[ERROR] No ralplan workflow state found. Please run 'joc ralplan' first.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!ralplanState.plan_path) {
+    console.log(`[ERROR] No plan path associated with the current ralplan state.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolvedStatePath = path.resolve(cwd, ralplanState.plan_path);
+  if (resolvedStatePath !== resolvedInputPath) {
+    console.log(
+      `[ERROR] Provided plan path does not match the active plan in the ralplan state.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // Idempotency: check if already approved
+  if (ralplanState.approved) {
+    console.log(`[SUCCESS] Plan is already approved.`);
+    return;
+  }
+
+  // Update ralplan-state.json to approved: true
+  ralplanState.approved = true;
+  await writeWorkflowState("ralplan", ralplanState, cwd);
+
+  console.log(`[SUCCESS] Plan approved successfully.`);
+}