@zebralabs/context-cli 0.1.0

package/package.json

@@ -0,0 +1,13 @@
+{
+    "name": "@zebralabs/context-cli",
+    "version": "0.1.0",
+    "description": "Context-as-Code CLI (help/list/compile/validate)",
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "ctx": "src/context.js"
+    },
+    "dependencies": {
+        "yaml": "^2.5.0"
+    }
+}

package/src/context.js

@@ -0,0 +1,517 @@
+#!/usr/bin/env node
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import YAML from "yaml";
+
+function die(msg, code = 1) {
+  console.error(`ERROR: ${msg}`);
+  process.exit(code);
+}
+
+function showHelp() {
+  console.log(`
+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.
+`.trim() + "\n");
+}
+
+function findRepoContextRoot(startDir) {
+  let dir = startDir;
+  while (true) {
+    const candidate = path.join(dir, "practices-and-standards", "context.yaml");
+    if (fs.existsSync(candidate)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readYamlFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  return YAML.parse(raw);
+}
+
+function listMarkdownFiles(dir) {
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    const entries = fs.readdirSync(cur, { withFileTypes: true });
+    for (const e of entries) {
+      const full = path.join(cur, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile() && e.name.toLowerCase().endsWith(".md")) out.push(full);
+    }
+  }
+  out.sort((a, b) => a.localeCompare(b));
+  return out;
+}
+
+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;
+  let endIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      fenceCount++;
+      if (fenceCount === 2) {
+        endIndex = i;
+        break;
+      }
+    }
+  }
+  if (endIndex === -1) return text; // malformed; keep
+  return lines.slice(endIndex + 1).join("\n");
+}
+
+function orderInstalledPacks(installed, precedence) {
+  if (!Array.isArray(precedence) || precedence.length === 0) return installed;
+
+  const byId = new Map(installed.map(p => [p.id, p]));
+  const ordered = [];
+
+  for (const id of precedence) {
+    if (byId.has(id)) {
+      ordered.push(byId.get(id));
+      byId.delete(id);
+    }
+  }
+  // stable remainder in original order
+  for (const p of installed) {
+    if (byId.has(p.id)) {
+      ordered.push(p);
+      byId.delete(p.id);
+    }
+  }
+  return ordered;
+}
+
+function resolvePackManifestPath(repoRoot, manifestRel) {
+  // manifestRel in your schema is "practices-and-standards/packs/..."
+  return path.join(repoRoot, manifestRel);
+}
+
+function cmdList(repoRoot, ctx) {
+  const installed = orderInstalledPacks(ctx.installed_packs ?? [], ctx.precedence ?? []);
+
+  console.log("\nInstalled Context Packs");
+  console.log("-----------------------");
+  for (const p of installed) {
+    const manifestPath = resolvePackManifestPath(repoRoot, p.manifest);
+    if (!fs.existsSync(manifestPath)) die(`Missing pack manifest: ${manifestPath}`);
+
+    const pack = readYamlFile(manifestPath);
+    const roots = pack?.contributes?.roots ?? [];
+
+    console.log(`\n- ${p.id} @ ${p.version}`);
+    console.log("  Contributes:");
+    for (const r of roots) console.log(`    - ${r}`);
+  }
+  console.log("");
+}
+
+function cmdValidate(repoRoot, ctx) {
+  const errors = [];
+  const warnings = [];
+
+  const installed = ctx.installed_packs ?? [];
+  const precedence = ctx.precedence ?? [];
+
+  if (!Array.isArray(installed) || installed.length === 0) {
+    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");
+    else {
+      if (seen.has(p.id)) errors.push(`Duplicate installed pack id: ${p.id}`);
+      seen.add(p.id);
+    }
+    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;
+
+    const manifestPath = resolvePackManifestPath(repoRoot, p.manifest);
+    if (!fs.existsSync(manifestPath)) {
+      errors.push(`Pack '${p.id}' manifest not found: ${manifestPath}`);
+      continue;
+    }
+
+    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`);
+    } else {
+      for (const r of roots) {
+        const rootPath = path.join(repoRoot, r);
+        if (!fs.existsSync(rootPath)) errors.push(`Pack '${p.id}' contributes root missing on disk: ${r}`);
+      }
+    }
+  }
+
+  console.log("\nValidation Report");
+  console.log("-----------------");
+
+  if (errors.length === 0) console.log("✅ OK: No blocking errors found.");
+  else {
+    console.log("❌ Errors:");
+    for (const e of errors) console.log(`  - ${e}`);
+  }
+
+  if (warnings.length > 0) {
+    console.log("\n⚠️ Warnings:");
+    for (const w of warnings) console.log(`  - ${w}`);
+  }
+
+  console.log("");
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+function cmdCompile(repoRoot, ctx) {
+  const installed = orderInstalledPacks(ctx.installed_packs ?? [], ctx.precedence ?? []);
+  const outDir = path.join(repoRoot, "practices-and-standards", ".compiled");
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const promptPath = path.join(outDir, "system-prompt.md");
+  const sourcesPath = path.join(outDir, "sources.md");
+  const reportPath = path.join(outDir, "report.md");
+
+  const compiledPacks = [];
+  const sources = [];
+  const docFiles = [];
+
+  for (const p of installed) {
+    const manifestPath = resolvePackManifestPath(repoRoot, p.manifest);
+    if (!fs.existsSync(manifestPath)) die(`Missing pack manifest: ${manifestPath}`);
+
+    const pack = readYamlFile(manifestPath);
+    compiledPacks.push(`- ${p.id} @ ${p.version}`);
+
+    const roots = pack?.contributes?.roots ?? [];
+    for (const r of roots) {
+      const rootPath = path.join(repoRoot, r);
+      if (!fs.existsSync(rootPath)) continue;
+      const files = listMarkdownFiles(rootPath);
+      for (const f of files) {
+        docFiles.push(f);
+        sources.push(path.relative(repoRoot, f).replaceAll("\\", "/"));
+      }
+    }
+  }
+
+  docFiles.sort((a, b) => a.localeCompare(b));
+
+  const lines = [];
+  lines.push("# AI Context: Engineering & Documentation Standards", "");
+  lines.push("You must follow the standards and methodologies below.", "");
+
+  for (const f of docFiles) {
+    let content = fs.readFileSync(f, "utf8");
+    content = stripFrontmatter(content);
+
+    lines.push("");
+    lines.push(`## Source: ${path.basename(f)}`);
+    lines.push("");
+    lines.push(content.trimEnd());
+  }
+
+  fs.writeFileSync(promptPath, lines.join("\n") + "\n", "utf8");
+
+  const uniqSources = [...new Set(sources)].sort();
+  fs.writeFileSync(
+    sourcesPath,
+    ["# Context Sources", "", ...uniqSources.map(s => `- ${s}`)].join("\n") + "\n",
+    "utf8"
+  );
+
+  const promptSizeBytes = fs.statSync(promptPath).size;
+  const report = [
+    "# Context Compile Report",
+    "",
+    `- Date: ${new Date().toISOString()}`,
+    `- Documents included: ${docFiles.length}`,
+    `- Unique sources: ${uniqSources.length}`,
+    `- system-prompt.md size: ${promptSizeBytes} bytes`,
+    "",
+    "## Packs Compiled",
+    ...compiledPacks,
+    "",
+    "## Outputs",
+    `- ${path.relative(repoRoot, promptPath).replaceAll("\\", "/")}`,
+    `- ${path.relative(repoRoot, sourcesPath).replaceAll("\\", "/")}`,
+    `- ${path.relative(repoRoot, reportPath).replaceAll("\\", "/")}`
+  ].join("\n") + "\n";
+
+  fs.writeFileSync(reportPath, report, "utf8");
+
+  console.log("\nContext compiled successfully");
+  console.log("Output:");
+  console.log(`  ${promptPath}`);
+  console.log(`  ${sourcesPath}`);
+  console.log(`  ${reportPath}`);
+  console.log("");
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function writeYamlFile(filePath, obj) {
+  fs.writeFileSync(filePath, YAML.stringify(obj), "utf8");
+}
+
+function readYamlIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return readYamlFile(filePath);
+}
+
+function isWindows() {
+  return process.platform === "win32";
+}
+
+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 runPwsh(command, { cwd } = {}) {
+  let exe = findPwsh();
+  let r = spawnSync(exe, ["-NoProfile", "-Command", command], { stdio: "inherit", cwd });
+  if (r.error && isWindows()) {
+    // fallback to Windows PowerShell
+    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}`);
+  }
+}
+
+async function downloadToFile(url, token, outPath) {
+  const res = await fetch(url, {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    die(`Download failed (${res.status} ${res.statusText}): ${url}\n${body}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  fs.writeFileSync(outPath, buf);
+}
+
+async function fetchJson(url, token) {
+  const res = await fetch(url, {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    die(`Request failed (${res.status} ${res.statusText}): ${url}\n${body}`);
+  }
+  return await res.json();
+}
+
+function ensureContextInitialized(repoRoot, registryUrlMaybe) {
+  const psRoot = path.join(repoRoot, "practices-and-standards");
+  ensureDir(psRoot);
+
+  const ctxPath = path.join(psRoot, "context.yaml");
+  let ctx = readYamlIfExists(ctxPath);
+
+  if (!ctx) {
+    ctx = {
+      schema: "context-install/v1",
+      ...(registryUrlMaybe ? { registry: registryUrlMaybe } : {}),
+      installed_packs: [],
+      precedence: []
+    };
+    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 = [];
+    if (!Array.isArray(ctx.precedence)) ctx.precedence = [];
+    writeYamlFile(ctxPath, ctx);
+  }
+
+  return { ctxPath, ctx, psRoot };
+}
+
+function upsertInstalledPack(ctxObj, packId, version) {
+  if (!Array.isArray(ctxObj.installed_packs)) ctxObj.installed_packs = [];
+
+  const manifest = `practices-and-standards/packs/${packId}/pack.yaml`;
+  const existing = ctxObj.installed_packs.find(p => p.id === packId);
+
+  if (existing) {
+    existing.version = version;
+    existing.manifest = manifest;
+  } else {
+    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");
+
+  // init or load context
+  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
+  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);
+
+  // Expand zip using PowerShell (no Node unzip deps)
+  console.log("Extracting...");
+  runPwsh(`Expand-Archive -Path "${zipPath}" -DestinationPath "${extractDir}" -Force`);
+
+  // 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})`);
+  }
+
+  // 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 });
+
+  // Update context.yaml
+  const ctx2 = readYamlFile(ctxPath);
+  upsertInstalledPack(ctx2, packId, version);
+  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("");
+}
+
+
+async function main() {
+  const cmd = (process.argv[2] ?? "help").toLowerCase();
+
+  if (cmd === "help") { showHelp(); return; }
+
+  // pack subcommands
+  if (cmd === "pack") {
+    const sub = (process.argv[3] ?? "").toLowerCase();
+    if (sub !== "install") {
+      console.log(`Unknown pack subcommand: ${sub}\n`);
+      showHelp();
+      process.exit(1);
+    }
+
+    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}`);
+    }
+
+    // Repo root: prefer existing context.yaml search, else assume cwd is repo root
+    const found = findRepoContextRoot(process.cwd());
+    const repoRoot = found ?? process.cwd();
+
+    await cmdPackInstall(repoRoot, packId, opts);
+    return;
+  }
+
+  // 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.");
+
+  const contextPath = path.join(repoRoot, "practices-and-standards", "context.yaml");
+  const ctx = readYamlFile(contextPath);
+
+  if (!ctx?.schema || ctx.schema !== "context-install/v1") {
+    die(`Unsupported or missing schema in context.yaml (expected 'context-install/v1')`);
+  }
+
+  switch (cmd) {
+    case "list": return cmdList(repoRoot, ctx);
+    case "compile": return cmdCompile(repoRoot, ctx);
+    case "validate": return cmdValidate(repoRoot, ctx);
+    default:
+      console.log(`Unknown command: ${cmd}\n`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main().catch(e => die(e?.stack || String(e)));
+