@thieung/agentkit-helper 0.1.0

package/lib/args.mjs

@@ -0,0 +1,258 @@
+export const COMMANDS = new Set([
+  "install", "update", "self-update", "update-all", "export", "doctor", "help",
+]);
+export const INSTALL_TARGETS = new Set([
+  "claude-code", "codex", "cursor", "dsh", "grok", "omp", "pi",
+]);
+export const UPDATE_TARGETS = new Set(["claude-code", "codex", "cursor", "grok", "omp", "pi"]);
+export const EXPORT_TARGETS = new Set(["agy", "portable"]);
+export const RUNTIME_TARGETS = new Set([...INSTALL_TARGETS]);
+export const KNOWN_TARGETS = new Set([...INSTALL_TARGETS, ...EXPORT_TARGETS]);
+export const CHANNELS = new Set(["stable", "beta"]);
+export const LANGUAGES = new Set(["vi", "en"]);
+export const KITS = new Set(["engineer", "marketing"]);
+
+export function splitTargetSpec(value) {
+  return String(value || "").split(",").map((target) => target.trim()).filter(Boolean);
+}
+
+export function targetSpecIsSupported(value, supportedTargets) {
+  const targets = splitTargetSpec(value);
+  return targets.length > 0 && targets.every((target) => supportedTargets.has(target));
+}
+
+export function validateForCommand(options) {
+  const selectedTarget = options.target || options.runtime;
+  const hasDiscoveryOptions = options.deepScanRoots.length > 0 ||
+    options.maxDepthChanged || options.excludes.length > 0;
+  if (options.command === "doctor") {
+    if (
+      options.global || selectedTarget || options.kit || options.channel || options.out ||
+      options.binaryOnly || options.dryRun || options.noSave || options.allowDowngrade ||
+      hasDiscoveryOptions
+    ) {
+      throw new Error("doctor accepts only --project and shared output flags");
+    }
+    return;
+  }
+  if (options.command === "install") {
+    if (selectedTarget && !targetSpecIsSupported(selectedTarget, INSTALL_TARGETS)) {
+      throw new Error(`target ${selectedTarget} is export-only; use the export command`);
+    }
+    if (options.out) throw new Error("--out is valid only with export");
+    if (options.allowDowngrade) throw new Error("--allow-downgrade is valid only with self-update or update --binary-only");
+    if (hasDiscoveryOptions) throw new Error("deep scan options are valid only with update-all");
+    return;
+  }
+  if (options.command === "update") {
+    if (selectedTarget && !targetSpecIsSupported(selectedTarget, UPDATE_TARGETS)) {
+      throw new Error(`target ${selectedTarget} is not supported by ak update`);
+    }
+    if (options.out) throw new Error("--out is valid only with export");
+    if (options.allowDowngrade && !options.binaryOnly) {
+      throw new Error("--allow-downgrade requires update --binary-only");
+    }
+    if (hasDiscoveryOptions) throw new Error("deep scan options are valid only with update-all");
+    return;
+  }
+  if (options.command === "self-update") {
+    if (
+      options.project || options.global || selectedTarget || options.kit || options.out || options.binaryOnly ||
+      options.noSave || hasDiscoveryOptions
+    ) {
+      throw new Error("self-update accepts --channel and shared output flags only");
+    }
+    return;
+  }
+  if (options.command === "update-all") {
+    if (
+      options.project || options.global || selectedTarget || options.kit || options.out || options.binaryOnly ||
+      options.noSave || options.allowDowngrade
+    ) {
+      throw new Error("update-all accepts discovery, channel, and shared output flags only");
+    }
+    return;
+  }
+  if (options.command === "export") {
+    if (options.project || options.binaryOnly || options.noSave || options.runtime || options.allowDowngrade) {
+      throw new Error("export accepts --target, --global, --out, --channel, and shared output flags");
+    }
+    if (selectedTarget && !EXPORT_TARGETS.has(selectedTarget)) {
+      throw new Error(`target ${selectedTarget} is an install runtime; use the install command`);
+    }
+    if (selectedTarget === "agy" && !options.global) {
+      throw new Error("agy export requires --global");
+    }
+    if (selectedTarget === "agy" && options.out) {
+      throw new Error("agy export uses --global, not --out");
+    }
+    if (selectedTarget === "portable" && options.global) {
+      throw new Error("portable export uses --out, not --global");
+    }
+    if (hasDiscoveryOptions) throw new Error("deep scan options are valid only with update-all");
+  }
+}
+
+function takeValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+export function parseArgs(argv) {
+  const options = {
+    command: null,
+    project: null,
+    global: false,
+    target: null,
+    runtime: null,
+    kit: null,
+    channel: null,
+    language: null,
+    out: null,
+    binaryOnly: false,
+    allowDowngrade: false,
+    dryRun: false,
+    yes: false,
+    noSave: false,
+    help: false,
+    version: false,
+    deepScanRoots: [],
+    maxDepth: 5,
+    maxDepthChanged: false,
+    excludes: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+
+    if (!argument.startsWith("-")) {
+      if (options.command) {
+        throw new Error(`unexpected argument: ${argument}`);
+      }
+      if (!COMMANDS.has(argument)) {
+        throw new Error(`unknown command: ${argument}`);
+      }
+      options.command = argument;
+      continue;
+    }
+
+    switch (argument) {
+      case "--project":
+        options.project = takeValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--global":
+        options.global = true;
+        break;
+      case "--target":
+        options.target = takeValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--runtime":
+        options.runtime = takeValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--kit":
+        options.kit = takeValue(argv, index, argument).toLowerCase();
+        index += 1;
+        break;
+      case "--channel":
+        options.channel = takeValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--language":
+        options.language = takeValue(argv, index, argument).toLowerCase();
+        index += 1;
+        break;
+      case "--out":
+        options.out = takeValue(argv, index, argument);
+        index += 1;
+        break;
+      case "--binary-only":
+        options.binaryOnly = true;
+        break;
+      case "--allow-downgrade":
+        options.allowDowngrade = true;
+        break;
+      case "--deep-scan":
+        options.deepScanRoots.push(takeValue(argv, index, argument));
+        index += 1;
+        break;
+      case "--max-depth": {
+        const value = Number(takeValue(argv, index, argument));
+        if (!Number.isInteger(value) || value < 1 || value > 20) {
+          throw new Error("--max-depth must be an integer from 1 to 20");
+        }
+        options.maxDepth = value;
+        options.maxDepthChanged = true;
+        index += 1;
+        break;
+      }
+      case "--exclude":
+        options.excludes.push(...takeValue(argv, index, argument)
+          .split(",").map((value) => value.trim()).filter(Boolean));
+        index += 1;
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--yes":
+      case "-y":
+        options.yes = true;
+        break;
+      case "--no-save":
+        options.noSave = true;
+        break;
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      case "--version":
+      case "-v":
+        options.version = true;
+        break;
+      default:
+        throw new Error(`unknown option: ${argument}`);
+    }
+  }
+
+  validateArgs(options);
+  return options;
+}
+
+function validateArgs(options) {
+  if (options.project && options.global) {
+    throw new Error("--project and --global cannot be used together");
+  }
+  if (options.target && options.runtime && options.target !== options.runtime) {
+    throw new Error("--target and --runtime must match when both are provided");
+  }
+  if (options.target && !targetSpecIsSupported(options.target, KNOWN_TARGETS)) {
+    throw new Error(`unsupported target: ${options.target}`);
+  }
+  if (options.runtime && splitTargetSpec(options.runtime).some((target) => EXPORT_TARGETS.has(target))) {
+    throw new Error(`runtime ${options.runtime} is export-only; use --target with the export command`);
+  }
+  if (options.runtime && !targetSpecIsSupported(options.runtime, RUNTIME_TARGETS)) {
+    throw new Error(`unsupported runtime: ${options.runtime}`);
+  }
+  if (options.channel && !CHANNELS.has(options.channel)) {
+    throw new Error(`unsupported channel: ${options.channel}`);
+  }
+  if (options.language && !LANGUAGES.has(options.language)) {
+    throw new Error(`unsupported language: ${options.language}`);
+  }
+  if (options.kit && !KITS.has(options.kit)) {
+    throw new Error(`unsupported kit: ${options.kit}`);
+  }
+  if (options.binaryOnly && options.command && options.command !== "update") {
+    throw new Error("--binary-only is valid only with update");
+  }
+  if (options.binaryOnly && (options.project || options.global || options.target || options.runtime || options.kit)) {
+    throw new Error("--binary-only cannot be combined with project, global, target, or Kit selection");
+  }
+  validateForCommand(options);
+}

