@harness-lab/cli 0.1.4 → 0.1.7

package/README.md

@@ -66,7 +66,7 @@ harness skill install
 ```
 
 This creates `.agents/skills/harness-lab-workshop` in the current Harness Lab repo checkout.
-After install, the CLI prints the first recommended agent commands, starting with `/workshop reference`.
+After install, the CLI prints the first recommended agent commands, starting with `Codex: $workshop reference` and `OpenCode: /workshop reference`.
 
 Default device/browser login:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-lab/cli",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Participant-facing Harness Lab CLI for facilitator auth and workshop operations",
   "license": "UNLICENSED",
   "type": "module",
@@ -33,6 +33,9 @@
   "bin": {
     "harness": "bin/harness.js"
   },
+  "dependencies": {
+    "chalk": "^5.6.2"
+  },
   "scripts": {
     "test": "node --test"
   }

package/src/io.js

@@ -1,4 +1,5 @@
 import readline from "node:readline/promises";
+import { Chalk } from "chalk";
 
 export async function prompt(io, label) {
   const rl = readline.createInterface({
@@ -17,3 +18,179 @@ export async function prompt(io, label) {
 export function writeLine(stream, line = "") {
   stream.write(`${line}\n`);
 }
+
+function supportsColor(stream, env = {}) {
+  if (!stream?.isTTY) {
+    return false;
+  }
+
+  if ("NO_COLOR" in env) {
+    return false;
+  }
+
+  return env.TERM !== "dumb";
+}
+
+function createStyler(stream, env) {
+  return new Chalk({ level: supportsColor(stream, env) ? 1 : 0 });
+}
+
+function getWrapWidth(stream) {
+  const width = Number(stream?.columns);
+  if (!Number.isFinite(width) || width <= 0) {
+    return 88;
+  }
+
+  return Math.max(60, Math.min(width, 100));
+}
+
+function wrapText(text, width, indent = "", subsequentIndent = indent) {
+  if (!text) {
+    return [indent.trimEnd()];
+  }
+
+  const firstLineWidth = Math.max(20, width - indent.length);
+  const laterLineWidth = Math.max(20, width - subsequentIndent.length);
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let currentPrefix = indent;
+  let currentText = "";
+
+  for (const word of words) {
+    const lineWidth = currentPrefix === indent ? firstLineWidth : laterLineWidth;
+    const candidate = currentText ? `${currentText} ${word}` : word;
+
+    if (candidate.length <= lineWidth || currentText.length === 0) {
+      currentText = candidate;
+      continue;
+    }
+
+    lines.push(`${currentPrefix}${currentText}`);
+    currentPrefix = subsequentIndent;
+    currentText = word;
+  }
+
+  lines.push(`${currentPrefix}${currentText}`);
+  return lines;
+}
+
+function writeWrapped(stream, text, options = {}) {
+  const width = options.width ?? getWrapWidth(stream);
+  const indent = options.indent ?? "";
+  const subsequentIndent = options.subsequentIndent ?? indent;
+
+  for (const line of wrapText(text, width, indent, subsequentIndent)) {
+    writeLine(stream, line);
+  }
+}
+
+export function createCliUi(io) {
+  function streamFor(target) {
+    return target === "stderr" ? io.stderr : io.stdout;
+  }
+
+  function blank(target = "stdout") {
+    writeLine(streamFor(target));
+  }
+
+  function heading(title, options = {}) {
+    const target = options.stream ?? "stdout";
+    const stream = streamFor(target);
+    const chalk = createStyler(stream, io.env);
+    writeLine(stream, chalk.cyan.bold(title));
+    writeLine(stream, chalk.dim("=".repeat(title.length)));
+  }
+
+  function section(title, options = {}) {
+    const target = options.stream ?? "stdout";
+    const stream = streamFor(target);
+    const chalk = createStyler(stream, io.env);
+    writeLine(stream, chalk.bold(title));
+  }
+
+  function paragraph(text, options = {}) {
+    writeWrapped(streamFor(options.stream ?? "stdout"), text, options);
+  }
+
+  function status(kind, text, options = {}) {
+    const target = options.stream ?? (kind === "error" ? "stderr" : "stdout");
+    const stream = streamFor(target);
+    const chalk = createStyler(stream, io.env);
+    const prefixMap = {
+      ok: chalk.green.bold("[ok]"),
+      info: chalk.cyan.bold("[info]"),
+      warn: chalk.yellow.bold("[warn]"),
+      error: chalk.red.bold("[error]"),
+    };
+    const prefix = prefixMap[kind] ?? "[info]";
+    writeWrapped(stream, `${prefix} ${text}`, {
+      indent: options.indent ?? "",
+      subsequentIndent: options.subsequentIndent ?? "       ",
+      width: options.width,
+    });
+  }
+
+  function keyValue(label, value, options = {}) {
+    const target = options.stream ?? "stdout";
+    const stream = streamFor(target);
+    const indent = options.indent ?? "  ";
+    const subsequentIndent = options.subsequentIndent ?? "  ";
+    const renderedValue = String(value);
+
+    if (!/\s/.test(renderedValue)) {
+      writeLine(stream, `${indent}${label}: ${renderedValue}`);
+      return;
+    }
+
+    writeWrapped(stream, `${label}: ${value}`, {
+      indent,
+      subsequentIndent,
+      width: options.width,
+    });
+  }
+
+  function numberedList(items, options = {}) {
+    const target = options.stream ?? "stdout";
+    const stream = streamFor(target);
+
+    items.forEach((item, index) => {
+      const indent = `  ${index + 1}. `;
+      writeWrapped(stream, item, {
+        indent,
+        subsequentIndent: "     ",
+        width: options.width,
+      });
+    });
+  }
+
+  function commandList(items, options = {}) {
+    const target = options.stream ?? "stdout";
+    const stream = streamFor(target);
+
+    for (const item of items) {
+      writeWrapped(stream, item, {
+        indent: "  ",
+        subsequentIndent: "    ",
+        width: options.width,
+      });
+    }
+  }
+
+  function json(title, value, options = {}) {
+    const target = options.stream ?? "stdout";
+    heading(title, { stream: target });
+    writeLine(streamFor(target), JSON.stringify(value, null, 2));
+  }
+
+  return {
+    blank,
+    heading,
+    section,
+    paragraph,
+    status,
+    keyValue,
+    numberedList,
+    commandList,
+    json,
+  };
+}

package/src/run-cli.js

@@ -1,9 +1,10 @@
 import { getDefaultDashboardUrl } from "./config.js";
 import { createHarnessClient, HarnessApiError } from "./client.js";
-import { prompt, writeLine } from "./io.js";
+import { createCliUi, prompt, writeLine } from "./io.js";
 import { deleteSession, readSession, sanitizeSession, writeSession, getSessionStorageMode, SessionStoreError } from "./session-store.js";
 import { installWorkshopSkill, SkillInstallError } from "./skill-install.js";
 import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -63,38 +64,57 @@ async function readJson(response) {
   }
 }
 
-function printUsage(io) {
-  writeLine(io.stdout, "Usage:");
-  writeLine(io.stdout, "  harness --help");
-  writeLine(io.stdout, "  harness --version");
-  writeLine(io.stdout, "  harness version");
-  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 skill install [--force]");
-  writeLine(io.stdout, "  harness workshop status");
-  writeLine(io.stdout, "  harness workshop archive [--notes TEXT]");
-  writeLine(io.stdout, "  harness workshop phase set <phase-id>");
+function printUsage(io, ui) {
+  ui.heading("Harness CLI");
+  ui.paragraph(`Version ${version}`);
+  ui.blank();
+  ui.section("Usage");
+  ui.commandList([
+    "harness --help",
+    "harness --version",
+    "harness version",
+  ]);
+  ui.blank();
+  ui.section("Commands");
+  ui.commandList([
+    "harness auth login [--auth device|basic|neon] [--dashboard-url URL] [--username USER] [--email EMAIL] [--password PASS] [--no-open]",
+    "harness auth logout",
+    "harness auth status",
+    "harness skill install [--force]",
+    "harness workshop status",
+    "harness workshop archive [--notes TEXT]",
+    "harness workshop phase set <phase-id>",
+  ]);
 }
 
 function printVersion(io) {
   writeLine(io.stdout, `harness ${version}`);
 }
 
-async function handleSkillInstall(io, deps, flags) {
+async function handleSkillInstall(io, ui, deps, flags) {
   try {
     const result = await installWorkshopSkill(deps.cwd ?? process.cwd(), { force: flags.force === true });
-    writeLine(io.stdout, `Installed Harness Lab workshop skill to ${result.installPath}`);
-    writeLine(io.stdout, "Codex and OpenCode should now discover it from this repo via .agents/skills.");
-    writeLine(io.stdout, "Next steps:");
-    writeLine(io.stdout, "  1. Open Codex or OpenCode in this repo.");
-    writeLine(io.stdout, "  2. Run `/workshop reference` for the command overview.");
-    writeLine(io.stdout, "  3. Run `/workshop setup` if your environment is not ready yet.");
-    writeLine(io.stdout, "  4. Run `/workshop` to get the current phase or fallback guidance.");
+    ui.heading("Workshop Skill");
+    if (result.mode === "already_bundled") {
+      ui.status("ok", "Harness Lab workshop skill is already bundled in this repo.");
+    } else {
+      ui.status("ok", "Installed the Harness Lab workshop skill bundle.");
+    }
+    ui.keyValue("Location", result.installPath);
+    ui.keyValue("Discovery", ".agents/skills");
+    ui.blank();
+    ui.section("Next steps");
+    ui.numberedList([
+      "Open Codex or OpenCode in this repo.",
+      "Start with the workshop reference card.",
+      "Codex: `$workshop reference`. OpenCode: `/workshop reference`.",
+      "Need setup help? Codex: `$workshop setup`. OpenCode: `/workshop setup`.",
+      "Other workshop commands follow the same pattern: `$workshop ...` in Codex and `/workshop ...` in OpenCode.",
+    ]);
     return 0;
   } catch (error) {
     if (error instanceof SkillInstallError) {
-      writeLine(io.stderr, `Skill install failed: ${error.message}`);
+      ui.status("error", `Skill install failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
     throw error;
