@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/clients/cli/commands/layout.mjs

@@ -1,263 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file layout command — thin CLI wrapper around api/layout.mjs.
- *
- * Subcommands:
- *   astryx layout expand "<expr>" [path]   compressed expression → validated TSX
- *   astryx layout check "<expr>"           validate + echo both canonical surfaces
- *   astryx layout grammar                  agent cheatsheet (alias table is branch-generated)
- *
- * The expression argument may also come from --file or stdin (`-`),
- * which is how multi-line outline (XLO) input usually arrives.
- *
- * The command surface (group + subcommand descriptions, args, flags) is sourced
- * from the colocated CommandDocs via `defineCommand`; this file supplies only the
- * actions.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, text, list, record, code, WARN} from '../formatters/index.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {layoutExpand, layoutCheck, layoutGrammar} from '../../../api/layout/layout.mjs';
-import {defineCommand} from '../lib/define-command.mjs';
-import {doc as layoutGroup} from './layout.doc.mjs';
-import {doc as layoutExpandCommand} from './layout-expand.doc.mjs';
-import {doc as layoutCheckCommand} from './layout-check.doc.mjs';
-import {doc as layoutGrammarCommand} from './layout-grammar.doc.mjs';
-import {doc as layoutExpandFn} from '../../../api/layout/layoutExpand.doc.mjs';
-import {doc as layoutCheckFn} from '../../../api/layout/layoutCheck.doc.mjs';
-import {doc as layoutGrammarFn} from '../../../api/layout/layoutGrammar.doc.mjs';
-import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
-
-/**
- * The api layer's @returns for these functions widen the `type` discriminator
- * to `string`, so annotate the command-local result with the precise response
- * shapes from the colocated api/layout/layout.type.mjs so narrowing + jsonOut
- * typecheck.
- *
- * @typedef {import('../../../api/layout/layout.type.mjs').LayoutExpandResponse} LayoutExpandResponse
- * @typedef {import('../../../api/layout/layout.type.mjs').LayoutCheckResponse} LayoutCheckResponse
- * @typedef {import('../../../api/layout/layout.type.mjs').LayoutGrammarResponse} LayoutGrammarResponse
- */
-
-/**
- * @typedef {object} LayoutExpandOptions
- * @property {string} [file]
- * @property {'compact'|'outline'|'auto'} [form]
- * @property {string} [name]
- * @property {boolean} [loose]
- */
-
-/**
- * @typedef {object} LayoutCheckOptions
- * @property {string} [file]
- * @property {'compact'|'outline'|'auto'} [form]
- * @property {boolean} [loose]
- */
-
-/**
- * Resolve the expression from arg, --file, or stdin ('-').
- * @param {string} [expr]
- * @param {{file?: string}} [options]
- * @returns {Promise<string>}
- */
-async function readExpression(expr, options = {}) {
-  if (options.file) {
-    // Validate the file exists + is a regular file + is reasonably sized.
-    // We intentionally do NOT confine the read path (the user running the CLI
-    // controls --file; this is a read, not a write). The size cap prevents OOM
-    // from infinite streams like /dev/zero.
-    const filePath = path.resolve(process.cwd(), options.file);
-    const stat = fs.statSync(filePath, {throwIfNoEntry: false});
-    if (!stat || !stat.isFile()) {
-      cliError(`File not found: ${options.file}`, {
-        code: ERROR_CODES.ERR_FILE_NOT_FOUND,
-      });
-    }
-    const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 MB
-    if (stat.size > MAX_FILE_SIZE) {
-      cliError(
-        `File "${options.file}" is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 5 MB)`,
-        {code: ERROR_CODES.ERR_FILE_NOT_FOUND},
-      );
-    }
-    try {
-      return fs.readFileSync(filePath, 'utf-8');
-    } catch (e) {
-      const errno = /** @type {NodeJS.ErrnoException} */ (e);
-      if (errno && errno.code === 'ENOENT') {
-        // A --file pointing at a missing file is foreseeable — surface a
-        // stable code, not the raw ENOENT errno (and no stack in human mode).
-        cliError(`File not found: ${options.file}`, {
-          code: ERROR_CODES.ERR_FILE_NOT_FOUND,
-        });
-      }
-      throw e;
-    }
-  }
-  if (expr === '-') {
-    /** @type {Buffer[]} */
-    const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
-    return Buffer.concat(chunks).toString('utf-8');
-  }
-  return expr ?? '';
-}
-
-/**
- * @param {import('commander').Command} program
- */
-export function registerLayout(program) {
-  const layoutCmd = defineCommand(program, layoutGroup);
-
-  defineCommand(layoutCmd, layoutExpandCommand, {
-    fn: layoutExpandFn,
-    action: async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ options) => {
-      const json = program.opts().json || false;
-      const source = await readExpression(expression, options);
-      if (!source || source.trim() === '') {
-        return cliError(
-          'No layout expression given — pass it as an argument, via --file, or on stdin',
-          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
-        );
-      }
-      /** @type {LayoutExpandResponse} */
-      let result;
-      try {
-        result = /** @type {LayoutExpandResponse} */ (await layoutExpand(source, {
-          targetPath,
-          form: options.form,
-          loose: options.loose || false,
-          name: options.name,
-          cwd: process.cwd(),
-        }));
-      } catch (e) {
-        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
-        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
-      }
-      // Expanding turns an expression into TSX — a transformation, not a
-      // lookup. What it produced is in the output; there is no set to count.
-      if (json) {
-        jsonOut(result);
-        return NO_RESULT_SET;
-      }
-
-      /** @type {import('../formatters/index.mjs').Block[]} */
-      const out = [];
-      if (result.data.warnings.length > 0) {
-        out.push(text(result.data.warnings.map(w => `${WARN} ${w}`).join('\n')));
-      }
-      if (result.data.written) {
-        out.push(
-          text(`[ok] Expanded to ${result.data.written}`),
-          record(
-            {
-              components: result.data.componentsUsed,
-              todos:
-                result.data.todos.length > 0
-                  ? `${result.data.todos.length} (search for "TODO(xle)")`
-                  : '',
-            },
-            {labels: {components: 'Components', todos: 'TODOs'}},
-          ),
-        );
-      } else {
-        // Raw expanded TSX (no target path) — preformatted, emitted verbatim.
-        out.push(code(result.data.code));
-      }
-      emit(...out);
-      return NO_RESULT_SET;
-    },
-  });
-
-  defineCommand(layoutCmd, layoutCheckCommand, {
-    fn: layoutCheckFn,
-    action: async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ options) => {
-      const json = program.opts().json || false;
-      const source = await readExpression(expression, options);
-      if (!source || source.trim() === '') {
-        return cliError(
-          'No layout expression given — pass it as an argument, via --file, or on stdin',
-          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
-        );
-      }
-      /** @type {LayoutCheckResponse} */
-      let result;
-      try {
-        result = /** @type {LayoutCheckResponse} */ (await layoutCheck(source, {
-          form: options.form,
-          loose: options.loose || false,
-          cwd: process.cwd(),
-        }));
-      } catch (e) {
-        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
-        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
-      }
-      // Exit code is the contract and must NOT depend on --json vs human: an
-      // invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
-      // works as a CI gate / agent check without parsing stdout. Decide it
-      // before the JSON return (parity with doctor integration validate).
-      if (!result.data.valid) process.exitCode = 1;
-
-      // A verdict on one expression: valid or not, with the errors that made
-      // it so. Nothing was looked up.
-      if (json) {
-        jsonOut(result);
-        return NO_RESULT_SET;
-      }
-
-      const {valid, form, errors, warnings, compact, outline} = result.data;
-      if (!valid) {
-        // Each error: the formatted issue, with a hanging "did you mean" line.
-        const items = errors.map(e =>
-          e.suggestions && e.suggestions.length > 0
-            ? [e.formatted, `did you mean: ${e.suggestions.join(', ')}?`]
-            : [e.formatted],
-        );
-        emit(
-          text(`[fail] Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`),
-          list(items),
-        );
-        return NO_RESULT_SET;
-      }
-
-      /** @type {import('../formatters/index.mjs').Block[]} */
-      const out = [text(`[ok] Valid (parsed as ${form})`)];
-      if (warnings.length > 0) {
-        out.push(text(warnings.map(w => `${WARN} ${w}`).join('\n')));
-      }
-      // The canonical compact/outline surfaces are preformatted — emit verbatim.
-      out.push(section('compact'), code(compact), section('outline'), code(outline));
-      emit(...out);
-      return NO_RESULT_SET;
-    },
-  });
-
-  defineCommand(layoutCmd, layoutGrammarCommand, {
-    fn: layoutGrammarFn,
-    action: async () => {
-      const json = program.opts().json || false;
-      /** @type {LayoutGrammarResponse} */
-      let result;
-      try {
-        result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
-      } catch (e) {
-        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
-        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
-      }
-      // One document, the same one every time: the grammar cheatsheet.
-      const answered = resultSet({count: 1, resultKind: 'doc'});
-      if (json) {
-        jsonOut(result);
-        return answered;
-      }
-      // The cheatsheet is a preformatted document — emit verbatim.
-      emit(code(result.data.text));
-      return answered;
-    },
-  });
-}

