Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
10.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

// GENERATED FILE — DO NOT EDIT.
// Source:     packages/cli/foundation/agent-docs/agent-doc-state.mjs
// Regenerate: pnpm generate:setup-contract
//
// @astryxdesign/core cannot import @astryxdesign/cli (the CLI peer-depends on
// core, so the import would be a cycle), but core's postinstall must answer
// "is Astryx set up?" exactly as the CLI does. The CLI's dependency-free leaf is
// therefore copied here verbatim and pinned by `pnpm check:setup-contract`,
// which runs inside `pnpm check:repo`.

/**
 * @file agent-doc-state — the canonical, dependency-free contract for "where
 * Astryx writes its agent block" and "has this project run init yet?".
 *
 * Deliberately a LEAF module: it imports only node builtins (`fs`, `path`), so
 * it is safe to load in constrained contexts — most importantly the CLI's
 * `postinstall` script, which runs at `npm install` time, before the rest of the
 * CLI's module graph is guaranteed importable. Its sibling `agent-docs.mjs`
 * reaches component discovery, package-manager detection, and the response
 * layer, so the pure setup-check lives HERE and `agent-docs.mjs` re-exports it.
 *
 * SINGLE SOURCE OF TRUTH for every "is Astryx set up?" enforcement layer:
 *   - layer 3 — the per-command setup nudge (`clients/cli/index.mjs`),
 *   - layer 2 — the CLI postinstall nudge (`scripts/postinstall.mjs`),
 *   - the `init` / `upgrade` / `agent-docs` commands (via `agent-docs.mjs`).
 * Core's postinstall (layer 1) is a separate published package and cannot import
 * the CLI, so it ships a package-local copy at
 * `packages/core/scripts/agent-doc-state.mjs`. That copy is GENERATED from this
 * file, byte for byte, by `scripts/generate-setup-contract.mjs`, and
 * `pnpm check:setup-contract` (part of `check:repo`) fails the build when the
 * two differ. Edit the contract HERE and nowhere else.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';

export const AGENTS_MD = 'AGENTS.md';
export const CLAUDE_MD = 'CLAUDE.md';
export const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
export const GEMINI_MD = 'GEMINI.md';
export const CURSOR_RULES = '.cursorrules';
export const HERMES_DOT_MD = '.hermes.md';
export const HERMES_MD = 'HERMES.md';

/**
 * The page workflow every Astryx agent text gives, written with the command
 * name `astryx`: the project agent docs and the computer-level skill both
 * render these lines, so the two never drift.
 */
export const WORKFLOW_TITLE =
  'WORKFLOW — start every page from a template, never from scratch:';
export const WORKFLOW_STEPS = Object.freeze([
  '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',
  '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',
  '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',
]);

/**
 * The self-check's fix for a project with no StyleX or Tailwind compiler,
 * and for an agent outside a project.
 */
export const SELF_CHECK_CSS =
  'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';

export const MARKER_START = '<!-- ASTRYX:START -->';
export const MARKER_END = '<!-- ASTRYX:END -->';
// Legacy markers — read during migration so the script finds existing XDS blocks
export const LEGACY_MARKER_START = '<!-- XDS:START -->';
export const LEGACY_MARKER_END = '<!-- XDS:END -->';

/**
 * The canonical set of EVERY location an --agent preset (or the default) can
 * write a managed Astryx block — the full block, or the one-line import of
 * AGENTS.md that the default writes to GEMINI.md. SINGLE
 * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
 * all derive from this list, so "where init writes" and "where we look" can
 * never drift. (Explicit --agent-docs-path targets are user-chosen and not
 * enumerable here.)
 */
export const AGENT_DOC_PATHS = [
  AGENTS_MD, // Codex / ChatGPT / Muse / generic
  CLAUDE_MD, // Claude Code (root)
  CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
  GEMINI_MD, // Gemini CLI
  CURSOR_RULES, // Cursor
  HERMES_DOT_MD, // Hermes
  HERMES_MD, // Hermes
];

/**
 * Markers whose presence means an Astryx block has been installed — the current
 * marker plus the legacy XDS one, so pre-rename projects still count as set up.
 */
export const INIT_MARKERS = [MARKER_START, LEGACY_MARKER_START];

/**
 * Find all existing agent doc files in a directory, across EVERY location any
 * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
 * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
 * @param {string} targetDir
 * @returns {string[]} Relative paths of existing agent doc files
 */
export function discoverAgentDocs(targetDir) {
  return AGENT_DOC_PATHS.filter(p => fs.existsSync(path.join(targetDir, p)));
}

