Function runAdd

packages/cli/src/commands/add.ts:152–220

(opts: RunAddArgs)

}

export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {
  const projectDir = resolve(opts.projectDir);

  // 1. Load (or write default) project config.
  let config = loadProjectConfig(projectDir);
  const hasConfig = existsSync(projectConfigPath(projectDir));
  if (!hasConfig && existsSync(resolve(projectDir, "index.html"))) {
    writeProjectConfig(projectDir, DEFAULT_PROJECT_CONFIG);
    config = DEFAULT_PROJECT_CONFIG;
  }

  // 2. Resolve the requested item and its transitive registryDependencies.
  //    The list comes back topologically sorted: dependencies first, the
  //    requested item last.
  let resolved: RegistryItem[];
  try {
    resolved = await resolveItemWithDependencies(opts.name, { baseUrl: config.registry });
  } catch (err) {
    throw new AddError(err instanceof Error ? err.message : String(err), "unknown-item");
  }
  // `resolveItemWithDependencies` always pushes the requested item last (or throws),
  // so the final element is the item the user asked for.
  const item = resolved[resolved.length - 1]!;

  if (item.type === "hyperframes:example") {
    throw new AddError(
      `"${item.name}" is an example — use \`hyperframes init <dir> --example ${item.name}\` instead.`,
      "example-type",
    );
  }

  // 3. Compatibility-gate every item we're about to install (dependencies
  //    included) before writing anything.
  const warnings = assertCompatibleOrThrow(resolved, opts.cliVersion);

  // 4. Remap targets per project config — each item by its own type.
  const installPlan: RegistryItem[] = resolved.map((resolvedItem) => ({
    ...resolvedItem,
    files: resolvedItem.files.map((f) => ({
      ...f,
      target: remapTarget(resolvedItem, f.target, config.paths),
    })),
  }));

  // 5. Install — dependencies first, requested item last.
  const written = await installAll(installPlan, projectDir, config.registry);

  // 6. Build include snippet + clipboard copy for the requested item.
  const itemForInstall = installPlan[installPlan.length - 1]!;
  const primaryFile =
    itemForInstall.files.find((f) => f.type === "hyperframes:snippet") ??
    itemForInstall.files.find((f) => f.type === "hyperframes:composition") ??
    itemForInstall.files[0];
  const snippetTargetRel = primaryFile?.target ?? "";
  const snippet = buildSnippet(item, snippetTargetRel);
  const clipboardCopied = !opts.skipClipboard && snippet ? copyToClipboard(snippet) : false;

  return {