@intelligo-dev/cli 1.0.0-beta.1 → 1.0.0-beta.13

package/src/commands/add.ts

@@ -0,0 +1,244 @@
+/**
+ * `intelligo add <feature>` — generate consumer-owned source.
+ *
+ * "Owned" is the operative word: the files land in the
+ * consumer's repository and Intelligo stops deciding what is in them.
+ * The manifest records what was written and its hash so a later
+ * upgrade can tell an untouched file from one the consumer has made
+ * their own, and refuse to overwrite the latter.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  emptyManifest,
+  hashContents,
+  readManifest,
+  recordFeature,
+  writeManifest,
+  type GeneratedFile,
+} from "../manifest.js";
+
+export type TemplateFile = { template: string; target: string };
+/** A route the feature needs called on a schedule (five-field cron). */
+export type TemplateCron = { path: string; schedule: string };
+export type TemplateFeature = {
+  templateVersion: string;
+  description: string;
+  /** Set when a registry item supersedes this template feature. */
+  deprecated?: string;
+  files: TemplateFile[];
+  cron?: TemplateCron;
+};
+export type TemplateCatalogue = Record<string, TemplateFeature>;
+
+export function readCatalogue(templatesDir: string): TemplateCatalogue {
+  return JSON.parse(
+    readFileSync(path.join(templatesDir, "manifest.json"), "utf8")
+  ) as TemplateCatalogue;
+}
+
+export type AddResult = {
+  feature: string;
+  /** The catalogue's deprecation notice, when the feature has one. */
+  deprecated?: string;
+  written: string[];
+  /** Present and modified by the consumer — left untouched. */
+  skippedCustomized: string[];
+  /** Present but not ours (no manifest record) — left untouched. */
+  skippedUnknown: string[];
+  /**
+   * The feature's schedule and what became of it: `written` to a new
+   * vercel.json, already `present` in the app's own, or `manual` — the
+   * app has a vercel.json without it, which is the consumer's to edit.
+   */
+  cron?: TemplateCron & { status: "written" | "present" | "manual" };
+};
+
+export type AddOptions = {
+  appRoot: string;
+  templatesDir: string;
+  frameworkVersion: string;
+  /** Re-write files the consumer has customized. Off by default. */
+  force?: boolean;
+  /**
+   * Placeholder substitutions applied to template contents, e.g.
+   * `{ __APP_NAME__: "acme" }`. Applied before hashing, so the
+   * recorded hash describes what actually landed on disk.
+   */
+  variables?: Record<string, string>;
+};
+
+export function substitute(
+  contents: string,
+  variables: Record<string, string> | undefined
+): string {
+  if (!variables) return contents;
+  return Object.entries(variables).reduce(
+    (out, [key, value]) => out.split(key).join(value),
+    contents
+  );
+}
+
+const VERCEL_CONFIG = "vercel.json";
+
+/**
+ * Schedule the cron in vercel.json when the app has none. An existing
+ * one is deployment configuration the consumer wrote: it is read to see
+ * whether the path is already scheduled, never written. The file is not
+ * recorded in the manifest either — it is the consumer's from the start.
+ */
+function scheduleCron(
+  appRoot: string,
+  cron: TemplateCron
+): "written" | "present" | "manual" {
+  const file = path.join(appRoot, VERCEL_CONFIG);
+  if (!existsSync(file)) {
+    const config = {
+      $schema: "https://openapi.vercel.sh/vercel.json",
+      crons: [cron],
+    };
+    writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+    return "written";
+  }
+  try {
+    const config = JSON.parse(readFileSync(file, "utf8")) as {
+      crons?: Array<{ path?: string }>;
+    };
+    return config.crons?.some((c) => c.path === cron.path)
+      ? "present"
+      : "manual";
+  } catch {
+    return "manual";
+  }
+}
+
+export function addFeature(feature: string, options: AddOptions): AddResult {
+  const catalogue = readCatalogue(options.templatesDir);
+  const spec = catalogue[feature];
+  if (!spec) {
+    throw new Error(
+      `Unknown feature "${feature}". Available: ${Object.keys(catalogue).join(", ")}`
+    );
+  }
+
+  const manifest =
+    readManifest(options.appRoot) ?? emptyManifest(options.frameworkVersion);
+  const previous = manifest.features[feature];
+  const previousByPath = new Map(
+    (previous?.files ?? []).map((f) => [f.path, f])
+  );
+
+  const result: AddResult = {
+    feature,
+    written: [],
+    skippedCustomized: [],
+    skippedUnknown: [],
+  };
+  if (spec.deprecated) result.deprecated = spec.deprecated;
+  const recorded: GeneratedFile[] = [];
+
+  for (const file of spec.files) {
+    const source = path.join(options.templatesDir, file.template);
+    const target = path.join(options.appRoot, file.target);
+    const contents = substitute(
+      readFileSync(source, "utf8"),
+      options.variables
+    );
+
+    if (existsSync(target) && !options.force) {
+      const current = hashContents(readFileSync(target, "utf8"));
+      const known = previousByPath.get(file.target);
+
+      if (!known) {
+        // Not ours: a file we never generated already occupies the
+        // path. Overwriting it would destroy work we cannot attribute.
+        result.skippedUnknown.push(file.target);
+        continue;
+      }
+      if (current !== known.hash) {
+        result.skippedCustomized.push(file.target);
+        // Keep the ORIGINAL hash: it is the baseline that says "this is
+        // customized", and replacing it with the current hash would
+        // silently re-adopt the consumer's file as ours.
+        recorded.push(known);
+        continue;
+      }
+    }
+
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, contents);
+    recorded.push({ path: file.target, hash: hashContents(contents) });
+    result.written.push(file.target);
+  }
+
+  if (spec.cron) {
+    result.cron = {
+      ...spec.cron,
+      status: scheduleCron(options.appRoot, spec.cron),
+    };
+  }
+
+  writeManifest(
+    options.appRoot,
+    recordFeature(
+      manifest,
+      feature,
+      spec.templateVersion,
+      recorded,
+      options.variables
+    )
+  );
+
+  return result;
+}
+
+export function formatAddResult(r: AddResult): string {
+  const lines = [`${r.feature}:`];
+  if (r.deprecated) lines.push(`  ⚠ deprecated: ${r.deprecated}`);
+  for (const f of r.written) lines.push(`  + ${f}`);
+  for (const f of r.skippedCustomized)
+    lines.push(`  = ${f} (yours — left alone; use --force to overwrite)`);
+  for (const f of r.skippedUnknown)
+    lines.push(`  ! ${f} (already exists and was not generated by Intelligo)`);
+  if (r.cron?.status === "written")
+    lines.push(`  + ${VERCEL_CONFIG} (${r.cron.path} on "${r.cron.schedule}")`);
+  if (
+    r.written.length === 0 &&
+    r.skippedCustomized.length === 0 &&
+    r.skippedUnknown.length === 0 &&
+    r.cron?.status !== "written"
+  )
+    lines.push("  nothing to do");
+  if (r.cron) lines.push(...cronNextSteps(r.cron));
+  return lines.join("\n");
+}
+
+/**
+ * Non-zero when a file the feature needs is still missing: one that
+ * exists but was not generated by Intelligo was left alone, so the
+ * feature is not installed as the catalogue describes it.
+ */
+export function addExitCode(r: AddResult): number {
+  return r.skippedUnknown.length > 0 ? 1 : 0;
+}
+
+function cronNextSteps(cron: NonNullable<AddResult["cron"]>): string[] {
+  const entry = JSON.stringify({ path: cron.path, schedule: cron.schedule });
+  const lines = ["", "  Next:"];
+  if (cron.status === "manual") {
+    lines.push(
+      `  - ${VERCEL_CONFIG} is yours and was left alone. Add to its "crons":`,
+      `      ${entry}`
+    );
+  }
+  lines.push(
+    "  - Set CRON_SECRET (32+ characters). Vercel sends it as the Bearer token itself.",
+    "  - Vercel Hobby runs a cron at most once a day and refuses a deployment that",
+    `    asks for more. On Hobby, or on any other host, remove the ${VERCEL_CONFIG} entry`,
+    "    and call the route from your own scheduler at the same cadence:",
+    `      curl -fsS -H "Authorization: Bearer $CRON_SECRET" https://<your-app>${cron.path}`
+  );
+  return lines;
+}

