@harness-lab/cli 0.2.1 → 0.2.2

package/assets/workshop-bundle/workshop-skill/template-agents.md

@@ -0,0 +1,35 @@
+# AGENTS.md Starter
+
+Použijte to jako krátkou mapu repa. Ne jako encyklopedii. Když detail patří jinam, odkažte na konkrétní soubor místo kopírování dlouhého textu.
+
+Nejdůležitější pravidlo:
+- napište, kam má agent sáhnout jako první
+- napište, co je source of truth
+- napište, jak se práce ověří
+- když se text nafukuje, přidejte deeper doc a odkažte na něj
+
+## Goal
+
+Popiš, co má agent v tomto repozitáři vytvořit nebo udržovat.
+
+## Context
+
+- Klíčové soubory a složky
+- Rozhodnutí, která už padla
+- Systémy nebo integrace, na které se navazuje
+- Kam má agent sáhnout jako první
+- Které docs nebo runbooky jsou source of truth
+
+## Constraints
+
+- Build/test/lint příkazy
+- Jazykové, architektonické a bezpečnostní standardy
+- Co agent nesmí dělat bez explicitního souhlasu
+- Public/private nebo auth boundary, pokud existuje
+
+## Done When
+
+- Jak poznáme, že je práce hotová
+- Jaké ověření musí proběhnout
+- Jak má vypadat handoff pro dalšího člověka nebo agenta
+- Jaký bude další safe move, pokud práce zůstane rozdělaná

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-lab/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Participant-facing Harness Lab CLI for facilitator auth and workshop operations",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,12 +20,13 @@
     "ai-agents"
   ],
   "engines": {
-    "node": ">=24"
+    "node": "22.x"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
+    "assets",
     "bin",
     "src",
     "README.md"
@@ -37,6 +38,10 @@
     "chalk": "^5.6.2"
   },
   "scripts": {
-    "test": "node --test"
+    "preverify:workshop-bundle": "node ./scripts/sync-workshop-bundle.mjs --with-repo-bundle",
+    "prepack": "node ./scripts/sync-workshop-bundle.mjs",
+    "sync:workshop-bundle": "node ./scripts/sync-workshop-bundle.mjs --with-repo-bundle",
+    "verify:workshop-bundle": "node ./scripts/verify-workshop-bundle.mjs",
+    "test": "npm run verify:workshop-bundle && node --test"
   }
 }

package/src/run-cli.js

