An open source design system that's fully customizable and agent ready
TypeScript
feat(core): postinstall nudge to run `npx @astryxdesign/cli init` (enforcement layer 1) (#4155)
Joey1ef4f07f0ecb
diff --git a/packages/core/package.json b/packages/core/package.jsonindex d938bd0c76..f0b56b7cda 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -636,6 +636,7 @@"files": ["dist","src",+ "scripts/postinstall.mjs","locales","docs.mjs","groups.doc.mjs",@@ -644,6 +645,7 @@],"scripts": {"prepack": "pnpm build",+ "postinstall": "node scripts/postinstall.mjs","build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs","build:i18n": "node scripts/build-pseudo-locale.mjs","build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",diff --git a/packages/core/scripts/postinstall.mjs b/packages/core/scripts/postinstall.mjsnew file mode 100644index 0000000000..9f42321195--- /dev/null+++ b/packages/core/scripts/postinstall.mjs@@ -0,0 +1,93 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file @astryxdesign/core postinstall — nudge to run `npx @astryxdesign/cli init`.+ *+ * Enforcement layer 1 of making `astryx init` foolproof: when the design system+ * is installed and the project hasn't run init yet, print a one-line next-step+ * so agents/humans discover it (this is the most common fresh-install entry).+ *+ * Self-contained: core is a separate package and cannot import the CLI, so the+ * agent-doc locations + marker below intentionally DUPLICATE the CLI's agent-doc+ * discovery in packages/cli/src/commands/agent-docs.mjs — keep them aligned with+ * that file. The .hermes.md / HERMES.md entries are an intentional superset (the+ * CLI writes those via `--agent hermes`). Non-interactive, never fails the+ * install, and quiet in the monorepo build, during npx's fetch, and once set up.+ */++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath, pathToFileURL} from 'node:url';++const HERE = fileURLToPath(import.meta.url);++// Duplicates the CLI's agent-doc locations + markers — keep aligned with+// packages/cli/src/commands/agent-docs.mjs. Hermes files are an intentional superset.+const AGENT_DOC_PATHS = [+ 'AGENTS.md',+ 'CLAUDE.md',+ '.claude/CLAUDE.md',+ '.cursorrules',+ '.hermes.md',+ 'HERMES.md',+];+const MARKERS = ['<!-- ASTRYX:START -->', '<!-- XDS:START -->'];++/**+ * True when the project already has the Astryx agent prompt installed (an Astryx+ * marker is present in any agent-doc file) — the same check the CLI performs.+ * @param {string} root @returns {boolean}+ */+export function isAstryxInitialized(root) {+ for (const rel of AGENT_DOC_PATHS) {+ try {+ const content = fs.readFileSync(path.join(root, rel), 'utf-8');+ if (MARKERS.some(m => content.includes(m))) return true;+ } catch {+ // Unreadable/missing — keep checking the others.+ }+ }+ return false;+}++/**+ * Pure decision: should the postinstall print the setup nudge? Unit-testable+ * without an actual npm install.+ * @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+ if (isSetUp) return false; // already set up — stay quiet+ return true;+}++function main() {+ const root = process.env.INIT_CWD || process.cwd();+ if (+ shouldNudge({+ scriptPath: HERE,+ npmCommand: process.env.npm_command,+ isSetUp: isAstryxInitialized(root),+ })+ ) {+ // Scoped package form (`@astryxdesign/cli`) — always resolves to us, even+ // before the CLI is installed. Bare `npx astryx` would fetch an unrelated+ // look-alike package (see PR #4151). After that lands, switch this to its+ // getCliInvocation() single source of truth.+ process.stdout.write(+ '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n',+ );+ }+}++// Run only when executed directly (`node scripts/postinstall.mjs`), never when+// imported by tests.+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {+ try {+ main();+ } catch {+ // never break an install+ }+ process.exit(0);+}diff --git a/packages/core/src/postinstall.test.mjs b/packages/core/src/postinstall.test.mjsnew file mode 100644index 0000000000..e087e8ca89--- /dev/null+++ b/packages/core/src/postinstall.test.mjs@@ -0,0 +1,71 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Guardrail tests for the @astryxdesign/core postinstall nudge (layer 1).+ *+ * The marker check mirrors the CLI's single source of truth (core can't import+ * the CLI). Tests that it detects the marker across EVERY agent-doc location+ * (incl. Hermes) + legacy markers, and that the nudge decision matrix is correct.+ */++import {describe, it, expect, beforeEach, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {isAstryxInitialized, shouldNudge} from '../scripts/postinstall.mjs';++const MARKER = '<!-- ASTRYX:START -->';++let tmp;+beforeEach(() => {+ tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-postinstall-'));+});+afterEach(() => {+ fs.rmSync(tmp, {recursive: true, force: true});+});+function write(rel, body) {+ const p = path.join(tmp, rel);+ fs.mkdirSync(path.dirname(p), {recursive: true});+ fs.writeFileSync(p, body);+}++describe('core postinstall — isAstryxInitialized (mirrors CLI contract)', () => {+ it('is false in an empty project', () => {+ expect(isAstryxInitialized(tmp)).toBe(false);+ });++ it.each(['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md'])(+ 'detects the marker in %s',+ file => {+ write(file, `# doc\n${MARKER}\nbody`);+ expect(isAstryxInitialized(tmp)).toBe(true);+ },+ );++ it('detects the legacy XDS marker', () => {+ write('AGENTS.md', '<!-- XDS:START -->');+ expect(isAstryxInitialized(tmp)).toBe(true);+ });+});++describe('core postinstall — shouldNudge', () => {+ const DEP = '/proj/node_modules/@astryxdesign/core/scripts/postinstall.mjs';+ const NPX = '/Users/x/.npm/_npx/a1/node_modules/@astryxdesign/core/scripts/postinstall.mjs';+ const REPO = '/repo/packages/core/scripts/postinstall.mjs';++ it('nudges for a real dependency install when not set up', () => {+ expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: false})).toBe(true);+ });+ it('quiet in the monorepo/source', () => {+ expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);+ });+ it('quiet during npx transient install (_npx path)', () => {+ expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);+ });+ it('quiet during npx (npm_command=exec)', () => {+ expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);+ });+ it('quiet once set up', () => {+ expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);+ });+});