package/src/commands/create-flow.ts

@@ -0,0 +1,228 @@
+/**
+ * The conversation around `createApp`: ask what the flags did not say,
+ * scaffold, and install the chosen registry items once the developer
+ * has approved the commands that do it.
+ *
+ * Nothing runs on the developer's machine without their say-so. In a
+ * terminal the commands are shown and confirmed; without one (CI, a
+ * pipe) they run only under `--yes`, and are otherwise printed.
+ */
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+import * as p from "@clack/prompts";
+
+import {
+  assertNotOccupied,
+  createApp,
+  deriveNames,
+  formatCreateResult,
+  formatNextSteps,
+  isOccupied,
+} from "./create.js";
+import {
+  detectPackageManager,
+  formatCommand,
+  hasLocalShadcn,
+  installPlan,
+  readRegistryCatalogue,
+  shortDescription,
+  withDependencies,
+  type Command,
+} from "../registry-items.js";
+
+export type CreateFlags = {
+  target?: string;
+  /** `--items a,b` — install these without asking. */
+  items?: string[];
+  /** `--all` — every page item. */
+  all: boolean;
+  /** `--yes` — approve the install commands without asking. */
+  yes: boolean;
+  /** `--no-install` — scaffold only; print the install commands. */
+  install: boolean;
+  /**
+   * `--link-workspace` — for scaffolding inside the Intelligo monorepo,
+   * where the packages are workspace members. The default is a version
+   * range, because that is what works everywhere else.
+   */
+  linkWorkspace: boolean;
+};
+
+export function parseCreateFlags(args: readonly string[]): CreateFlags {
+  let target: string | undefined;
+  let items: string[] | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--items" || arg.startsWith("--items=")) {
+      const list = arg === "--items" ? (args[++i] ?? "") : arg.slice(8);
+      items = list
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (!arg.startsWith("-") && target === undefined) {
+      target = arg;
+    }
+  }
+  return {
+    target,
+    items,
+    all: args.includes("--all"),
+    yes: args.includes("--yes") || args.includes("-y"),
+    install: !args.includes("--no-install"),
+    linkWorkspace: args.includes("--link-workspace"),
+  };
+}
+
+/** The pages a first app most likely wants; the picker starts with them ticked. */
+const SUGGESTED = ["app-shell", "auth-login", "auth-signup", "dashboard"];
+
+function bail(
+  value: unknown,
+  message = "Nothing was created."
+): value is symbol {
+  if (!p.isCancel(value)) return false;
+  p.cancel(message);
+  return true;
+}
+
+function run(c: Command, cwd: string): boolean {
+  const result = spawnSync(c.command, c.args, {
+    cwd,
+    stdio: "inherit",
+    // pnpm, npx and friends are .cmd shims on Windows.
+    shell: process.platform === "win32",
+  });
+  return result.status === 0;
+}
+
+export async function runCreate(
+  flags: CreateFlags,
+  context: {
+    templatesDir: string;
+    frameworkVersion: string;
+    /** stdin and stdout are a terminal: prompts are allowed. */
+    interactive: boolean;
+  }
+): Promise<number> {
+  const { interactive } = context;
+  const catalogue = readRegistryCatalogue(context.templatesDir);
+  const packageManager = detectPackageManager();
+
+  if (interactive) p.intro("intelligo create");
+
+  // 1. Where.
+  let target = flags.target;
+  if (!target) {
+    if (!interactive) {
+      console.error(
+        "Usage: intelligo create <directory> [--items a,b | --all] [--yes] [--no-install]"
+      );
+      return 1;
+    }
+    const answer = await p.text({
+      message: "Project name",
+      placeholder: "my-app",
+      validate: (v) => {
+        if (!v) return "A name is required.";
+        try {
+          deriveNames(v);
+        } catch (error) {
+          return (error as Error).message;
+        }
+        return isOccupied(v) ? `${v} is not empty.` : undefined;
+      },
+    });
+    if (bail(answer)) return 1;
+    target = answer;
+  }
+  // Before any question about items, so nobody chooses pages for an
+  // app that is then refused.
+  assertNotOccupied(target);
+
+  // 2. What.
+  let selected: string[] = [];
+  if (flags.all) selected = Object.keys(catalogue.items);
+  else if (flags.items) selected = flags.items;
+  else if (interactive) {
+    const answer = await p.multiselect({
+      message: "Which pages should be installed? (space to toggle)",
+      options: Object.entries(catalogue.items).map(([name, item]) => ({
+        value: name,
+        label: item.title,
+        hint: shortDescription(item.description),
+      })),
+      initialValues: SUGGESTED.filter((n) => n in catalogue.items),
+      required: false,
+    });
+    if (bail(answer)) return 1;
+    selected = answer;
+  }
+  const items = withDependencies(selected, catalogue.requires);
+  const added = items.filter((n) => !selected.includes(n));
+  if (interactive && added.length > 0) {
+    p.log.info(`Also installing what they build on: ${added.join(", ")}`);
+  }
+
+  // 3. The scaffold.
+  const result = createApp({
+    target,
+    templatesDir: context.templatesDir,
+    frameworkVersion: context.frameworkVersion,
+    linkWorkspace: flags.linkWorkspace,
+  });
+  const appRoot = path.resolve(target);
+  if (interactive) {
+    p.log.success(`Scaffolded ${result.written.length} files in ${target}`);
+  }
+
+  // 4. The pages — only with approval.
+  const plan = installPlan(items, { appRoot, packageManager });
+  let approved = plan.length > 0 && flags.install && flags.yes;
+  if (plan.length > 0 && flags.install && !flags.yes && interactive) {
+    const needsInstall = !hasLocalShadcn(appRoot);
+    p.note(plan.map(formatCommand).join("\n"), "Commands to run in " + target);
+    const answer = await p.confirm({
+      message: needsInstall
+        ? `shadcn is not installed yet — install the dependencies (shadcn included) with ${packageManager} and add ${items.length} page(s)?`
+        : `Add ${items.length} page(s) with shadcn?`,
+    });
+    if (bail(answer, `The scaffold is in ${target}; nothing was installed.`))
+      return 1;
+    approved = answer;
+  }
+
+  let pending: Command[] = [];
+  if (approved) {
+    for (const [i, command] of plan.entries()) {
+      if (interactive) p.log.step(formatCommand(command));
+      else console.log(`› ${formatCommand(command)}`);
+      if (!run(command, appRoot)) {
+        pending = plan.slice(i);
+        const message = `\`${formatCommand(command)}\` failed — the scaffold is in place; run the rest by hand.`;
+        if (interactive) p.log.error(message);
+        else console.error(message);
+        break;
+      }
+    }
+  } else {
+    pending = plan;
+  }
+
+  const next = {
+    packageManager,
+    installed: approved && pending.length === 0,
+    pending,
+  };
+  if (interactive) {
+    p.note(formatNextSteps(target, next), "Next");
+    p.outro(
+      next.installed ? `${items.length} page(s) installed.` : "Scaffold ready."
+    );
+  } else {
+    console.log(formatCreateResult(target, result, next));
+  }
+  // A failed install is a failure; a declined one is a choice.
+  return approved && pending.length > 0 ? 1 : 0;
+}

