Skip to content

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.json
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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);
+ });
+});