Skip to content

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