/**
 * Whether `content` holds an Astryx block. A managed block that only imports
 * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
 * not count: it holds nothing once that file has lost its block. A malformed
 * block still counts, so a half-written file reads as set up.
 *
 * @param {string} content
 * @returns {boolean}
 */
export function holdsAstryxBlock(content) {
  for (const marker of INIT_MARKERS) {
    let at = content.indexOf(marker);
    while (at !== -1) {
      const from = at + marker.length;
      const end = content.indexOf('<!--', from);
      const inner = (
        end === -1 ? content.slice(from) : content.slice(from, end)
      ).trim();
      if (!/^@\S+$/.test(inner)) return true;
      at = content.indexOf(marker, from);
    }
  }
  return false;
}

/**
 * Single source of truth for "is Astryx set up in this project?" — true when any
 * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
 * run. Reused by the init & upgrade commands, the per-command setup nudge
 * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
 * postinstall (separate package, layer 1) mirrors the same marker contract.
 *
 * @param {string} [targetDir=process.cwd()]
 * @returns {boolean}
 */
export function isAstryxInitialized(targetDir = process.cwd()) {
  for (const rel of discoverAgentDocs(targetDir)) {
    try {
      const content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
      if (holdsAstryxBlock(content)) {
        return true;
      }
    } catch {
      // Unreadable file — ignore and keep checking the others.
    }
  }
  return false;
}

/**
 * Does an agent working in `startDir` already have the Astryx prompt in reach?
 *
 * Coding agents read the agent docs between the repository root and the folder
 * they work in. So inside a git repository, init's block in any folder from
 * `startDir` up to the repository root counts: a workspace package of a
 * monorepo initialized at its root is set up. Outside a repository only
 * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
 * per-command nudge and the postinstall nudges ask this.
 *
 * @param {string} [startDir=process.cwd()]
 * @returns {boolean}
 */
export function isAstryxPromptInReach(startDir = process.cwd()) {
  const start = path.resolve(startDir);
  const repositoryRoot = findRepositoryRoot(start);
  if (!repositoryRoot) return isAstryxInitialized(start);
  for (let dir = start; ; dir = path.dirname(dir)) {
    if (isAstryxInitialized(dir)) return true;
    if (dir === repositoryRoot) return false;
  }
}

/**
 * The nearest folder at or above `start` that holds `.git` (a folder, or the
 * file a worktree uses), or null outside a repository.
 * @param {string} start
 * @returns {string | null}
 */
function findRepositoryRoot(start) {
  for (let dir = start; ;) {
    if (fs.existsSync(path.join(dir, '.git'))) return dir;
    const parent = path.dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

/**
 * The invocation the setup nudge falls back to when the CLI's picker
 * (`getCliInvocation`) cannot be loaded. Scoped package form
 * (`@astryxdesign/cli`) — always resolves to us, even before the CLI is
 * installed. npx with the unscoped name would fetch an unrelated look-alike
 * package (see PR #4151).
 */
export const SETUP_INVOCATION = 'npx @astryxdesign/cli';

/**
 * The one-line next-step every setup layer prints. Kept here so layer 1
 * (core), layer 2 (cli postinstall) and layer 3 (each command) can never word
 * it differently. Each layer passes the stem from the CLI's picker when it can
 * load it.
 *
 * @param {string} [invocation] the CLI invocation stem, e.g. `pnpm exec astryx`
 * @param {{before?: string | null}} [options] `before`: a command to run
 *   first, such as the one that adds the CLI to a project that has none
 * @returns {string}
 */
export function setupNudge(
  invocation = SETUP_INVOCATION,
  {before = null} = {},
) {
  const run = before
    ? `\`${before}\`, then \`${invocation} init\``
    : `\`${invocation} init\``;
  return `\nNext step: run ${run} to finish setup and install the Astryx agent prompt.\n\n`;
}

/** The nudge with the fallback invocation. */
export const SETUP_NUDGE = setupNudge();

/**
 * Pure decision: should a postinstall print the setup nudge? Shared by BOTH
 * postinstall layers, so the matrix cannot drift between them, and unit-testable
 * without an actual npm install.
 *
 * @param {object} [opts]
 * @param {string} [opts.scriptPath] - Absolute path of the calling script
 *   (location tells us dependency vs monorepo vs npx-cache).
 * @param {string} [opts.npmCommand] - process.env.npm_command ('install', 'exec', …).
 * @param {boolean} [opts.isSetUp] - Whether the project already ran init.
 * @returns {boolean}
 */
export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {
  if (!scriptPath || !scriptPath.includes('node_modules')) return false; // monorepo/source build
  if (scriptPath.includes('_npx') || npmCommand === 'exec') return false; // npx transient — init runs next
  if (isSetUp) return false; // already set up — stay quiet
  return true;
}