@astryxdesign/cli 0.1.6-canary.ff5dfca → 0.1.7-canary.04cd8f7

package/docs/integration-authoring.md

@@ -1,105 +0,0 @@
-# Authoring an Astryx Integration
-
-> **Status:** working notes. This should eventually move to the public wiki
-> alongside the rest of the integration-authoring guidance; it lives here for
-> now so it ships and is versioned with the CLI.
-
-An **Integration** is an npm package that contributes components, templates, and/or
-codemods to a consumer's design-system workflow. Consumers install the 3rd party
-package, add a line to their astryx.config file:
-
-```js
-import {createConfig} from '@astryxdesign/cli/config';
-
-export default createConfig({
-  integrations: ['@acme/astryx-widgets'],
-  ...
-});
-```
-
-Then the integration's components and templates will be surfaced alongside Astryx
-components in the Astryx CLI.
-
-```sh
-astryx component AcmeCarousel --props
-astryx component --list --package @acme/astryx-widgets
-```
-
-## The Integration File
-
-In order to register your package as an Astryx Integration, create an
-`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
-tells Astryx where to find your components, templates, codemods, etc.
-
-```js
-// astryx.integration.{ts,mjs,js}
-import {createIntegration} from '@astryxdesign/cli/integration';
-
-export default createIntegration({
-  components: './components',
-  templates: './templates',
-  codemods: './codemods',
-  issuesUrl: 'https://github.com/acme/widgets/issues',
-});
-```
-
-## Components
-
-Your components themselves may be exported from your library as you see fit (consumers
-will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
-file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
-
-```js
-// AcmeCarousel.doc.ts
-import {createComponentDoc} from '@astryxdesign/cli/doc';
-
-export default createComponentDoc({
-  name: 'AcmeCarousel',
-  description: '...',
-  ...
-});
-```
-
-## Templates
-
-Templates are typically not exported from the package directly, but instead accessed
-via the Astryx CLI. Consumers can look through your templates and materialize them
-into their apps.
-
-You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
-(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
-
-```js
-// AcmeLandingPage.template.ts
-import {createPageTemplate} from '@astryxdesign/cli/template';
-
-export default createPageTemplate({
-  ...
-});
-```
-
-Note that, since the CLI needs access to the template source code, you need to make sure
-that it is included in your published package. This will also allow us to render previews
-of templates in the future by bundling your template into a doc site build.
-
-Typically, this is done via the package.json `exports` key.
-
-```jsonc
-{
-  "exports": {
-    // ...
-    "./templates/*.tsx": "./templates/*.tsx",
-  },
-}
-```
-
-In order to verify that it's working, you can test importing the template component like this:
-
-```ts
-import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
-```
-
-Import **with the `.tsx` extension** — an extensionless specifier won't resolve
-under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
-above is what lets that import type-check without consumers enabling
-`allowImportingTsExtensions`.

package/src/utils/interactive.mjs

@@ -1,76 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Interactivity contract for the CLI.
- *
- * A single source of truth for "can this process prompt the user?". Several
- * commands launch @clack/prompts wizards; in a non-interactive context (CI,
- * piped stdin/stdout, no TTY) those prompts block forever. Historically each
- * command answered this question differently — some checked `stdout.isTTY`,
- * one checked `stdin.isTTY`, one added `!process.env.CI`, and some had no
- * guard at all. This module centralizes the check so every command behaves
- * identically.
- *
- * Two entry points, for two situations:
- *
- *   - `requireInteractive()` — for commands whose prompt IS the work
- *     (e.g. `astryx init`, `astryx theme`). With no TTY there is nothing to do, so
- *     fail fast (exit 1) with actionable, non-interactive guidance.
- *
- *   - `isInteractive()` — for commands with an OPTIONAL secondary prompt
- *     that runs after the primary work has already succeeded; callers use
- *     this to skip the prompt gracefully in non-interactive contexts.
- */
-
-/**
- * True when the process can safely run an interactive prompt.
- *
- * Requires BOTH stdin and stdout to be TTYs (clack reads stdin and renders to
- * stdout) and that we are not in a CI environment. A CI runner may allocate a
- * pseudo-TTY, so `process.env.CI` is an explicit override: never prompt in CI.
- *
- * @param {object} [env] - Override hook for tests.
- * @param {boolean} [env.stdinTTY=process.stdin.isTTY]
- * @param {boolean} [env.stdoutTTY=process.stdout.isTTY]
- * @param {boolean} [env.ci=Boolean(process.env.CI)]
- * @returns {boolean}
- */
-export function isInteractive({
-  stdinTTY = Boolean(process.stdin && process.stdin.isTTY),
-  stdoutTTY = Boolean(process.stdout && process.stdout.isTTY),
-  ci = Boolean(process.env.CI),
-} = {}) {
-  if (ci) return false;
-  return stdinTTY && stdoutTTY;
-}
-
-/**
- * Guard for commands whose primary action is an interactive wizard. When the
- * process is non-interactive, prints an actionable error and exits 1 instead
- * of hanging on a prompt that will never receive input.
- *
- * @param {object} options
- * @param {string} options.command - Command name for the message, e.g. 'init'.
- * @param {string} options.hint - Concrete non-interactive invocation, e.g.
- *   '`pnpm astryx init --all` or `--features agents,theme,template`'.
- * @param {boolean} [options.json=false] - When true, the command does not
- *   support --json; we still exit 1 but skip the human-formatted guidance.
- * @param {object} [env] - Forwarded to isInteractive (test hook).
- * @returns {void} Returns when interactive; otherwise calls process.exit(1).
- */
-export function requireInteractive({command, hint, json = false} = {}, env) {
-  if (isInteractive(env)) return;
-  const name = command ? `astryx ${command}` : 'this command';
-  console.error(
-    `Error: \`${name}\` with no flags is interactive and requires a TTY.`,
-  );
-  if (hint) {
-    console.error(`Run non-interactively with: ${hint}`);
-  }
-  if (!json) {
-    console.error(
-      'Detected a non-interactive environment (no TTY, piped I/O, or CI=1).',
-    );
-  }
-  process.exit(1);
-}

