An open source design system that's fully customizable and agent ready
TypeScript
astryx init foolproof: @astryxdesign/cli postinstall nudge (#4154)
Joey4494847c70e2
diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 60a8cb2d70..b9e3630d30 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -67,12 +67,14 @@"files": ["bin","src",+ "scripts/postinstall.mjs","templates","docs","CHANGELOG.md"],"scripts": {"astryx": "node bin/astryx.mjs",+ "postinstall": "node scripts/postinstall.mjs","typecheck:template-docs": "tsc --project tsconfig.template-docs.json","typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json"},diff --git a/packages/cli/scripts/postinstall.mjs b/packages/cli/scripts/postinstall.mjsnew file mode 100644index 0000000000..4ecfcc7a37--- /dev/null+++ b/packages/cli/scripts/postinstall.mjs@@ -0,0 +1,74 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file @astryxdesign/cli postinstall — nudge to run `astryx init`.+ *+ * Enforcement layer 2 of making `astryx init` foolproof: when the CLI is+ * installed as a project dependency and the project hasn't run init yet, print a+ * one-line next-step so agents/humans discover it.+ *+ * Reuses the ONE setup check (isAstryxInitialized from agent-docs.mjs — a+ * dep-free import chain, safe at install time). Non-interactive, never fails the+ * install, and stays quiet:+ * - in the monorepo/source build (not under node_modules),+ * - during npx's transient fetch (npx runs the bin — likely `init` — right+ * after, so nudging here would double up), and+ * - once setup is already done.+ */++import {fileURLToPath, pathToFileURL} from 'node:url';++const HERE = fileURLToPath(import.meta.url);++/**+ * Pure decision: should the postinstall print the setup nudge? Split out so the+ * matrix is unit-testable without an actual npm install.+ *+ * @param {object} opts+ * @param {string} opts.scriptPath - Absolute path of this 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;+}++/** @param {string} root @returns {Promise<boolean>} */+async function projectIsSetUp(root) {+ try {+ const {isAstryxInitialized} = await import('../src/commands/agent-docs.mjs');+ return isAstryxInitialized(root);+ } catch {+ return false; // best-effort — if the check can't load, fall through and nudge+ }+}++async function main() {+ const root = process.env.INIT_CWD || process.cwd();+ const nudge = shouldNudge({+ scriptPath: HERE,+ npmCommand: process.env.npm_command,+ isSetUp: await projectIsSetUp(root),+ });+ if (nudge) {+ // Scoped package form (`@astryxdesign/cli`) — always resolves to us. 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) {+ main()+ .catch(() => {})+ .finally(() => process.exit(0));+}diff --git a/packages/cli/src/commands/cli-postinstall.test.mjs b/packages/cli/src/commands/cli-postinstall.test.mjsnew file mode 100644index 0000000000..c7f538fccd--- /dev/null+++ b/packages/cli/src/commands/cli-postinstall.test.mjs@@ -0,0 +1,42 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Guardrail tests for the @astryxdesign/cli postinstall nudge (layer 2).+ *+ * Tests the pure decision matrix (shouldNudge) — nudges for a real dependency+ * install when not set up; stays quiet in the monorepo/source, during npx's+ * transient fetch (path _npx or npm_command=exec), and once set up.+ */++import {describe, it, expect} from 'vitest';+import {shouldNudge} from '../../scripts/postinstall.mjs';++const DEP = '/proj/node_modules/@astryxdesign/cli/scripts/postinstall.mjs'; // real dep install+const NPX = '/Users/x/.npm/_npx/a1b2/node_modules/@astryxdesign/cli/scripts/postinstall.mjs';+const REPO = '/repo/packages/cli/scripts/postinstall.mjs'; // monorepo/source++describe('cli postinstall — shouldNudge', () => {+ 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 (not under node_modules)', () => {+ expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);+ });++ it('quiet during npx transient install (path contains _npx)', () => {+ expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);+ });++ it('quiet during npx (npm_command=exec) — avoids double-nudge before init', () => {+ expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);+ });++ it('quiet once the project is already set up', () => {+ expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);+ });++ it('quiet with no script path (defensive)', () => {+ expect(shouldNudge({})).toBe(false);+ });+});