package/clients/cli/lib/update-check.mjs

@@ -1,83 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Check for newer @astryxdesign/core versions via local signals.
- *
- * Resolution order:
- * 1. $ASTRYX_LATEST_VERSION env var
- * 2. If unset: no hint (no network calls from this module)
- *
- * When a newer version is detected, returns a hint string for CLI output.
- * Also sets $ASTRYX_LATEST_VERSION for subsequent commands in the same shell.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {semverGt} from '../../../foundation/env/semver.mjs';
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
-
-/**
- * Read the latest available version from local signals.
- * No network calls — purely an env-var check ($ASTRYX_LATEST_VERSION),
- * so it takes no arguments.
- *
- * @returns {string|null} Latest version string, or null if unknown
- */
-export function getLatestVersion() {
-  // 1. Check env var (fastest — set by previous CLI run)
-  const envVersion = process.env.ASTRYX_LATEST_VERSION;
-  if (envVersion && /^\d+\.\d+\.\d+/.test(envVersion)) {
-    return envVersion;
-  }
-
-  return null;
-}
-
-/**
- * Get the currently installed @astryxdesign/core version from the consumer's package.json.
- *
- * @param {string} [cwd] - Project directory
- * @returns {string|null} Installed version, or null
- */
-export function getInstalledVersion(cwd = process.cwd()) {
-  try {
-    const pkgPath = path.resolve(cwd, 'package.json');
-    if (!fs.existsSync(pkgPath)) return null;
-
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    const deps = {...pkg.dependencies, ...pkg.devDependencies};
-    const version = deps['@astryxdesign/core'];
-    if (!version) return null;
-
-    // Strip semver range prefix
-    return version.replace(/^[^\d]*/, '');
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check for available updates and return a hint string if one exists.
- * Also sets $ASTRYX_LATEST_VERSION env var for subsequent commands.
- *
- * @param {string} [cwd] - Project directory
- * @returns {string|null} FYI hint string, or null if up to date / unknown
- */
-export function checkForUpdate(cwd = process.cwd()) {
-  const latest = getLatestVersion();
-  if (!latest) return null;
-
-  // Persist for subsequent commands in this shell session
-  process.env.ASTRYX_LATEST_VERSION = latest;
-
-  const installed = getInstalledVersion(cwd);
-  if (!installed) return null;
-
-  // Use semver-aware comparison so '0.0.20' is correctly treated as greater
-  // than '0.0.5' (lexicographic compare gets that backwards).
-  if (semverGt(latest, installed)) {
-    return `FYI: A newer version of @astryxdesign/core (${latest}) is available. Install the new package version, then run: ${getCliInvocation()} upgrade --from <old-version> --apply`;
-  }
-
-  return null;
-}

package/clients/cli/lib/update-check.test.mjs

@@ -1,137 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {
-  getLatestVersion,
-  getInstalledVersion,
-  checkForUpdate,
-} from './update-check.mjs';
-
-let tmpDir;
-const originalEnv = {};
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-update-check-'));
-  // Save and clear env
-  originalEnv.ASTRYX_LATEST_VERSION = process.env.ASTRYX_LATEST_VERSION;
-  delete process.env.ASTRYX_LATEST_VERSION;
-});
-
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
-  // Restore env
-  if (originalEnv.ASTRYX_LATEST_VERSION !== undefined) {
-    process.env.ASTRYX_LATEST_VERSION = originalEnv.ASTRYX_LATEST_VERSION;
-  } else {
-    delete process.env.ASTRYX_LATEST_VERSION;
-  }
-});
-
-describe('getLatestVersion', () => {
-  it('reads from ASTRYX_LATEST_VERSION env var', () => {
-    process.env.ASTRYX_LATEST_VERSION = '0.0.8';
-    expect(getLatestVersion()).toBe('0.0.8');
-  });
-
-  it('ignores invalid env var values', () => {
-    process.env.ASTRYX_LATEST_VERSION = 'not-a-version';
-    expect(getLatestVersion()).toBeNull();
-  });
-
-  it('returns null when no signals exist', () => {
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({name: 'test'}),
-    );
-    expect(getLatestVersion()).toBeNull();
-  });
-});
-
-describe('getInstalledVersion', () => {
-  it('reads @astryxdesign/core version from dependencies', () => {
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.0.7'}}),
-    );
-    expect(getInstalledVersion(tmpDir)).toBe('0.0.7');
-  });
-
-  it('strips semver range prefix', () => {
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '~0.0.5'}}),
-    );
-    expect(getInstalledVersion(tmpDir)).toBe('0.0.5');
-  });
-
-  it('returns null when @astryxdesign/core is not a dependency', () => {
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {react: '^19.0.0'}}),
-    );
-    expect(getInstalledVersion(tmpDir)).toBeNull();
-  });
-});
-
-describe('checkForUpdate', () => {
-  it('returns hint when newer version is available', () => {
-    process.env.ASTRYX_LATEST_VERSION = '0.0.8';
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.0.7'}}),
-    );
-
-    const hint = checkForUpdate(tmpDir);
-    expect(hint).toContain('0.0.8');
-    expect(hint).toContain('astryx upgrade --from <old-version> --apply');
-    expect(hint).toContain('FYI');
-  });
-
-  it('returns null when up to date', () => {
-    process.env.ASTRYX_LATEST_VERSION = '0.0.7';
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.0.7'}}),
-    );
-
-    expect(checkForUpdate(tmpDir)).toBeNull();
-  });
-
-  it('returns null when no latest version is known', () => {
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.0.7'}}),
-    );
-
-    expect(checkForUpdate(tmpDir)).toBeNull();
-  });
-
-  it('uses semver (not lexicographic) comparison for double-digit patches', () => {
-    // Regression: with string compare, '0.0.20' > '0.0.5' is false because
-    // '2' < '5' lexicographically. Users on 0.0.5 would never be told that
-    // 0.0.20 is available.
-    process.env.ASTRYX_LATEST_VERSION = '0.0.20';
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.0.5'}}),
-    );
-
-    const hint = checkForUpdate(tmpDir);
-    expect(hint).toContain('0.0.20');
-  });
-
-  it('does not suggest an upgrade when latest < installed (semver)', () => {
-    // The mirror-image bug: '0.0.9' > '0.0.10' is true under string compare,
-    // so a stale env hint of 0.0.9 would falsely claim it's "newer" than 0.0.10.
-    process.env.ASTRYX_LATEST_VERSION = '0.0.9';
-    fs.writeFileSync(
-      path.join(tmpDir, 'package.json'),
-      JSON.stringify({dependencies: {'@astryxdesign/core': '^0.0.10'}}),
-    );
-
-    expect(checkForUpdate(tmpDir)).toBeNull();
-  });
-});