package/src/utils/interactive.test.mjs

@@ -1,70 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Unit tests for the interactivity contract.
- *
- * isInteractive() is pure given its injected env, so these are fast unit
- * tests. The "does the command actually fail fast instead of hanging" proof
- * lives in the per-command subprocess tests (init/theme non-interactive).
- */
-
-import {describe, it, expect, vi, afterEach} from 'vitest';
-import {isInteractive, requireInteractive} from './interactive.mjs';
-
-describe('isInteractive', () => {
-  it('is true only when stdin AND stdout are TTYs and not CI', () => {
-    expect(isInteractive({stdinTTY: true, stdoutTTY: true, ci: false})).toBe(true);
-  });
-
-  it('is false when stdin is not a TTY (piped input)', () => {
-    expect(isInteractive({stdinTTY: false, stdoutTTY: true, ci: false})).toBe(false);
-  });
-
-  it('is false when stdout is not a TTY (piped output)', () => {
-    expect(isInteractive({stdinTTY: true, stdoutTTY: false, ci: false})).toBe(false);
-  });
-
-  it('is false in CI even with a pseudo-TTY on both streams', () => {
-    expect(isInteractive({stdinTTY: true, stdoutTTY: true, ci: true})).toBe(false);
-  });
-});
-
-describe('requireInteractive', () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('returns (does not exit) when interactive', () => {
-    const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
-      throw new Error('exit should not be called');
-    });
-    expect(() =>
-      requireInteractive(
-        {command: 'init', hint: '`astryx init --all`'},
-        {stdinTTY: true, stdoutTTY: true, ci: false},
-      ),
-    ).not.toThrow();
-    expect(exit).not.toHaveBeenCalled();
-  });
-
-  it('exits 1 with actionable guidance when non-interactive', () => {
-    const exit = vi
-      .spyOn(process, 'exit')
-      .mockImplementation(() => {
-        throw new Error('__exit__');
-      });
-    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
-    expect(() =>
-      requireInteractive(
-        {command: 'theme', hint: '`astryx theme <preset>`'},
-        {stdinTTY: false, stdoutTTY: false, ci: false},
-      ),
-    ).toThrow('__exit__');
-    expect(exit).toHaveBeenCalledWith(1);
-    const output = err.mock.calls.map(c => c.join(' ')).join('\n');
-    expect(output).toMatch(/requires a TTY/i);
-    expect(output).toMatch(/astryx theme <preset>/);
-    expect(output).toMatch(/`astryx theme`/);
-    expect(output).not.toMatch(/\bxds\b/);
-  });
-});