@harness-lab/cli 0.2.9 → 0.3.0

package/src/run-cli.js

@@ -166,6 +166,19 @@ function summarizeWorkshopInstance(instance) {
   };
 }
 
+function summarizeParticipantAccess(participantAccess) {
+  return {
+    instanceId: participantAccess?.instanceId ?? null,
+    active: participantAccess?.active ?? false,
+    version: participantAccess?.version ?? null,
+    codeId: participantAccess?.codeId ?? null,
+    expiresAt: participantAccess?.expiresAt ?? null,
+    canRevealCurrent: participantAccess?.canRevealCurrent ?? false,
+    source: participantAccess?.source ?? "missing",
+    currentCode: participantAccess?.currentCode ?? null,
+  };
+}
+
 function resolveCurrentInstanceTarget(session, env) {
   if (typeof session?.selectedInstanceId === "string" && session.selectedInstanceId.trim().length > 0) {
     return {
@@ -210,6 +223,7 @@ function printUsage(io, ui) {
     "harness workshop status",
     "harness workshop list-instances",
     "harness workshop show-instance <instance-id>",
+    "harness workshop participant-access [<instance-id>] [--rotate] [--code VALUE]",
     "harness workshop archive [--notes TEXT]",
     "harness workshop create-instance [<instance-id>] [--template-id ID] [--content-lang cs|en] [--event-title TEXT] [--city CITY]",
     "harness workshop update-instance <instance-id> [--content-lang cs|en] [--event-title TEXT] [--city CITY]",
@@ -592,6 +606,22 @@ async function handleAuthLogout(io, ui, env, deps) {
   return 0;
 }
 
+function renderSelectedInstanceBanner(ui, target) {
+  if (ui.jsonMode) {
+    return;
+  }
+  const instanceId = target.instanceId ?? "none";
+  const label = target.source === "session"
+    ? "Selected instance (locally selected)"
+    : target.instanceId
+      ? `Selected instance (from ${target.source})`
+      : "Selected instance";
+  ui.keyValue(label, instanceId);
+  if (!target.instanceId) {
+    ui.keyValue("", "no instance is currently selected — run `harness workshop select-instance <id>` to pin one");
+  }
+}
+
 async function handleWorkshopStatus(io, ui, env, deps) {
   const session = await requireSession(io, ui, env);
   if (!session) {
@@ -602,6 +632,8 @@ async function handleWorkshopStatus(io, ui, env, deps) {
     const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
     const target = resolveCurrentInstanceTarget(session, env);
 
+    renderSelectedInstanceBanner(ui, target);
+
     if (target.source === "session" && target.instanceId) {
       const [instanceResult, agenda] = await Promise.all([
         client.getWorkshopInstance(target.instanceId),
@@ -609,6 +641,11 @@ async function handleWorkshopStatus(io, ui, env, deps) {
       ]);
       ui.json("Workshop Status", {
         ok: true,
+        selectedInstance: {
+          instanceId: target.instanceId,
+          source: target.source,
+          selected: true,
+        },
         targetInstanceId: target.instanceId,
         targetSource: target.source,
         ...summarizeWorkshopInstance(instanceResult.instance),
@@ -622,6 +659,11 @@ async function handleWorkshopStatus(io, ui, env, deps) {
     const [workshop, agenda] = await Promise.all([client.getWorkshopStatus(), client.getAgenda()]);
     ui.json("Workshop Status", {
       ok: true,
+      selectedInstance: {
+        instanceId: target.instanceId ?? null,
+        source: target.source,
+        selected: Boolean(target.instanceId),
+      },
       targetInstanceId: target.instanceId,
       targetSource: target.source,
       workshopId: workshop.workshopId,
@@ -801,6 +843,55 @@ async function handleWorkshopShowInstance(io, ui, env, positionals, flags, deps)
   }
 }
 
+async function handleWorkshopParticipantAccess(io, ui, env, positionals, flags, deps) {
+  const session = await requireSession(io, ui, env);
+  if (!session) {
+    return 1;
+  }
+
+  const instanceId = await readRequiredCommandValue(
+    io,
+    flags,
+    ["id", "instance-id"],
+    "Instance id: ",
+    readOptionalPositional(positionals, 2) ?? session.selectedInstanceId,
+  );
+  if (!instanceId) {
+    ui.status("error", "Instance id is required.", { stream: "stderr" });
+    return 1;
+  }
+
+  try {
+    const client = createHarnessClient({ fetchFn: deps.fetchFn, session });
+    if (flags.rotate === true) {
+      const result = await client.issueWorkshopParticipantAccess(instanceId, {
+        ...(typeof flags.code === "string" ? { code: flags.code } : {}),
+      });
+      ui.json("Workshop Participant Access", {
+        ok: true,
+        issuedCode: result.issuedCode ?? null,
+        ...summarizeParticipantAccess(result.participantAccess),
+        participantAccess: result.participantAccess,
+      });
+      return 0;
+    }
+
+    const result = await client.getWorkshopParticipantAccess(instanceId);
+    ui.json("Workshop Participant Access", {
+      ok: true,
+      ...summarizeParticipantAccess(result.participantAccess),
+      participantAccess: result.participantAccess,
+    });
+    return 0;
+  } catch (error) {
+    if (error instanceof HarnessApiError) {
+      ui.status("error", `Participant access failed: ${error.message}`, { stream: "stderr" });
+      return 1;
+    }
+    throw error;
+  }
+}
+
 async function handleWorkshopArchive(io, ui, env, flags, deps) {
   const session = await requireSession(io, ui, env);
   if (!session) {
@@ -1118,6 +1209,10 @@ export async function runCli(argv, io, deps = {}) {
     return handleWorkshopShowInstance(io, ui, io.env, positionals, flags, mergedDeps);
   }
 
+  if (scope === "workshop" && action === "participant-access") {
+    return handleWorkshopParticipantAccess(io, ui, io.env, positionals, flags, mergedDeps);
+  }
+
   if (scope === "workshop" && action === "archive") {
     return handleWorkshopArchive(io, ui, io.env, flags, mergedDeps);
   }

package/src/skill-install.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import process from "node:process";
 import {
   createWorkshopBundleManifestFromDirectory,
   createWorkshopBundleManifestFromSource,
@@ -12,6 +13,8 @@ import {
   WORKSHOP_SKILL_NAME,
 } from "./workshop-bundle.js";
 
+const MIN_NODE_MAJOR = 22;
+
 export class SkillInstallError extends Error {
   constructor(message, options = {}) {
     super(message);
@@ -20,6 +23,81 @@ export class SkillInstallError extends Error {
   }
 }
 
+function assertSupportedNodeVersion() {
+  const raw = process.versions?.node;
+  if (!raw) {
+    return;
+  }
+  const major = Number.parseInt(raw.split(".")[0], 10);
+  if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
+    throw new SkillInstallError(
+      `Harness CLI requires Node.js ${MIN_NODE_MAJOR} or newer. This process is running Node.js ${raw}. Upgrade with your version manager (for example \`nvm install --lts\`) and re-run \`harness skill install\`.`,
+      { code: "unsupported_node_version" },
+    );
+  }
+}
+
+function translateFileSystemError(error, context) {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    return null;
+  }
+
+  const targetPath = error.path ? ` (${error.path})` : "";
+
+  if (error.code === "EACCES" || error.code === "EPERM") {
+    return new SkillInstallError(
+      `Harness CLI could not ${context}${targetPath} because the current user does not have write permission. Try running from a directory you own, or adjust the directory permissions. On macOS and Linux, that usually means avoiding system paths like /usr. On Windows, avoid running from a protected location such as C:\\Program Files.`,
+      { code: "install_permission_denied" },
+    );
+  }
+
+  if (error.code === "ENOSPC") {
+    return new SkillInstallError(
+      `Harness CLI could not ${context}${targetPath} because the disk is full. Free some space and re-run \`harness skill install\`.`,
+      { code: "install_no_space" },
+    );
+  }
+
+  if (error.code === "ENAMETOOLONG" || error.code === "ENOTDIR") {
+    return new SkillInstallError(
+      `Harness CLI could not ${context}${targetPath}. The target path is too long or part of it is not a directory. On Windows, this often happens when the repository lives in a deeply nested folder — move the repo closer to the drive root (for example C:\\repos\\your-project) and try again.`,
+      { code: "install_path_invalid" },
+    );
+  }
+
+  if (error.code === "EROFS") {
+    return new SkillInstallError(
+      `Harness CLI could not ${context}${targetPath} because the file system is read-only. Re-run \`harness skill install\` from a writable directory.`,
+      { code: "install_read_only" },
+    );
+  }
+
+  if (error.code === "EBUSY") {
+    return new SkillInstallError(
+      `Harness CLI could not ${context}${targetPath} because the target is busy (another process may hold it open). Close editors or agents pointing at \`.agents/skills/\` and re-run \`harness skill install\`.`,
+      { code: "install_target_busy" },
+    );
+  }
+
+  return null;
+}
+
+async function fsWithActionableError(operation, context) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof SkillInstallError) {
+      throw error;
+    }
+    const translated = translateFileSystemError(error, context);
+    if (translated) {
+      translated.cause = error;
+      throw translated;
+    }
+    throw error;
+  }
+}
+
 async function resolveBundleSource() {
   const packagedBundlePath = getPackagedWorkshopBundlePath();
   if (await pathExists(path.join(packagedBundlePath, "SKILL.md"))) {
@@ -43,8 +121,14 @@ async function resolveBundleSource() {
 }
 
 async function ensureDirectory(targetPath) {
-  await fs.mkdir(targetPath, { recursive: true });
-  const stat = await fs.stat(targetPath);
+  await fsWithActionableError(
+    () => fs.mkdir(targetPath, { recursive: true }),
+    `create the install target directory`,
+  );
+  const stat = await fsWithActionableError(
+    () => fs.stat(targetPath),
+    `inspect the install target directory`,
+  );
   if (!stat.isDirectory()) {
     throw new SkillInstallError(`Install target is not a directory: ${targetPath}`, {
       code: "invalid_target",
@@ -71,14 +155,22 @@ async function getSourceBundleManifest(resolvedBundle) {
 
 async function installFromResolvedBundle(resolvedBundle, installPath) {
   if (resolvedBundle.mode === "packaged_bundle") {
-    await fs.cp(resolvedBundle.sourcePath, installPath, { recursive: true });
+    await fsWithActionableError(
+      () => fs.cp(resolvedBundle.sourcePath, installPath, { recursive: true }),
+      `copy the workshop bundle into the install target`,
+    );
     return;
   }
 
-  await createWorkshopBundleFromSource(resolvedBundle.sourceRoot, installPath);
+  await fsWithActionableError(
+    () => createWorkshopBundleFromSource(resolvedBundle.sourceRoot, installPath),
+    `build the workshop bundle from source into the install target`,
+  );
 }
 
 export async function installWorkshopSkill(startDir, options = {}) {
+  assertSupportedNodeVersion();
+
   const resolvedBundle = await resolveBundleSource();
   if (!resolvedBundle) {
     throw new SkillInstallError(
@@ -106,7 +198,10 @@ export async function installWorkshopSkill(startDir, options = {}) {
       };
     }
 
-    await fs.rm(installPath, { recursive: true, force: true });
+    await fsWithActionableError(
+      () => fs.rm(installPath, { recursive: true, force: true }),
+      `remove the previous workshop bundle before refreshing it`,
+    );
 
     return {
       ...(await installFreshBundle(resolvedBundle, installPath, targetRoot)),
@@ -115,7 +210,10 @@ export async function installWorkshopSkill(startDir, options = {}) {
   }
 
   if (existingInstall && options.force === true) {
-    await fs.rm(installPath, { recursive: true, force: true });
+    await fsWithActionableError(
+      () => fs.rm(installPath, { recursive: true, force: true }),
+      `remove the previous workshop bundle before reinstalling`,
+    );
   }
 
   const result = await installFreshBundle(resolvedBundle, installPath, targetRoot);
@@ -130,7 +228,10 @@ export async function installWorkshopSkill(startDir, options = {}) {
 }
 
 async function installFreshBundle(resolvedBundle, installPath, targetRoot) {
-  await fs.mkdir(path.dirname(installPath), { recursive: true });
+  await fsWithActionableError(
+    () => fs.mkdir(path.dirname(installPath), { recursive: true }),
+    `create the parent directory for the installed skill`,
+  );
   await installFromResolvedBundle(resolvedBundle, installPath);
 
   return {

package/src/workshop-bundle.js

@@ -26,8 +26,26 @@ const FILE_COPIES = [
   ["docs/locales/en/learner-reference-gallery.md", "docs/locales/en/learner-reference-gallery.md"],
   ["materials/participant-resource-kit.md", "materials/participant-resource-kit.md"],
   ["materials/locales/en/participant-resource-kit.md", "materials/locales/en/participant-resource-kit.md"],
+  ["materials/coaching-codex.md", "materials/coaching-codex.md"],
 ];
 
+// Files that live inside DIRECTORY_COPIES source trees but must not ship to
+// participants. These are author/maintainer/copy-editor artifacts that have no
+// runtime purpose inside the installed workshop skill. Keep the set minimal —
+// every entry should be a file that (a) has no workshop-skill reference and
+// (b) is clearly authoring/governance content rather than participant-facing.
+const EXCLUDED_BUNDLE_PATHS = new Set([
+  "content/style-guide.md",
+  "content/style-examples.md",
+  "content/czech-reject-list.md",
+  "content/czech-editorial-review-checklist.md",
+  "workshop-blueprint/edit-boundaries.md",
+]);
+
+function isExcludedBundlePath(bundleRelativePath) {
+  return EXCLUDED_BUNDLE_PATHS.has(normalizePathForManifest(bundleRelativePath));
+}
+
 export function getPackageRoot() {
   return packageRoot;
 }
@@ -66,24 +84,31 @@ async function copyDirectoryTree(sourceRoot, targetRoot) {
     await copyDirectoryRecursive(
       path.join(sourceRoot, sourceRelativePath),
       path.join(targetRoot, targetRelativePath),
+      targetRelativePath,
     );
   }
 }
 
-async function copyDirectoryRecursive(sourcePath, targetPath) {
+async function copyDirectoryRecursive(sourcePath, targetPath, bundleRelativePrefix) {
   const entries = await fs.readdir(sourcePath, { withFileTypes: true });
   await fs.mkdir(targetPath, { recursive: true });
 
   for (const entry of entries) {
     const sourceEntryPath = path.join(sourcePath, entry.name);
     const targetEntryPath = path.join(targetPath, entry.name);
+    const entryBundleRelativePath = bundleRelativePrefix
+      ? path.join(bundleRelativePrefix, entry.name)
+      : entry.name;
 
     if (entry.isDirectory()) {
-      await copyDirectoryRecursive(sourceEntryPath, targetEntryPath);
+      await copyDirectoryRecursive(sourceEntryPath, targetEntryPath, entryBundleRelativePath);
       continue;
     }
 
     if (entry.isFile()) {
+      if (isExcludedBundlePath(entryBundleRelativePath)) {
+        continue;
+      }
       await fs.copyFile(sourceEntryPath, targetEntryPath);
     }
   }
@@ -187,6 +212,9 @@ export async function createWorkshopBundleManifestFromSource(sourceRoot) {
       if (targetRelative === "workshop-skill/SKILL.md") {
         continue;
       }
+      if (isExcludedBundlePath(targetRelative)) {
+        continue;
+      }
 
       entries.push({
         absolutePath: file.absolutePath,

package/assets/workshop-bundle/content/czech-editorial-review-checklist.md

@@ -1,88 +0,0 @@
-# Czech Editorial Review Checklist
-
-Použijte tento checklist při revizi českého obsahu pro účastníky, hlavně pro:
-
-- workshop agenda a presenter scenes
-- pokyny pro participant room
-- project briefs
-- challenge cards
-- setup, reference, recap, follow-up a learner-kit materiály
-
-Tento checklist doplňuje [`content/style-guide.md`](./style-guide.md) a [`content/style-examples.md`](./style-examples.md). Není to náhrada. Je to poslední quality gate před tím, než se text bere jako workshop-ready.
-
-## 1. Přirozenost češtiny
-
-- Zní text jako přirozená čeština, ne jako překlad?
-- Přečetl by to český developer bez škobrtnutí?
-- Nejsou ve větách doslovné anglické kalky?
-- Nejsou věty zbytečně dlouhé nebo toporné?
-
-## 2. Kvalita míchání češtiny a angličtiny
-
-- Zůstává česká věta česká?
-- Jsou anglické termíny použité jen tam, kde jsou v developerské praxi opravdu přirozené?
-- Není v textu náhodně promíchaná angličtina jen proto, že původní zdroj byl anglický?
-- Když se méně známý anglický termín objevuje poprvé, je stručně ukotvený česky?
-
-## 3. Jasnost instrukce
-
-- Je z textu jasné, co má člověk udělat právě teď?
-- Mají věty konkrétní slovesa jako `spusťte`, `zkontrolujte`, `doplňte`, `ověřte`?
-- Neschovává se akce za abstraktní formulace typu „je vhodné realizovat“?
-- Nejsou odstavce přeplněné více cíli najednou?
-
-## 4. Workshop voice
-
-- Zní text jako zkušený peer, ne jako marketér nebo korporát?
-- Drží se text klidného, věcného a praktického tónu?
-- Nezní text jako slide, slogan nebo generický AI obsah?
-- Je z textu cítit disciplína workshopu: kontext zapsaný v repu, ověření, handoff?
-
-## 5. Terminologická disciplína
-
-- Jsou opakované workshop terms použité konzistentně?
-- Neobjevují se slabé nebo matoucí fráze jen proto, že znějí „AI-ish“?
-- Jsou výrazy jako `safe move`, `handoff`, `checkpoint`, `workflow`, `review`, `skill`, `runbook` použité záměrně, ne náhodně?
-- Není stejná věc jednou česky a podruhé napůl anglicky bez důvodu?
-
-## 6. Vyhněte se těmto signálům
-
-Pokud se v textu objeví něco z toho, vraťte ho do editace:
-
-- doslovný překlad anglické vazby
-- česká věta s náhodně vloženými anglickými slovy mimo technické termíny
-- korporátní nebo školometský tón
-- fráze, které nic nekotví k akci
-- generické AI obraty bez konkrétního významu
-
-## 7. Spoken check
-
-Přečtěte text nahlas nebo aspoň polohlasem.
-
-Text vrátit do editace, pokud:
-
-- se nedá říct plynule
-- obsahuje nepřirozený slovosled
-- zní tvrdě přeloženě
-- potřebuje v hlavě „opravovat“, co tím autor asi myslel
-
-## 8. Cross-locale check
-
-Pokud text vznikal z anglického source:
-
-- není to doslovný překlad?
-- drží česká verze stejný význam, ale přirozenější formulací?
-- není česká verze výrazně slabší, plošší nebo méně konkrétní než anglická?
-- není anglický source sám o sobě slabý a nehodí se nejdřív přepsat?
-
-## 9. Before publish
-
-Před schválením českého textu pro účastníky musí být možné říct `ano` na všechno:
-
-1. Je to přirozená čeština?
-2. Rozumí tomu český developer napoprvé?
-3. Je jasné, co má člověk udělat nebo pochopit?
-4. Drží text workshop voice bez hype a bez korporátu?
-5. Je míchání češtiny a angličtiny disciplinované?
-6. Neobsahuje text slabé fráze nebo „AI slop“?
-7. Obstojí text při čtení nahlas?

package/assets/workshop-bundle/content/style-examples.md

@@ -1,127 +0,0 @@
-# Czech Style Examples
-
-## Do / Don't
-
-### 1. Instrukce
-
-Do:
-
-- „Otevřete repozitář a nejdřív doplňte `AGENTS.md`.“
-
-Don't:
-
-- „V prvním kroku je vhodné provést vytvoření souboru `AGENTS.md`.“
-
-### 2. Setup
-
-Do:
-
-- „Když se setup sekne, přejděte na Codex App nebo web fallback.“
-
-Don't:
-
-- „V případě komplikací v procesu instalace je možné využít alternativní variantu přístupu.“
-
-### 3. Facilitation
-
-Do:
-
-- „Prvních 10 minut po rotaci jen čtěte a mapujte repo.“
-
-Don't:
-
-- „Po realizaci rotace doporučujeme zahájit aktivitu detailní analýzou repozitáře.“
-
-### 4. Workshop framing
-
-Do:
-
-- „Dnes nejde o to být nejrychlejší. Jde o to předat práci tak, aby ji cizí tým dokázal převzít.“
-
-Don't:
-
-- „Hlavním cílem dnešního dne je maximalizace schopnosti efektivního předávání výstupů mezi týmy.“
-
-### 5. Czech + English
-
-Do:
-
-- „Nejdřív spusťte `/plan`, potom implementujte malý krok a nakonec udělejte `/review`.“
-
-Don't:
-
-- „Nejdříve vytvořte plán, pak proveďte implementaci a následně zrevidujte změnu.“
-
-Poznámka:
-
-Tady je angličtina přirozenější, protože jde o konkrétní commands a workflow terms.
-
-### 6. Technical explanation
-
-Do:
-
-- „Monitoring teď běží jako manuální MVP. Ondřej spustí scan repozitářů a z výsledku připraví intermezzo brief.“
-
-Don't:
-
-- „Monitoring je aktuálně realizován prostřednictvím minimální životaschopné verze manuálního typu.“
-
-### 7. Briefs
-
-Do:
-
-- „Mock data jsou v pořádku, pokud workflow působí realisticky.“
-
-Don't:
-
-- „Použití simulovaných dat je akceptovatelné za předpokladu, že výsledný proces bude působit realisticky.“
-
-### 8. Error / fallback messaging
-
-Do:
-
-- „Pokud vám nefunguje CLI, pokračujte přes App a neztrácejte dalších 20 minut.“
-
-Don't:
-
-- „V případě nefunkčnosti rozhraní příkazové řádky doporučujeme zvážit alternativní postup.“
-
-## Approved English Terms
-
-Tyto výrazy se v textech pro účastníky běžně nechávají v angličtině:
-
-- `prompt`
-- `review`
-- `workflow`
-- `skill`
-- `runbook`
-- `build`
-- `deploy`
-- `checkpoint`
-- `fallback`
-- `handoff`
-- `CLI`
-- `App`
-- `repo`
-- `README`
-- `AGENTS.md`
-- `Done When`
-
-## Usually Better In Czech
-
-Tyto části bývají lepší česky:
-
-- cíle a instrukce
-- facilitační věty
-- reflexe a uzavírání
-- vysvětlení, proč něco děláme
-- očekávání a pravidla workshopu
-
-## Rewrite Heuristic
-
-Když text zní moc tvrdě přeloženě, uprav ho takto:
-
-1. zkrať větu
-2. vrať české sloveso do aktivního rodu
-3. nech technický termín v angličtině
-4. zkontroluj, že věta vede k akci