@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/integrations/validate-contributions.mjs

@@ -24,7 +24,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {isValidSemver} from '../env/semver.mjs';
-import {findSourceOnlyCandidates} from './contribution-inventory.mjs';
+import {
+  findSourceOnlyCandidates,
+  findTemplateSourceOnlyCandidates,
+} from './contribution-inventory.mjs';
 import {
   CODEMOD_FILE_RE,
   CODEMOD_SKIP_DIRS,
@@ -56,6 +59,9 @@ import {discoverIntegrationThemes} from '../discovery/theme-discovery.mjs';
 /** Stable issue code for an invalid optional agent-doc contribution. */
 export const INVALID_AGENT_DOCS = 'invalid_agent_docs';
 
+/** Stable issue code for a `cliCommand` that was ignored as invalid. */
+export const INVALID_CLI_COMMAND = 'invalid_cli_command';
+
 /** Stable issue code for a package whose provider ID is already claimed. */
 export const DUPLICATE_PROVIDER = 'duplicate_provider';
 
@@ -295,6 +301,32 @@ async function checkTemplates(integration, issues) {
       issueError('invalid_template', /** @type {any} */ (err).message),
     );
   }
+  checkTemplateSourcesWithoutDoc(integration, issues);
+}
+
+/**
+ * Warn about a `.tsx` directly in the templates root with no same-stem template
+ * metadata: template discovery pairs sources with docs, so `astryx template`
+ * never lists it. A PascalCase file directly in a shared components root is
+ * left to the component check, which already warns about it.
+ * @param {LoadedIntegration} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+function checkTemplateSourcesWithoutDoc(integration, issues) {
+  const root = /** @type {string} */ (integration.templates);
+  const sharedComponents =
+    integration.components != null &&
+    path.resolve(integration.components) === path.resolve(root);
+  for (const file of findTemplateSourceOnlyCandidates(root)) {
+    if (sharedComponents && /^[A-Z]/u.test(file)) continue;
+    const stem = file.slice(0, -'.tsx'.length);
+    issues.push(
+      issueWarning(
+        'source_without_template_doc',
+        `Template source "${file}" has no same-stem metadata file ${stem}.doc.mjs, so \`astryx template\` never lists it. Fix: add ${stem}.doc.mjs beside it with type: 'page' or 'block'; \`astryx docs authoring integration-template-doc\` lists its fields. If it is not a template, move it out of the templates root.`,
+      ),
+    );
+  }
 }
 
 /**
@@ -450,6 +482,14 @@ export async function validateLoadedIntegration(loaded) {
   if (loaded.__agentDocsError) {
     issues.push(issueError(INVALID_AGENT_DOCS, loaded.__agentDocsError));
   }
+  if (loaded.__cliCommandError) {
+    issues.push(
+      issueWarning(
+        INVALID_CLI_COMMAND,
+        `${loaded.__cliCommandError}. The command is ignored; printed commands use the package-manager prefix.`,
+      ),
+    );
+  }
   checkRoots(
     {
       components: loaded.components,

package/foundation/release/agent-text-worker.d.mts

@@ -0,0 +1,4 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export {};

package/foundation/release/agent-text-worker.mjs

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The global copy's background step that keeps the computer-level
+ * agent text installed (spec AST-081 FR8), as its own detached process.
+ *
+ * Started by `maybeKeepAgentText` (global-state.mjs) from the global copy,
+ * with one argument, the per-user configuration folder. It writes the files
+ * the person's settings choose, with this release's text and the plain `astryx` command, and keeps every file a
+ * person edited, every file without the Astryx markers, and every link, as
+ * `astryx init --user` does. It then records this release as the one that
+ * wrote the text. It writes nothing to any stream and never reaches a
+ * person: it is not a command and takes no options.
+ *
+ * @input  argv[2]: the per-user configuration folder (the state file's); the
+ *   settings file
+ * @output the computer-level agent text and the updated global state on disk
+ * @position foundation/release — one of the two detached processes the CLI
+ *   starts; the other is refresh-worker.mjs.
+ */
+
+import {fileURLToPath} from 'node:url';
+import {
+  COMPUTER_COMMAND,
+  writeComputerAgentText,
+} from '../agent-docs/computer-agent-text.mjs';
+import {
+  computerAgentTextSettings,
+  recordComputerAgentTextSettings,
+} from '../env/user-settings.mjs';
+import {recordAgentTextWritten} from './global-state.mjs';
+import {readJson} from './project.mjs';
+
+const stateDir = process.argv[2];
+if (stateDir) {
+  try {
+    const settings = computerAgentTextSettings();
+    if (settings.install) {
+      const {links} = writeComputerAgentText({command: COMPUTER_COMMAND});
+      recordComputerAgentTextSettings({
+        install: true,
+        links: [...new Set([...settings.links, ...links])],
+      });
+      const pkg = readJson(
+        fileURLToPath(new URL('../../package.json', import.meta.url)),
+      );
+      recordAgentTextWritten(pkg?.version ?? null, stateDir);
+    }
+  } catch {
+    // A home folder that cannot be written is tried again later.
+  }
+}

