@zebralabs/context-cli 0.1.0 → 0.1.3

package/package.json

@@ -1,13 +1,22 @@
 {
     "name": "@zebralabs/context-cli",
-    "version": "0.1.0",
+    "version": "0.1.3",
     "description": "Context-as-Code CLI (help/list/compile/validate)",
     "license": "MIT",
     "type": "module",
     "bin": {
         "ctx": "src/context.js"
     },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
     "dependencies": {
-        "yaml": "^2.5.0"
+        "yaml": "^2.5.0",
+        "extract-zip": "^2.0.1"
+    },
+    "scripts": {
+        "smoke": "node src/context.js help"
     }
 }

package/src/context.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import os from "node:os";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -16,23 +16,32 @@ function showHelp() {
 Context-as-Code CLI
 
 Usage:
-  context help
-  context list
-  context compile
-  context validate
-
-Commands:
-  list     Show installed packs and the documentation roots they contribute.
-  compile  Build a single AI-ready context bundle at practices-and-standards/.compiled/.
-           Output: system-prompt.md (paste/upload to AI), sources.md (what was included), report.md.
-  validate Validate that context.yaml and pack manifests are consistent and files exist.
+  ctx help
+  ctx list
+  ctx compile
+  ctx validate
+
+Pack install:
+  ctx pack install <packId> [--repo-root <path>] [--mode SkipExisting|Overwrite]
+                           ([--zip <path>] | [--registry <url> [--version <x.y.z>] --token <token>])
+
+Examples (local zip test):
+  ctx pack install pack-01-documentation-management --zip D:\\packs\\pack-01-documentation-management-v0.1.0.zip
+
+Examples (registry download):
+  ctx pack install pack-01-documentation-management --registry https://example.com --token YOURTOKEN
+  ctx pack install pack-01-documentation-management --registry https://example.com --token YOURTOKEN --version 0.1.0
+
+Notes:
+- Zip must contain: practices-and-standards/install.ps1
+- Installer merges into <repo-root>/docs/practices-and-standards/
 `.trim() + "\n");
 }
 
 function findRepoContextRoot(startDir) {
   let dir = startDir;
   while (true) {
-    const candidate = path.join(dir, "practices-and-standards", "context.yaml");
+    const candidate = path.join(dir, "docs", "practices-and-standards", "context.yaml");
     if (fs.existsSync(candidate)) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) return null;
@@ -62,7 +71,6 @@ function listMarkdownFiles(dir) {
 }
 
 function stripFrontmatter(text) {
-  // Remove YAML frontmatter if the file starts with ---
   if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return text;
   const lines = text.split(/\r?\n/);
   let fenceCount = 0;
@@ -76,7 +84,7 @@ function stripFrontmatter(text) {
       }
     }
   }
-  if (endIndex === -1) return text; // malformed; keep
+  if (endIndex === -1) return text;
   return lines.slice(endIndex + 1).join("\n");
 }
 
@@ -92,7 +100,6 @@ function orderInstalledPacks(installed, precedence) {
       byId.delete(id);
     }
   }
-  // stable remainder in original order
   for (const p of installed) {
     if (byId.has(p.id)) {
       ordered.push(p);
@@ -103,7 +110,6 @@ function orderInstalledPacks(installed, precedence) {
 }
 
 function resolvePackManifestPath(repoRoot, manifestRel) {
-  // manifestRel in your schema is "practices-and-standards/packs/..."
   return path.join(repoRoot, manifestRel);
 }
 
@@ -137,7 +143,6 @@ function cmdValidate(repoRoot, ctx) {
     warnings.push("No installed packs found in context.yaml");
   }
 
-  // duplicate installed ids
   const seen = new Set();
   for (const p of installed) {
     if (!p?.id) errors.push("Installed pack missing id");
@@ -148,13 +153,11 @@ function cmdValidate(repoRoot, ctx) {
     if (!p?.manifest) errors.push(`Pack '${p?.id ?? "unknown"}' missing manifest path`);
   }
 
-  // precedence unknown ids
   const installedIds = new Set(installed.map(p => p.id).filter(Boolean));
   for (const pid of precedence) {
     if (!installedIds.has(pid)) warnings.push(`precedence references unknown pack id: ${pid}`);
   }
 
-  // manifest checks
   for (const p of installed) {
     if (!p?.id || !p?.manifest) continue;
 
@@ -165,18 +168,6 @@ function cmdValidate(repoRoot, ctx) {
     }
 
     const pack = readYamlFile(manifestPath);
-    const manifestId = pack?.id;
-    if (manifestId && manifestId !== p.id) {
-      warnings.push(`Pack '${p.id}' manifest id mismatch: manifest says '${manifestId}'`);
-    }
-
-    const parts = p.manifest.split(/[\\/]/);
-    const packsIdx = parts.indexOf("packs");
-    const folderId = (packsIdx >= 0 && parts[packsIdx + 1]) ? parts[packsIdx + 1] : null;
-    if (folderId && folderId !== p.id) {
-      warnings.push(`Pack '${p.id}' manifest folder mismatch: path folder is '${folderId}'`);
-    }
-
     const roots = pack?.contributes?.roots ?? [];
     if (!Array.isArray(roots) || roots.length === 0) {
       warnings.push(`Pack '${p.id}' has no contributes.roots`);
@@ -208,7 +199,8 @@ function cmdValidate(repoRoot, ctx) {
 
 function cmdCompile(repoRoot, ctx) {
   const installed = orderInstalledPacks(ctx.installed_packs ?? [], ctx.precedence ?? []);
-  const outDir = path.join(repoRoot, "practices-and-standards", ".compiled");
+  const psRoot = path.join(repoRoot, "docs", "practices-and-standards");
+  const outDir = path.join(psRoot, ".compiled");
   fs.mkdirSync(outDir, { recursive: true });
 
   const promptPath = path.join(outDir, "system-prompt.md");
@@ -296,32 +288,41 @@ function ensureDir(p) {
 }
 
 function writeYamlFile(filePath, obj) {
-  fs.writeFileSync(filePath, YAML.stringify(obj), "utf8");
+  const text = YAML.stringify(obj, { indent: 2 });
+  fs.writeFileSync(filePath, text.endsWith("\n") ? text : (text + "\n"), "utf8");
 }
 
-function readYamlIfExists(filePath) {
-  if (!fs.existsSync(filePath)) return null;
-  return readYamlFile(filePath);
+function readYamlFileSafe(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  try {
+    return YAML.parse(raw);
+  } catch (e) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backup = `${filePath}.backup-${stamp}.yaml`;
+    fs.copyFileSync(filePath, backup);
+    return null;
+  }
 }
 
-function isWindows() {
-  return process.platform === "win32";
+function readYamlIfExistsSafe(filePath) {
+  if(!fs.existsSync(filePath)) return null;
+  return readYamlFileSafe(filePath);
 }
 
-function findPwsh() {
-  // Prefer pwsh (PowerShell 7). Fallback to Windows PowerShell on Windows.
-  // We'll just try spawning; if it fails, we fallback.
-  return "pwsh";
+function isWindows() {
+  return process.platform === "win32";
 }
 
 function runPwsh(command, { cwd } = {}) {
-  let exe = findPwsh();
+  // Prefer pwsh, fallback to powershell (Windows PowerShell)
+  let exe = "pwsh";
   let r = spawnSync(exe, ["-NoProfile", "-Command", command], { stdio: "inherit", cwd });
-  if (r.error && isWindows()) {
-    // fallback to Windows PowerShell
+
+  if ((r.error || r.status !== 0) && isWindows()) {
     exe = "powershell";
     r = spawnSync(exe, ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", command], { stdio: "inherit", cwd });
   }
+
   if (r.status !== 0) {
     die(`PowerShell command failed (exit ${r.status}): ${command}`);
   }
@@ -351,11 +352,11 @@ async function fetchJson(url, token) {
 }
 
 function ensureContextInitialized(repoRoot, registryUrlMaybe) {
-  const psRoot = path.join(repoRoot, "practices-and-standards");
+  const psRoot = path.join(repoRoot, "docs", "practices-and-standards");
   ensureDir(psRoot);
 
   const ctxPath = path.join(psRoot, "context.yaml");
-  let ctx = readYamlIfExists(ctxPath);
+  let ctx = readYamlIfExistsSafe(ctxPath);
 
   if (!ctx) {
     ctx = {
@@ -366,7 +367,6 @@ function ensureContextInitialized(repoRoot, registryUrlMaybe) {
     };
     writeYamlFile(ctxPath, ctx);
   } else {
-    // Ensure schema exists
     if (!ctx.schema) ctx.schema = "context-install/v1";
     if (registryUrlMaybe && !ctx.registry) ctx.registry = registryUrlMaybe;
     if (!Array.isArray(ctx.installed_packs)) ctx.installed_packs = [];
@@ -377,10 +377,26 @@ function ensureContextInitialized(repoRoot, registryUrlMaybe) {
   return { ctxPath, ctx, psRoot };
 }
 
+function normalizeContext(ctx) {
+  const out = (ctx && typeof ctx === "object") ? ctx : {};
+  out.schema = out.schema || "context-install/v1";
+
+  if (!Array.isArray(out.installed_packs)) out.installed_packs = [];
+  if (!Array.isArray(out.precedence)) out.precedence = [];
+
+  // Defensive: remove accidental duplicates / wrong shapes
+  out.installed_packs = out.installed_packs.filter(p => p && typeof p === "object");
+  out.precedence = out.precedence.filter(x => typeof x === "string");
+
+  return out;
+}
+
+
 function upsertInstalledPack(ctxObj, packId, version) {
   if (!Array.isArray(ctxObj.installed_packs)) ctxObj.installed_packs = [];
+  if (!Array.isArray(ctxObj.precedence)) ctxObj.precedence = [];
 
-  const manifest = `practices-and-standards/packs/${packId}/pack.yaml`;
+  const manifest = `docs/practices-and-standards/packs/${packId}/pack.yaml`;
   const existing = ctxObj.installed_packs.find(p => p.id === packId);
 
   if (existing) {
@@ -390,68 +406,129 @@ function upsertInstalledPack(ctxObj, packId, version) {
     ctxObj.installed_packs.push({ id: packId, version, manifest });
   }
 
-  // Keep precedence additive unless user already configured it
   if (!Array.isArray(ctxObj.precedence)) ctxObj.precedence = [];
   if (!ctxObj.precedence.includes(packId)) ctxObj.precedence.push(packId);
 }
 
 async function cmdPackInstall(repoRoot, packId, opts) {
-  const token = opts.token;
-  if (!token) die("Missing required --token");
+  const mode = opts.mode || "SkipExisting";
+  if (!["SkipExisting", "Overwrite"].includes(mode)) {
+    die("Invalid --mode. Use SkipExisting or Overwrite.");
+  }
 
-  // init or load context
+  // init or load context.yaml (always)
   const { ctxPath, ctx } = ensureContextInitialized(repoRoot, opts.registry);
 
-  // Determine registry
-  const registry = opts.registry || ctx.registry;
-  if (!registry) die("No registry configured. Provide --registry <url> or set registry: in practices-and-standards/context.yaml");
-
-  // Determine version
-  let version = opts.version;
-  if (!version) {
-    const latestUrl = `${registry.replace(/\/$/, "")}/packs/${encodeURIComponent(packId)}/latest`;
-    const latest = await fetchJson(latestUrl, token);
-    version = latest?.version;
-    if (!version) die(`Registry did not return a version from ${latestUrl}`);
-  }
-
-  // Download zip
+  // Create temp workspace
   const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), "context-pack-"));
-  const zipPath = path.join(tmpBase, `${packId}-${version}.zip`);
   const extractDir = path.join(tmpBase, "extract");
   ensureDir(extractDir);
 
-  const dlUrl = `${registry.replace(/\/$/, "")}/packs/${encodeURIComponent(packId)}/${encodeURIComponent(version)}/download`;
-  console.log(`\nDownloading ${packId}@${version}...`);
-  await downloadToFile(dlUrl, token, zipPath);
+  try {
+    let zipPath = null;
+    let version = opts.version;
 
-  // Expand zip using PowerShell (no Node unzip deps)
-  console.log("Extracting...");
-  runPwsh(`Expand-Archive -Path "${zipPath}" -DestinationPath "${extractDir}" -Force`);
+    if (opts.zip) {
+      zipPath = path.isAbsolute(opts.zip) ? opts.zip : path.join(process.cwd(), opts.zip);
+      if (!fs.existsSync(zipPath)) die(`Zip not found: ${zipPath}`);
+      // version will be discovered from pack.yaml after extraction if not provided
+    } else {
+      const token = opts.token;
+      if (!token) die("Missing required --token for registry install.");
 
-  // Find installer inside extracted zip
-  // Your zips contain: practices-and-standards/install.ps1 at the root of the zip payload
-  const extractedPsRoot = path.join(extractDir, "practices-and-standards");
-  const installer = path.join(extractedPsRoot, "install.ps1");
-  if (!fs.existsSync(installer)) {
-    die(`Downloaded pack does not contain practices-and-standards/install.ps1 (looked at: ${installer})`);
-  }
+      const registry = opts.registry || ctx.registry;
+      if (!registry) die("No registry configured. Provide --registry <url> or set registry: in docs/practices-and-standards/context.yaml");
 
-  // Run installer: it will merge into repoRoot/practices-and-standards
-  console.log("Installing (merge)...");
-  const cmd = `& "${installer}" -TargetRoot "${repoRoot}" -PackId "${packId}" -Mode "SkipExisting"`;
-  runPwsh(cmd, { cwd: extractDir });
+      if (!version) {
+        const latestUrl = `${registry.replace(/\/$/, "")}/packs/${encodeURIComponent(packId)}/latest`;
+        const latest = await fetchJson(latestUrl, token);
+        version = latest?.version;
+        if (!version) die(`Registry did not return a version from ${latestUrl}`);
+      }
 
-  // Update context.yaml
-  const ctx2 = readYamlFile(ctxPath);
-  upsertInstalledPack(ctx2, packId, version);
-  if (opts.registry && !ctx2.registry) ctx2.registry = opts.registry;
-  writeYamlFile(ctxPath, ctx2);
+      const dlUrl = `${registry.replace(/\/$/, "")}/packs/${encodeURIComponent(packId)}/${encodeURIComponent(version)}/download`;
+      zipPath = path.join(tmpBase, `${packId}-${version}.zip`);
+      console.log(`\nDownloading ${packId}@${version}...`);
+      await downloadToFile(dlUrl, token, zipPath);
+    }
 
-  console.log("\n✅ Pack installed.");
-  console.log(`- Pack: ${packId} @ ${version}`);
-  console.log(`- Updated: ${path.relative(repoRoot, ctxPath).replaceAll("\\", "/")}`);
-  console.log("");
+    // Extract zip
+    console.log("Extracting...");
+    runPwsh(`Expand-Archive -Path "${zipPath}" -DestinationPath "${extractDir}" -Force`);
+
+    // Find installer
+    const installer = path.join(extractDir, "practices-and-standards", "install.ps1");
+    if (!fs.existsSync(installer)) {
+      die(`Pack zip does not contain practices-and-standards/install.ps1 (looked at: ${installer})`);
+    }
+
+    if (!version) {
+      const packYamlPath = path.join(
+        extractDir,
+        "practices-and-standards",
+        "packs",
+        packId,
+        "pack.yaml"
+      );
+    
+      if (fs.existsSync(packYamlPath)) {
+        const packMeta = readYamlFile(packYamlPath);
+        if (packMeta?.version) version = String(packMeta.version);
+      }
+    
+      if (!version) version = "0.0.0";
+    }
+    
+    // Run installer
+    console.log(`Installing (mode=${mode})...`);
+    const installCmd = `& "${installer}" -TargetRoot "${repoRoot}" -PackId "${packId}" -Mode "${mode}"`;
+    runPwsh(installCmd, { cwd: extractDir });
+
+    // Update context.yaml (safe read + repair)
+    let ctx2 = readYamlFileSafe(ctxPath);
+    if (!ctx2) {
+      // If YAML was corrupted by an external process, repair by resetting to a clean baseline.
+      ctx2 = {
+        schema: "context-install/v1",
+        ...(opts.registry ? { registry: opts.registry } : {}),
+        installed_packs: [],
+        precedence: []
+      };
+    }
+
+    ctx2 = normalizeContext(ctx2);
+
+    upsertInstalledPack(ctx2, packId, version);
+
+    if (!Array.isArray(ctx2.precedence)) ctx2.precedence = [];
+    if (!ctx2.precedence.includes(packId)) ctx2.precedence.push(packId);
+    if (opts.registry && !ctx2.registry) ctx2.registry = opts.registry;
+
+    writeYamlFile(ctxPath, ctx2);
+
+
+    console.log("\n✅ Pack installed.");
+    console.log(`- Pack: ${packId} @ ${version}`);
+    console.log(`- Updated: ${path.relative(repoRoot, ctxPath).replaceAll("\\", "/")}`);
+    console.log("");
+  } finally {
+    try { fs.rmSync(tmpBase, { recursive: true, force: true }); } catch {}
+  }
+}
+
+function parseOpts(args) {
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--token") opts.token = args[++i];
+    else if (a === "--version") opts.version = args[++i];
+    else if (a === "--registry") opts.registry = args[++i];
+    else if (a === "--zip") opts.zip = args[++i];
+    else if (a === "--mode") opts.mode = args[++i];
+    else if (a === "--repo-root") opts.repoRoot = args[++i];
+    else die(`Unknown option: ${a}`);
+  }
+  return opts;
 }
 
 
@@ -460,7 +537,12 @@ async function main() {
 
   if (cmd === "help") { showHelp(); return; }
 
-  // pack subcommands
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    // Make sure package.json has version (or hardcode a constant)
+    console.log("0.1.3");
+    return;
+  }
+
   if (cmd === "pack") {
     const sub = (process.argv[3] ?? "").toLowerCase();
     if (sub !== "install") {
@@ -470,22 +552,13 @@ async function main() {
     }
 
     const packId = process.argv[4];
-    if (!packId) die("Usage: context pack install <packId> --token <token> [--version <v>] [--registry <url>]");
-
-    // parse flags
-    const args = process.argv.slice(5);
-    const opts = {};
-    for (let i = 0; i < args.length; i++) {
-      const a = args[i];
-      if (a === "--token") opts.token = args[++i];
-      else if (a === "--version") opts.version = args[++i];
-      else if (a === "--registry") opts.registry = args[++i];
-      else die(`Unknown option: ${a}`);
-    }
+    if (!packId) die("Usage: ctx pack install <packId> [--zip <path>] | [--registry <url> --token <token> ...]");
+
+    const opts = parseOpts(process.argv.slice(5));
 
-    // Repo root: prefer existing context.yaml search, else assume cwd is repo root
-    const found = findRepoContextRoot(process.cwd());
-    const repoRoot = found ?? process.cwd();
+    const repoRoot = opts.repoRoot
+      ? (path.isAbsolute(opts.repoRoot) ? opts.repoRoot : path.join(process.cwd(), opts.repoRoot))
+      : (findRepoContextRoot(process.cwd()) ?? process.cwd());
 
     await cmdPackInstall(repoRoot, packId, opts);
     return;
@@ -493,9 +566,9 @@ async function main() {
 
   // Existing behavior: these require an existing context.yaml
   const repoRoot = findRepoContextRoot(process.cwd());
-  if (!repoRoot) die("Could not find practices-and-standards/context.yaml in this directory or any parent.");
+  if (!repoRoot) die("Could not find docs/practices-and-standards/context.yaml in this directory or any parent.");
 
-  const contextPath = path.join(repoRoot, "practices-and-standards", "context.yaml");
+  const contextPath = path.join(repoRoot, "docs", "practices-and-standards", "context.yaml");
   const ctx = readYamlFile(contextPath);
 
   if (!ctx?.schema || ctx.schema !== "context-install/v1") {
@@ -514,4 +587,3 @@ async function main() {
 }
 
 main().catch(e => die(e?.stack || String(e)));
-