@harness-lab/cli 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# Harness CLI
+
+Small facilitator-facing CLI for Harness Lab.
+
+Current shipped scope:
+
+- `harness auth login`
+- `harness auth logout`
+- `harness auth status`
+- `harness workshop status`
+- `harness workshop archive`
+- `harness workshop phase set <phase-id>`
+
+Current implementation posture:
+
+- targets the existing shared dashboard facilitator APIs
+- defaults to a browser/device approval flow backed by dashboard-side facilitator broker sessions
+- keeps `--auth basic` and `--auth neon` as explicit local-dev/bootstrap fallback modes
+- stores session material in macOS Keychain, Windows Credential Manager, or Linux Secret Service by default
+- only uses file storage under `HARNESS_CLI_HOME` or `~/.harness` when `HARNESS_SESSION_STORAGE=file` is set explicitly
+- supports brokered facilitator commands over the same workshop APIs used by the dashboard
+
+## Usage
+
+## Install
+
+Participant-facing default install:
+
+```bash
+npm install -g @harness-lab/cli
+```
+
+Verify the binary:
+
+```bash
+harness --help
+```
+
+Development or fallback install from this repository:
+
+```bash
+npm install -g ./harness-cli
+```
+
+or:
+
+```bash
+cd harness-cli
+npm link
+```
+
+Default device/browser login:
+
+```bash
+harness auth login \
+  --dashboard-url https://harness-lab-dashboard.vercel.app
+```
+
+The CLI prints a verification URL plus user code, optionally opens the browser when supported, then polls until the facilitator approves the request on `/admin/device`.
+
+Explicit local file-mode / Basic Auth fallback:
+
+```bash
+harness auth login \
+  --auth basic \
+  --dashboard-url http://localhost:3000 \
+  --username facilitator \
+  --password secret
+```
+
+Explicit Neon email/password bootstrap fallback:
+
+```bash
+harness auth login \
+  --auth neon \
+  --dashboard-url https://harness-lab-dashboard.vercel.app \
+  --email facilitator@example.com
+```
+
+Workshop commands:
+
+```bash
+harness auth status
+harness workshop status
+harness workshop phase set rotation
+harness workshop archive --notes "Manual archive"
+harness auth logout
+```
+
+Environment variables:
+
+- `HARNESS_DASHBOARD_URL`
+- `HARNESS_AUTH_MODE`
+- `HARNESS_ADMIN_USERNAME`
+- `HARNESS_ADMIN_PASSWORD`
+- `HARNESS_FACILITATOR_EMAIL`
+- `HARNESS_FACILITATOR_PASSWORD`
+- `HARNESS_CLI_HOME`
+- `HARNESS_SESSION_STORAGE` (`keychain`, `credential-manager`, `secret-service`, or `file`)
+
+## Release Gate
+
+Public npm publication is controlled by the release gate in
+[docs/harness-cli-publication-gate.md](/Users/ondrejsvec/projects/Bobo/harness-lab/docs/harness-cli-publication-gate.md).
+Normal development should still happen from this repository; npm is the participant-facing distribution path, not a substitute for repo-local development.