@@ -173,7 +173,7 @@ function printUsage(io, ui) {
     "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 skill install [--target PATH] [--force]",
     "harness workshop status",
     "harness workshop archive [--notes TEXT]",
     "harness workshop create-instance [<instance-id>] [--template-id ID] [--event-title TEXT] [--city CITY]",
@@ -190,23 +190,30 @@ function printVersion(io) {
 
 async function handleSkillInstall(io, ui, deps, flags) {
   try {
-    const result = await installWorkshopSkill(deps.cwd ?? process.cwd(), { force: flags.force === true });
+    const result = await installWorkshopSkill(deps.cwd ?? process.cwd(), {
+      force: flags.force === true,
+      target: readStringFlag(flags, "target"),
+    });
     ui.heading("Workshop Skill");
-    if (result.mode === "already_bundled") {
-      ui.status("ok", "Harness Lab workshop skill is already bundled in this repo.");
+    if (result.mode === "already_current") {
+      ui.status("ok", "Harness Lab workshop skill is already current at the target path.");
+    } else if (result.mode === "refreshed") {
+      ui.status("ok", "Refreshed the installed Harness Lab workshop skill bundle.");
     } else {
       ui.status("ok", "Installed the Harness Lab workshop skill bundle.");
     }
+    ui.keyValue("Target", result.targetRoot);
     ui.keyValue("Location", result.installPath);
     ui.keyValue("Discovery", ".agents/skills");
+    ui.keyValue("Bundle source", result.sourceMode === "packaged_bundle" ? "packaged portable bundle" : "source checkout fallback");
     ui.blank();
     ui.section("Next steps");
     ui.numberedList([
-      "Open Codex or pi in this repo.",
-      "Start with the workshop reference card.",
-      "Codex: `$workshop reference`.",
-      "pi: `/skill:workshop`, then ask for the workshop reference card.",
-      "Need setup help? Codex: `$workshop setup`. pi: `/skill:workshop`, then ask for setup help.",
+      "Open Codex or pi in the target repo.",
+      "Start with the workshop command menu.",
+      "Codex: `$workshop commands`.",
+      "pi: `/skill:workshop`, then ask for the workshop commands.",
+      "Next: `$workshop reference`, `$workshop brief`, and `$workshop resources`.",
     ]);
     return 0;
   } catch (error) {

package/src/skill-install.js

@@ -1,5 +1,16 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import {
+  createWorkshopBundleManifestFromDirectory,
+  createWorkshopBundleManifestFromSource,
+  createWorkshopBundleFromSource,
+  getInstalledSkillPath,
+  getPackagedWorkshopBundlePath,
+  getRepoWorkshopSourceRoot,
+  pathExists,
+  readWorkshopBundleManifest,
+  WORKSHOP_SKILL_NAME,
+} from "./workshop-bundle.js";
 
 export class SkillInstallError extends Error {
   constructor(message, options = {}) {
@@ -9,94 +20,124 @@ export class SkillInstallError extends Error {
   }
 }
 
-const SKILL_NAME = "harness-lab-workshop";
+async function resolveBundleSource() {
+  const packagedBundlePath = getPackagedWorkshopBundlePath();
+  if (await pathExists(path.join(packagedBundlePath, "SKILL.md"))) {
+    return {
+      mode: "packaged_bundle",
+      sourcePath: packagedBundlePath,
+      sourceRoot: packagedBundlePath,
+    };
+  }
 
-async function pathExists(targetPath) {
-  try {
-    await fs.access(targetPath);
-    return true;
-  } catch {
-    return false;
+  const repoSourceRoot = getRepoWorkshopSourceRoot();
+  if (await pathExists(path.join(repoSourceRoot, "workshop-skill", "SKILL.md"))) {
+    return {
+      mode: "repo_source",
+      sourcePath: repoSourceRoot,
+      sourceRoot: repoSourceRoot,
+    };
   }
+
+  return null;
 }
 
-export async function findHarnessLabRepoRoot(startDir) {
-  let currentDir = path.resolve(startDir);
+async function ensureDirectory(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+  const stat = await fs.stat(targetPath);
+  if (!stat.isDirectory()) {
+    throw new SkillInstallError(`Install target is not a directory: ${targetPath}`, {
+      code: "invalid_target",
+    });
+  }
+}
 
-  while (true) {
-    if (await pathExists(path.join(currentDir, "workshop-skill", "SKILL.md"))) {
-      return currentDir;
-    }
+async function hasInstalledSkill(targetRoot) {
+  return pathExists(path.join(getInstalledSkillPath(targetRoot), "SKILL.md"));
+}
 
-    const parentDir = path.dirname(currentDir);
-    if (parentDir === currentDir) {
-      return null;
+async function getSourceBundleManifest(resolvedBundle) {
+  if (resolvedBundle.mode === "packaged_bundle") {
+    const manifest = await readWorkshopBundleManifest(resolvedBundle.sourcePath);
+    if (manifest) {
+      return manifest;
     }
 
-    currentDir = parentDir;
+    return createWorkshopBundleManifestFromDirectory(resolvedBundle.sourcePath);
   }
-}
 
-export function getInstalledSkillPath(repoRoot) {
-  return path.join(repoRoot, ".agents", "skills", SKILL_NAME);
+  return createWorkshopBundleManifestFromSource(resolvedBundle.sourceRoot);
 }
 
-async function hasBundledRepoSkill(repoRoot) {
-  return pathExists(path.join(getInstalledSkillPath(repoRoot), "SKILL.md"));
+async function installFromResolvedBundle(resolvedBundle, installPath) {
+  if (resolvedBundle.mode === "packaged_bundle") {
+    await fs.cp(resolvedBundle.sourcePath, installPath, { recursive: true });
+    return;
+  }
+
+  await createWorkshopBundleFromSource(resolvedBundle.sourceRoot, installPath);
 }
 
 export async function installWorkshopSkill(startDir, options = {}) {
-  const repoRoot = await findHarnessLabRepoRoot(startDir);
-  if (!repoRoot) {
+  const resolvedBundle = await resolveBundleSource();
+  if (!resolvedBundle) {
     throw new SkillInstallError(
-      "Harness CLI could not find `workshop-skill/SKILL.md`. Run this command inside a Harness Lab repo checkout.",
-      { code: "repo_not_found" },
+      "Harness CLI could not find a portable workshop bundle. Reinstall `@harness-lab/cli` or run from a Harness Lab source checkout.",
+      { code: "bundle_not_found" },
     );
   }
 
-  const installPath = getInstalledSkillPath(repoRoot);
-  const bundledRepoSkill = await hasBundledRepoSkill(repoRoot);
+  const targetRoot = path.resolve(startDir, options.target ?? ".");
+  await ensureDirectory(targetRoot);
+
+  const installPath = getInstalledSkillPath(targetRoot);
+  const existingInstall = await hasInstalledSkill(targetRoot);
+  const sourceManifest = await getSourceBundleManifest(resolvedBundle);
+
+  if (existingInstall && options.force !== true) {
+    const installedManifest = await createWorkshopBundleManifestFromDirectory(installPath);
+    if (installedManifest.contentHash === sourceManifest.contentHash) {
+      return {
+        installPath,
+        skillName: WORKSHOP_SKILL_NAME,
+        mode: "already_current",
+        sourceMode: resolvedBundle.mode,
+        targetRoot,
+      };
+    }
+
+    await fs.rm(installPath, { recursive: true, force: true });
 
-  if (bundledRepoSkill) {
     return {
-      repoRoot,
-      installPath,
-      skillName: SKILL_NAME,
-      mode: "already_bundled",
+      ...(await installFreshBundle(resolvedBundle, installPath, targetRoot)),
+      mode: "refreshed",
     };
   }
 
-  if ((await pathExists(installPath)) && options.force !== true) {
-    throw new SkillInstallError(
-      `Skill already installed at ${installPath}. Re-run with --force to replace it.`,
-      { code: "already_installed" },
-    );
+  if (existingInstall && options.force === true) {
+    await fs.rm(installPath, { recursive: true, force: true });
   }
 
-  if (options.force === true) {
-    await fs.rm(installPath, { recursive: true, force: true });
+  const result = await installFreshBundle(resolvedBundle, installPath, targetRoot);
+  if (existingInstall && options.force === true) {
+    return {
+      ...result,
+      mode: "refreshed",
+    };
   }
 
-  await fs.mkdir(installPath, { recursive: true });
-  await fs.cp(path.join(repoRoot, "workshop-skill"), path.join(installPath, "workshop-skill"), { recursive: true });
-  await fs.cp(path.join(repoRoot, "content"), path.join(installPath, "content"), { recursive: true });
-  await fs.cp(path.join(repoRoot, "workshop-blueprint"), path.join(installPath, "workshop-blueprint"), { recursive: true });
-  await fs.rm(path.join(installPath, "workshop-skill", "SKILL.md"), { force: true });
-  await fs.mkdir(path.join(installPath, "docs"), { recursive: true });
-  await fs.copyFile(path.join(repoRoot, "workshop-skill", "SKILL.md"), path.join(installPath, "SKILL.md"));
-  await fs.copyFile(
-    path.join(repoRoot, "docs", "workshop-event-context-contract.md"),
-    path.join(installPath, "docs", "workshop-event-context-contract.md"),
-  );
-  await fs.copyFile(
-    path.join(repoRoot, "docs", "harness-cli-foundation.md"),
-    path.join(installPath, "docs", "harness-cli-foundation.md"),
-  );
+  return result;
+}
+
+async function installFreshBundle(resolvedBundle, installPath, targetRoot) {
+  await fs.mkdir(path.dirname(installPath), { recursive: true });
+  await installFromResolvedBundle(resolvedBundle, installPath);
 
   return {
-    repoRoot,
     installPath,
-    skillName: SKILL_NAME,
+    skillName: WORKSHOP_SKILL_NAME,
     mode: "installed",
+    sourceMode: resolvedBundle.mode,
+    targetRoot,
   };
 }

package/src/workshop-bundle.js

@@ -0,0 +1,233 @@
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const WORKSHOP_SKILL_NAME = "harness-lab-workshop";
+export const WORKSHOP_BUNDLE_MANIFEST = "bundle-manifest.json";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+
+const DIRECTORY_COPIES = [
+  ["workshop-skill", "workshop-skill"],
+  ["content", "content"],
+  ["workshop-blueprint", "workshop-blueprint"],
+];
+
+const FILE_COPIES = [
+  ["workshop-skill/SKILL.md", "SKILL.md"],
+  ["docs/workshop-event-context-contract.md", "docs/workshop-event-context-contract.md"],
+  ["docs/harness-cli-foundation.md", "docs/harness-cli-foundation.md"],
+  ["docs/learner-resource-kit.md", "docs/learner-resource-kit.md"],
+  ["docs/learner-reference-gallery.md", "docs/learner-reference-gallery.md"],
+  ["materials/participant-resource-kit.md", "materials/participant-resource-kit.md"],
+];
+
+export function getPackageRoot() {
+  return packageRoot;
+}
+
+export function getPackagedWorkshopBundlePath() {
+  return path.join(packageRoot, "assets", "workshop-bundle");
+}
+
+export function getRepoWorkshopSourceRoot() {
+  return path.resolve(packageRoot, "..");
+}
+
+export function getRepoBundledWorkshopSkillPath() {
+  return path.join(getRepoWorkshopSourceRoot(), ".agents", "skills", WORKSHOP_SKILL_NAME);
+}
+
+export function getInstalledSkillPath(targetRoot) {
+  return path.join(targetRoot, ".agents", "skills", WORKSHOP_SKILL_NAME);
+}
+
+export function getBundleManifestPath(bundleRoot) {
+  return path.join(bundleRoot, WORKSHOP_BUNDLE_MANIFEST);
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyDirectoryTree(sourceRoot, targetRoot) {
+  for (const [sourceRelativePath, targetRelativePath] of DIRECTORY_COPIES) {
+    await fs.cp(path.join(sourceRoot, sourceRelativePath), path.join(targetRoot, targetRelativePath), { recursive: true });
+  }
+}
+
+async function copyBundleFiles(sourceRoot, targetRoot) {
+  for (const [sourceRelativePath, targetRelativePath] of FILE_COPIES) {
+    const targetPath = path.join(targetRoot, targetRelativePath);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.copyFile(path.join(sourceRoot, sourceRelativePath), targetPath);
+  }
+}
+
+function normalizePathForManifest(targetPath) {
+  return targetPath.split(path.sep).join("/");
+}
+
+async function listFilesRecursive(rootPath) {
+  const entries = [];
+
+  async function walk(currentPath, relativePrefix = "") {
+    const dirEntries = await fs.readdir(currentPath, { withFileTypes: true });
+    dirEntries.sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of dirEntries) {
+      const entryRelativePath = relativePrefix ? path.join(relativePrefix, entry.name) : entry.name;
+      const entryPath = path.join(currentPath, entry.name);
+
+      if (entry.isDirectory()) {
+        await walk(entryPath, entryRelativePath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        entries.push({
+          absolutePath: entryPath,
+          relativePath: normalizePathForManifest(entryRelativePath),
+        });
+      }
+    }
+  }
+
+  await walk(rootPath);
+  return entries;
+}
+
+async function readPackageVersion() {
+  const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+  return String(packageJson.version);
+}
+
+async function createManifestFromEntries(entries) {
+  const bundleVersion = await readPackageVersion();
+  const files = [];
+
+  for (const entry of entries) {
+    const contents = await fs.readFile(entry.absolutePath);
+    const sha256 = crypto.createHash("sha256").update(contents).digest("hex");
+    files.push({
+      path: entry.relativePath,
+      sha256,
+    });
+  }
+
+  files.sort((left, right) => left.path.localeCompare(right.path));
+
+  const contentHash = crypto
+    .createHash("sha256")
+    .update(
+      files
+        .map((file) => `${file.path}:${file.sha256}`)
+        .join("\n"),
+    )
+    .digest("hex");
+
+  return {
+    manifestVersion: 1,
+    bundleName: WORKSHOP_SKILL_NAME,
+    bundleVersion,
+    contentHash,
+    files,
+  };
+}
+
+export async function createWorkshopBundleManifestFromDirectory(bundleRoot) {
+  const files = await listFilesRecursive(bundleRoot);
+  return createManifestFromEntries(
+    files.filter((file) => file.relativePath !== WORKSHOP_BUNDLE_MANIFEST),
+  );
+}
+
+export async function createWorkshopBundleManifestFromSource(sourceRoot) {
+  const entries = [];
+
+  for (const [sourceRelativePath, targetRelativePath] of DIRECTORY_COPIES) {
+    const sourceDirectory = path.join(sourceRoot, sourceRelativePath);
+    const sourceFiles = await listFilesRecursive(sourceDirectory);
+
+    for (const file of sourceFiles) {
+      const targetRelative = normalizePathForManifest(path.join(targetRelativePath, file.relativePath));
+      if (targetRelative === "workshop-skill/SKILL.md") {
+        continue;
+      }
+
+      entries.push({
+        absolutePath: file.absolutePath,
+        relativePath: targetRelative,
+      });
+    }
+  }
+
+  for (const [sourceRelativePath, targetRelativePath] of FILE_COPIES) {
+    entries.push({
+      absolutePath: path.join(sourceRoot, sourceRelativePath),
+      relativePath: normalizePathForManifest(targetRelativePath),
+    });
+  }
+
+  return createManifestFromEntries(entries);
+}
+
+export async function readWorkshopBundleManifest(bundleRoot) {
+  try {
+    const manifest = JSON.parse(await fs.readFile(getBundleManifestPath(bundleRoot), "utf8"));
+    if (!manifest || typeof manifest.contentHash !== "string") {
+      return null;
+    }
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+async function writeWorkshopBundleManifest(bundleRoot, manifest) {
+  await fs.writeFile(
+    getBundleManifestPath(bundleRoot),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+export async function createWorkshopBundleFromSource(sourceRoot, targetRoot, options = {}) {
+  if (options.clean === true) {
+    await fs.rm(targetRoot, { recursive: true, force: true });
+  }
+  await fs.mkdir(targetRoot, { recursive: true });
+  await copyDirectoryTree(sourceRoot, targetRoot);
+  await fs.rm(path.join(targetRoot, "workshop-skill", "SKILL.md"), { force: true });
+  await copyBundleFiles(sourceRoot, targetRoot);
+  const manifest = await createWorkshopBundleManifestFromSource(sourceRoot);
+  await writeWorkshopBundleManifest(targetRoot, manifest);
+}
+
+export async function syncPackagedWorkshopBundle() {
+  const sourceRoot = getRepoWorkshopSourceRoot();
+  const bundleRoot = getPackagedWorkshopBundlePath();
+  await createWorkshopBundleFromSource(sourceRoot, bundleRoot, { clean: true });
+  return {
+    sourceRoot,
+    bundleRoot,
+  };
+}
+
+export async function syncRepoBundledWorkshopSkill() {
+  const sourceRoot = getRepoWorkshopSourceRoot();
+  const bundleRoot = getRepoBundledWorkshopSkillPath();
+  await createWorkshopBundleFromSource(sourceRoot, bundleRoot, { clean: true });
+  return {
+    sourceRoot,
+    bundleRoot,
+  };
+}