package/src/commands/create.ts

@@ -0,0 +1,139 @@
+/**
+ * `intelligo create <name>` — a new application on the framework.
+ *
+ * This is onboarding, not the product boundary: what it writes is the
+ * consumer's from the moment it lands, and the enduring relationship is the versioned packages, not this
+ * scaffold. So it generates through the same manifest machinery as
+ * `add`, which means the very first upgrade already knows which files
+ * you have since edited.
+ *
+ * In a terminal it asks for the project name when none is given, then
+ * which registry pages to install (`--items a,b` or `--all` answer that
+ * without asking). The pages are installed by the shadcn CLI the scaffold
+ * declares, after the dependencies — and only once you approve the exact
+ * commands, or pass `--yes`. `--no-install` stops after the scaffold and
+ * prints them instead.
+ */
+
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+import { addFeature, formatAddResult, type AddResult } from "./add.js";
+import {
+  formatCommand,
+  type Command,
+  type PackageManager,
+} from "../registry-items.js";
+
+export type CreateOptions = {
+  /** Directory to create the app in; created if absent. */
+  target: string;
+  templatesDir: string;
+  frameworkVersion: string;
+  /**
+   * Emit `workspace:*` for the @intelligo-dev/* dependencies instead of a
+   * version range. Only meaningful when scaffolding inside this
+   * monorepo — outside it, pnpm fails the install with "workspace
+   * protocol used outside a workspace".
+   */
+  linkWorkspace?: boolean;
+};
+
+/** A package name and product slug derived from the directory name. */
+export function deriveNames(target: string): {
+  appName: string;
+  appSlug: string;
+} {
+  const base = path.basename(path.resolve(target));
+  const slug = base
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!slug) {
+    throw new Error(`Cannot derive a project name from "${target}".`);
+  }
+  return { appName: slug, appSlug: slug };
+}
+
+export function isOccupied(target: string): boolean {
+  const dir = path.resolve(target);
+  return existsSync(dir) && readdirSync(dir).length > 0;
+}
+
+/** Scaffolding into an occupied directory is how people lose work. */
+export function assertNotOccupied(target: string): void {
+  if (isOccupied(target)) {
+    throw new Error(
+      `${path.resolve(target)} is not empty. Create the app in a new directory, or use ` +
+        `\`intelligo add app-scaffold\` inside an existing one.`
+    );
+  }
+}
+
+export function createApp(options: CreateOptions): AddResult {
+  const target = path.resolve(options.target);
+
+  assertNotOccupied(target);
+  mkdirSync(target, { recursive: true });
+
+  const { appName, appSlug } = deriveNames(target);
+
+  return addFeature("app-scaffold", {
+    appRoot: target,
+    templatesDir: options.templatesDir,
+    frameworkVersion: options.frameworkVersion,
+    variables: {
+      __APP_NAME__: appName,
+      __APP_SLUG__: appSlug,
+      __INTELLIGO_DEP__: options.linkWorkspace
+        ? "workspace:*"
+        : `^${options.frameworkVersion}`,
+    },
+  });
+}
+
+export type NextSteps = {
+  packageManager: PackageManager;
+  /** Whether `create` already installed the dependencies. */
+  installed: boolean;
+  /** Install commands the developer declined, or that did not get to run. */
+  pending?: Command[];
+};
+
+/** A path the reader can paste into a shell, spaces and quotes included. */
+function shellQuote(value: string): string {
+  return /^[\w@%+=:,./-]+$/.test(value)
+    ? value
+    : `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+export function formatNextSteps(target: string, next: NextSteps): string {
+  const pm = next.packageManager;
+  return [
+    `cd ${shellQuote(path.relative(process.cwd(), path.resolve(target)) || ".")}`,
+    "cp .env.example .env.local   # then fill it in",
+    ...(next.pending?.length
+      ? next.pending.map(formatCommand)
+      : next.installed
+        ? []
+        : [`${pm} install`]),
+    `${pm === "npm" ? "npm run" : pm} dev`,
+  ].join("\n");
+}
+
+export function formatCreateResult(
+  target: string,
+  r: AddResult,
+  next: NextSteps = { packageManager: "pnpm", installed: false }
+): string {
+  return [
+    formatAddResult(r),
+    "",
+    "Next:",
+    ...formatNextSteps(target, next)
+      .split("\n")
+      .map((line) => `  ${line}`),
+    "",
+    "`intelligo doctor` will tell you what is still missing.",
+  ].join("\n");
+}