package/clients/cli/update-hint-commands.test.mjs

@@ -1,54 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Guards the update-hint command allowlist.
- *
- * The post-action update hint only fires for a small set of commands
- * (see UPDATE_HINT_COMMANDS in index.mjs). Every name in that set must
- * map to a real, registered command — otherwise the entry is dead and
- * the hint can never fire for it. This test imports the assembled
- * program and verifies the invariant so a stale reference can't creep in.
- *
- * Historically there was a dead 'doctor' entry in UPDATE_HINT_COMMANDS that
- * referenced a command that didn't exist. `doctor` is now a real command
- * (the health check), but it is intentionally NOT in the update-hint set —
- * the hint is for content commands (component/docs) that agents read, not
- * for the diagnostic command. This test pins both invariants.
- */
-
-import {describe, it, expect} from 'vitest';
-import {program} from './index.mjs';
-
-/** Commands the update hint is expected to fire for. */
-const HINTED_COMMANDS = ['component', 'docs'];
-
-/** Real commands that must NOT trigger the update hint. */
-const NON_HINTED_COMMANDS = ['doctor'];
-
-function registeredCommandNames() {
-  return program.commands.map((c) => c.name());
-}
-
-describe('update hint commands', () => {
-  it('fires only for real, registered commands', () => {
-    const registered = new Set(registeredCommandNames());
-    for (const name of HINTED_COMMANDS) {
-      expect(registered.has(name)).toBe(true);
-    }
-  });
-
-  it('registers the real "doctor" command', () => {
-    const registered = new Set(registeredCommandNames());
-    expect(registered.has('doctor')).toBe(true);
-  });
-
-  it('does not fire the update hint for the doctor command', () => {
-    // UPDATE_HINT_COMMANDS is intentionally limited to content commands.
-    // Doctor is a diagnostic; its output should not carry an update hint.
-    expect(NON_HINTED_COMMANDS).not.toContain('component');
-    expect(NON_HINTED_COMMANDS).not.toContain('docs');
-    for (const name of NON_HINTED_COMMANDS) {
-      expect(HINTED_COMMANDS).not.toContain(name);
-    }
-  });
-});