@@ -109,23 +129,23 @@ function formatStorageError(error) {
   return "Harness CLI could not access the configured session store.";
 }
 
-async function persistSession(io, env, session) {
+async function persistSession(io, ui, env, session) {
   try {
     await writeSession(env, session);
     return true;
   } catch (error) {
-    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    ui.status("error", `Session storage failed: ${formatStorageError(error)}`, { stream: "stderr" });
     return false;
   }
 }
 
-async function handleBasicAuthLogin(io, env, flags, deps) {
+async function handleBasicAuthLogin(io, ui, 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.");
+    ui.status("error", "Username and password are required.", { stream: "stderr" });
     return 1;
   }
 
@@ -142,31 +162,33 @@ async function handleBasicAuthLogin(io, env, flags, deps) {
 
   try {
     const payload = await client.verifyAccess();
-    if (!(await persistSession(io, env, session))) {
+    if (!(await persistSession(io, ui, env, session))) {
       return 1;
     }
-    writeLine(io.stdout, `Logged in to ${dashboardUrl}`);
-    writeLine(io.stdout, `Session storage: ${getSessionStorageMode(env)}`);
+    ui.heading("Auth Login");
+    ui.status("ok", "Logged in.");
+    ui.keyValue("Dashboard", dashboardUrl);
+    ui.keyValue("Session storage", getSessionStorageMode(env));
     if (payload?.workshopId) {
-      writeLine(io.stdout, `Workshop: ${payload.workshopId}`);
+      ui.keyValue("Workshop", payload.workshopId);
     }
     return 0;
   } catch (error) {
     if (error instanceof HarnessApiError) {
-      writeLine(io.stderr, `Login failed: ${error.message}`);
+      ui.status("error", `Login failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
     throw error;
   }
 }
 
-async function handleNeonAuthLogin(io, env, flags, deps) {
+async function handleNeonAuthLogin(io, ui, 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.");
+    ui.status("error", "Email and password are required.", { stream: "stderr" });
     return 1;
   }
 
@@ -187,13 +209,13 @@ async function handleNeonAuthLogin(io, env, flags, deps) {
         : 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}`);
+    ui.status("error", `Login failed: ${message}`, { stream: "stderr" });
     return 1;
   }
 
   const setCookie = signInResponse.headers?.get?.("set-cookie");
   if (!setCookie) {
-    writeLine(io.stderr, "Login failed: auth response did not include a session cookie.");
+    ui.status("error", "Login failed: auth response did not include a session cookie.", { stream: "stderr" });
     return 1;
   }
 
@@ -209,25 +231,27 @@ async function handleNeonAuthLogin(io, env, flags, deps) {
   try {
     const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
     const authSession = await client.getAuthSession();
-    if (!(await persistSession(io, env, session))) {
+    if (!(await persistSession(io, ui, env, session))) {
       return 1;
     }
-    writeLine(io.stdout, `Logged in to ${dashboardUrl}`);
-    writeLine(io.stdout, `Session storage: ${getSessionStorageMode(env)}`);
+    ui.heading("Auth Login");
+    ui.status("ok", "Logged in.");
+    ui.keyValue("Dashboard", dashboardUrl);
+    ui.keyValue("Session storage", getSessionStorageMode(env));
     if (authSession?.user?.email) {
-      writeLine(io.stdout, `Facilitator: ${authSession.user.email}`);
+      ui.keyValue("Facilitator", authSession.user.email);
     }
     return 0;
   } catch (error) {
     if (error instanceof HarnessApiError) {
-      writeLine(io.stderr, `Session verification failed: ${error.message}`);
+      ui.status("error", `Session verification failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
     throw error;
   }
 }
 
-async function handleDeviceAuthLogin(io, env, flags, deps) {
+async function handleDeviceAuthLogin(io, ui, env, flags, deps) {
   const dashboardUrl = String(flags["dashboard-url"] ?? getDefaultDashboardUrl(env));
   const client = createHarnessClient({
     fetchFn: deps.fetchFn,
@@ -236,10 +260,11 @@ async function handleDeviceAuthLogin(io, env, flags, deps) {
 
   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.");
+    ui.heading("Device Login");
+    ui.status("info", "Approve the login in a browser. The CLI will continue automatically.");
+    ui.keyValue("Open", deviceAuth.verificationUriComplete ?? deviceAuth.verificationUri);
+    ui.keyValue("Code", deviceAuth.userCode);
+    ui.keyValue("Expires", deviceAuth.expiresAt);
 
     if (flags["no-open"] !== true && typeof deps.openUrl === "function") {
       await deps.openUrl(deviceAuth.verificationUriComplete ?? deviceAuth.verificationUri);
@@ -265,42 +290,44 @@ async function handleDeviceAuthLogin(io, env, flags, deps) {
           expiresAt: result.expiresAt,
         };
 
-        if (!(await persistSession(io, env, session))) {
+        if (!(await persistSession(io, ui, env, session))) {
           return 1;
         }
 
-        writeLine(io.stdout, `Logged in to ${dashboardUrl}`);
-        writeLine(io.stdout, `Session storage: ${getSessionStorageMode(env)}`);
+        ui.blank();
+        ui.status("ok", "Logged in.");
+        ui.keyValue("Dashboard", dashboardUrl);
+        ui.keyValue("Session storage", getSessionStorageMode(env));
         if (result.session?.role) {
-          writeLine(io.stdout, `Facilitator role: ${result.session.role}`);
+          ui.keyValue("Facilitator role", result.session.role);
         }
         return 0;
       }
 
       if (result.status === "access_denied") {
-        writeLine(io.stderr, "Login failed: device authorization was denied.");
+        ui.status("error", "Login failed: device authorization was denied.", { stream: "stderr" });
         return 1;
       }
 
       if (result.status === "expired_token") {
-        writeLine(io.stderr, "Login failed: device authorization expired.");
+        ui.status("error", "Login failed: device authorization expired.", { stream: "stderr" });
         return 1;
       }
 
-      writeLine(io.stderr, "Login failed: device authorization could not be completed.");
+      ui.status("error", "Login failed: device authorization could not be completed.", { stream: "stderr" });
       return 1;
     }
 
-    writeLine(io.stderr, "Login failed: device authorization expired.");
+    ui.status("error", "Login failed: device authorization expired.", { stream: "stderr" });
     return 1;
   } catch (error) {
     if (error instanceof HarnessApiError) {
-      writeLine(io.stderr, `Login failed: ${error.message}`);
+      ui.status("error", `Login failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
 
     if (error instanceof SessionStoreError) {
-      writeLine(io.stderr, `Session storage failed: ${error.message}`);
+      ui.status("error", `Session storage failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
 
@@ -308,45 +335,45 @@ async function handleDeviceAuthLogin(io, env, flags, deps) {
   }
 }
 
-async function handleAuthLogin(io, env, flags, deps) {
+async function handleAuthLogin(io, ui, env, flags, deps) {
   const authMode = String(flags.auth ?? env.HARNESS_AUTH_MODE ?? "device");
 
   if (authMode === "device") {
-    return handleDeviceAuthLogin(io, env, flags, deps);
+    return handleDeviceAuthLogin(io, ui, env, flags, deps);
   }
 
   if (authMode === "neon") {
-    return handleNeonAuthLogin(io, env, flags, deps);
+    return handleNeonAuthLogin(io, ui, env, flags, deps);
   }
 
-  return handleBasicAuthLogin(io, env, flags, deps);
+  return handleBasicAuthLogin(io, ui, env, flags, deps);
 }
 
-async function requireSession(io, env) {
+async function requireSession(io, ui, env) {
   try {
     const session = await readSession(env);
     if (!session) {
-      writeLine(io.stderr, "No active session. Run `harness auth login` first.");
+      ui.status("error", "No active session. Run `harness auth login` first.", { stream: "stderr" });
       return null;
     }
     return session;
   } catch (error) {
-    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    ui.status("error", `Session storage failed: ${formatStorageError(error)}`, { stream: "stderr" });
     return null;
   }
 }
 
-async function handleAuthStatus(io, env, deps) {
+async function handleAuthStatus(io, ui, env, deps) {
   let session;
   try {
     session = await readSession(env);
   } catch (error) {
-    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    ui.status("error", `Session storage failed: ${formatStorageError(error)}`, { stream: "stderr" });
     return 1;
   }
 
   if (!session) {
-    writeLine(io.stdout, "Not logged in.");
+    ui.status("info", "Not logged in.");
     return 0;
   }
 
@@ -354,14 +381,11 @@ async function handleAuthStatus(io, env, deps) {
     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),
-      );
+      ui.json("Auth Status", { ok: true, session: sanitizeSession(session, env), remoteSession: deviceSession.session });
       return 0;
     } catch (error) {
       if (error instanceof HarnessApiError) {
-        writeLine(io.stdout, JSON.stringify({ ok: false, session: sanitizeSession(session, env), error: error.message }, null, 2));
+        ui.json("Auth Status", { ok: false, session: sanitizeSession(session, env), error: error.message });
         return 1;
       }
       throw error;
@@ -372,30 +396,27 @@ async function handleAuthStatus(io, env, deps) {
     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),
-      );
+      ui.json("Auth Status", { ok: true, session: sanitizeSession(session, env), remoteSession: authSession });
       return 0;
     } catch (error) {
       if (error instanceof HarnessApiError) {
-        writeLine(io.stdout, JSON.stringify({ ok: false, session: sanitizeSession(session, env), error: error.message }, null, 2));
+        ui.json("Auth Status", { ok: false, session: sanitizeSession(session, env), error: error.message });
         return 1;
       }
       throw error;
     }
   }
 
-  writeLine(io.stdout, JSON.stringify({ ok: true, session: sanitizeSession(session, env) }, null, 2));
+  ui.json("Auth Status", { ok: true, session: sanitizeSession(session, env) });
   return 0;
 }
 
-async function handleAuthLogout(io, env, deps) {
+async function handleAuthLogout(io, ui, env, deps) {
   let session;
   try {
     session = await readSession(env);
   } catch (error) {
-    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    ui.status("error", `Session storage failed: ${formatStorageError(error)}`, { stream: "stderr" });
     return 1;
   }
 
@@ -424,15 +445,15 @@ async function handleAuthLogout(io, env, deps) {
   try {
     await deleteSession(env);
   } catch (error) {
-    writeLine(io.stderr, `Session storage failed: ${formatStorageError(error)}`);
+    ui.status("error", `Session storage failed: ${formatStorageError(error)}`, { stream: "stderr" });
     return 1;
   }
-  writeLine(io.stdout, "Logged out.");
+  ui.status("ok", "Logged out.");
   return 0;
 }
 
-async function handleWorkshopStatus(io, env, deps) {
-  const session = await requireSession(io, env);
+async function handleWorkshopStatus(io, ui, env, deps) {
+  const session = await requireSession(io, ui, env);
   if (!session) {
     return 1;
   }
@@ -440,32 +461,25 @@ async function handleWorkshopStatus(io, env, deps) {
   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,
-      ),
-    );
+    ui.json("Workshop Status", {
+      ok: true,
+      workshopId: workshop.workshopId,
+      workshopMeta: workshop.workshopMeta,
+      currentPhase: agenda.phase,
+      templates: workshop.templates,
+    });
     return 0;
   } catch (error) {
     if (error instanceof HarnessApiError) {
-      writeLine(io.stderr, `Workshop status failed: ${error.message}`);
+      ui.status("error", `Workshop status failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
     throw error;
   }
 }
 
-async function handleWorkshopArchive(io, env, flags, deps) {
-  const session = await requireSession(io, env);
+async function handleWorkshopArchive(io, ui, env, flags, deps) {
+  const session = await requireSession(io, ui, env);
   if (!session) {
     return 1;
   }
@@ -473,25 +487,25 @@ async function handleWorkshopArchive(io, env, flags, deps) {
   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));
+    ui.json("Workshop Archive", result);
     return 0;
   } catch (error) {
     if (error instanceof HarnessApiError) {
-      writeLine(io.stderr, `Archive failed: ${error.message}`);
+      ui.status("error", `Archive failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
     throw error;
   }
 }
 
-async function handleWorkshopPhaseSet(io, env, positionals, deps) {
+async function handleWorkshopPhaseSet(io, ui, env, positionals, deps) {
   const phaseId = positionals[3];
   if (!phaseId) {
-    writeLine(io.stderr, "Phase id is required.");
+    ui.status("error", "Phase id is required.", { stream: "stderr" });
     return 1;
   }
 
-  const session = await requireSession(io, env);
+  const session = await requireSession(io, ui, env);
   if (!session) {
     return 1;
   }
@@ -499,11 +513,11 @@ async function handleWorkshopPhaseSet(io, env, positionals, deps) {
   try {
     const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
     const result = await client.setCurrentPhase(phaseId);
-    writeLine(io.stdout, JSON.stringify(result, null, 2));
+    ui.json("Workshop Phase", result);
     return 0;
   } catch (error) {
     if (error instanceof HarnessApiError) {
-      writeLine(io.stderr, `Phase update failed: ${error.message}`);
+      ui.status("error", `Phase update failed: ${error.message}`, { stream: "stderr" });
       return 1;
     }
     throw error;
@@ -513,11 +527,12 @@ async function handleWorkshopPhaseSet(io, env, positionals, deps) {
 export async function runCli(argv, io, deps = {}) {
   const fetchFn = deps.fetchFn ?? globalThis.fetch;
   const mergedDeps = { fetchFn, sleepFn: deps.sleepFn, openUrl: deps.openUrl, cwd: deps.cwd };
+  const ui = createCliUi(io);
   const { positionals, flags } = parseArgs(argv);
   const [scope, action, subaction] = positionals;
 
   if (flags.help === true) {
-    printUsage(io);
+    printUsage(io, ui);
     return 0;
   }
 
@@ -532,7 +547,7 @@ export async function runCli(argv, io, deps = {}) {
   }
 
   if (!scope) {
-    printUsage(io);
+    printUsage(io, ui);
     return 1;
   }
 
@@ -541,33 +556,44 @@ export async function runCli(argv, io, deps = {}) {
   }
 
   if (scope === "auth" && action === "login") {
-    return handleAuthLogin(io, io.env, flags, mergedDeps);
+    return handleAuthLogin(io, ui, io.env, flags, mergedDeps);
   }
 
   if (scope === "auth" && action === "logout") {
-    return handleAuthLogout(io, io.env, mergedDeps);
+    return handleAuthLogout(io, ui, io.env, mergedDeps);
   }
 
   if (scope === "auth" && action === "status") {
-    return handleAuthStatus(io, io.env, mergedDeps);
+    return handleAuthStatus(io, ui, io.env, mergedDeps);
   }
 
   if (scope === "skill" && action === "install") {
-    return handleSkillInstall(io, mergedDeps, flags);
+    return handleSkillInstall(io, ui, mergedDeps, flags);
   }
 
   if (scope === "workshop" && action === "status") {
-    return handleWorkshopStatus(io, io.env, mergedDeps);
+    return handleWorkshopStatus(io, ui, io.env, mergedDeps);
   }
 
   if (scope === "workshop" && action === "archive") {
-    return handleWorkshopArchive(io, io.env, flags, mergedDeps);
+    return handleWorkshopArchive(io, ui, io.env, flags, mergedDeps);
   }
 
   if (scope === "workshop" && action === "phase" && subaction === "set") {
-    return handleWorkshopPhaseSet(io, io.env, positionals, mergedDeps);
+    return handleWorkshopPhaseSet(io, ui, io.env, positionals, mergedDeps);
   }
 
-  printUsage(io);
+  printUsage(io, ui);
   return 1;
 }
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const exitCode = await runCli(process.argv.slice(2), {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    env: process.env,
+  });
+
+  process.exitCode = exitCode;
+}

package/src/skill-install.js

@@ -41,6 +41,10 @@ export function getInstalledSkillPath(repoRoot) {
   return path.join(repoRoot, ".agents", "skills", SKILL_NAME);
 }
 
+async function hasBundledRepoSkill(repoRoot) {
+  return pathExists(path.join(getInstalledSkillPath(repoRoot), "SKILL.md"));
+}
+
 export async function installWorkshopSkill(startDir, options = {}) {
   const repoRoot = await findHarnessLabRepoRoot(startDir);
   if (!repoRoot) {
@@ -51,6 +55,17 @@ export async function installWorkshopSkill(startDir, options = {}) {
   }
 
   const installPath = getInstalledSkillPath(repoRoot);
+  const bundledRepoSkill = await hasBundledRepoSkill(repoRoot);
+
+  if (bundledRepoSkill) {
+    return {
+      repoRoot,
+      installPath,
+      skillName: SKILL_NAME,
+      mode: "already_bundled",
+    };
+  }
+
   if ((await pathExists(installPath)) && options.force !== true) {
     throw new SkillInstallError(
       `Skill already installed at ${installPath}. Re-run with --force to replace it.`,
@@ -78,5 +93,10 @@ export async function installWorkshopSkill(startDir, options = {}) {
     path.join(installPath, "docs", "harness-cli-foundation.md"),
   );
 
-  return { repoRoot, installPath, skillName: SKILL_NAME };
+  return {
+    repoRoot,
+    installPath,
+    skillName: SKILL_NAME,
+    mode: "installed",
+  };
 }