package/foundation/release/cache.d.mts

@@ -0,0 +1,310 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The per-user cache directory every Astryx cache lives in, never inside a
+ * project (`foundation/env/user-dirs.mjs`).
+ * @returns {string}
+ */
+export function userCacheDir(): string;
+/**
+ * The folder all cached releases live in.
+ * @param {string} [cacheDir]
+ * @returns {string}
+ */
+export function releasesDir(cacheDir?: string): string;
+/**
+ * Is `version` a plain release version?
+ * @param {unknown} version
+ * @returns {version is string}
+ */
+export function isReleaseVersion(version: unknown): version is string;
+/**
+ * A cached, verified release.
+ * @typedef {object} CachedRelease
+ * @property {string} version
+ * @property {string} dir the release folder
+ * @property {string} cliDir its `@astryxdesign/cli`
+ * @property {string} coreDir its `@astryxdesign/core`
+ * @property {string} bin the CLI's `astryx` entry file
+ */
+/**
+ * The entry file a CLI package's `astryx` bin points at.
+ * @param {string} cliDir
+ * @returns {string | null}
+ */
+export function cliBinOf(cliDir: string): string | null;
+/**
+ * The cached release `version`, when it is installed and verified: its
+ * marker parses, names the version, and records the bytes of the CLI's and
+ * Core's package.json and the CLI's entry file, and those files still have
+ * them, and the number and total size of the two packages' files are the
+ * ones recorded. Anything else is a damaged release, which counts as absent and is
+ * replaced the next time a run needs it.
+ * @param {string} version
+ * @param {string} [cacheDir]
+ * @returns {CachedRelease | null}
+ */
+export function cachedRelease(version: string, cacheDir?: string): CachedRelease | null;
+/** Forget which releases this process verified, so the next look checks again. */
+export function forgetVerifiedReleases(): void;
+/**
+ * The size record of a release's two packages.
+ * @param {string} dir the release folder
+ * @returns {{cli: {count: number, bytes: number}, core: {count: number, bytes: number}} | null}
+ */
+export function releaseTree(dir: string): {
+    cli: {
+        count: number;
+        bytes: number;
+    };
+    core: {
+        count: number;
+        bytes: number;
+    };
+} | null;
+/**
+ * Is `dir` inside the release cache? A copy that lives there was started by
+ * global mode, never installed by a person.
+ * @param {string} dir
+ * @param {string} [cacheDir]
+ * @returns {boolean}
+ */
+export function isInReleaseCache(dir: string, cacheDir?: string): boolean;
+/**
+ * How to start npm, never through a shell, so nothing a project declares is
+ * read by one: npm's own entry file run with this Node, from beside the
+ * running Node, else from beside an `npm` on the PATH (on Windows, npm's
+ * `npm.cmd` shim sits next to its `node_modules`); else `npm` on the PATH,
+ * started directly. An `npm` beside the running Node or on the PATH that
+ * links to npm's entry file (as distribution packages install it, such as
+ * `/usr/bin/npm` to `/usr/lib/node_modules_22/npm/bin/npm-cli.js`) counts as
+ * that entry file.
+ * @param {{env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, execPath?: string}} [where]
+ *   `execPath`: the Node that runs npm (default: this one)
+ * @returns {{command: string, prefix: string[], shell: false}}
+ */
+export function npmCommand(where?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    execPath?: string;
+}): {
+    command: string;
+    prefix: string[];
+    shell: false;
+};
+/**
+ * Whether `spec` reads as an npm version range and nothing else: versions,
+ * `x`/`*` wildcards, prerelease tags, the range operators, `||`, and spaces.
+ * Anything a shell or npm would read as more, such as `&`, `;`, a lone `|`,
+ * quotes, or a URL, is refused.
+ * @param {string} spec
+ * @returns {boolean}
+ */
+export function isVersionRange(spec: string): boolean;
+/**
+ * The result of running npm.
+ * @typedef {object} NpmResult
+ * @property {number | null} status
+ * @property {NodeJS.Signals | null} [signal] the signal that ended npm, such as Ctrl-C's
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {Error} [error]
+ */
+/**
+ * Run npm synchronously with no output on the caller's streams.
+ * @param {string[]} args
+ * npm runs under npm-guard.mjs, which gives it a process group of its own
+ * and ends that group when the time limit passes, when this run goes away
+ * (even killed outright), or when this run receives Ctrl-C. So no install
+ * outlives the run that started it.
+ *
+ * @param {string[]} args
+ * @param {{cwd?: string, timeoutMs?: number, pidFile?: string, npm?: {command: string, prefix: string[], shell?: false}}} [options]
+ *   `pidFile` receives npm's process id while it runs (the release lock's
+ *   record); `npm` replaces how npm is started (tests).
+ * @returns {NpmResult}
+ */
+export function runNpm(args: string[], options?: {
+    cwd?: string;
+    timeoutMs?: number;
+    pidFile?: string;
+    npm?: {
+        command: string;
+        prefix: string[];
+        shell?: false;
+    };
+}): NpmResult;
+/**
+ * The newest published version that `spec` (a dist-tag or a range) names,
+ * asked of the registry through npm.
+ * @param {string} name e.g. `@astryxdesign/core`
+ * @param {string} spec e.g. `latest`, `^0.6.8`
+ * @param {{run?: typeof runNpm}} [options]
+ * @returns {string | null}
+ */
+export function resolvePublishedVersion(name: string, spec: string, options?: {
+    run?: typeof runNpm;
+}): string | null;
+/**
+ * The release the registry tags `latest` for the CLI, and the Node range it
+ * declares; null when the registry cannot be asked, with the reason given to
+ * `onFailure`: `npm-missing` (npm cannot be started), `npm-failed: <npm's
+ * error code>` (npm ran and failed, such as on ECONNREFUSED or E404), or
+ * `bad-reply` (npm's answer names no release).
+ * @param {{run?: typeof runNpm, onFailure?: (reason: string) => void}} [options]
+ * @returns {{version: string, node: string | null} | null}
+ */
+export function resolveLatestRelease(options?: {
+    run?: typeof runNpm;
+    onFailure?: (reason: string) => void;
+}): {
+    version: string;
+    node: string | null;
+} | null;
+/**
+ * How long a failed install of a release is remembered, so offline runs do
+ * not start npm again on every run (spec AST-081 FR2): 2 minutes after a
+ * first failure, so a passing registry hiccup is retried soon, and 10 minutes
+ * after a second failure in a row. A successful install forgets it.
+ * @param {number} failures the failures in a row, 1 or more
+ * @returns {number}
+ */
+export function failedInstallWaitMs(failures: number): number;
+/**
+ * The recorded failed installs of `version` in a row, when the last was
+ * within its wait (failedInstallWaitMs), or null.
+ * @param {string} version
+ * @param {string} cacheDir
+ * @param {number} [now]
+ * @returns {{at: number, reason: string, failures: number, waitMs: number} | null}
+ */
+export function recentFailedInstall(version: string, cacheDir: string, now?: number): {
+    at: number;
+    reason: string;
+    failures: number;
+    waitMs: number;
+} | null;
+/**
+ * Take a lock folder, or return false when another live run holds it. A lock
+ * whose holder has gone, such as a run stopped with Ctrl-C or killed, is taken
+ * over at once, and one from another computer once its holder has stopped
+ * renewing it. Throws when the cache folder cannot be written.
+ * @param {string} lockDir
+ * @param {{now?: number}} [options] the clock, for tests
+ * @returns {boolean}
+ */
+export function tryLock(lockDir: string, { now }?: {
+    now?: number;
+}): boolean;
+/**
+ * Whether a process's arguments are this CLI's install of `version`, as
+ * runNpm starts it: the program (`argv[0]`) is npm, or node running npm's
+ * entry file `npm-cli.js` (`argv[1]`), each exactly by name, and the arguments
+ * include `install` and `@astryxdesign/cli@<version>`. A program that only has
+ * `npm` somewhere in its name or arguments is not.
+ * @param {string[]} argv
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function isReleaseInstall(argv: string[], version: string): boolean;
+/**
+ * End the npm process group a stale lock records, only when that process is
+ * surely the install the lock was taken for: its command line is this CLI's
+ * install of the lock's release (isReleaseInstall), the lock is younger than
+ * any install may take, and the process started no earlier than the lock.
+ * Anything less certain is left alone, and the lock is simply taken over,
+ * since a recorded process id can name an unrelated process once the install
+ * ended.
+ * @param {string} lockDir a `.lock-<version>` folder
+ * @param {{now?: number, procRoot?: string, factsOf?: (pid: number) => {argv: string[] | null, startedAt: number | null}}} [options]
+ *   the clock, the process table's folder, and the fact reader, for tests
+ * @returns {'ended' | 'left'} whether a process group was ended
+ */
+export function endRecordedInstall(lockDir: string, { now, procRoot, factsOf }?: {
+    now?: number;
+    procRoot?: string;
+    factsOf?: (pid: number) => {
+        argv: string[] | null;
+        startedAt: number | null;
+    };
+}): "ended" | "left";
+/**
+ * Why a release could not be made available.
+ * @typedef {object} ReleaseUnavailable
+ * @property {string} version
+ * @property {string} reason one plain sentence
+ * @property {NodeJS.Signals} [signal] the install was stopped by this signal
+ */
+/**
+ * Install release `version` into the cache, verify it, and return it. A
+ * release already cached returns at once. When another run is installing the
+ * same release, this waits for it.
+ *
+ * @param {string} version
+ * @param {{cacheDir?: string, run?: typeof runNpm, nodeVersion?: string, waitMs?: number, onProgress?: (event: 'install' | 'wait', version: string) => void}} [options]
+ *   `onProgress` hears once when an install starts and once when the run
+ *   starts waiting for another run's install.
+ * @returns {CachedRelease | ReleaseUnavailable}
+ */
+export function ensureRelease(version: string, options?: {
+    cacheDir?: string;
+    run?: typeof runNpm;
+    nodeVersion?: string;
+    waitMs?: number;
+    onProgress?: (event: "install" | "wait", version: string) => void;
+}): CachedRelease | ReleaseUnavailable;
+/**
+ * The longest an install may take: generous, so a slow but moving download
+ * finishes, while a stalled one still ends in ERR_VERSIONS_UNAVAILABLE.
+ */
+export const INSTALL_TIMEOUT_MS: number;
+/**
+ * A cached, verified release.
+ */
+export type CachedRelease = {
+    version: string;
+    /**
+     * the release folder
+     */
+    dir: string;
+    /**
+     * its `@astryxdesign/cli`
+     */
+    cliDir: string;
+    /**
+     * its `@astryxdesign/core`
+     */
+    coreDir: string;
+    /**
+     * the CLI's `astryx` entry file
+     */
+    bin: string;
+};
+/**
+ * The result of running npm.
+ */
+export type NpmResult = {
+    status: number | null;
+    /**
+     * the signal that ended npm, such as Ctrl-C's
+     */
+    signal?: NodeJS.Signals | null | undefined;
+    stdout: string;
+    stderr: string;
+    error?: Error | undefined;
+};
+/**
+ * Why a release could not be made available.
+ */
+export type ReleaseUnavailable = {
+    version: string;
+    /**
+     * one plain sentence
+     */
+    reason: string;
+    /**
+     * the install was stopped by this signal
+     */
+    signal?: NodeJS.Signals | undefined;
+};