ghcopilot-hub 1.0.0

package/tooling/cli/src/lib/fs-utils.js

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+export function fromRoot(rootDir, targetPath) {
+  return path.join(rootDir, ...targetPath.split("/"));
+}
+
+export function relativeFrom(rootDir, targetPath) {
+  return toPosixPath(path.relative(rootDir, targetPath));
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+export async function readTextIfExists(targetPath) {
+  if (!(await pathExists(targetPath))) {
+    return null;
+  }
+
+  return fs.readFile(targetPath, "utf8");
+}
+
+export async function walkFiles(rootDir) {
+  if (!(await pathExists(rootDir))) {
+    return [];
+  }
+
+  const results = [];
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const absolutePath = path.join(rootDir, entry.name);
+
+    if (entry.isDirectory()) {
+      results.push(...(await walkFiles(absolutePath)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      results.push(absolutePath);
+    }
+  }
+
+  return results;
+}
+
+export async function removeEmptyDirectories(rootDir, stopAtDir) {
+  if (!(await pathExists(rootDir))) {
+    return;
+  }
+
+  if (path.resolve(rootDir) === path.resolve(stopAtDir)) {
+    return;
+  }
+
+  const entries = await fs.readdir(rootDir);
+  if (entries.length > 0) {
+    return;
+  }
+
+  await fs.rmdir(rootDir);
+  await removeEmptyDirectories(path.dirname(rootDir), stopAtDir);
+}

package/tooling/cli/src/lib/managed-header.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+import crypto from "node:crypto";
+
+import { MANAGED_BY } from "./constants.js";
+
+function getHeaderStyle(targetRelativePath) {
+  const extension = path.extname(targetRelativePath).toLowerCase();
+
+  if (extension === ".json" || extension === ".jsonc" || extension === ".code-workspace") {
+    return {
+      renderLine: (key, value) => `// ${key}: ${value}`,
+      parseLine: (line) => {
+        const match = line.match(/^\/\/\s([^:]+):\s(.*)$/);
+        return match ? { key: match[1], value: match[2] } : null;
+      },
+    };
+  }
+
+  return {
+    renderLine: (key, value) => `<!-- ${key}: ${value} -->`,
+    parseLine: (line) => {
+      const match = line.match(/^<!--\s([^:]+):\s(.*)\s-->$/);
+      return match ? { key: match[1], value: match[2] } : null;
+    },
+  };
+}
+
+export function hashContent(content) {
+  return crypto.createHash("sha256").update(content.replace(/\r\n/g, "\n")).digest("hex");
+}
+
+export function renderManagedFile({ targetRelativePath, sourceRelativePath, revision, body }) {
+  const style = getHeaderStyle(targetRelativePath);
+  const normalizedBody = body.replace(/\r\n/g, "\n");
+  const header = [
+    style.renderLine("managed-by", MANAGED_BY),
+    style.renderLine("source", sourceRelativePath),
+    style.renderLine("revision", revision),
+    style.renderLine("content-hash", hashContent(normalizedBody)),
+  ].join("\n");
+
+  return `${header}\n\n${normalizedBody}`;
+}
+
+export function parseManagedFile({ targetRelativePath, content }) {
+  const style = getHeaderStyle(targetRelativePath);
+  const normalized = content.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  const header = {};
+  let index = 0;
+
+  while (index < lines.length) {
+    const parsedLine = style.parseLine(lines[index]);
+    if (!parsedLine) {
+      break;
+    }
+
+    header[parsedLine.key] = parsedLine.value;
+    index += 1;
+  }
+
+  if (header["managed-by"] !== MANAGED_BY) {
+    return null;
+  }
+
+  if (lines[index] === "") {
+    index += 1;
+  }
+
+  return {
+    header,
+    body: lines.slice(index).join("\n"),
+  };
+}

package/tooling/cli/src/lib/manifest.js

@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { CliError } from "./errors.js";
+import { MANIFEST_PATH } from "./constants.js";
+import { ensureDir, fromRoot, pathExists, readTextIfExists } from "./fs-utils.js";
+
+export const DEFAULT_MANIFEST = {
+  packs: [],
+  skills: [],
+  excludeSkills: [],
+  settings: {
+    onConflict: "fail",
+    preserveLocalOverrides: true,
+  },
+};
+
+export function normalizeManifest(rawManifest) {
+  const manifest = structuredClone(DEFAULT_MANIFEST);
+  const raw = rawManifest ?? {};
+
+  manifest.packs = normalizeStringArray(raw.packs, "packs");
+  manifest.skills = normalizeStringArray(raw.skills, "skills");
+  manifest.excludeSkills = normalizeStringArray(raw.excludeSkills, "excludeSkills");
+
+  const rawSettings = raw.settings ?? {};
+  const onConflict = rawSettings.onConflict ?? DEFAULT_MANIFEST.settings.onConflict;
+
+  if (!["fail", "overwrite"].includes(onConflict)) {
+    throw new CliError('Manifest setting "settings.onConflict" must be "fail" or "overwrite".');
+  }
+
+  manifest.settings = {
+    onConflict,
+    preserveLocalOverrides:
+      typeof rawSettings.preserveLocalOverrides === "boolean"
+        ? rawSettings.preserveLocalOverrides
+        : DEFAULT_MANIFEST.settings.preserveLocalOverrides,
+  };
+
+  return manifest;
+}
+
+export async function readManifest(projectDir, options = {}) {
+  const manifestPath = fromRoot(projectDir, MANIFEST_PATH);
+  const manifestText = await readTextIfExists(manifestPath);
+
+  if (manifestText === null) {
+    if (options.allowMissing) {
+      return null;
+    }
+
+    throw new CliError(`Manifest not found at ${MANIFEST_PATH}. Run "ghcopilot-hub init" first.`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(manifestText);
+  } catch (error) {
+    throw new CliError(`Manifest at ${MANIFEST_PATH} is not valid JSON: ${error.message}`);
+  }
+
+  return normalizeManifest(parsed);
+}
+
+export async function writeManifest(projectDir, manifest) {
+  const manifestPath = fromRoot(projectDir, MANIFEST_PATH);
+  await ensureDir(path.dirname(manifestPath));
+  await fs.writeFile(
+    manifestPath,
+    `${JSON.stringify(normalizeManifest(manifest), null, 2)}\n`,
+    "utf8"
+  );
+}
+
+export async function ensureManifest(projectDir) {
+  const manifestPath = fromRoot(projectDir, MANIFEST_PATH);
+  if (!(await pathExists(manifestPath))) {
+    await writeManifest(projectDir, DEFAULT_MANIFEST);
+  }
+
+  return readManifest(projectDir);
+}
+
+function normalizeStringArray(value, fieldName) {
+  if (value === undefined) {
+    return [];
+  }
+
+  if (!Array.isArray(value)) {
+    throw new CliError(`Manifest field "${fieldName}" must be an array of strings.`);
+  }
+
+  return [
+    ...new Set(
+      value.map((item) => {
+        if (typeof item !== "string" || item.trim() === "") {
+          throw new CliError(`Manifest field "${fieldName}" must contain only non-empty strings.`);
+        }
+
+        return item.trim();
+      })
+    ),
+  ].sort();
+}

package/tooling/cli/src/lib/resolver.js

@@ -0,0 +1,53 @@
+import { CliError } from "./errors.js";
+
+const DEFAULT_SKILL_IDS = ["ghcopilot-hub-consumer"];
+
+export function resolveProjectState({ catalog, manifest }) {
+  const packMap = new Map(catalog.packs.map((pack) => [pack.name, pack]));
+  const skillMap = new Map(catalog.skills.map((skill) => [skill.id, skill]));
+
+  const resolvedSkillIds = new Set();
+
+  for (const skillId of DEFAULT_SKILL_IDS) {
+    if (!skillMap.has(skillId)) {
+      throw new CliError(`Hub is missing required default skill "${skillId}".`);
+    }
+
+    resolvedSkillIds.add(skillId);
+  }
+
+  for (const packName of manifest.packs) {
+    const pack = packMap.get(packName);
+    if (!pack) {
+      throw new CliError(`Manifest references unknown pack "${packName}".`);
+    }
+
+    for (const skillId of pack.skills) {
+      resolvedSkillIds.add(skillId);
+    }
+  }
+
+  for (const skillId of manifest.skills) {
+    if (!skillMap.has(skillId)) {
+      throw new CliError(`Manifest references unknown skill "${skillId}".`);
+    }
+
+    resolvedSkillIds.add(skillId);
+  }
+
+  for (const skillId of manifest.excludeSkills) {
+    if (!skillMap.has(skillId)) {
+      throw new CliError(`Manifest excludes unknown skill "${skillId}".`);
+    }
+
+    resolvedSkillIds.delete(skillId);
+  }
+
+  const skills = [...resolvedSkillIds].sort().map((skillId) => skillMap.get(skillId));
+
+  return {
+    agents: catalog.agents,
+    skills,
+    baseFiles: catalog.baseFiles,
+  };
+}

package/tooling/cli/src/lib/sync-engine.js

@@ -0,0 +1,262 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { CliError } from "./errors.js";
+import { MANAGED_ROOTS, getRequiredDirs } from "./constants.js";
+import {
+  ensureDir,
+  fromRoot,
+  pathExists,
+  readTextIfExists,
+  removeEmptyDirectories,
+  walkFiles,
+} from "./fs-utils.js";
+import { hashContent, parseManagedFile, renderManagedFile } from "./managed-header.js";
+
+export async function createDesiredFiles({ resolvedState, revision }) {
+  const desiredFiles = [];
+
+  for (const baseFile of resolvedState.baseFiles) {
+    desiredFiles.push(await materializeDesiredFile(baseFile, revision));
+  }
+
+  for (const agent of resolvedState.agents) {
+    desiredFiles.push(await materializeDesiredFile(agent, revision));
+  }
+
+  for (const skill of resolvedState.skills) {
+    for (const file of skill.files) {
+      desiredFiles.push(await materializeDesiredFile(file, revision));
+    }
+  }
+
+  return desiredFiles.sort((left, right) =>
+    left.targetRelativePath.localeCompare(right.targetRelativePath)
+  );
+}
+
+export async function planProjectSync({ projectDir, desiredFiles, onConflict }) {
+  const desiredMap = new Map(desiredFiles.map((file) => [file.targetRelativePath, file]));
+  const existingManagedEntries = await scanManagedEntries(projectDir);
+
+  const create = [];
+  const update = [];
+  const remove = [];
+  const conflicts = [];
+  const unchanged = [];
+  const missingManaged = [];
+  const drifted = [];
+  const unexpectedManaged = [];
+  const unexpectedUnmanaged = [];
+
+  for (const desiredFile of desiredFiles) {
+    const absolutePath = fromRoot(projectDir, desiredFile.targetRelativePath);
+    const currentContent = await readTextIfExists(absolutePath);
+
+    if (currentContent === null) {
+      create.push({ targetRelativePath: desiredFile.targetRelativePath, reason: "missing" });
+      missingManaged.push(desiredFile.targetRelativePath);
+      continue;
+    }
+
+    if (currentContent === desiredFile.renderedContent) {
+      unchanged.push({ targetRelativePath: desiredFile.targetRelativePath });
+      continue;
+    }
+
+    const parsedManaged = parseManagedFile({
+      targetRelativePath: desiredFile.targetRelativePath,
+      content: currentContent,
+    });
+
+    if (!parsedManaged) {
+      conflicts.push({
+        targetRelativePath: desiredFile.targetRelativePath,
+        reason: "expected managed file but found unmanaged content",
+      });
+      unexpectedUnmanaged.push(desiredFile.targetRelativePath);
+      continue;
+    }
+
+    if (parsedManaged.body === desiredFile.body) {
+      update.push({
+        targetRelativePath: desiredFile.targetRelativePath,
+        reason: "revision metadata changed",
+      });
+      continue;
+    }
+
+    const currentHash = hashContent(parsedManaged.body);
+    const isLocallyDrifted = parsedManaged.header["content-hash"] !== currentHash;
+
+    if (isLocallyDrifted && onConflict !== "overwrite") {
+      conflicts.push({
+        targetRelativePath: desiredFile.targetRelativePath,
+        reason: "managed file drifted locally",
+      });
+      drifted.push(desiredFile.targetRelativePath);
+      continue;
+    }
+
+    update.push({
+      targetRelativePath: desiredFile.targetRelativePath,
+      reason: isLocallyDrifted ? "overwrite drifted managed file" : "hub content changed",
+    });
+
+    if (isLocallyDrifted) {
+      drifted.push(desiredFile.targetRelativePath);
+    }
+  }
+
+  for (const entry of existingManagedEntries) {
+    if (desiredMap.has(entry.targetRelativePath)) {
+      continue;
+    }
+
+    if (entry.kind === "managed") {
+      const isLocallyDrifted = entry.header["content-hash"] !== hashContent(entry.body);
+      if (isLocallyDrifted && onConflict !== "overwrite") {
+        conflicts.push({
+          targetRelativePath: entry.targetRelativePath,
+          reason: "managed file scheduled for deletion but drifted locally",
+        });
+        drifted.push(entry.targetRelativePath);
+        continue;
+      }
+
+      remove.push({
+        targetRelativePath: entry.targetRelativePath,
+        reason: "orphaned managed file",
+      });
+      continue;
+    }
+
+    unexpectedUnmanaged.push(entry.targetRelativePath);
+  }
+
+  for (const entry of existingManagedEntries) {
+    if (entry.kind === "managed" && !desiredMap.has(entry.targetRelativePath)) {
+      unexpectedManaged.push(entry.targetRelativePath);
+    }
+  }
+
+  return {
+    create,
+    update,
+    remove,
+    unchanged,
+    conflicts,
+    diagnostics: {
+      missingManaged,
+      drifted: [...new Set(drifted)].sort(),
+      unexpectedManaged: [...new Set(unexpectedManaged)].sort(),
+      unexpectedUnmanaged: [...new Set(unexpectedUnmanaged)].sort(),
+    },
+  };
+}
+
+export async function applyProjectSync({ projectDir, desiredFiles, plan, preserveLocalOverrides }) {
+  if (plan.conflicts.length > 0) {
+    const summary = plan.conflicts
+      .map((conflict) => `${conflict.targetRelativePath}: ${conflict.reason}`)
+      .join("\n");
+    throw new CliError(`Cannot apply sync because conflicts were detected:\n${summary}`);
+  }
+
+  const requiredDirs = getRequiredDirs(preserveLocalOverrides);
+
+  for (const requiredDir of requiredDirs) {
+    await ensureDir(fromRoot(projectDir, requiredDir));
+  }
+
+  const desiredMap = new Map(desiredFiles.map((file) => [file.targetRelativePath, file]));
+
+  for (const operation of [...plan.create, ...plan.update]) {
+    const file = desiredMap.get(operation.targetRelativePath);
+    const targetPath = fromRoot(projectDir, operation.targetRelativePath);
+    await ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, file.renderedContent, "utf8");
+  }
+
+  for (const operation of plan.remove) {
+    const targetPath = fromRoot(projectDir, operation.targetRelativePath);
+    if (await pathExists(targetPath)) {
+      await fs.rm(targetPath, { force: true });
+      await removeEmptyDirectories(path.dirname(targetPath), projectDir);
+    }
+  }
+
+  for (const requiredDir of requiredDirs) {
+    await ensureDir(fromRoot(projectDir, requiredDir));
+  }
+}
+
+export async function validateManagedProject({ projectDir, desiredFiles, onConflict }) {
+  return planProjectSync({ projectDir, desiredFiles, onConflict });
+}
+
+async function materializeDesiredFile(file, revision) {
+  const body = await fs.readFile(file.sourcePath, "utf8");
+
+  return {
+    sourcePath: file.sourcePath,
+    sourceRelativePath: file.sourceRelativePath,
+    targetRelativePath: file.targetRelativePath,
+    body,
+    renderedContent: renderManagedFile({
+      targetRelativePath: file.targetRelativePath,
+      sourceRelativePath: file.sourceRelativePath,
+      revision,
+      body,
+    }),
+  };
+}
+
+async function scanManagedEntries(projectDir) {
+  const entries = [];
+
+  for (const managedRoot of MANAGED_ROOTS) {
+    const absoluteRoot = fromRoot(projectDir, managedRoot);
+    if (!(await pathExists(absoluteRoot))) {
+      continue;
+    }
+
+    const stat = await fs.stat(absoluteRoot);
+    const files = stat.isDirectory() ? await walkFiles(absoluteRoot) : [absoluteRoot];
+
+    for (const absolutePath of files) {
+      const targetRelativePath = path.relative(projectDir, absolutePath).split(path.sep).join("/");
+      const content = await fs.readFile(absolutePath, "utf8");
+      const parsedManaged = parseManagedFile({ targetRelativePath, content });
+
+      if (parsedManaged) {
+        entries.push({
+          kind: "managed",
+          targetRelativePath,
+          header: parsedManaged.header,
+          body: parsedManaged.body,
+        });
+        continue;
+      }
+
+      entries.push({
+        kind: "unmanaged",
+        targetRelativePath,
+        content,
+      });
+    }
+  }
+
+  return entries.filter((entry) => entry.targetRelativePath !== ".github/ghcopilot-hub.json");
+}
+
+export function summarizePlan(plan) {
+  return {
+    create: plan.create.length,
+    update: plan.update.length,
+    remove: plan.remove.length,
+    unchanged: plan.unchanged.length,
+    conflicts: plan.conflicts.length,
+    drifted: plan.diagnostics.drifted.length,
+  };
+}