package/bin/harness.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from "../src/run-cli.js";
+
+const exitCode = await runCli(process.argv.slice(2), {
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  env: process.env,
+});
+
+process.exitCode = exitCode;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@harness-lab/cli",
+  "version": "0.1.0",
+  "description": "Participant-facing Harness Lab CLI for facilitator auth and workshop operations",
+  "license": "UNLICENSED",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ondrej-svec/harness-lab.git",
+    "directory": "harness-cli"
+  },
+  "homepage": "https://github.com/ondrej-svec/harness-lab/tree/main/harness-cli",
+  "bugs": {
+    "url": "https://github.com/ondrej-svec/harness-lab/issues"
+  },
+  "keywords": [
+    "harness-lab",
+    "cli",
+    "workshop",
+    "ai-agents"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "harness": "./bin/harness.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/client.js

@@ -0,0 +1,101 @@
+export class HarnessApiError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "HarnessApiError";
+    this.status = details.status ?? null;
+    this.payload = details.payload ?? null;
+  }
+}
+
+function normalizeBaseUrl(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+async function parseJsonResponse(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+export function createHarnessClient({ fetchFn, session }) {
+  if (!session?.dashboardUrl) {
+    throw new HarnessApiError("Missing session configuration");
+  }
+
+  const baseUrl = normalizeBaseUrl(session.dashboardUrl);
+  const authHeaders = {};
+
+  if (session.authorizationHeader) {
+    authHeaders.authorization = session.authorizationHeader;
+  }
+
+  if (session.cookieHeader) {
+    authHeaders.cookie = session.cookieHeader;
+  }
+
+  if (session.accessToken) {
+    authHeaders.authorization = `Bearer ${session.accessToken}`;
+  }
+
+  async function request(path, options = {}) {
+    const response = await fetchFn(`${baseUrl}${path}`, {
+      method: options.method ?? "GET",
+      headers: {
+        accept: "application/json",
+        ...authHeaders,
+        ...(options.body ? { "content-type": "application/json" } : {}),
+        ...(options.headers ?? {}),
+      },
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    const payload = await parseJsonResponse(response);
+    if (!response.ok) {
+      const message =
+        payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+          ? payload.error
+          : `Request failed with status ${response.status}`;
+      throw new HarnessApiError(message, { status: response.status, payload });
+    }
+
+    return payload;
+  }
+
+  return {
+    verifyAccess() {
+      return request("/api/workshop");
+    },
+    getAuthSession() {
+      return request("/api/auth/get-session");
+    },
+    signOutAuthSession() {
+      return request("/api/auth/sign-out", { method: "POST" });
+    },
+    startDeviceAuthorization() {
+      return request("/api/auth/device/start", { method: "POST" });
+    },
+    pollDeviceAuthorization(deviceCode) {
+      return request("/api/auth/device/poll", { method: "POST", body: { deviceCode } });
+    },
+    getDeviceSession() {
+      return request("/api/auth/device/session");
+    },
+    signOutDeviceSession() {
+      return request("/api/auth/device/logout", { method: "POST" });
+    },
+    getWorkshopStatus() {
+      return request("/api/workshop");
+    },
+    getAgenda() {
+      return request("/api/agenda");
+    },
+    setCurrentPhase(currentId) {
+      return request("/api/agenda", { method: "PATCH", body: { currentId } });
+    },
+    archiveWorkshop(notes) {
+      return request("/api/workshop/archive", { method: "POST", body: notes ? { notes } : {} });
+    },
+  };
+}

package/src/config.js

@@ -0,0 +1,14 @@
+import os from "node:os";
+import path from "node:path";
+
+export function getDefaultDashboardUrl(env) {
+  return env.HARNESS_DASHBOARD_URL ?? "http://localhost:3000";
+}
+
+export function getCliHome(env) {
+  return env.HARNESS_CLI_HOME ?? path.join(os.homedir(), ".harness");
+}
+
+export function getSessionFilePath(env) {
+  return path.join(getCliHome(env), "session.json");
+}

package/src/io.js

@@ -0,0 +1,19 @@
+import readline from "node:readline/promises";
+
+export async function prompt(io, label) {
+  const rl = readline.createInterface({
+    input: io.stdin,
+    output: io.stderr,
+  });
+
+  try {
+    const value = await rl.question(label);
+    return value.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export function writeLine(stream, line = "") {
+  stream.write(`${line}\n`);
+}

package/src/run-cli.js

@@ -0,0 +1,518 @@
+import { getDefaultDashboardUrl } from "./config.js";
+import { createHarnessClient, HarnessApiError } from "./client.js";
+import { prompt, writeLine } from "./io.js";
+import { deleteSession, readSession, sanitizeSession, writeSession, getSessionStorageMode, SessionStoreError } from "./session-store.js";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value.startsWith("--")) {
+      const key = value.slice(2);
+      const next = argv[index + 1];
+      if (!next || next.startsWith("--")) {
+        flags[key] = true;
+        continue;
+      }
+      flags[key] = next;
+      index += 1;
+      continue;
+    }
+    positionals.push(value);
+  }
+
+  return { positionals, flags };
+}
+
+function buildBasicAuthorizationHeader(username, password) {
+  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+}
+
+function buildCookieHeader(setCookieValue) {
+  return setCookieValue
+    .split(/,(?=[^;]+=[^;]+)/)
+    .map((cookie) => cookie.split(";")[0]?.trim())
+    .filter(Boolean)
+    .join("; ");
+}
+
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function printUsage(io) {
+  writeLine(io.stdout, "Usage:");
+  writeLine(io.stdout, "  harness auth login [--auth device|basic|neon] [--dashboard-url URL] [--username USER] [--email EMAIL] [--password PASS] [--no-open]");
+  writeLine(io.stdout, "  harness auth logout");
+  writeLine(io.stdout, "  harness auth status");
+  writeLine(io.stdout, "  harness workshop status");
+  writeLine(io.stdout, "  harness workshop archive [--notes TEXT]");
+  writeLine(io.stdout, "  harness workshop phase set <phase-id>");
+}
+
+function formatStorageError(error) {
+  if (error instanceof SessionStoreError) {
+    return error.message;
+  }
+
+  return "Harness CLI could not access the configured session store.";
+}
+
+async function persistSession(io, env, session) {
+  try {
+    await writeSession(env, session);
+    return true;
+  } catch (error) {
+    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    return false;
+  }
+}
+
+async function handleBasicAuthLogin(io, env, flags, deps) {
+  const dashboardUrl = String(flags["dashboard-url"] ?? getDefaultDashboardUrl(env));
+  const username = String(flags.username ?? env.HARNESS_ADMIN_USERNAME ?? (await prompt(io, "Username: ")));
+  const password = String(flags.password ?? env.HARNESS_ADMIN_PASSWORD ?? (await prompt(io, "Password: ")));
+
+  if (!username || !password) {
+    writeLine(io.stderr, "Username and password are required.");
+    return 1;
+  }
+
+  const session = {
+    authType: "basic",
+    mode: "local-dev",
+    dashboardUrl,
+    username,
+    authorizationHeader: buildBasicAuthorizationHeader(username, password),
+    loggedInAt: new Date().toISOString(),
+  };
+
+  const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+
+  try {
+    const payload = await client.verifyAccess();
+    if (!(await persistSession(io, env, session))) {
+      return 1;
+    }
+    writeLine(io.stdout, `Logged in to ${dashboardUrl}`);
+    writeLine(io.stdout, `Session storage: ${getSessionStorageMode(env)}`);
+    if (payload?.workshopId) {
+      writeLine(io.stdout, `Workshop: ${payload.workshopId}`);
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      writeLine(io.stderr, `Login failed: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+async function handleNeonAuthLogin(io, env, flags, deps) {
+  const dashboardUrl = String(flags["dashboard-url"] ?? getDefaultDashboardUrl(env));
+  const email = String(flags.email ?? env.HARNESS_FACILITATOR_EMAIL ?? (await prompt(io, "Email: ")));
+  const password = String(flags.password ?? env.HARNESS_FACILITATOR_PASSWORD ?? (await prompt(io, "Password: ")));
+
+  if (!email || !password) {
+    writeLine(io.stderr, "Email and password are required.");
+    return 1;
+  }
+
+  const signInResponse = await deps.fetchFn(`${dashboardUrl.replace(/\/$/, "")}/api/auth/sign-in/email`, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ email, password }),
+  });
+
+  const payload = await readJson(signInResponse);
+  if (!signInResponse.ok) {
+    const message =
+      payload && typeof payload === "object" && "message" in payload && typeof payload.message === "string"
+        ? payload.message
+        : payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+          ? payload.error
+          : `Login failed with status ${signInResponse.status}`;
+    writeLine(io.stderr, `Login failed: ${message}`);
+    return 1;
+  }
+
+  const setCookie = signInResponse.headers?.get?.("set-cookie");
+  if (!setCookie) {
+    writeLine(io.stderr, "Login failed: auth response did not include a session cookie.");
+    return 1;
+  }
+
+  const session = {
+    authType: "neon",
+    mode: "session-cookie",
+    dashboardUrl,
+    email,
+    cookieHeader: buildCookieHeader(setCookie),
+    loggedInAt: new Date().toISOString(),
+  };
+
+  try {
+    const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+    const authSession = await client.getAuthSession();
+    if (!(await persistSession(io, env, session))) {
+      return 1;
+    }
+    writeLine(io.stdout, `Logged in to ${dashboardUrl}`);
+    writeLine(io.stdout, `Session storage: ${getSessionStorageMode(env)}`);
+    if (authSession?.user?.email) {
+      writeLine(io.stdout, `Facilitator: ${authSession.user.email}`);
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      writeLine(io.stderr, `Session verification failed: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+async function handleDeviceAuthLogin(io, env, flags, deps) {
+  const dashboardUrl = String(flags["dashboard-url"] ?? getDefaultDashboardUrl(env));
+  const client = createHarnessClient({
+    fetchFn: deps.fetchFn,
+    session: { dashboardUrl },
+  });
+
+  try {
+    const deviceAuth = await client.startDeviceAuthorization();
+    writeLine(io.stdout, `Open: ${deviceAuth.verificationUriComplete ?? deviceAuth.verificationUri}`);
+    writeLine(io.stdout, `Code: ${deviceAuth.userCode}`);
+    writeLine(io.stdout, `Expires: ${deviceAuth.expiresAt}`);
+    writeLine(io.stdout, "Approve the login in a browser, then the CLI will continue automatically.");
+
+    if (flags["no-open"] !== true && typeof deps.openUrl === "function") {
+      await deps.openUrl(deviceAuth.verificationUriComplete ?? deviceAuth.verificationUri);
+    }
+
+    while (Date.now() < Date.parse(deviceAuth.expiresAt)) {
+      const result = await client.pollDeviceAuthorization(deviceAuth.deviceCode);
+
+      if (result.status === "authorization_pending") {
+        await (deps.sleepFn ?? sleep)(Number(result.intervalSeconds ?? deviceAuth.intervalSeconds ?? 5) * 1000);
+        continue;
+      }
+
+      if (result.status === "authorized") {
+        const session = {
+          authType: "device",
+          mode: "broker-token",
+          dashboardUrl,
+          accessToken: result.accessToken,
+          neonUserId: result.session?.neonUserId ?? null,
+          role: result.session?.role ?? null,
+          loggedInAt: new Date().toISOString(),
+          expiresAt: result.expiresAt,
+        };
+
+        if (!(await persistSession(io, env, session))) {
+          return 1;
+        }
+
+        writeLine(io.stdout, `Logged in to ${dashboardUrl}`);
+        writeLine(io.stdout, `Session storage: ${getSessionStorageMode(env)}`);
+        if (result.session?.role) {
+          writeLine(io.stdout, `Facilitator role: ${result.session.role}`);
+        }
+        return 0;
+      }
+
+      if (result.status === "access_denied") {
+        writeLine(io.stderr, "Login failed: device authorization was denied.");
+        return 1;
+      }
+
+      if (result.status === "expired_token") {
+        writeLine(io.stderr, "Login failed: device authorization expired.");
+        return 1;
+      }
+
+      writeLine(io.stderr, "Login failed: device authorization could not be completed.");
+      return 1;
+    }
+
+    writeLine(io.stderr, "Login failed: device authorization expired.");
+    return 1;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      writeLine(io.stderr, `Login failed: ${error.message}`);
+      return 1;
+    }
+
+    if (error instanceof SessionStoreError) {
+      writeLine(io.stderr, `Session storage failed: ${error.message}`);
+      return 1;
+    }
+
+    throw error;
+  }
+}
+
+async function handleAuthLogin(io, env, flags, deps) {
+  const authMode = String(flags.auth ?? env.HARNESS_AUTH_MODE ?? "device");
+
+  if (authMode === "device") {
+    return handleDeviceAuthLogin(io, env, flags, deps);
+  }
+
+  if (authMode === "neon") {
+    return handleNeonAuthLogin(io, env, flags, deps);
+  }
+
+  return handleBasicAuthLogin(io, env, flags, deps);
+}
+
+async function requireSession(io, env) {
+  try {
+    const session = await readSession(env);
+    if (!session) {
+      writeLine(io.stderr, "No active session. Run `harness auth login` first.");
+      return null;
+    }
+    return session;
+  } catch (error) {
+    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    return null;
+  }
+}
+
+async function handleAuthStatus(io, env, deps) {
+  let session;
+  try {
+    session = await readSession(env);
+  } catch (error) {
+    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    return 1;
+  }
+
+  if (!session) {
+    writeLine(io.stdout, "Not logged in.");
+    return 0;
+  }
+
+  if (session.authType === "device") {
+    try {
+      const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+      const deviceSession = await client.getDeviceSession();
+      writeLine(
+        io.stdout,
+        JSON.stringify({ ok: true, session: sanitizeSession(session, env), remoteSession: deviceSession.session }, null, 2),
+      );
+      return 0;
+    } catch (error) {
+      if (error instanceof HarnessApiError) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, session: sanitizeSession(session, env), error: error.message }, null, 2));
+        return 1;
+      }
+      throw error;
+    }
+  }
+
+  if (session.authType === "neon") {
+    try {
+      const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+      const authSession = await client.getAuthSession();
+      writeLine(
+        io.stdout,
+        JSON.stringify({ ok: true, session: sanitizeSession(session, env), remoteSession: authSession }, null, 2),
+      );
+      return 0;
+    } catch (error) {
+      if (error instanceof HarnessApiError) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, session: sanitizeSession(session, env), error: error.message }, null, 2));
+        return 1;
+      }
+      throw error;
+    }
+  }
+
+  writeLine(io.stdout, JSON.stringify({ ok: true, session: sanitizeSession(session, env) }, null, 2));
+  return 0;
+}
+
+async function handleAuthLogout(io, env, deps) {
+  let session;
+  try {
+    session = await readSession(env);
+  } catch (error) {
+    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    return 1;
+  }
+
+  if (session?.authType === "device") {
+    try {
+      const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+      await client.signOutDeviceSession();
+    } catch (error) {
+      if (!(error instanceof HarnessApiError)) {
+        throw error;
+      }
+    }
+  }
+
+  if (session?.authType === "neon") {
+    try {
+      const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+      await client.signOutAuthSession();
+    } catch (error) {
+      if (!(error instanceof HarnessApiError)) {
+        throw error;
+      }
+    }
+  }
+
+  try {
+    await deleteSession(env);
+  } catch (error) {
+    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    return 1;
+  }
+  writeLine(io.stdout, "Logged out.");
+  return 0;
+}
+
+async function handleWorkshopStatus(io, env, deps) {
+  const session = await requireSession(io, env);
+  if (!session) {
+    return 1;
+  }
+
+  try {
+    const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+    const [workshop, agenda] = await Promise.all([client.getWorkshopStatus(), client.getAgenda()]);
+    writeLine(
+      io.stdout,
+      JSON.stringify(
+        {
+          ok: true,
+          workshopId: workshop.workshopId,
+          workshopMeta: workshop.workshopMeta,
+          currentPhase: agenda.phase,
+          templates: workshop.templates,
+        },
+        null,
+        2,
+      ),
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      writeLine(io.stderr, `Workshop status failed: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+async function handleWorkshopArchive(io, env, flags, deps) {
+  const session = await requireSession(io, env);
+  if (!session) {
+    return 1;
+  }
+
+  try {
+    const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+    const result = await client.archiveWorkshop(typeof flags.notes === "string" ? flags.notes : undefined);
+    writeLine(io.stdout, JSON.stringify(result, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      writeLine(io.stderr, `Archive failed: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+async function handleWorkshopPhaseSet(io, env, positionals, deps) {
+  const phaseId = positionals[3];
+  if (!phaseId) {
+    writeLine(io.stderr, "Phase id is required.");
+    return 1;
+  }
+
+  const session = await requireSession(io, env);
+  if (!session) {
+    return 1;
+  }
+
+  try {
+    const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+    const result = await client.setCurrentPhase(phaseId);
+    writeLine(io.stdout, JSON.stringify(result, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      writeLine(io.stderr, `Phase update failed: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+export async function runCli(argv, io, deps = {}) {
+  const fetchFn = deps.fetchFn ?? globalThis.fetch;
+  if (typeof fetchFn !== "function") {
+    throw new Error("Fetch is required to run the harness CLI.");
+  }
+
+  const mergedDeps = { fetchFn, sleepFn: deps.sleepFn, openUrl: deps.openUrl };
+  const { positionals, flags } = parseArgs(argv);
+  const [scope, action, subaction] = positionals;
+
+  if (flags.help === true) {
+    printUsage(io);
+    return 0;
+  }
+
+  if (!scope) {
+    printUsage(io);
+    return 1;
+  }
+
+  if (scope === "auth" && action === "login") {
+    return handleAuthLogin(io, io.env, flags, mergedDeps);
+  }
+
+  if (scope === "auth" && action === "logout") {
+    return handleAuthLogout(io, io.env, mergedDeps);
+  }
+
+  if (scope === "auth" && action === "status") {
+    return handleAuthStatus(io, io.env, mergedDeps);
+  }
+
+  if (scope === "workshop" && action === "status") {
+    return handleWorkshopStatus(io, io.env, mergedDeps);
+  }
+
+  if (scope === "workshop" && action === "archive") {
+    return handleWorkshopArchive(io, io.env, flags, mergedDeps);
+  }
+
+  if (scope === "workshop" && action === "phase" && subaction === "set") {
+    return handleWorkshopPhaseSet(io, io.env, positionals, mergedDeps);
+  }
+
+  printUsage(io);
+  return 1;
+}

package/src/session-store.js

@@ -0,0 +1,348 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execFile as nodeExecFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getCliHome, getSessionFilePath } from "./config.js";
+
+const execFile = promisify(nodeExecFile);
+const serviceName = "harness-cli.session";
+const accountName = "active";
+
+export class SessionStoreError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "SessionStoreError";
+    this.code = details.code ?? "session_store_error";
+  }
+}
+
+let testDeps = null;
+
+function getDeps() {
+  return (
+    testDeps ?? {
+      platform: os.platform(),
+      execFile,
+    }
+  );
+}
+
+async function ensureCliHome(env) {
+  await fs.mkdir(getCliHome(env), { recursive: true, mode: 0o700 });
+}
+
+async function readFileSession(env) {
+  const filePath = getSessionFilePath(env);
+
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function writeFileSession(env, session) {
+  await ensureCliHome(env);
+  const filePath = getSessionFilePath(env);
+  await fs.writeFile(filePath, JSON.stringify(session, null, 2) + "\n", { mode: 0o600 });
+}
+
+async function deleteFileSession(env) {
+  const filePath = getSessionFilePath(env);
+
+  try {
+    await fs.rm(filePath);
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+}
+
+async function readKeychainSession() {
+  try {
+    const { stdout } = await getDeps().execFile("/usr/bin/security", [
+      "find-generic-password",
+      "-a",
+      accountName,
+      "-s",
+      serviceName,
+      "-w",
+    ]);
+    return JSON.parse(stdout.trim());
+  } catch (error) {
+    const stderr = error && typeof error === "object" && "stderr" in error ? String(error.stderr) : "";
+    if (stderr.includes("could not be found")) {
+      return null;
+    }
+    throw new SessionStoreError("macOS Keychain is unavailable for Harness CLI session storage.", {
+      code: "keychain_unavailable",
+    });
+  }
+}
+
+async function writeKeychainSession(session) {
+  try {
+    await getDeps().execFile("/usr/bin/security", [
+      "add-generic-password",
+      "-U",
+      "-a",
+      accountName,
+      "-s",
+      serviceName,
+      "-w",
+      JSON.stringify(session),
+    ]);
+  } catch {
+    throw new SessionStoreError("Failed to write the Harness CLI session to macOS Keychain.", {
+      code: "keychain_write_failed",
+    });
+  }
+}
+
+async function deleteKeychainSession() {
+  try {
+    await getDeps().execFile("/usr/bin/security", [
+      "delete-generic-password",
+      "-a",
+      accountName,
+      "-s",
+      serviceName,
+    ]);
+  } catch (error) {
+    const stderr = error && typeof error === "object" && "stderr" in error ? String(error.stderr) : "";
+    if (stderr.includes("could not be found")) {
+      return;
+    }
+    throw new SessionStoreError("Failed to remove the Harness CLI session from macOS Keychain.", {
+      code: "keychain_delete_failed",
+    });
+  }
+}
+
+function getWindowsCredentialCommand(action, value = "") {
+  const safeValue = value.replace(/'/g, "''");
+
+  if (action === "read") {
+    return [
+      "-NoProfile",
+      "-Command",
+      `$vault = New-Object Windows.Security.Credentials.PasswordVault; try { $credential = $vault.Retrieve('${serviceName}', '${accountName}'); $credential.RetrievePassword(); Write-Output $credential.Password } catch { exit 3 }`,
+    ];
+  }
+
+  if (action === "write") {
+    return [
+      "-NoProfile",
+      "-Command",
+      `$vault = New-Object Windows.Security.Credentials.PasswordVault; try { $existing = $vault.Retrieve('${serviceName}', '${accountName}'); $vault.Remove($existing) } catch {}; $vault.Add((New-Object Windows.Security.Credentials.PasswordCredential('${serviceName}', '${accountName}', '${safeValue}')))` ,
+    ];
+  }
+
+  return [
+    "-NoProfile",
+    "-Command",
+    `$vault = New-Object Windows.Security.Credentials.PasswordVault; try { $existing = $vault.Retrieve('${serviceName}', '${accountName}'); $vault.Remove($existing) } catch { exit 0 }`,
+  ];
+}
+
+async function readCredentialManagerSession() {
+  try {
+    const { stdout } = await getDeps().execFile("powershell", getWindowsCredentialCommand("read"));
+    return JSON.parse(stdout.trim());
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === 3) {
+      return null;
+    }
+    throw new SessionStoreError(
+      "Windows Credential Manager is unavailable. Use HARNESS_SESSION_STORAGE=file only if you need an explicit insecure fallback.",
+      { code: "credential_manager_unavailable" },
+    );
+  }
+}
+
+async function writeCredentialManagerSession(session) {
+  try {
+    await getDeps().execFile("powershell", getWindowsCredentialCommand("write", JSON.stringify(session)));
+  } catch {
+    throw new SessionStoreError("Failed to write the Harness CLI session to Windows Credential Manager.", {
+      code: "credential_manager_write_failed",
+    });
+  }
+}
+
+async function deleteCredentialManagerSession() {
+  try {
+    await getDeps().execFile("powershell", getWindowsCredentialCommand("delete"));
+  } catch {
+    throw new SessionStoreError("Failed to remove the Harness CLI session from Windows Credential Manager.", {
+      code: "credential_manager_delete_failed",
+    });
+  }
+}
+
+async function readSecretServiceSession() {
+  try {
+    const { stdout } = await getDeps().execFile("/bin/sh", [
+      "-lc",
+      `secret-tool lookup service '${serviceName}' account '${accountName}'`,
+    ]);
+    const value = stdout.trim();
+    return value ? JSON.parse(value) : null;
+  } catch {
+    throw new SessionStoreError(
+      "Linux Secret Service is unavailable. Use HARNESS_SESSION_STORAGE=file only if you need an explicit insecure fallback.",
+      { code: "secret_service_unavailable" },
+    );
+  }
+}
+
+async function writeSecretServiceSession(session) {
+  try {
+    await getDeps().execFile("/bin/sh", [
+      "-lc",
+      `printf '%s' "$HARNESS_SESSION_JSON" | secret-tool store --label='Harness CLI session' service '${serviceName}' account '${accountName}'`,
+    ], {
+      env: {
+        ...process.env,
+        HARNESS_SESSION_JSON: JSON.stringify(session),
+      },
+    });
+  } catch {
+    throw new SessionStoreError("Failed to write the Harness CLI session to Linux Secret Service.", {
+      code: "secret_service_write_failed",
+    });
+  }
+}
+
+async function deleteSecretServiceSession() {
+  try {
+    await getDeps().execFile("/bin/sh", [
+      "-lc",
+      `secret-tool clear service '${serviceName}' account '${accountName}'`,
+    ]);
+  } catch {
+    throw new SessionStoreError("Failed to remove the Harness CLI session from Linux Secret Service.", {
+      code: "secret_service_delete_failed",
+    });
+  }
+}
+
+export function getSessionStorageMode(env) {
+  const requested = env.HARNESS_SESSION_STORAGE;
+  if (requested === "file" || requested === "keychain" || requested === "credential-manager" || requested === "secret-service") {
+    return requested;
+  }
+
+  if (getDeps().platform === "darwin") {
+    return "keychain";
+  }
+
+  if (getDeps().platform === "win32") {
+    return "credential-manager";
+  }
+
+  if (getDeps().platform === "linux") {
+    return "secret-service";
+  }
+
+  throw new SessionStoreError(
+    "Harness CLI does not know a secure session store for this platform. Set HARNESS_SESSION_STORAGE=file only if you need an explicit insecure fallback.",
+    { code: "unsupported_platform" },
+  );
+}
+
+function getStorageHint(storage) {
+  if (storage === "file") {
+    return "file storage";
+  }
+
+  if (storage === "keychain") {
+    return "macOS Keychain";
+  }
+
+  if (storage === "credential-manager") {
+    return "Windows Credential Manager";
+  }
+
+  return "Linux Secret Service";
+}
+
+export async function readSession(env) {
+  const storage = getSessionStorageMode(env);
+  if (storage === "keychain") {
+    return readKeychainSession();
+  }
+  if (storage === "credential-manager") {
+    return readCredentialManagerSession();
+  }
+  if (storage === "secret-service") {
+    return readSecretServiceSession();
+  }
+  return readFileSession(env);
+}
+
+export async function writeSession(env, session) {
+  const storage = getSessionStorageMode(env);
+  if (storage === "keychain") {
+    return writeKeychainSession(session);
+  }
+  if (storage === "credential-manager") {
+    return writeCredentialManagerSession(session);
+  }
+  if (storage === "secret-service") {
+    return writeSecretServiceSession(session);
+  }
+  return writeFileSession(env, session);
+}
+
+export async function deleteSession(env) {
+  const storage = getSessionStorageMode(env);
+  if (storage === "keychain") {
+    return deleteKeychainSession();
+  }
+  if (storage === "credential-manager") {
+    return deleteCredentialManagerSession();
+  }
+  if (storage === "secret-service") {
+    return deleteSecretServiceSession();
+  }
+  return deleteFileSession(env);
+}
+
+export async function sessionExists(env) {
+  return (await readSession(env)) !== null;
+}
+
+export function sanitizeSession(session, env) {
+  if (!session) {
+    return null;
+  }
+
+  return {
+    dashboardUrl: session.dashboardUrl,
+    authType: session.authType,
+    username: session.username ?? null,
+    email: session.email ?? null,
+    loggedInAt: session.loggedInAt,
+    expiresAt: session.expiresAt ?? null,
+    mode: session.mode ?? "local-dev",
+    storage: getSessionStorageMode(env),
+    storageLabel: getStorageHint(getSessionStorageMode(env)),
+    sessionHealth: session.expiresAt ? (Date.parse(session.expiresAt) > Date.now() ? "active" : "expired") : "active",
+  };
+}
+
+export function resolveProjectRelativePath(env, relativePath) {
+  return path.join(getCliHome(env), relativePath);
+}
+
+export function setSessionStoreDepsForTests(deps) {
+  testDeps = deps;
+}