package/lib/colors.mjs

@@ -0,0 +1,21 @@
+import { stdout } from "node:process";
+
+const tones = {
+  binary: "1;32",
+  command: "36",
+  group: "1;34",
+  prompt: "1;36",
+  section: "1;36",
+  target: "1;35",
+  warning: "1;33",
+};
+
+export function supportsColor(stream = stdout) {
+  return Boolean(stream.isTTY) && !("NO_COLOR" in process.env) && process.env.TERM !== "dumb";
+}
+
+export function colorText(message, tone, { stream = stdout, enabled = supportsColor(stream) } = {}) {
+  const code = tones[tone];
+  if (!enabled || !code) return message;
+  return `\u001B[${code}m${message}\u001B[0m`;
+}

package/lib/commands.mjs

@@ -0,0 +1,106 @@
+export function installArgs({ global, target, channel, kit = "engineer" }, { force = false } = {}) {
+  return [
+    "kit",
+    "install",
+    kit,
+    "--target",
+    target,
+    ...(global ? ["--global"] : []),
+    "--channel",
+    channel,
+    "--yes",
+    ...(force ? ["--force"] : []),
+    "--verbose",
+  ];
+}
+
+export function exportArgs({ global, out, target, channel, kit = "engineer" }) {
+  return [
+    "kit",
+    "install",
+    kit,
+    "--target",
+    target,
+    ...(global ? ["--global"] : []),
+    ...(out ? ["--out", out] : []),
+    "--channel",
+    channel,
+    "--yes",
+    "--verbose",
+  ];
+}
+
+function updateBase({ global, project, target, channel, kit = "engineer" }) {
+  return [
+    "update",
+    ...(global ? ["--global"] : [project]),
+    "--kits",
+    kit,
+    "--target",
+    target,
+    "--channel",
+    channel,
+  ];
+}
+
+export function updatePreviewArgs(selection) {
+  return [...updateBase(selection), "--show-diff", "--dry-run", "--verbose"];
+}
+
+export function updateApplyArgs(selection) {
+  return [...updateBase(selection), "--yes", "--verbose"];
+}
+
+export function selfUpdateCheckArgs(channel) {
+  return ["self-update", "--check", "--channel", channel];
+}
+
+export function selfUpdateApplyArgs(channel) {
+  return ["self-update", "--channel", channel, "--yes"];
+}
+
+export function selfUpdateJsonCheckArgs(channel) {
+  return [...selfUpdateCheckArgs(channel), "--json"];
+}
+
+export function selfUpdateJsonApplyArgs(channel) {
+  return [...selfUpdateApplyArgs(channel), "--json"];
+}
+
+export function globalUpdatePreviewArgs(channel, targets, kit = "engineer") {
+  return [
+    "update", "--global", "--kits", kit, "--target", targets.join(","),
+    "--channel", channel, "--show-diff", "--dry-run", "--verbose",
+  ];
+}
+
+export function globalUpdateApplyArgs(channel, targets, kit = "engineer") {
+  return [
+    "update", "--global", "--kits", kit, "--target", targets.join(","),
+    "--channel", channel, "--yes", "--verbose",
+  ];
+}
+
+export function projectUpdatePreviewArgs(project, target, channel, kit = "engineer") {
+  return [
+    "update", project, "--kits", kit, "--target", target,
+    "--channel", channel, "--show-diff", "--dry-run", "--verbose",
+  ];
+}
+
+export function projectUpdateApplyArgs(project, target, channel, kit = "engineer") {
+  return [
+    "update", project, "--kits", kit, "--target", target,
+    "--channel", channel, "--yes", "--verbose",
+  ];
+}
+
+function quote(value) {
+  return /^[A-Za-z0-9_./:@=-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+export function formatCommand(binary, args) {
+  return [binary, ...args].map(quote).join(" ");
+}

package/lib/config.mjs

@@ -0,0 +1,68 @@
+import { lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { CHANNELS, INSTALL_TARGETS, KITS, targetSpecIsSupported } from "./args.mjs";
+
+export const CONFIG_NAME = ".ak-kit.json";
+
+function validateConfig(value, path) {
+  if (!value || typeof value !== "object") {
+    throw new Error(`invalid helper config: ${path}`);
+  }
+  if (value.schemaVersion !== 1 || !KITS.has(value.kit) || value.scope !== "project") {
+    throw new Error(`unsupported helper config contract: ${path}`);
+  }
+  if (!targetSpecIsSupported(value.target, INSTALL_TARGETS) || !CHANNELS.has(value.channel)) {
+    throw new Error(`invalid target or channel in helper config: ${path}`);
+  }
+  return value;
+}
+
+export async function readProjectConfig(project) {
+  const path = resolve(project, CONFIG_NAME);
+  try {
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink()) {
+      throw new Error(`refusing symlinked helper config: ${path}`);
+    }
+    return validateConfig(JSON.parse(await readFile(path, "utf8")), path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    if (error instanceof SyntaxError) {
+      throw new Error(`invalid JSON in helper config: ${path}`);
+    }
+    throw error;
+  }
+}
+
+export async function writeProjectConfig(project, selection) {
+  const path = resolve(project, CONFIG_NAME);
+  try {
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink()) {
+      throw new Error(`refusing symlinked helper config: ${path}`);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const value = {
+    schemaVersion: 1,
+    kit: selection.kit || "engineer",
+    target: selection.target,
+    channel: selection.channel,
+    scope: "project",
+  };
+  const temporaryPath = resolve(project, `${CONFIG_NAME}.tmp-${process.pid}-${randomUUID()}`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+    });
+    await rename(temporaryPath, path);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  return path;
+}

package/lib/discovery.mjs

@@ -0,0 +1,206 @@
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, parse, resolve } from "node:path";
+
+export const DEFAULT_SCAN_EXCLUDES = new Set([
+  ".git", "node_modules", "dist", "build", "out", ".next", ".cache", "Library", ".Trash",
+]);
+
+function expandHome(input, home) {
+  if (input === "~") return home;
+  if (input.startsWith("~/")) return resolve(home, input.slice(2));
+  return input;
+}
+
+async function canonicalDirectory(input, { home = homedir(), rejectBroad = false } = {}) {
+  const absolute = resolve(expandHome(input, home));
+  const metadata = await lstat(absolute);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+    throw new Error(`not a real directory: ${input}`);
+  }
+  const canonical = await realpath(absolute);
+  if (rejectBroad) {
+    const canonicalHome = await realpath(home);
+    if (canonical === parse(canonical).root || canonical === canonicalHome) {
+      throw new Error(`deep scan root is too broad: ${canonical}`);
+    }
+  }
+  return canonical;
+}
+
+export async function isOwnedProject(project) {
+  try {
+    const marker = resolve(project, ".agentkit", "ownership.json");
+    const metadata = await lstat(marker);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+    const value = JSON.parse(await readFile(marker, "utf8"));
+    return Boolean(
+      value && typeof value === "object" && !Array.isArray(value) &&
+      value.version === 1 && typeof value.project_id === "string" && value.project_id.trim(),
+    );
+  } catch (error) {
+    if (error.code === "ENOENT" || error instanceof SyntaxError) return false;
+    throw error;
+  }
+}
+
+async function hasManifest(path, kit) {
+  try {
+    const metadata = await lstat(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return Boolean(
+      value && typeof value === "object" && !Array.isArray(value) &&
+      value.version === 1 && value.kit === kit,
+    );
+  } catch (error) {
+    if (error.code === "ENOENT" || error instanceof SyntaxError) return false;
+    throw error;
+  }
+}
+
+export async function findKitRuntimes(root, supportedRuntimes, kit) {
+  const runtimes = [];
+  for (const runtime of supportedRuntimes) {
+    const manifest = resolve(
+      root, ".agentkit", "adapters", runtime, kit, ".agentkit", "install-manifest.json",
+    );
+    if (await hasManifest(manifest, kit)) runtimes.push(runtime);
+  }
+  return runtimes;
+}
+
+export function findEngineerRuntimes(root, supportedRuntimes) {
+  return findKitRuntimes(root, supportedRuntimes, "engineer");
+}
+
+export async function discoverGlobalKitInstalls({
+  akHome = resolve(homedir(), ".agentkit"),
+  supportedRuntimes = [],
+  kits = ["engineer", "marketing"],
+} = {}) {
+  const root = resolve(akHome, "..");
+  const installs = [];
+  for (const kit of kits) {
+    const runtimes = await findKitRuntimes(root, supportedRuntimes, kit);
+    if (runtimes.length > 0) installs.push({ kit, runtimes });
+  }
+  return installs;
+}
+
+export async function discoverGlobalEngineerRuntimes({
+  akHome = resolve(homedir(), ".agentkit"),
+  supportedRuntimes = [],
+} = {}) {
+  return findKitRuntimes(resolve(akHome, ".."), supportedRuntimes, "engineer");
+}
+
+export function parseProjectRegistry(output) {
+  const value = JSON.parse(output);
+  const projects = value?.data?.projects;
+  if (value?.schema_version !== 1 || !Array.isArray(projects)) {
+    throw new Error("unsupported ak projects list JSON contract");
+  }
+  return projects
+    .filter((project) => typeof project?.dir === "string" && project.dir.trim())
+    .map((project) => ({ name: project.name || basename(project.dir), path: project.dir }));
+}
+
+export async function scanForOwnedProjects(
+  inputRoot,
+  { maxDepth = 5, excludes = [], home = homedir() } = {},
+) {
+  const root = await canonicalDirectory(inputRoot, { home, rejectBroad: true });
+  const excluded = new Set([...DEFAULT_SCAN_EXCLUDES, ...excludes]);
+  const projects = [];
+  const warnings = [];
+  const pending = [{ path: root, depth: 0 }];
+
+  while (pending.length > 0) {
+    const current = pending.pop();
+    try {
+      if (await isOwnedProject(current.path)) projects.push(current.path);
+      if (current.depth >= maxDepth) continue;
+      const entries = await readdir(current.path, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+        if (entry.name === ".agentkit" || excluded.has(entry.name)) continue;
+        pending.push({ path: resolve(current.path, entry.name), depth: current.depth + 1 });
+      }
+    } catch (error) {
+      if (error.code === "EACCES" || error.code === "EPERM" || error.code === "ENOENT") {
+        warnings.push(`${current.path}: ${error.code}`);
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  projects.sort();
+  return { root, projects, warnings };
+}
+
+export async function discoverProjectCandidates({
+  cwd = process.cwd(),
+  registryOutput,
+  deepScanRoots = [],
+  maxDepth = 5,
+  excludes = [],
+  home = homedir(),
+  supportedRuntimes = [],
+  kits = ["engineer", "marketing"],
+}) {
+  const candidates = new Map();
+  const warnings = [];
+
+  async function add(path, source, name) {
+    try {
+      const canonical = await canonicalDirectory(path, { home });
+      if (!(await isOwnedProject(canonical))) return;
+      const installs = [];
+      for (const kit of kits) {
+        const runtimes = await findKitRuntimes(canonical, supportedRuntimes, kit);
+        installs.push(...runtimes.map((runtime) => ({ kit, runtime })));
+      }
+      if (installs.length === 0) return;
+      const existing = candidates.get(canonical);
+      if (existing) {
+        existing.sources.add(source);
+        return;
+      }
+      candidates.set(canonical, {
+        id: `project:${canonical}`,
+        kind: "project",
+        name: name || basename(canonical),
+        path: canonical,
+        installs,
+        runtimes: [...new Set(installs.map((install) => install.runtime))],
+        sources: new Set([source]),
+      });
+    } catch (error) {
+      if (error.code === "ENOENT" || error.code === "EACCES" || error.code === "EPERM") {
+        warnings.push(`${path}: ${error.code}`);
+        return;
+      }
+      throw error;
+    }
+  }
+
+  await add(cwd, "current");
+  for (const project of parseProjectRegistry(registryOutput)) {
+    await add(project.path, "registry", project.name);
+  }
+  for (const root of deepScanRoots) {
+    const result = await scanForOwnedProjects(root, { maxDepth, excludes, home });
+    warnings.push(...result.warnings);
+    for (const project of result.projects) await add(project, "deep-scan");
+  }
+
+  return {
+    projects: [...candidates.values()].map((candidate) => ({
+      ...candidate,
+      sources: [...candidate.sources].sort(),
+    })).sort((left, right) => left.path.localeCompare(right.path)),
+    warnings,
+  };
+}